DSH plugin compaction: summary events and pruning
After compaction, the useful question is not "how many tokens vanished" but "can the vanished segment be rebuilt." DSH plugin splits that answer across three log events: a lock, a summary, and a close. Read all three and you can tell whether a compaction finished, failed, or crashed in the middle.
Three events write the log only
compaction/* are log facts; only the replacement user/message changes what the model sees.(source)
Compaction adds three events to SessionEventMap through declaration merging: compaction/start, compaction/summary, and compaction/end. All three write the log only — recording the lock, the summary, the selected range, shadowed event seqs, token counts, and the model call — and never enter the surface. They deliberately do not extend SurfaceEventType, because only message-producing events reach the model.
The summary therefore rides on a separate user/message carrying surfaceOp: { op: 'replace', startSeq, endSeq }. That is the single surface change a summary compaction performs; understand it, and you will stop looking for "what the model saw" inside compaction/summary.
The lock order is intentional: append compaction/start, generate the summary and write compaction/summary plus the replacing user/message, then append compaction/end. Releasing the lock last means a crash mid-operation surfaces as a detectable leftover lock — a start without a matching end — rather than an end falsely claiming success.
The lock marker is a point in time, not an exclusive container. While a summary is pending, unrelated idle injections may appear between a standalone manual start and end; the manual path revalidates only the selected position span, so injection context after the replacement checkpoint survives. An active unmatched start blocks every entry point, while an unmatched start before a newer session/end-seed is stale evidence from a previous lifecycle and is ignored.
The summary payload can rebuild one call
It records not just the result but exactly which request produced the summary.(source)
The compaction/summary payload carries summary, optional rawOutput, optional llmStreamCall, shadowedRange, shadowedSeqs, shadowedTokenCount, provider, model, optional maxTokens, and optional usage.
The relationships matter:
llmStreamCall: truemeans the result was produced by exactly one call through this context'sctx.llm.stream(), and a completerawOutputis then required;- a
rawOutputwithout that marker says nothing about the call path; provider,model, and optionalmaxTokensform the summary call's envelope, so once logged, that one-shot request can be rebuilt from log plus code;shadowedRangeis the shadowed surface boundary pair — a position span, not a numeric interval.
That last point saves debugging time. Compare start and end numerically to count "how many were compacted" and you will be wrong in any session that has seen replacements.
Which CompactionResult field is authoritative
Read shadowedSeqs; do not do arithmetic on the range.(source)
A successful compaction returns CompactionResult with compactionId, optional sourceCommandId, startSeq, summarySeq, endSeq, summary, shadowedRange, shadowedSeqs, and shadowedTokenCount.
compactionId is the stable identity of the whole persisted lifecycle; manual compaction also carries sourceCommandId. The three seqs point at appended events and serve log navigation. shadowedRange is documented as a surface position span: when an earlier replace placed a high-seq summary node into an old interval's position, start can exceed end. shadowedSeqs, in surface order, is the authoritative shadowed node set.
The three entry points also differ slightly in output shape: compactIfNeeded(agent, trigger, signal) returns null when no safe range exists; compactNow(agent, signal) runs as between-turn agent maintenance and likewise returns null without writing when no valid range exists; compactRegion(start, end, agent, signal?) force-compacts an inclusive surface interval and rejects unbalanced boundaries. All three return CompactionResult on success.
Manual compaction has six expected failure codes: busy, cancelled, changed, summary, commit, persistence. changed and summary close the failed attempt and persist it to the log without writing the summary replacement; image offloads recorded during recovery still stand. commit may occur after partial changes; persistence means the in-memory marker pair closed while flush failed. Cancellation is independent of these failures and throws the original abort cause after necessary cleanup.
Image offload is an event plus a pure projection
It does not change surface structure; it explains why an image is gone.(source)
compaction-image-offload owns the image/offload declaration and its pure message projection. Each target names the current input node and exact image positions counted depth-first:
interface ImageOffloadTarget {
seq: SessionSeq
imageIndexes: number[]
}
The key constraint: the event keeps node and message identity but carries no surfaceOp. So it adds no surface event and changes no node order; readers substitute a placeholder at the named positions through the pure projection.
The other half of that contract lives on the failure: routing answers IMAGE_OFFLOAD_REQUIRED with a count of images standing in the way, and this plugin's only job is to pick which occurrences to drop, log them as evidence, and let the step run again.
Pruning and compaction are different operations
Pruning changes text length; only compaction changes surface structure.(source)
The optional tool-result pruner does deterministic head/middle/tail trimming and touches only tool result nodes in the current surface. Three methods with clear boundaries:
measureContent(blocks)— counts text by Unicode code point and scores non-text blocks as zero;pruneContent(blocks)— replaces middle text when over budget while preserving rich block order; slicing by code point rather than UTF-16 unit never splits a surrogate pair, though grapheme clusters can still split;pruneSession(session)— prunes every over-budget tool result against one stable snapshot of the current surface.
Landed records live in PrunedEntry: originalSeq, replacementSeq, callId, charsBefore, charsAfter. Each replacement keeps the full event data except content, references the shadowed node so replay can recover the input, and is preceded immediately by a compaction/prune shadow-price event that prices the shadowed node through the injected token meter, so pure consumers can subtract without per-node state.
Remember pruneSession error semantics: it throws if the session rejects one replacement, but replacements committed earlier in that run remain persisted. After a failure, do not assume nothing changed.
Verification: a session with images and long output
Assert compaction artifacts item by item; do not settle for a lower token total.(source)
- Build a session with images and oversized tool output, and record the pre-compaction
shadowedSeqscandidates. - Run one compaction and assert the log holds start, summary, and end in the correct order.
- Assert
shadowedSeqsmatches the actual shadowed surface nodes one to one rather than deriving them from a seq interval. - Hard-kill the process during summarization, restart, and assert the leftover lock is detectable (start without end) and never treated as complete.
- Run tool-result pruning alone and assert
charsRemovedequals the sum of eachcharsBefore - charsAfter. - Force one image offload and assert node order is unchanged, no surface event was added, and the projection matches the target
imageIndexes.
If step 3 disagrees, check whether you iterated shadowedRange as a numeric interval. In a session that has seen replacements, a position span and a numeric interval are not the same thing.
For triggers and error recovery, see how compaction works; for reading a compacted source from the reference side, see referencing a compacted source session.
One line to close: the three events only log, the lock is believable only when released last, the summary reaches the surface through a user message, the range is authoritative only as shadowedSeqs, and neither pruning nor image offload touches surface structure.
FAQ
No. All three DSH plugin compaction events write the log only. DSH plugin carries the summary itself on a separate user/message with a replace surfaceOp, and that is the sole surface change.
No. DSH plugin defines it as a surface position span. When earlier replacements occurred, start may exceed end, so the authoritative shadowed node set is shadowedSeqs.
No. DSH plugin's image/offload events keep node and message identity but carry no surfaceOp, so a pure message projection explains the missing image without adding a surface event.
No. DSH plugin implements them separately. Pruning trims over-budget tool result text in the current surface, while compaction replaces a surface range with a summary node.
Related Terms
- compaction/start
- compaction/start is appended when compaction begins, carrying turn attribution: a number for an unfinished automatic turn, null for a manual attempt.— packages/compaction/compaction/src/types.ts
- shadowedSeqs
- shadowedSeqs lists every shadowed surface node seq in surface order and is the authoritative compaction range set.— packages/compaction/compaction/src/types.ts
- CompactionResult
- CompactionResult is the outcome of a successful compaction: transaction id, three event seqs, summary, shadowed range, and token counts.— packages/compaction/compaction/src/types.ts
- PrunedEntry
- PrunedEntry records one landed tool result prune: original seq, replacement seq, callId, and code point counts before and after.— packages/compaction/compaction-tool-result-pruner/src/types.ts
Sources
- DeepSeek Harness reference - Compaction· deepseek-ai
- packages/compaction/compaction/src/types.ts· deepseek-ai