refactor: narrow compaction surface

packages/compact/compact/README.md

@@ -19,7 +19,7 @@ Both methods are **abstract** — the backend owns the entire strategy (token es
 | Member | Semantics |
 |---|---|
 | `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. |
-| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
+| `compactRegion(start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) from `agent.session` into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. |
 
 `compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The session being compacted comes from the agent context; the turn that the `compact/*` events belong to is recoverable from the log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value.
 

packages/compact/compact/src/index.ts

@@ -14,7 +14,8 @@
  * implementation (deferred) / consumer (a `/compact` tool, deferred) — modeled
  * on the bash trio. Unlike `dsh-bash`, this interface necessarily
  * depends on `dsh-session` and `dsh-llm`: the contract's verbs are defined over
- * a `Session` and its output is the `ContentBlock` vocabulary. That deviation
+ * an agent-owned `Session` and the durable summary event uses the
+ * `ContentBlock` vocabulary. That deviation
  * from the "interface depends only on cordis" guidance is intentional and
  * recorded in the [compaction capability-seam RFC](../../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md).
  *
@@ -132,10 +133,10 @@ export abstract class CompactService extends Service {
    * open (unclosed) tail step is invalid — its tool-calls have no results yet.
    * `dsh-session` exports `isToolPairingBalanced` for this check.
    *
-   * @param session - the session whose surface is mutated.
    * @param start - inclusive seq of the first surface node to compact.
    * @param end - inclusive seq of the last surface node to compact.
-   * @param agent - agent context used by router-aware summarizers.
+   * @param agent - agent context whose session is mutated and whose routing
+   *   options are used by summarizers.
    * @param signal - optional cancellation signal. A backend that summarizes via
    *   `ctx.llm.stream()` MUST forward this into the call's `GenerateOptions.signal`
    *   so an abort/dispose tears down the in-flight summarization rather than
@@ -146,10 +147,10 @@ export abstract class CompactService extends Service {
    *   prior replace can leave the surface non-monotonic in seq order), or if
    *   either boundary is not a balanced tool-pairing cut (would split a step's
    *   tool-call/result pair).
-   * @returns what the compaction did (the replaced range and its summary node).
+   * @returns the replaced range and its token accounting. The durable
+   *   `compact/summary` event owns the summary and bookkeeping-event identity.
    */
   abstract compactRegion(
-    session: Session,
     start: number,
     end: number,
     agent: CompactAgentContext,

packages/compact/compact/src/types.ts

@@ -49,14 +49,6 @@ declare module '@deepseek-ai/dsh-session' {
 
 /** Result of a successful compaction operation. */
 export interface CompactionResult {
-  /** The seq of the appended `compact/start` event. */
-  startSeq: number
-  /** The seq of the appended `compact/summary` event. */
-  summarySeq: number
-  /** The seq of the appended `compact/end` event. */
-  endSeq: number
-  /** The summary content blocks produced by the backend. */
-  summary: ContentBlock[]
   /**
    * The surface-boundary pair that was shadowed: the seqs of the first
    * (`start`) and last (`end`) surface nodes of the replaced range. A

packages/compact/compact/tests/compact.spec.ts

@@ -27,28 +27,24 @@ class StubCompactService extends CompactService {
   }
 
   override async compactRegion(
-    session: Session,
     start: number,
     end: number,
-    _agent: CompactAgentContext,
+    agent: CompactAgentContext,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
     this.lastSignal = signal
+    const session = agent.session
     // Minimal stub honoring the lock + log-only event contract.
-    const startEvent = session.append('compact/start', { turn: 0 })
-    const summaryEvent = session.append('compact/summary', {
+    session.append('compact/start', { turn: 0 })
+    session.append('compact/summary', {
       summary: [{ type: 'text', text: 'stub' }],
       shadowedRange: { start, end },
       shadowedSeqs: [],
       shadowedTokenCount: 0,
       model: 'stub',
     })
-    const endEvent = session.append('compact/end', { turn: 0 })
+    session.append('compact/end', { turn: 0 })
     return {
-      startSeq: startEvent.seq,
-      summarySeq: summaryEvent.seq,
-      endSeq: endEvent.seq,
-      summary: [{ type: 'text', text: 'stub' }],
       shadowedRange: { start, end },
       shadowedSeqs: [],
       shadowedTokenCount: 0,
@@ -88,7 +84,7 @@ describe('CompactService seam', () => {
     const svc = new StubCompactService(ctx)
     const session = new Session(SessionId('s'))
 
-    const result = await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'))
+    const result = await svc.compactRegion(0, 0, stubAgent(session, 'm'))
 
     const startEvent = session.events.find(e => e.type === 'compact/start')
     expect(startEvent).toBeDefined()
@@ -96,8 +92,9 @@ describe('CompactService seam', () => {
     // verify the runtime value is absent.
     const raw = startEvent as unknown as { surfaceOp?: unknown }
     expect(raw.surfaceOp).toBeUndefined()
-    expect(result.summarySeq).toBeGreaterThan(result.startSeq)
-    expect(result.endSeq).toBeGreaterThan(result.summarySeq)
+    expect(result.shadowedRange).toEqual({ start: 0, end: 0 })
+    expect(session.events.filter(e => e.type.startsWith('compact/')).map(e => e.type))
+      .toEqual(['compact/start', 'compact/summary', 'compact/end'])
   })
 
   it('threads the cancellation signal through to the backend', async () => {
@@ -106,7 +103,7 @@ describe('CompactService seam', () => {
     const session = new Session(SessionId('s'))
     const controller = new AbortController()
 
-    await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), controller.signal)
+    await svc.compactRegion(0, 0, stubAgent(session, 'm'), controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
 
     await svc.compactIfNeeded(stubAgent(session), '', [], controller.signal)