feat: history compaction (opt-in) — bound context growth without cache thrash

[mgoldsborough]

Stacked on #402 (which is stacked on #401). Review/merge the stack in order. Default-off (features.compaction), so safe to merge at any point in the stack — zero behavior change until a tenant enables it.

Why

With the rolling cache anchor (#401) a long run caches cheaply, but the conversation's message history still grows across runs until the prompt approaches the model's context window. The naive fix — windowing out the oldest messages every turn — busts the prompt cache every turn, the exact pathology #401 removes.

Compaction folds the oldest turns into a single summary at run start as a deliberate, infrequent re-anchor: one cache re-write when it fires, then a smaller prefix that re-caches and stays stable until the next compaction. It also bounds the irreducible cache-read floor of a very large conversation (flagged in the audit) and gives the overflow path headroom so a long thread never hits the hard 400.

What's in it

Core (conversation/compaction.ts)

• planCompaction (pure): whether/where to compact. Triggers at ~triggerRatio (0.7) of the message budget, keeps the recent ~keepRatio (0.35) verbatim, and snaps the boundary to a user-turn start so whole turns — and their tool-call/result pairs — stay intact on both sides.
• summarizeMessages: the model call (the fast slot — a cheap forked call that never touches the main loop's cache), with untrusted-data framing + XML containment, mirroring auto-title.ts. The transcript names tool calls (name + bounded args), tool results, and resource links so a tool-heavy thread's substance survives the summary, rather than collapsing every non-text part to a bare [tool-call] placeholder.
• compactionSummaryMessages: renders the summary as a valid user→assistant replay seed (<conversation-summary> contained, closing-tags escaped), used identically in-memory and on reload.
• compactConversationMessages: end-to-end helper (plan + summarize + emit event → seed + kept tail), best-effort — returns the input unchanged on no-op or any failure.

Persistence + replay

• history.compacted event { summary, compactedThroughTs }, appended after the turns it summarizes; the boundary timestamp marks where verbatim replay resumes.
• reconstructMessages honors the most recent compaction (earlier ones are subsumed). Compaction scopes the model context only: history() → the LLM context builder reads the compacted view, while the web client, export, and fork() read the full verbatim history via reconstructMessages(events, { ignoreCompaction: true }). Users keep complete scrollback; forks copy the real turns. (Two projections of one conversation, intentionally — the model sees the re-anchored prefix, the user sees everything.)
• ConversationStore.appendEvent? — optional interface method; event-sourced stores only (message-based legacy/in-memory stores have no event stream), so callers feature-detect.

Wiring (runtime.ts, both chat paths)

• After the message budget resolves, Runtime.maybeCompactHistory feature-detects (features.compaction + appendEvent), resolves the fast model, compacts the raw history, persists the event, and the run rehydrates the result exactly once (compactedHistory ?? history). The trigger estimate runs pre-rehydration by design — rehydration inlines file bytes the ts-keyed estimate must not serialize — so it can under-fire vs. true prompt size, but the overflow windowing path still bounds the hard context limit. Best-effort throughout — a summarizer failure falls back to the full history and never fails the turn.
• features.compaction: opt-in, default false.

Correctness fixes (from QA review)

• fork() reads the verbatim projection, not the compacted one. Previously fork routed through history() → the compacted array, so forking a compacted conversation baked the summary seed in as real events, permanently dropped the pre-boundary turns the UI still shows, and sliced atMessage (an index into the user's full-history view) against the shorter compacted array. Fixed via readMessages(id, { ignoreCompaction: true }).
• Single rehydration per turn (was double on compaction turns — the first result was discarded).
• CHANGELOG corrected: the earlier "compacted view consistent across history(), the LLM context builder, and the web client" was false — the web client/export/fork read full verbatim history. The entry now states the projection split honestly.

Tests

Planner thresholds, boundary snapping, keep-ratio bound, min-summarized guard; summary rendering + closing-tag escape; the model-call helper; the wiring helper (compacts + emits one event + returns seed/tail, no-op below threshold with the model never called, best-effort fallback on failure); reconstruction (single + accumulated compactions, no-compaction passthrough). New regressions for the QA fixes: reconstructMessages with ignoreCompaction returns the full verbatim history; fork() of a compacted conversation preserves every pre-boundary turn and carries no summary seed while history() on the source stays compacted; the summarizer transcript includes tool name/args/result.

End-to-end wiring test (test/integration/compaction-wiring.test.ts): enabling features.compaction and driving real /v1/chat turns past the budget persists a history.compacted event, and asserts the model view is compacted while the verbatim view holds every turn — pinning the feature gate, the no-op reference-equality contract, and the persist/reload round trip. bun run verify:static green; unit + integration green. (One unrelated pre-existing test:bundles failure — missing dompurify in bundles/automations/ui — reproduces on the base without these changes.)

Follow-ups (not blocking)

• Tuning of triggerRatio/keepRatio/summary length once it runs on real traffic, and whether to also compact within a single very long run (today bounded by maxIterations). Validate on the hq tenant before enabling broadly — same playbook as fix(engine): roll the prompt-cache breakpoint to defeat long-run cache thrash #401.
• Lossless fork: fork() still reconstructs→re-serializes (synthetic run spans, zeroed usage); copying raw event lines would be lossless. Pre-existing, not compaction-induced.
• Summary call usage telemetry: summarizeMessages (and its mirror auto-title.ts) discard result.usage, so the forked fast-slot calls are invisible to cost/usage accounting. Thread usage out of both and emit it — done together to stay consistent.
• Unify the two reconstructors: conversation/event-reconstructor.ts (model/fork) and the bundle's jsonl-reader.ts (UI/export) are independent implementations that could drift; the compaction split is correct in both today but they're worth consolidating.