Documentation
¶
Overview ¶
Package compactor owns session-aware compaction work that used to live inline in pkg/runtime: extracting the conversation to summarize, computing the kept-tail boundary, and running the default LLM-based summarization strategy.
The runtime calls into this package once it has decided that compaction should run (the trigger logic in pkg/runtime/loop.go) and once it has dispatched the before_compaction hook (which may supply its own summary, in which case this package is bypassed entirely). The runtime owns event emission and session mutation; this package produces the summary text and reports the structural facts the runtime needs to apply it.
This separation is deliberate: nothing in here imports pkg/runtime, which keeps the dependency direction clean (runtime → compactor) and lets future strategies (a non-LLM truncator, a remote summarizer, a model-specific variant) live alongside RunLLM without bloating the runtime package.
Index ¶
Constants ¶
const MaxSummaryTokens = 16_000
MaxSummaryTokens caps the summary's output length when using the default LLM strategy. Exposed because the runtime subtracts it from the model's context budget when deciding whether the model lookup produced a workable limit.
Variables ¶
This section is empty.
Functions ¶
func ComputeFirstKeptEntry ¶
ComputeFirstKeptEntry returns the index in sess.Messages of the first message preserved verbatim after compaction, given the [maxKeepTokens] window. Used by the runtime when a hook supplies its own summary so the kept-tail policy stays consistent across the two strategies.
Types ¶
type LLMArgs ¶
type LLMArgs struct {
// Session is the parent session whose conversation is being
// compacted. The strategy reads from it but does not mutate it.
Session *session.Session
// Agent is the parent agent. Its model is cloned (with structured
// output disabled and a hard MaxTokens cap) to perform the
// summarization.
Agent *agent.Agent
// AdditionalPrompt is an optional extra instruction appended to
// the canonical compaction prompt (e.g. "focus on code changes").
// Empty in the proactive/overflow paths; populated by the manual
// /compact command.
AdditionalPrompt string
// ContextLimit is the parent model's context-window size in
// tokens, used to truncate the conversation we hand to the
// summarizer so the request itself doesn't blow the window.
// Required: zero is rejected, since the LLM strategy needs a real
// number to work with.
ContextLimit int64
// RunAgent runs the synthesized compaction agent against the
// synthesized child session. Required.
RunAgent RunAgent
}
LLMArgs is the input to RunLLM.
type Result ¶
type Result struct {
// Summary is the text that replaces the compacted conversation.
Summary string
// FirstKeptEntry is the index in the parent session's Messages
// slice of the first message preserved verbatim after compaction.
// All earlier non-system messages are folded into Summary.
FirstKeptEntry int
// Cost is the dollar cost of producing Summary (zero for non-LLM
// strategies).
Cost float64
// InputTokens is the new "input tokens so far" tally for the
// parent session after compaction. The runtime assigns it to
// sess.InputTokens; sess.OutputTokens is reset to 0.
InputTokens int64
}
Result is the structural outcome of running a compaction strategy. The runtime applies it to the parent session by appending a session.Item with FirstKeptEntry set, resetting the running input/output token tally, and recording Cost as the item's cost.
func RunLLM ¶
RunLLM is the default LLM-based summarization strategy. It clones the parent agent's model with summary-friendly options, builds a fresh compaction agent + child session, hands the work to [LLMArgs.RunAgent], and returns the produced summary together with the kept-tail boundary the runtime needs to apply it.
Returns (nil, nil) when the model returns an empty summary; callers should treat that as "compaction was a no-op" and skip the apply step.
Source Files