compact.md 3.0 KB
ctx.compact
CompactService (abstract seam) — provided by @deepseek-ai/dsh-compact.
Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. Load one implementation per context as ctx.compact.
ctx.compact.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>
Check token pressure and compact if the conversation is too large. Estimate the next request, including its session prefix, derived history, and system prompt. Above threshold, compact a head-anchored range ending at a balanced tool boundary and reconsolidate any prior automatic checkpoint. Return null when no compaction is needed or an open tail leaves no safe cutoff. A single oversized retained unit or prefix cannot be repaired here.
agent— agent context owning the session surface and model options.fullSystemPrompt— assembled system prompt, counted toward the estimate.sessionPrefix— the instance's composed session prefix, counted toward the estimate.signal— cancellation signal; model-backed implementations must forward it.
Returns the compaction result, or null if no compaction was needed.
ctx.compact.compactRegion(start, end, agent, signal?)
abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
Forcibly compact a range of surface nodes into a single summary node. start and end name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation and rejects active, missing, reversed, or unbalanced ranges. The target session is agent.session. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks.
start— first surface seq, inclusive.end— last surface seq, inclusive.agent— context whose session is mutated and whose routing options guide summarization.signal— optional cancellation; model-backed implementations must forward it.
Returns the appended event seqs, summary, replaced range, and token accounting.