Compaction is an optional capability, outside the agent loop — meaning it may not be installed at all (minimal preset has none). When installed, the mechanism is:
| Event | Payload highlights | Purpose |
|---|---|---|
| compaction/start | { turn } | Takes the log lock; a number means an automatic turn, null means a manual attempt |
| compaction/summary | Summary, shadowed range and seqs, estimated tokens, model envelope | Records the summary and which span it shadows |
| compaction/end | { turn, error? } | Releases the lock; error records a failed attempt |
The key design: none of these reach the surface
The docs are explicit: all three are log-only and never enter the surface. The model never sees that a compaction happened.
What actually changes what the model sees is a separate step: the summary rides on a user/message carrying surfaceOp: { op: 'replace', start, end }. That is the only surface change compaction makes.
Why the lock matters: crashes are detectable
The three events form a lock: start takes it, summary is generated, the record is written, the replacement message lands, end releases. A crash mid-way looks like an orphan lock (a start with no end) — detectable.
Had end been written before the work, a crash would look like 'compaction completed' when it did not. The designer treated 'a crash must tell the truth' as a hard requirement.
What this means for you
- After compaction, earlier detail may survive only as a summary: exact numbers, file paths, corrections you made may not all be in it.
- Restate important constraints; do not assume they cross a compaction.
- Split fidelity-critical work: several short sessions on a long document beat one long session.