compaction: model-capability context compaction (not API payload slices)

[btipling]

Parent

#548 (agent session architecture)

Problem

The only “compaction” we have is drop oldest rows and slice the
string. That is an API-payload habit. Other harnesses (Pi
CompactionEntry + retainedTail; OpenCode summary parts) compact to
the model window and keep a checkpoint so they do not re-walk the entire
log.

We need that for intelligence, independent of how Blob is paged.

Goal

A compaction mechanism keyed on model capability (A3’s budget):

• When projected prompt tokens would exceed window - reserve, summarize
  older turns at clean turn boundaries (never split a tool call from its
  result).
• Persist a checkpoint (summary + retained tail) on the session so the
  next turn does not resend the warehouse.
• Storage may still hold the full Blob (OpenCode lesson: logical compact ≠
  delete disk). Paint does not need the pre-checkpoint body.

Success: a 6-hour session on a 200k model still produces a coherent
continue; the Gateway POST stays inside the window; the agent can answer
from the checkpoint + tail + working notes (A2) + tool fold (A1).

Constraints (lock)

• Compaction text is labeled as a summary, never as live assistant
  prose (honesty).
• Do not compact mid-tool-call / mid-tool_run group.
• Function/Gateway transport ceilings still apply to the prompt we send.
• Wasm does not run the summarizer (server / host fold only).

Non-goals

• Deleting Blob history when we compact the prompt
• Client tokenizer as fake % UI (harness: show live context size from model usage (not client math) #327 / feat(#539): context/usage status slot — bounded provider-usage summary (chat+agent, JSON + stream done) folded into the Wasm context slot #547)
• Pi’s JSONL DAG / /tree branching (out of scope unless a later spike)

Suggested next

create-plan after A3’s window source is locked (or one combined plan if
reviewer prefers). Depends on A1/A2 or the compacted summary will have
nothing useful to say about tools/findings.

Peer harness notes

Pi compaction (take the mechanics, not JSONL-on-disk):

• Trigger: contextTokens > contextWindow - reserve (inference budget: replace 400-row / 3.5M-char fold with model-window token budget #551 policy).
• Walk back to a keepRecentTokens tail; cut only on user/assistant/
  custom boundaries — never between tool_use and tool_result (agent memory: structured truncated tool_result on the wire (not Tool: crumbs) #549).
• serializeConversation() with tool outputs capped (~2k chars) at compact
  time.
• Extract read/modified paths from the tool log into the summary so
  “what did you already find?” works without raw dumps.
• Persist CompactionEntry + retainedTail; later builds start at the
  checkpoint. OpenCode discards verbose completed tool parts from the
  prompt but keeps them on disk — same as our Blob vs inference split.

Skip: /tree branch summaries, SQLite, part/*.json.

Orrery (2026-08-15)

Compaction is a cache-flush event. Only run it at:

• an explicit phase boundary (plan accepted, milestone, wrap-up — phase from feat: session TODO lists — one item per turn, host auto-continues with full list in the prompt #536 todos, not vibes), or
• a hard ceiling (occupancy > window − reserve).

Write the summary into a durable-spec slot (stable region, with #550 notes + files-touched), not as a new history head that churns every compact. Post-compact prefix bills fresh until re-warmed — do not compact mid-mechanical tool streak.

Family switch (#551) prefers the same boundary. retainedTail still starts after the checkpoint.