refactor(compact): turn-agnostic retention + dedicated agent/pre-request seam

Reform the compaction blueprint so a runaway turn survives and the design
stops drifting across review rounds:

- Drop in-flight-turn protection ("layer 2"). Retention is a uniform tail→head
  whole-unit walk; the only structural guard is step-alignment. A single turn
  that alone exceeds the window now compacts its own early closed steps instead
  of being retained verbatim (the failure mode that motivated this).
- Move auto-compaction off the agent/request waterfall onto a new awaited
  agent/pre-request loop seam, fired before history derivation. Compaction
  mutates the surface; the loop derives once from the result — no double-derive,
  and a listener structurally cannot act on not-yet-derived messages.
- Tighten compactIfNeeded to required (session, system, model, signal).
- Enforce a single-pass convergence invariant in resolveConfig: reject configs
  where summarizationMaxTokens + retainTokens exceeds the threshold, so a
  compaction can never immediately re-trigger.
- Document the crash vs recoverable failure taxonomy; core session repair stays
  compaction-agnostic (a log-only orphaned compact/start is inert).
- Wire dsh-compact-basic into examples/coding-agent and add a with-key
  compaction e2e (compaction's first real-world exercise + runaway net).
- Rewrite the RFC to encode the blueprint and move it to implemented/.

The runaway-turn snapshot is a named deferred follow-up: dsh-llm-replay cannot
yet serve the interleaved summarization model call.

examples/coding-agent/cordis.yml

@@ -65,6 +65,16 @@
       failures before moving on. Verify your work by running the code or
       tests. Keep answers brief and factual.
 
+# Automatic context compaction: when the derived history approaches the model's
+# context window, summarize an older range into a checkpoint so a long-running
+# or tool-heavy session keeps fitting. A leaf entry (needs ctx.llm + the
+# agent-loop's `agent/pre-request` seam from the app above).
+- id: compact-basic
+  name: '@deepseek-ai/dsh-compact-basic'
+  config:
+    contextWindow: 128000
+    retainTokens: 20480
+
 # The subagent seam + BOTH in-process backends + two model-facing tools, as leaf
 # entries after the app (which provides ctx.agents/ctx.tools). spawn (a fresh
 # child) and fork (a child seeded with the parent's completed-turn prefix) are

examples/coding-agent/tests/compaction.e2e.ts

@@ -0,0 +1,95 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { Context } from 'cordis'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { codingHarness, finalText, SYSTEM_PROMPT, waitForIdle } from './harness.ts'
+
+/**
+ * The compaction smoke test: a real model runs a multi-step bash task with a
+ * deliberately tiny context window, so the auto-compaction listener fires
+ * MID-SESSION and summarizes the older history into a checkpoint. This is the
+ * first end-to-end exercise of the compaction seam (it is wired nowhere else),
+ * and the runaway-survival regression net — it proves a session that grows past
+ * the window keeps running rather than overflowing. Key-gated.
+ *
+ * Verifies the WORLD, not the agent's self-report: a compact/start…end pair
+ * landed in the real session log, the surface actually shrank (a replace node
+ * exists and shadowed older nodes), and the agent still produced a final answer
+ * after compaction (so the summarized history did not break the conversation).
+ */
+
+let workdir: string | undefined
+let ctx: Context | undefined
+
+afterEach(async () => {
+  await ctx?.fiber.dispose()
+  ctx = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compacts mid-flight and keeps running', () => {
+  it('summarizes older history into a checkpoint without breaking the task', async () => {
+    workdir = await mkdtemp(join(tmpdir(), 'dsh-compaction-'))
+    // A few files for the model to read, so multiple bash steps accumulate
+    // surface nodes (tool calls + results) and grow the history.
+    for (let i = 1; i <= 4; i++) {
+      await writeFile(join(workdir, `file${i}.txt`), `This is file number ${i}. `.repeat(40))
+    }
+
+    // Tiny window so a handful of steps crosses the threshold. The convergence
+    // invariant requires summarizationMaxTokens + retainTokens <= window *
+    // ratio = floor(8000 * 0.5) = 4000; 1500 + 2000 = 3500 <= 4000.
+    ctx = await codingHarness(workdir, {
+      compact: {
+        contextWindow: 8000,
+        thresholdRatio: 0.5,
+        retainTokens: 2000,
+        summarizationMaxTokens: 1500,
+      },
+    })
+    const agent = ctx.agentLoop.create(AgentId('e2e-compaction'), {
+      model: 'deepseek-v4-flash',
+      systemPrompt: SYSTEM_PROMPT,
+    })
+
+    agent.send([{
+      type: 'text',
+      text: 'Read file1.txt, file2.txt, file3.txt, and file4.txt one at a time using cat '
+        + '(a separate bash command for each). After reading all four, tell me how many '
+        + 'files you read and the number mentioned in file1.txt.',
+    }])
+    await waitForIdle(ctx, agent)
+
+    const events = [...agent.session.events]
+
+    // A compaction ran: the start…end bracket landed in the real log.
+    const starts = events.filter(e => e.type === 'compact/start')
+    const ends = events.filter(e => e.type === 'compact/end')
+    expect(starts.length).toBeGreaterThan(0)
+    expect(ends.length).toBe(starts.length) // every start was released
+
+    // It succeeded at least once: a compact/summary provenance event and a
+    // replace-op user/message (the surface mutation) both landed.
+    const summaries = events.filter(e => e.type === 'compact/summary')
+    expect(summaries.length).toBeGreaterThan(0)
+    const replaceNode = events.find((e) => {
+      const se = e as unknown as { type: string; surfaceOp?: unknown }
+      return se.type === 'user/message' && typeof se.surfaceOp === 'object' && se.surfaceOp !== null
+    })
+    expect(replaceNode).toBeDefined()
+
+    // The summary shadowed real older nodes (the surface shrank vs. the raw
+    // message-producing event count).
+    const summaryData = summaries[0]!.data as { shadowedSeqs: number[] }
+    expect(summaryData.shadowedSeqs.length).toBeGreaterThan(0)
+
+    // The conversation survived compaction: the agent produced a final answer
+    // that reflects the work (it read four files).
+    const answer = finalText(events).toLowerCase()
+    expect(answer.length).toBeGreaterThan(0)
+    expect(answer).toMatch(/\b(4|four)\b/)
+  }, 240_000)
+})

examples/coding-agent/tests/harness.ts

@@ -10,6 +10,8 @@ import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as ToolBash from '@deepseek-ai/dsh-tool-bash'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic'
 
 /**
  * Shared harness for the coding-agent e2e suites: the full plugin stack
@@ -21,7 +23,19 @@ export const SYSTEM_PROMPT = 'You are a coding agent. Your only tool is bash; '
   + 'do file operations with cat/grep/heredocs, check [exit code: N] markers, '
   + 'and report results briefly.'
 
-export async function codingHarness(workdir: string, persistenceRoot?: string): Promise<Context> {
+/** Options for {@link codingHarness}. */
+export interface CodingHarnessOptions {
+  /** Durable JSONL persistence root (the resume suite needs it; others stay file-free). */
+  persistenceRoot?: string
+  /**
+   * Load {@link BasicCompactService} with this config so the compaction e2e can
+   * trigger compaction at a small, controlled history size. Omitted ⇒ no
+   * compaction plugin (the default suites run without it).
+   */
+  compact?: BasicCompactConfig
+}
+
+export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise<Context> {
   const ctx = new Context()
   await ctx.plugin(LlmService)
   await ctx.plugin(SessionStore)
@@ -32,10 +46,13 @@ export async function codingHarness(workdir: string, persistenceRoot?: string):
   await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] })
   await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
   await ctx.plugin(ToolBash)
+  // Compaction is opt-in: only the compaction e2e loads it, with a lowered
+  // contextWindow/retainTokens so a short real session crosses the threshold.
+  if (options.compact !== undefined) await ctx.plugin(BasicCompactService, options.compact)
   // Durable JSONL persistence is opt-in: only the resume e2e needs it, and the
   // other suites stay file-free. Loaded last so a resume's deferred
   // `ctx.inject(['sessionPersistence'])` resolves once this is present.
-  if (persistenceRoot !== undefined) await ctx.plugin(SessionPersistenceJsonl, { root: persistenceRoot })
+  if (options.persistenceRoot !== undefined) await ctx.plugin(SessionPersistenceJsonl, { root: options.persistenceRoot })
   return ctx
 }
 

examples/coding-agent/tests/resume.e2e.ts

@@ -38,7 +38,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     // Run 1: a fresh agent on a KNOWN session id learns a secret, then we
     // dispose the whole context (simulating process exit) so only the JSONL
     // log on disk survives.
-    ctx = await codingHarness(process.cwd(), root)
+    ctx = await codingHarness(process.cwd(), { persistenceRoot: root })
     const first = ctx.agents.create({
       agentId: AgentId('resume-1'),
       sessionId: SESSION_ID,
@@ -52,7 +52,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('resume: continue a persisted ses
     // Run 2: a brand-new context over the SAME root resumes the persisted
     // session. The loaded event log seeds the live session, so the model sees
     // run 1's exchange as conversation history.
-    ctx = await codingHarness(process.cwd(), root)
+    ctx = await codingHarness(process.cwd(), { persistenceRoot: root })
     const resumed = (await ctx.agents.resume({
       agentId: AgentId('resume-2'),
       resumeSessionId: SESSION_ID,