feat(core): compact v2 session context (#30986)

specs/v2/config.md

@@ -348,7 +348,7 @@ Behavior affecting long-running conversations and context management.
 | ------------ | ----------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
 | `compaction` | Automatic compaction, pruning, and context reserve settings | redesign | Group retained verbatim history under `keep` and rename context headroom to `buffer`. |
 
-Retain the compaction capability but redesign the less clear limits. `keep.turns` is the maximum number of recent user turns to preserve verbatim after compaction, and `keep.tokens` is the token budget for those retained turns. `buffer` is the token headroom reserved so automatic compaction triggers before the input window is exhausted.
+Retain the compaction capability but redesign the less clear limits. `keep.tokens` is the token budget for recent history serialized into the textual compaction checkpoint. `buffer` is the token headroom reserved so automatic compaction triggers before the input window is exhausted.
 
 ```jsonc
 {
@@ -356,7 +356,6 @@ Retain the compaction capability but redesign the less clear limits. `keep.turns
     "auto": true,
     "prune": true,
     "keep": {
-      "turns": 2,
       "tokens": 2000,
     },
     "buffer": 10000,

specs/v2/schema-changelog.md

@@ -1,5 +1,16 @@
 # V2 Schema Changelog
 
+## 2026-06-05: Execute Automatic Session Compaction
+
+- Trigger automatic compaction before provider turns using the complete estimated request and absolute model-aware headroom.
+- Preserve the existing structured summary contract and update prior summaries with newly compacted history.
+- Store token-bounded recent history as plain serialized text inside the checkpoint instead of replaying provider-native messages.
+- Keep compaction starts durable and progress deltas live-only; activate history cutover only from a durable completed summary.
+- Version the completed event as `session.next.compaction.ended.2` rather than changing the existing synchronized v1 payload in place.
+- Reload the replacement Context Epoch and continue the original pending turn after compaction.
+- Preserve full durable history; compaction changes only the active model representation.
+- Defer provider-overflow recovery, explicit manual compaction, and deterministic old tool-result pruning.
+
 Record V2 database, durable-event, projected-message, HTTP, and generated SDK schema changes here. Each entry states why the contract changed and whether consumers or stored data need compatibility handling. Commit messages for schema-affecting changes should include the same summary.
 
 This document covers meaningful contract changes introduced on the `feat/opencode-embedded-api` branch since its divergence from `origin/dev`. Mechanical file moves and internal refactors are omitted unless they changed stored data, replay behavior, public HTTP or SDK shapes, or model-facing tool contracts.

specs/v2/session.md

@@ -98,12 +98,22 @@ Current Context Epoch follow-ups:
 
 - Add configured, remote, and nested instruction sources with explicit precedence and removal semantics.
 - Add durable post-crash activity recovery for promoted or provider-dispatched work.
-- Integrate actual automatic/context-pressure compaction with epoch replacement.
+- Add provider-overflow recovery and explicit manual compaction on top of automatic request-budget compaction.
 - Add operational metrics for observation latency, unavailable sources, contention, baseline size, and chronological-update growth.
 - Consider watcher-backed per-file caching only if measurements show direct safe-boundary observation is too expensive.
 - Expose plugin-defined Context Sources only after plugin reload and scoped cleanup semantics are designed.
 - Add clustered Session execution ownership and stale-runtime fencing.
 
+## Automatic Compaction
+
+Before each provider turn, the runner estimates the complete model-visible request and compares it with the selected model's context window minus absolute reserved headroom. The reserve is the greater of the requested/model output allowance and configured `compaction.buffer`. When the request exceeds that budget and older complete turns are available, the runner compacts before executing the pending turn.
+
+Compaction keeps the full transcript durable while replacing its active model representation with one hidden checkpoint containing a structured rolling summary and token-bounded serialized recent context. Provider-native assistant, reasoning, and tool messages never survive across the boundary, avoiding signature and encrypted-reasoning failures when the earlier prefix changes.
+
+`session.next.compaction.started.1` durably identifies the attempt. Compaction deltas are live-only progress. `session.next.compaction.ended.2` durably stores the final summary and serialized recent context; only this completed event projects a model-visible compaction message and requests Context Epoch replacement. A failed or interrupted attempt therefore leaves the previous history boundary active.
+
+Repeated compactions update the previous structured summary with newly compacted messages. The runner then reloads projected history and executes the original pending turn. Provider overflow recovery and deterministic old tool-result pruning remain separate follow-ups.
+
 ## V1 Runtime Context Parity
 
 This is the canonical checklist for model-visible runtime context still needed before the V2 runner replaces V1. Keep each behavior in its owning boundary rather than treating all model-visible text as a durable Context Source. Update this table in the PR that changes a status.