Module compaction 

Context compaction — deciding when to compact and where to cut.

Compaction summarizes an old prefix of the conversation and keeps a recent suffix. The prefix is discarded from what the model sees, so only the kept suffix must be valid on the wire. The one invariant that makes a suffix invalid is an orphaned ToolResult: a kept tool result whose matching ToolCall (which lives in a preceding Assistant message) was summarized away. Providers reject that as an unmatched tool result.

safe_cut returns the earliest index at which the conversation may be split so the kept suffix ctx[cut..] is self-consistent. It only ever moves the cut earlier than requested — summarizing less rather than breaking the pairing — and returns 0 when no boundary pairs everything.

The reverse direction needs no check: the agent loop never leaves a ToolCall without its ToolResult, and a ToolResult always follows its ToolCall, so a kept call’s results (later indices) are kept too.

CompactionPolicy decides when to compact (the trigger) and how much recent history to keep. Retention is absolute — a token budget plus a turn floor — not a fraction of the window, so it means the same thing on an 8k and a 1M model. The trigger uses the provider-reported input-token count (never an estimate); only the cut boundary uses estimate_tokens.

Structs

CompactionPolicy

When to compact and how much recent context to retain.

Summary

A produced summary and the usage that generated it.

Enums

CompactOutcome

What a compaction pass did.

Constants

DEFAULT_KEEP_RECENT_TOKENS

Recent context kept verbatim by default, in tokens — an absolute budget (pi-style), independent of the model’s window size.

DEFAULT_KEEP_RECENT_TURNS

Complete turns always kept by default, whatever their token size.

DEFAULT_MIN_REMAINING

Tokens held free below the working ceiling by default: the trigger fires once fewer than this many remain.

Functions

compact_ctx

Summarize the older prefix of ctx in place: keep the newest messages per policy, replace the rest with a summary message, and — when a session is open — persist the boundary so a resume rebuilds the same view.

cut_for_policy

Cut for policy: keep the newest messages up to keep_recent_tokens but never fewer than keep_recent_turns turns, made tool-safe by safe_cut.

estimate_tokens

Rough per-message token estimate (~4 chars/token plus a small fixed overhead). Used only to place the cut boundary; the compaction trigger uses provider-reported token counts, never this.

safe_cut

Earliest index at which ctx may be split so the kept suffix ctx[cut..] has no orphaned tool result.

summarize

Summarize conversation with the configured LLM, optionally focused by instructions (the /compact <prompt> argument). Drives the same StreamFn the agent uses, collecting the streamed text. Returns an error string on a stream error, or when the summarizer produces no text.

summary_message

The message injected in place of a summarized prefix.