fix(compact): address PR 110 review findings

Honor cancellation and disposal around async pre-step setup before the loop can open a step or call the model.

Route compaction summarization through agent/request so router agents can select the model, and remove the stale model argument from agent/pre-step.

Document serial events and the approximate convergence bound, regenerate the Cordis catalog, and add regression coverage for router compaction, HMR cleanup, and assembly/pre-step interruption.

packages/compact/compact/README.md

@@ -18,10 +18,10 @@ Both methods are **abstract** — the backend owns the entire strategy (token es
 
 | Member | Semantics |
 |---|---|
-| `compactIfNeeded(session, system, model, 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 always supplies the assembled `system`, the `model`, and the turn `signal`. |
-| `compactRegion(session, start, end, model, 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. |
+| `compactIfNeeded(agent, turn, step, fullSystemPrompt, 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, lifecycle context, assembled `fullSystemPrompt`, and turn `signal`; router-aware summarizers can use the agent lifecycle context to route their own model call through `agent/request`. |
+| `compactRegion(session, start, end, agent, turn, step, 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. |
 
-`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 turn that the `compact/*` events belong to is not a parameter — it is recoverable from the log (the currently-open turn), so the backend stamps it without the caller supplying it.
+`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.
 
 ## Surface contract
 

packages/compact/compact/src/index.ts

@@ -27,6 +27,12 @@ import type { CompactionResult } from './types.ts'
 
 export type { CompactionResult } from './types.ts'
 
+/** Minimal agent context compaction needs without depending on the agent package. */
+export interface CompactAgentContext {
+  session: Session
+  options: { model?: string }
+}
+
 declare module 'cordis' {
   interface Context {
     compact: CompactService
@@ -84,9 +90,10 @@ export abstract class CompactService extends Service {
    *   exceeds the budget, compaction cannot help and the call may go out
    *   over-budget. Bounding an individual unit's size is a separate concern.
    *
-   * @param session - the session whose surface may be compacted.
-   * @param system - the assembled system prompt, counted toward the estimate.
-   * @param model - the summarization model (a backend may override via config).
+   * @param agent - agent context owning the session surface and model options.
+   * @param turn - turn number of the pre-step checkpoint.
+   * @param step - step number about to start.
+   * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
    * @param signal - cancellation signal. A backend summarizing 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
@@ -94,9 +101,10 @@ export abstract class CompactService extends Service {
    * @returns the compaction result, or `null` if no compaction was needed.
    */
   abstract compactIfNeeded(
-    session: Session,
-    system: string,
-    model: string,
+    agent: CompactAgentContext,
+    turn: number,
+    step: number,
+    fullSystemPrompt: string,
     signal: AbortSignal,
   ): Promise<CompactionResult | null>
 
@@ -120,7 +128,9 @@ export abstract class CompactService extends Service {
    * @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 model - summarization model.
+   * @param agent - agent context used by router-aware summarizers.
+   * @param turn - lifecycle turn forwarded to request-routing seams.
+   * @param step - lifecycle step forwarded to request-routing seams.
    * @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
@@ -136,7 +146,9 @@ export abstract class CompactService extends Service {
     session: Session,
     start: number,
     end: number,
-    model: string,
+    agent: CompactAgentContext,
+    turn: number,
+    step: number,
     signal?: AbortSignal,
   ): Promise<CompactionResult>
 }

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

@@ -3,6 +3,7 @@ import { Context } from 'cordis'
 import { CompactService } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
 import { Session, SessionId } from '@deepseek-ai/dsh-session'
+import type { CompactAgentContext } from '@deepseek-ai/dsh-compact'
 
 /**
  * A trivial concrete CompactService implementing the abstract contract. The
@@ -15,10 +16,11 @@ class StubCompactService extends CompactService {
   lastSignal: AbortSignal | undefined
 
   override async compactIfNeeded(
-    _session: Session,
-    _systemPrompt?: string,
-    _model?: string,
-    signal?: AbortSignal,
+    _agent: CompactAgentContext,
+    _turn: number,
+    _step: number,
+    _fullSystemPrompt: string,
+    signal: AbortSignal,
   ): Promise<CompactionResult | null> {
     this.lastSignal = signal
     return null
@@ -28,7 +30,9 @@ class StubCompactService extends CompactService {
     session: Session,
     start: number,
     end: number,
-    _model: string,
+    _agent: CompactAgentContext,
+    _turn: number,
+    _step: number,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
     this.lastSignal = signal
@@ -54,6 +58,10 @@ class StubCompactService extends CompactService {
 }
 
 describe('CompactService seam', () => {
+  function stubAgent(session: Session, model?: string): CompactAgentContext {
+    return { session, options: model === undefined ? {} : { model } }
+  }
+
   it('registers as ctx.compact', () => {
     const ctx = new Context()
     void new StubCompactService(ctx)
@@ -72,7 +80,8 @@ describe('CompactService seam', () => {
   it('exposes the abstract contract methods', async () => {
     const ctx = new Context()
     const svc = new StubCompactService(ctx)
-    expect(await svc.compactIfNeeded(new Session(SessionId('s')))).toBeNull()
+    const session = new Session(SessionId('s'))
+    expect(await svc.compactIfNeeded(stubAgent(session), 1, 1, '', new AbortController().signal)).toBeNull()
   })
 
   it('compact/* events merge into SessionEventMap and are log-only', async () => {
@@ -80,7 +89,7 @@ describe('CompactService seam', () => {
     const svc = new StubCompactService(ctx)
     const session = new Session(SessionId('s'))
 
-    const result = await svc.compactRegion(session, 0, 0, 'm')
+    const result = await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), 1, 1)
 
     const startEvent = session.events.find(e => e.type === 'compact/start')
     expect(startEvent).toBeDefined()
@@ -98,10 +107,10 @@ describe('CompactService seam', () => {
     const session = new Session(SessionId('s'))
     const controller = new AbortController()
 
-    await svc.compactRegion(session, 0, 0, 'm', controller.signal)
+    await svc.compactRegion(session, 0, 0, stubAgent(session, 'm'), 1, 1, controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
 
-    await svc.compactIfNeeded(session, undefined, undefined, controller.signal)
+    await svc.compactIfNeeded(stubAgent(session), 1, 1, '', controller.signal)
     expect(svc.lastSignal).toBe(controller.signal)
   })
 })