Documentation
¶
Overview ¶
Package compaction keeps a conversation within a model's context window using three mechanisms aligned 1:1 with claude-code (see docs/COMPACTION-SPEC-3.md):
- MicroCompact — clear stale COMPACTABLE tool-result bodies (non-destructive: the result can be re-read). Keeps the most recent N compactable results and clears the rest.
- AutoCompact — summarize the working head behind a compact boundary at the token threshold (or predictively). Non-destructive: the full history is retained in the message array; only messages after the last boundary are sent to the model (llm.MessagesForAPI).
- Reactive — on a prompt-too-long (413) error, force one AutoCompact and retry. It reuses AutoCompact; it is not a separate algorithm.
Snip and Context-Collapse are intentionally absent: snip's removal decision can only come from a model tool / user command (no automatic trigger), and context-collapse is disabled by default in claude-code. Thresholds are derived from the model's context window (minus a summary reservation and a buffer), with a predictive pre-request check. Token counts prefer the previous model response's input_tokens and otherwise fall back to a 4/3-scaled per-block length estimate.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EstimateTokens ¶
EstimateTokens approximates the token footprint of messages (~4 chars/token), counting each block by type (text, thinking text, tool_use name+input, and nested tool_result content). Mirrors claude-code roughTokenCountEstimation (without the 4/3 scale, which count applies).
func IsOverflow ¶
IsOverflow reports whether err is a context-length / prompt-too-long failure.
Types ¶
type Compactor ¶
type Compactor struct {
// contains filtered or unexported fields
}
Compactor applies the strategy. Construct with New.
func New ¶
func New(cfg Config, summarize Summarizer) *Compactor
New builds a Compactor. summarize may be nil to disable AutoCompact.
func (*Compactor) IsOverflow ¶
IsOverflow is the method form (satisfies the harness Compactor interface).
func (*Compactor) Pre ¶
Pre conditions the history before a model request: MicroCompact to clear stale tool results, then AutoCompact at the threshold (or predictively). Both are non-destructive. lastInputTokens is the previous response's total token size (0 if none yet), used as the initial gate count.
type Config ¶
type Config struct {
// ContextWindow is the model's total context window in tokens (default 200000).
ContextWindow int
// MaxOutputTokens is the model's max output capability; the summary reservation
// is min(MaxOutputTokens, 20000) (default 8000).
MaxOutputTokens int
// KeepRecent is the number of recent messages AutoCompact always preserves as
// the un-summarized tail (default 8). MicroCompact uses its own microKeepRecent.
KeepRecent int
}
Config tunes the compactor.
type Summarizer ¶
Summarizer condenses messages into a digest. Injected so the host controls which model summarizes (and so tests can mock).
func ProviderSummarizer ¶
func ProviderSummarizer(p llm.Provider, maxOutputTokens int, nonStreaming bool) Summarizer
ProviderSummarizer builds a Summarizer backed by an llm.Provider. It replays the real conversation messages (not a rendered text transcript) followed by the summary-request user message, with thinking disabled and output capped at min(20000, maxOutputTokens). It retries transient stream failures (MAX_COMPACT_STREAMING_RETRIES) and, if the summary request itself overflows, drops the oldest API-round groups and retries (MAX_PTL_RETRIES).
Source Files