feat(llm): add replay token metering (PR2 round 1)

docs/agent-lifecycle.md

@@ -45,6 +45,8 @@ sequenceDiagram
   Driver-->>SDK: <code>agent/status</code> idle
 ```
 
+The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.
+
 SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.
 
 Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog.

docs/architecture.md

@@ -24,6 +24,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages contribute service
 | ctx key | Package family | Role |
 |---|---|---|
 | `ctx.llm` | [`llm/`](../packages/llm/README.md) | adapter registry and streaming model calls |
+| `ctx.tokenMeter` | [`llm/token-meter`](../packages/llm/token-meter/README.md) | replay-aware per-model request and surface pressure |
 | `ctx.bash` | [`bash/`](../packages/bash/README.md) | foreground/background command execution |
 | `ctx.sandbox` | [`sandbox/`](../packages/sandbox/README.md) | same-world process confinement (argv wrapping, per-call policy) |
 | `ctx.codeRuntime` | [`code-runtime/`](../packages/code-runtime/README.md) | model-written program execution |
@@ -124,7 +125,7 @@ Durability is a plugin concern. Persistence backends buffer synchronous `session
 
 ### Model Content
 
-Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, compaction pricing, and persistence, so block types remain a repo-wide contract.
+Messages are arrays of typed content blocks (`text`, `reasoning`, `tool-call`, `tool-result`). The union derives from the merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types are coordinated across adapters, UI bridges, token metering, and persistence, so block types remain a repo-wide contract. Replay measurement types are cataloged in [token-meter.md](core-data-structures/token-meter.md).
 
 Streaming is a raw chunk protocol (`block-start` through `finish`) with `BlockAssembler` as the shared chunk-to-block assembler. The loop logs raw chunks while assembling them for dispatch. `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register with `ctx.llm.registerAdapter(models, adapter)`. StreamChunk conventions live in [llm-streaming.md](core-data-structures/llm-streaming.md).
 

docs/capability-seams.md

@@ -14,6 +14,8 @@ flowchart LR
   pkg_llm_replay["llm-replay"]
   pkg_agent_loop["agent-loop"]
   pkg_compact_basic["compact-basic"]
+  pkg_token_meter["token-meter"]
+  svc_tokenMeter["ctx.tokenMeter<br/>Replay token measurement"]
   pkg_session["session"]
   svc_sessions["ctx.sessions<br/>In-memory session store"]
   pkg_agent["agent"]
@@ -120,6 +122,7 @@ flowchart LR
   pkg_subagent_mock --> svc_subagents
   pkg_subagent_spawn --> svc_subagents
   pkg_system_prompt --> svc_systemPrompt
+  pkg_token_meter --> svc_tokenMeter
   pkg_tools --> svc_tools
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
@@ -162,6 +165,7 @@ flowchart LR
   svc_systemPrompt --> pkg_tool_fs
   svc_systemPrompt --> pkg_tool_web
   svc_systemPrompt --> pkg_tools
+  svc_tokenMeter --> pkg_compact_basic
   svc_tools --> pkg_acp
   svc_tools --> pkg_agent_loop
   svc_tools --> pkg_tool_ask_user
@@ -183,6 +187,7 @@ flowchart LR
 | ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |
 | --- | --- | --- | --- | --- | --- | --- |
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
+| `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-model/session replay folds; pressure consumers share immutable revisioned measurements. |
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`session-query`](../packages/session-query/session-query) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | - | - | Resolves live and optional persisted logs into one logical corpus for exact reads. |

docs/config-catalog.md

@@ -207,44 +207,33 @@ Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:24`](../package
 
 ## `@deepseek-ai/dsh-compact-basic`
 
-Requires: `llm`
+Requires: `llm` · `tokenMeter`
 
 ```ts config-catalog
-/**
- * Backend configuration. Every knob is REQUIRED except `auto` and
- * `charsPerToken`: there is no concrete data yet to justify default
- * thresholds/budgets, so a consumer must state each value explicitly rather
- * than inherit a guessed default. `auto` alone defaults to `true`
- * (auto-compaction is the intended posture), and `charsPerToken` defaults to
- * the English-text heuristic its estimator was calibrated on.
- */
+/** Basic compaction configuration; every common field has a deployment default. */
 export interface BasicCompactConfig {
-  /** Context window size in tokens. */
-  contextWindow: number
-  /** Compact when estimated token usage exceeds this fraction of context window. */
-  thresholdRatio: number
-  /** Number of tokens of recent context to retain during compaction. */
-  retainTokens: number
-  /** Model to use for summarization (`''` — uses the agent's model). */
-  summarizationModel: string
-  /** Provider generation cap for the summarization call. */
-  maxTokens: number
-  /** Extra compaction attempts when the first compacted surface is still over threshold. */
-  compactionRetries: number
-  /** Enable automatic compaction on the `agent/pre-step` seam (default true). */
+  /** Field-wise pressure/retention overrides keyed by configured token-meter model name. */
+  models?: Record<string, ModelCompactConfig>
+  /** Summary model; `''` resolves the latest routed model, then `AgentOptions.model`. Defaults to `''`. */
+  summarizationModel?: string
+  /** Provider generation cap for summarization. Defaults to `8192`. */
+  maxTokens?: number
+  /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+  compactionRetries?: number
+  /** Enable the automatic `agent/pre-step` pressure listener. Defaults to `true`. */
   auto?: boolean
-  /**
-   * Text density for the token estimator: estimated tokens = chars /
-   * `charsPerToken`. Defaults to 4 (typical English text). A CJK-heavy
-   * deployment should set ~1-2 — CJK runs at roughly 1-2 chars per token, so
-   * the default UNDERestimates several-fold and compaction fires far too late.
-   * May be fractional.
-   */
-  charsPerToken?: number
+}
+
+/** Optional pressure and retention policy for one metered model. */
+export interface ModelCompactConfig {
+  /** Compact at this fraction of the model's configured context window. Defaults to `0.8`. */
+  thresholdRatio?: number
+  /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
+  retainTokens?: number
 }
 ```
 
-Source: [`packages/compact/compact-basic/src/types.ts:20`](../packages/compact/compact-basic/src/types.ts)
+Source: [`packages/compact/compact-basic/src/types.ts:16`](../packages/compact/compact-basic/src/types.ts)
 
 ## `@deepseek-ai/dsh-fs-local`
 
@@ -796,6 +785,26 @@ export interface Config {
 
 Source: [`packages/context/time-context/src/index.ts:22`](../packages/context/time-context/src/index.ts)
 
+## `@deepseek-ai/dsh-token-meter`
+
+```ts config-catalog
+/** Token-meter plugin configuration. */
+export interface TokenMeterConfig {
+  /** Built-in field overrides and custom model profiles, keyed by routed model name. */
+  models?: Record<string, ModelTokenMeterConfig>
+}
+
+/** Optional pricing fields for one configured model. */
+export interface ModelTokenMeterConfig {
+  /** Provider context-window capacity in tokens. Required for a custom model. */
+  contextWindow?: number
+  /** Heuristic text density in characters per token. Defaults to `4`. */
+  charsPerToken?: number
+}
+```
+
+Source: [`packages/llm/token-meter/src/types.ts:19`](../packages/llm/token-meter/src/types.ts)
+
 ## `@deepseek-ai/dsh-tool-cordis`
 
 Requires: `tools`

docs/cordis-catalog/services.md

@@ -86,7 +86,7 @@ Source: [`packages/code-runtime/code-runtime/src/index.ts:31`](../../packages/co
 
 ## `ctx.compact` — `CompactService` (abstract seam)
 
-Abstract compaction service. Implementations own token estimation, retention, and summarization, but a successful run must replace the selected surface span with one summary node and prevent concurrent compaction of the same session. Load one implementation per context as `ctx.compact`.
+Abstract compaction service. Implementations own trigger policy, retention, and summarization, and may consume a separate measurement service. A successful run replaces the selected surface span with one summary node and prevents concurrent compaction of the same session. Load one implementation per context as `ctx.compact`.
 
 ```ts cordis-catalog
 abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>
@@ -95,7 +95,7 @@ abstract compactRegion( session: Session, start: number, end: number, agent: Com
 
 Types: [Message](../core-data-structures/core.md)
 
-Source: [`packages/compact/compact/src/index.ts:37`](../../packages/compact/compact/src/index.ts)
+Source: [`packages/compact/compact/src/index.ts:38`](../../packages/compact/compact/src/index.ts)
 
 ## `ctx.fs` — `FileSystem` (abstract seam)
 
@@ -241,6 +241,16 @@ async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 
 Source: [`packages/core/system-prompt/src/index.ts:213`](../../packages/core/system-prompt/src/index.ts)
 
+## `ctx.tokenMeter` — `TokenMeterService`
+
+Concrete registry and replay owner for all configured model meters.
+
+```ts cordis-catalog
+resolve(model: string): ModelTokenMeter
+```
+
+Source: [`packages/llm/token-meter/src/index.ts:145`](../../packages/llm/token-meter/src/index.ts)
+
 ## `ctx.tools` — `ToolRegistry`
 
 Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.

docs/core-data-structures/compaction.md

@@ -50,7 +50,7 @@ interface CompactionResult {
 
 ## The service
 
-`CompactService` exposes `compactIfNeeded(...)` for pressure-triggered compaction, returning `null` when no compaction is needed, and `compactRegion(...)` for an explicit inclusive surface range. The pre-step caller supplies the agent, full prompt, session prefix, and abort signal; implementations must forward that signal to summarization. Estimation, retention, event sequencing, and summarization remain backend policy.
+`CompactService` exposes `compactIfNeeded(...)` for pressure-triggered compaction, returning `null` when no compaction is needed, and `compactRegion(...)` for an explicit inclusive surface range. The pre-step caller supplies the agent, full prompt, session prefix, and abort signal; implementations must forward that signal to summarization. The seam owns no pricing API: `dsh-compact-basic` resolves the routed model through [`ctx.tokenMeter`](token-meter.md), whose model-bound handle owns estimation and replay, while the backend owns retention, event sequencing, and summarization.
 
 Auto-compaction runs at serial `agent/pre-step`, before the step and request derivation, so it can replace surface nodes while keeping trace events outside the step. Region boundaries preserve tool-call/result pairing but do not preserve whole turns, allowing early closed steps of one oversized turn to compact. `dsh-compact-basic` owns the retention and failure details.
 

docs/core-data-structures/core.md

@@ -16,6 +16,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | Sub-page | Owns |
 |---|---|
 | [llm-streaming.md](llm-streaming.md) | the `StreamChunk` wire protocol + adapter contract, `BlockAssembler`, the `LlmAdapter` seam |
+| [token-meter.md](token-meter.md) | immutable scalar and positional replay measurements with consumed-log revisions |
 | [scope.md](scope.md) | scoped registration identity, dispatch carriers, and the owned `Scope` context |
 | [session.md](session.md) | the full `SessionEventMap` variant catalog, `TurnTrigger`/`TurnEndReason`, `deriveMessages()`, the turn-enclosure invariant |
 | [persistence.md](persistence.md) | the durability seam: `SessionPersistence`, JSONL + SQLite backends, `session/flush`, crash recovery, `SessionHeader` |

docs/core-data-structures/session.md

@@ -150,6 +150,8 @@ type SessionEvent<T extends SessionEventType = SessionEventType> = {
 
 `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`.
 
+For `assistant/message`, a present `sourceEventSeqs: []` is a complete known-empty provider stream, while an absent field means legacy or otherwise unrecorded provenance. The loop writes the field for every successful model call; every other surface event requires a non-empty list when the field is present.
+
 ## Surface types
 
 The five message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`) carry surface metadata declaring how they join the derived surface linked list. See the [session surface RFC](../rfc/implemented/architecture/2026-06-18-session-surface.md).
@@ -186,6 +188,8 @@ export interface SurfaceIntent {
 
 Required for `SurfaceEventType` events — every message-producing event must declare how it joins the surface, the sole source of derived history. Non-surface types reject it at compile time.
 
+The same provenance distinction applies here: only `assistant/message` may carry a present empty `sourceEventSeqs`; omission does not assert that its source stream was empty.
+
 ### `SurfaceNode` — a node in the surface linked list
 
 ```ts type-equiv

docs/core-data-structures/token-meter.md

@@ -0,0 +1,52 @@
+# Token Meter
+
+`@deepseek-ai/dsh-token-meter` exposes detached replay measurements for request pressure and positional surface pricing. Scalar and surface snapshots carry the number of durable events consumed as `logRevision`; consumers compare revisions before making a joint decision.
+
+Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts)
+
+## `TokenMeasurement`
+
+```ts type-equiv
+interface TokenMeasurement {
+  /** Model profile used for every heuristic component. */
+  readonly model: string
+  /** Number of durable events consumed; equal to the next unread event seq. */
+  readonly logRevision: number
+  /** Provider or heuristic anchor used for this measurement. */
+  readonly baseline: TokenMeasurementBaseline
+  /** Signed repricing of current surface content relative to the baseline anchor. */
+  readonly surfaceDeltaTokens: number
+  /** Non-negative current request-and-response pressure. */
+  readonly totalTokens: number
+}
+```
+
+`baseline.kind === 'usage'` means a successful provider call has the same model and canonical envelope. `estimated` means the meter repriced the complete envelope and surface. Signed `surfaceDeltaTokens` preserves growth and shrinkage relative to a matching provider or estimated anchor.
+
+## `TokenSurfaceNode`
+
+```ts type-equiv
+interface TokenSurfaceNode {
+  /** Durable sequence number of the surface event. */
+  readonly seq: number
+  /** Heuristic tokens for the exact message projected by this node. */
+  readonly tokens: number
+}
+```
+
+## `TokenSurfaceMeasurement`
+
+```ts type-equiv
+interface TokenSurfaceMeasurement {
+  /** Model profile used to price every node. */
+  readonly model: string
+  /** Number of durable events consumed; equal to the next unread event seq. */
+  readonly logRevision: number
+  /** Total heuristic tokens across the current surface. */
+  readonly totalTokens: number
+  /** Current surface nodes in positional head-to-tail order. */
+  readonly nodes: readonly TokenSurfaceNode[]
+}
+```
+
+Surface order is authoritative; replacement nodes can have higher durable seqs than later positional nodes. The snapshot is immutable and does not grow when the underlying replay fold advances.

docs/event-producer-consumer.md

@@ -27,7 +27,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:39`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:46`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:56`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | - |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:68`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent), [`token-meter`](../packages/llm/token-meter) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:78`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:92`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:66`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |

docs/module-graph.md

@@ -15,6 +15,7 @@ flowchart TD
     pkg_llm["llm"]
     pkg_llm_deepseek["llm-deepseek"]
     pkg_llm_pi_ai["llm-pi-ai"]
+    pkg_token_meter["token-meter"]
   end
   subgraph group_core["packages/core"]
     pkg_agent["agent"]
@@ -135,6 +136,8 @@ flowchart TD
   pkg_fs --> pkg_llm
   pkg_web --> pkg_llm
   pkg_sandbox --> pkg_llm
+  pkg_token_meter --> pkg_llm
+  pkg_token_meter --> pkg_session
   pkg_agent --> pkg_brand
   pkg_agent --> pkg_llm
   pkg_agent --> pkg_scope
@@ -165,6 +168,7 @@ flowchart TD
   pkg_compact_basic --> pkg_compact
   pkg_compact_basic --> pkg_llm
   pkg_compact_basic --> pkg_session
+  pkg_compact_basic --> pkg_token_meter
   pkg_hook_protocol --> pkg_bash
   pkg_hook_protocol --> pkg_session
   pkg_session_persistence_jsonl --> pkg_session
@@ -358,6 +362,7 @@ flowchart TD
 | [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm) |
 | [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) |
 | [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`llm`](../packages/llm/llm) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
 | [`bash`](../packages/bash/bash) | `bash` | [`brand`](../packages/util/brand), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
 | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) |
@@ -372,7 +377,7 @@ flowchart TD
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`session`](../packages/core/session) |
 | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |

docs/rfc/INDEX.md

@@ -144,6 +144,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [The agent is a registration scope](implemented/architecture/2026-07-08-agent-scope-contexts.md) | 2026-07-08 |
 | [Single-file executable SDK runtime distribution (single-exe)](implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) | 2026-07-10 |
 | [Agent-scope runtime design and correctness](implemented/architecture/2026-07-12-agent-scope-runtime-design.md) | 2026-07-12 |
+| [Replay token meter service](implemented/architecture/2026-07-15-replay-token-meter-service.md) | 2026-07-15 |
 
 ### Process
 

docs/rfc/implemented/architecture/2026-06-18-session-surface.md

@@ -14,7 +14,7 @@ Add a **surface** — a derived, cached linked list of "surface nodes" (the subs
 
 Every `SessionEvent` gains two optional fields (structural metadata, like `seq`/`time`):
 
-- **`sourceEventSeqs?: number[]`** — seq numbers of events that are provenance sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). Provenance is a core design principle; without it, the replace-range operation cannot be validated on replay.
+- **`sourceEventSeqs?: number[]`** — seq numbers of events that are provenance sources (e.g., the `assistant/chunk` seqs that built an `assistant/message`, or the surface nodes shadowed by a compaction marker). A present `[]` is valid only on `assistant/message` and records a known empty provider stream; omission there means legacy or otherwise unrecorded provenance. Other surface events require a non-empty list when the field is present. Provenance is a core design principle; without it, the replace-range operation cannot be validated on replay.
 - **`surfaceOp?: SurfaceOp`** — how this event entered the surface. Absent for non-surface events.
 
 ### SurfaceOp: two operations
@@ -25,7 +25,7 @@ export type SurfaceOp =
   | { op: 'replace'; start: number; end: number }  // shadow [start, end] inclusive
 ```
 
-1. **Append** — add a new node to the tail. Used by `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`. The loop passes `surfaceOp: 'append'` on all such appends, and `sourceEventSeqs` where applicable (e.g., `assistant/message` records its `assistant/chunk` sources; `tool/result` records its `tool/call` source).
+1. **Append** — add a new node to the tail. Used by `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`. The loop passes `surfaceOp: 'append'` on all such appends and records `sourceEventSeqs` where applicable: every successful `assistant/message` records its complete `assistant/chunk` source set, including `[]`, while `tool/result` records its `tool/call` source.
 
 2. **Replace** — remove nodes from `start` through `end` (both inclusive) and insert a new node in their place. Both `start` and `end` must be valid surface node seqs in the current surface; `start === end` replaces a single node. The node's `sourceEventSeqs` must contain every shadowed surface node. The shadowed events remain in the log but are no longer on the surface.
 
@@ -47,7 +47,7 @@ The `repair.ts` module synthesizes `tool/result` closers for orphaned tool calls
 
 ### Invariants
 
-The dev-mode invariants plugin validates: `sourceEventSeqs` references (non-empty, no duplicates, references earlier events, references known seqs) and `surfaceOp` (replace `start ≤ end`, both endpoints are on the tracked surface, the range is non-reversed in surface position, and `sourceEventSeqs` includes every node the range shadows).
+The dev-mode invariants plugin validates: `sourceEventSeqs` references (only `assistant/message` may use an empty list; otherwise no duplicates, references earlier events, and references known seqs) and `surfaceOp` (replace `start ≤ end`, both endpoints are on the tracked surface, the range is non-reversed in surface position, and `sourceEventSeqs` includes every node the range shadows).
 
 Every surface-eligible event must carry `surfaceOp` or it would disappear from derived history. Typed `append` overloads enforce this for literal event types; runtime checks in `append` and the seed constructor cover widened unions and loaded logs. Invalid seeds are rejected rather than upgraded under the pre-release format policy.
 

docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-15-replay-token-meter-service.md: 4452c151e122c4a4ad72e3f0bc2616cd2fa28b9d
+2026-07-15-replay-token-meter-service.zh.md: 23edc11ffd19b9cfaeb794f3608e9ced4e7dbb7b

docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md

@@ -0,0 +1,57 @@
+# RFC: Replay token meter service
+
+Status: implemented
+
+English | [中文](2026-07-15-replay-token-meter-service.zh.md)
+
+## Problem
+
+Context pressure is useful outside compaction. A compaction backend, an overflow guard, or a future request-policy plugin can all need the same answer: how much of one model's window does the durable request consume? Keeping that fold inside `dsh-compact-basic` duplicates replay logic, makes measurement unavailable without compaction, and encourages callers to reuse accounting from the wrong model.
+
+Provider usage is not a complete answer. It describes one successful call under one exact request envelope, while the current surface can grow, shrink, or be replaced afterward. Sessions also switch models, old logs can lack chunk provenance, and provider fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines exact anchors with conservative model-specific repricing and exposes the log revision consumed by each result.
+
+## Decision
+
+### One concrete LLM-family service
+
+`@deepseek-ai/dsh-token-meter` is one concrete package under `packages/llm/` and registers `ctx.tokenMeter`. It is not split into an interface and backend before a second implementation exists. Its public entry point resolves an exact model name to a stable `ModelTokenMeter`; unknown names throw `TokenMeterError` with `TOKEN_METER_MODEL_UNCONFIGURED` instead of inheriting a universal window.
+
+The built-in `deepseek-v4-flash` and `deepseek-v4-pro` profiles use a 128,000-token context window and four characters per estimated token. `models` overrides merge field-by-field. A custom name requires `contextWindow`, while `charsPerToken` defaults to four. Direct construction reports typed profile errors; Loader mounts first apply the package's Schemastery shape validation.
+
+### Model-bound replay folds
+
+Each model/session pair owns an isolated incremental fold. Active folds advance from `session/event`; every read catches up through the durable tail, so listener ordering, seeded sessions, and service reload do not change the answer. The fold tracks canonical request headers and deltas, step boundaries, surface appends and replacements, assistant usage, and assistant-chunk provenance. A malformed next event fails transactionally and remains unread rather than partially mutating state.
+
+`measure(session, requestHeader?)` returns scalar pressure. `measureSurface(session)` returns positional per-node prices for retention and replacement decisions. `estimateMessage(message)` applies the handle's profile without session state. Results are detached, deeply immutable snapshots carrying `logRevision`; a consumer compares scalar and surface revisions before making one decision.
+
+Provider usage is reused only when the handle's model and canonical request envelope equal the successful-call anchor. Any system, prefix, tool, or call-config change causes complete repricing under the requested model. Surface changes remain a signed delta from a matching anchor, including negative values after a shrinking replacement. A success by another model changes the shared surface but never overwrites this model's anchor.
+
+Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reasoning is not added a second time. Every successful model call records an `assistant/message`, including content-less and max-token calls, with its exact earlier chunk seqs. An explicit empty provenance list means a known empty provider stream; absent legacy provenance conservatively treats the durable assistant output as provider output.
+
+### Compact-basic consumes, but does not own, measurement
+
+`dsh-compact-basic` requires `ctx.tokenMeter`; `CompactService` gains no token methods or types. The backend is factored into configuration, automatic triggering, region transaction, and summarizer modules, while `summarize()` remains its sole subclass hook. The conversation model's meter consistently prices pressure, retention, shadowed content, provenance, and non-shrinking-summary rejection.
+
+Every metered model receives a compact policy with defaults: threshold ratio `0.8`, retained tail `floor(contextWindow × 0.16)`, summarization model `''`, maximum summary output `8192`, one extra compaction attempt, and automatic triggering enabled. Per-model compact overrides merge `thresholdRatio` and `retainTokens`; retention must remain below the resulting threshold. Empty summarization model resolves the latest logged routed model, then `AgentOptions.model`.
+
+The pre-step trigger measures a provisional envelope: the current prompt and prefix override logged values, while the latest logged header supplies model, tools, and other call config. A model-less router-only agent skips that provisional check because `agent/request` can route later; naming an unknown model remains an error.
+
+## Testing
+
+Unit coverage pins profiles, field-wise overrides, custom and unknown models, envelope invalidation, model switching, usage and missing-usage paths, seeded append/replace replay, signed deltas, provenance modes, malformed boundaries, immutable snapshots, listener ordering, reload, compact defaults, routing fallback, retention, convergence, and transaction rollback. A real Loader/Include YAML fixture loads the exact zero-config token-meter and compact-basic package names in dependency order.
+
+## Alternatives considered
+
+- **Keep estimation inside `CompactService`** — rejected because measurement has consumers and replay semantics independent of compaction; it would also force every compactor to expose the same unrelated API.
+- **Split a token-meter interface from a heuristic backend immediately** — rejected because only one implementation exists. One concrete service preserves the future seam without speculative packages or configuration.
+- **Give unknown models a 128,000-token fallback** — rejected because a plausible but wrong capacity can trigger destructive policy at the wrong point. Unknown routed names fail with their exact name.
+- **Copy complete history into each scalar result** — rejected because below-threshold reads are common. Immutable revisioned scalars and a separate surface snapshot preserve consistency without an O(history) copy.
+- **Treat provider usage as portable between models or envelopes** — rejected because tokenization, context capacity, tools, prefixes, and call config are model/request facts. Mismatch reprices the whole current request.
+
+## Consequences
+
+- Token pressure has one replay-aware owner that compaction and future plugins can share.
+- Defaults make the bundled DeepSeek composition usable with two zero-config plugin entries, while custom models must state the one fact that cannot be guessed safely: context capacity.
+- Heuristic density and provider usage remain estimates of provider behavior. Maintainers must update built-in profiles and overflow wording as models evolve.
+- Measurements fail loudly on malformed durable boundaries. This turns corrupted replay into a named integration failure instead of silently drifting pressure.
+- The pre-step compact integration can skip a router-only first check and can miss tool or routing changes applied later in request middleware.

docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md

@@ -0,0 +1,57 @@
+# RFC: 重放式 token 计量服务
+
+Status: implemented
+
+[English](2026-07-15-replay-token-meter-service.md) | 中文
+
+## 问题
+
+上下文压力并不只对压缩有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求占用了某个模型多少上下文窗口？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现重放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方错误复用其他模型的核算结果。
+
+提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换模型，旧日志可能缺少 chunk 来源，提供方字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把精确锚点与保守的逐模型重新定价结合起来，并公开每个结果已经消费的日志修订号。
+
+## 决策
+
+### 一个具体的 LLM 家族服务
+
+`@deepseek-ai/dsh-token-meter` 是 `packages/llm/` 下的单个具体 package，并注册 `ctx.tokenMeter`。在第二种实现出现之前，它不会被拆成接口与后端。公开入口把精确模型名解析为稳定的 `ModelTokenMeter`；未知名称抛出带 `TOKEN_METER_MODEL_UNCONFIGURED` 的 `TokenMeterError`，而不是继承通用窗口。
+
+内置的 `deepseek-v4-flash` 与 `deepseek-v4-pro` profile 都采用 128,000 token 上下文窗口，以及每 token 四个字符的估算密度。`models` 覆盖按字段合并。自定义名称必须提供 `contextWindow`，而 `charsPerToken` 默认为四。直接构造会报告类型化 profile 错误；Loader 挂载则先应用 package 的 Schemastery 形状校验。
+
+### 绑定模型的重放折叠
+
+每个模型/会话对都有隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范请求头及其增量、步骤边界、表层追加与替换、assistant usage，以及 assistant chunk 来源。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。
+
+`measure(session, requestHeader?)` 返回标量压力。`measureSurface(session)` 返回用于保留与替换决策的逐位置节点价格。`estimateMessage(message)` 不依赖会话状态，直接应用该 handle 的 profile。结果是分离且深度不可变的快照，并携带 `logRevision`；消费者在一次联合决策前比较标量与表层修订号。
+
+只有当 handle 的模型与规范请求信封都等于成功调用锚点时，服务才复用提供方 usage。系统提示词、前缀、工具或调用配置任一变化都会在请求模型下重新定价完整当前请求。表层变化相对匹配锚点保留有符号增量，包括缩小替换后的负值。其他模型的成功调用会改变共享表层，但绝不会覆盖当前模型的锚点。
+
+Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早 chunk seq。显式空来源列表表示已知为空的提供方流；旧日志中缺失的来源则保守地把持久 assistant 输出视为提供方输出。
+
+### compact-basic 消费计量，但不拥有计量
+
+`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。后端拆分为配置、自动触发、区域事务与摘要器模块，而 `summarize()` 仍是唯一的子类 hook。会话模型的 meter 一致用于压力、保留、被遮蔽内容、来源以及非缩小摘要拒绝。
+
+每个已计量模型都会获得默认压缩策略：阈值比例 `0.8`、保留尾部 `floor(contextWindow × 0.16)`、摘要模型 `''`、摘要最大输出 `8192`、一次额外压缩尝试，以及启用自动触发。逐模型压缩覆盖按字段合并 `thresholdRatio` 与 `retainTokens`；保留值必须小于最终阈值。空摘要模型先解析最近记录的实际路由模型，再使用 `AgentOptions.model`。
+
+pre-step 触发器计量临时请求信封：当前提示词与前缀覆盖日志值，最近记录的请求头提供模型、工具及其他调用配置。没有模型的纯路由 agent 会跳过该临时检查，因为 `agent/request` 仍可稍后路由；显式命名未知模型仍然报错。
+
+## 测试
+
+单元覆盖固定 profile、按字段覆盖、自定义与未知模型、信封失效、模型切换、有无 usage 的路径、种子追加/替换重放、有符号增量、来源模式、畸形边界、不可变快照、监听器顺序、重载、压缩默认值、路由回退、保留、收敛与事务回滚。真实 Loader/Include YAML fixture 按依赖顺序加载精确的零配置 token-meter 与 compact-basic package 名称。
+
+## 考虑过的替代方案
+
+- **把估算保留在 `CompactService` 内**——不予采纳，因为计量拥有独立于压缩的消费者与重放语义；它还会强迫每个压缩器暴露同一套无关 API。
+- **立即把 token meter 拆成接口与启发式后端**——不予采纳，因为目前只有一种实现。单个具体服务保留未来接缝，同时避免推测性的 package 与配置。
+- **给未知模型提供 128,000 token 回退**——不予采纳，因为看似合理但错误的容量会在错误时点触发破坏性策略。未知路由名称会携带精确名称失败。
+- **在每个标量结果中复制完整历史**——不予采纳，因为低于阈值的读取很常见。不可变且带修订号的标量与独立表层快照，在不进行 O(history) 复制的情况下保持一致性。
+- **在模型或信封之间移用提供方 usage**——不予采纳，因为分词、上下文容量、工具、前缀与调用配置都是模型/请求事实。不匹配时会重新定价完整当前请求。
+
+## 后果
+
+- Token 压力拥有一个可供压缩与未来插件共享的重放感知所有者。
+- 默认值让内置 DeepSeek 组合只需两个零配置插件条目即可使用，而自定义模型必须声明唯一不能安全猜测的事实：上下文容量。
+- 启发式密度与提供方 usage 仍然只是提供方行为的估计。随着模型演进，维护者必须更新内置 profile 与溢出措辞。
+- 遇到畸形持久边界时，计量会明确失败。这会把损坏的重放转化为具名集成错误，而不是让压力静默漂移。
+- pre-step 压缩集成可能跳过纯路由的首次检查，也可能错过请求中间件稍后应用的工具或路由变化。

docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md

@@ -8,7 +8,7 @@ A long-running agent conversation grows without bound. As the event log accumula
 
 The [session surface](../../implemented/architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — a linked list over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of nodes and insert a replacement, with `sourceEventSeqs` recording provenance so the decision replays deterministically. What remained was the plugin that *decides what to compact and produces the summary*.
 
-Two forces shape the design. First, compaction is **swappable**: token counting can be a char/4 heuristic or a real tokenizer, and summarization can be a model call, a template, or a remote service — these vary independently of *when* and *which range* to compact. Second, `SurfaceEventType` is closed to five event types (`user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`); only those may carry `surfaceOp`. A bespoke `compaction/*` event therefore **cannot** itself appear on the surface — the compiler rejects `surfaceOp` on it and the invariants plugin rejects it at runtime.
+Two forces shape the design. First, compaction policy and reusable token measurement vary independently: measurement belongs to the LLM-family [`ctx.tokenMeter` service](../../implemented/architecture/2026-07-15-replay-token-meter-service.md), while summarization can be a model call, a template, or a remote service. Second, `SurfaceEventType` is closed to five event types (`user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`); only those may carry `surfaceOp`. A bespoke `compaction/*` event therefore **cannot** itself appear on the surface — the compiler rejects `surfaceOp` on it and the invariants plugin rejects it at runtime.
 
 ## Decision
 
@@ -17,7 +17,7 @@ Two forces shape the design. First, compaction is **swappable**: token counting
 Per the [capability-seams RFC](../../implemented/architecture/2026-06-13-capability-seams.md), compaction ships as separate packages so the contract, the algorithm, and (later) the consumer surface evolve independently:
 
 1. **Interface** — `@deepseek-ai/dsh-compact`: an abstract `CompactService` owning the `ctx.compact` key, the `CompactionResult` vocabulary, and the `compact/*` session events. It declares `compactIfNeeded()` and `compactRegion()` as **abstract** — the contract states *what* compaction does, not *how*.
-2. **Implementation** — `@deepseek-ai/dsh-compact-basic`: a concrete `BasicCompactService` that owns the entire algorithm — token estimation (chars per token — the `charsPerToken` config, default 4 — + per-block overhead), the tail→head retention walk, summarization via `ctx.llm.stream()`, the surface replacement, the lock, and the `agent/pre-step` auto-compaction listener. A tokenizer-based or template-based backend is a sibling package (or a subclass overriding the two protected estimation/summarization hooks).
+2. **Implementation** — `@deepseek-ai/dsh-compact-basic`: a concrete `BasicCompactService` that consumes `ctx.tokenMeter` and owns the tail→head retention walk, summarization via `ctx.llm.stream()`, the surface replacement, the lock, and the `agent/pre-step` auto-compaction listener. `summarize()` is its sole subclass hook; pricing and replay stay with the meter.
 3. **Consumer** — deferred. A `/compact` tool and slash command will `inject: ['compact']` and call the contract; they are intentionally out of scope here so the seam settles first.
 
 ### The contract depends on `dsh-session` and `dsh-llm` — a deliberate deviation
@@ -28,9 +28,9 @@ This is not a coupling smell — it is the contract's domain. The "only cordis"
 
 ### Abstract `compactIfNeeded` / `compactRegion`, algorithm in the backend
 
-An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface, with only `estimateContentTokens()` and `summarize()` abstract. That recouples the contract to one strategy: a backend that wants a different retention policy or a different event-sequencing would have to fight inherited concrete code. Making both core methods abstract puts every *how* decision in the backend, where it belongs, and keeps the interface a pure statement of *what*. The backend remains internally factored — `estimateContentTokens()` and `summarize()` are `protected` hooks a sub-backend can override without reimplementing the walk — but that factoring is the backend's private concern, not the contract's.
+An earlier draft put the full algorithm (the retention walk, token-summing, text extraction) as concrete methods on the interface. That recouples the contract to one strategy: a backend that wants a different retention policy or event sequence would have to fight inherited concrete code. Making both core methods abstract puts every *how* decision in the backend and keeps the interface a statement of *what*. Token measurement is not a compaction hook at all; the standalone service lets multiple consumers share one model/session replay fold.
 
-`compactIfNeeded(agent, turn, step, fullSystemPrompt, signal)` takes **required** parameters (not the original all-optional shape). The auto-compaction seam (below) always supplies the agent, lifecycle context, assembled system prompt (counted toward the estimate), and the turn's abort signal, so optionality would only invite a hidden default at the seam. The session being compacted comes from the agent context. `compactRegion(session, start, end, agent, turn, step, signal?)` keeps an optional signal (a manual caller may omit it). Passing lifecycle context rather than a concrete model keeps router agents honest: the backend's summarization request can run through `agent/request`, where model-routing plugins already choose the actual model.
+`compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` takes required pressure inputs and cancellation. The session comes from the agent. `compactRegion(session, start, end, agent, signal?)` keeps an optional signal for manual callers. The pre-step integration resolves a provisional model from the latest logged request header, then `AgentOptions.model`; a model-less router-only first step skips pressure because `agent/request` can route later. The default summarizer resolves its model from explicit config, the latest logged routed model, then agent options.
 
 ### Auto-compaction runs on `agent/pre-step`, a dedicated surface-mutation seam
 
@@ -40,7 +40,7 @@ The fix is a dedicated loop seam, **`agent/pre-step`** (`@mode serial`), fired b
 
 ```
 assembly = ctx.systemPrompt.assemble()
-await ctx.serial('agent/pre-step', agent, turn, step, system, signal)  ⟵ compaction mutates the surface here
+await ctx.serial('agent/pre-step', agent, turn, step, system, prefix, signal)  ⟵ compaction mutates the surface here
 session('step/start')                 ⟵ the step opens AFTER the seam
 messages = session.deriveMessages()   ⟵ single derive, reflects the compaction
 request  = waterfall agent/request    ⟵ pure request transform (hooks, model switch)
@@ -64,7 +64,7 @@ Auto-compaction always starts at the surface head, merging the prior checkpoint
 
 ### Approximate convergence invariant
 
-`resolveConfig` validates numeric knobs but does NOT reject based on a pretend summary-length invariant. Convergence is dynamic: provider output caps can be spent on hidden or surfaced reasoning tokens, and the model may emit a summary of unpredictable size. `maxTokens` is only the provider-side generation cap for the summarization call; reasoning blocks are stripped before the checkpoint is stored. If a compacted surface is still over threshold, `compactIfNeeded()` re-compacts the head checkpoint up to `compactionRetries` extra times, but each committed summary must be smaller than the content it shadows. The sole residual is the single-unit-overflow case above (a backward-rounded oversized step can push the retained tail over budget) — which is exactly the out-of-scope concern, not a thrash bug.
+`resolveConfig` supplies usable common defaults: threshold ratio `0.8`, retained tail `floor(contextWindow × 0.16)`, empty summarization-model override, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`. Optional per-model threshold/retention fields merge over those defaults and must name a configured meter profile; retained tokens must be below the resulting threshold. Convergence remains dynamic because provider output caps can be spent on hidden or surfaced reasoning tokens and summary size is unpredictable. If the compacted surface remains over threshold, `compactIfNeeded()` re-compacts the head checkpoint up to the configured retry count, but each committed summary must be smaller than what it shadows.
 
 ### Surface replacement: `compact/*` events are log-only; one `user/message` carries the summary
 
@@ -103,19 +103,19 @@ Two failure paths, both documented:
 
 ## Alternatives considered
 
-- **The full algorithm as concrete interface methods** (only estimation/summarization abstract) — the earlier draft; rejected because it recouples the contract to one retention strategy. Both core methods are abstract; the `protected` estimation/summarization hooks are the backend's private factoring, not the contract's.
+- **The full algorithm as concrete interface methods** — rejected because it recouples the contract to one retention strategy. Both core methods are abstract; reusable measurement is a separate LLM-family service and `summarize()` is basic's sole hook.
 - **Compaction on the `agent/request` waterfall** — the earlier cut; rejected for the double-derive it forced and for handing the listener context it structurally cannot compact. The dedicated `agent/pre-step` seam makes the layering correct by construction.
 - **A separate `compact/error` event** — rejected: `compact/end` keeps an `error?` field, mirroring `tool/result`'s self-contained error — one event tells success from failure without correlating a sibling.
 - **Teaching core turn-repair about `compact/*`** — rejected: the log-only orphan is inert, and a core module patched for every future `xxx/start … xxx/end` plugin pair is exactly the coupling the capability-seam architecture exists to avoid.
 
 ## Consequences
 
-- **New packages**: `packages/compact/compact` (interface) and a sibling `compact-basic` (backend) under `packages/compact/`, wired into the root tsconfigs. The consumer tier is deferred.
+- **Packages**: `packages/compact/compact` supplies the interface and `compact-basic` supplies the backend. `packages/llm/token-meter` owns replay-aware measurement independently. The consumer tier is deferred.
 - **New loop seam**: `agent/pre-step` (`@mode serial`) declared in `dsh-agent` and emitted by `dsh-agent-loop` after system assembly and before `step/start`. This is a documented change to the loop — `docs/architecture.md` records it and the generated cordis catalog carries its signature.
 - **`SessionEventMap`** gains `compact/start` / `compact/summary` / `compact/end` by declaration merging (merge-extensible); `SurfaceEventType` is **not** touched. These are session events, not cordis `Events`, so the event-taxonomy gate needs no entry.
 - **`dsh-compact`** owns `toolPairingBalancedBefore(session, node)` and `toolPairingBalancedAfter(session, node)`, the cached surface-edge checks that `compactRegion` and `compactIfNeeded` use to avoid splitting a tool-call/result pair. The cache validates current membership by seq and resolves after-edges from its positional successor map instead of trusting a caller-retained `node.next`; stale or missing seqs and orphan results reject. `dsh-session` continues to own the surface `replace` operation, positional nodes, and rewrite generation.
 - **`dsh-invariants`** drops its `surface replace: start must be <= end` assertion: a head-anchored compaction lands a high-seq replacement node at an older range's *position*, so `start > end` numerically is normal and valid (the range is positional, validated by the surface's `indexOf` checks that remain). The turn-enclosure invariant is reused unchanged.
-- **Wiring**: `dsh-compact-basic` is loaded in `examples/coding-agent`'s `cordis.yml`, so the seam ships in the real demo (it was previously loaded nowhere).
+- **Wiring**: `examples/coding-agent/cordis.yml` loads zero-config `dsh-token-meter` before `dsh-compact-basic`; bundled DeepSeek profiles and compact defaults make the pair usable without repeated numeric policy.
 
 ## Testing
 

examples/coding-agent/composition.md

@@ -23,6 +23,8 @@ flowchart LR
   bundle_agent_core --> spine_sessions["ctx.sessions"]
   bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
   bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_coding_token_meter["token-meter<br/>@deepseek-ai/dsh-token-meter"]
+  cfg --> plugin_coding_token_meter
   plugin_coding_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
   cfg --> plugin_coding_compact_basic
   plugin_coding_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
@@ -55,6 +57,7 @@ flowchart LR
 | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
 | `bash` | `@deepseek-ai/dsh-bash-local` |
 | `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` |
+| `token-meter` | `@deepseek-ai/dsh-token-meter` |
 | `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
 | `subagent` | `@deepseek-ai/dsh-subagent` |
 | `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |

examples/coding-agent/cordis.yml

@@ -45,17 +45,14 @@
       Verify your work by running the code or tests. Keep answers brief and
       factual.
 
-# Summarize an older range when derived history approaches the context window.
-# This leaf consumes `ctx.llm` and the app's `agent/pre-step` seam.
+# Replay-aware request pressure for the bundled DeepSeek model profiles.
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+# Summarize an older range when measured history approaches the context window.
+# Built-in model policies provide the ordinary threshold and retained-tail defaults.
 - id: compact-basic
   name: '@deepseek-ai/dsh-compact-basic'
-  config:
-    contextWindow: 128000
-    thresholdRatio: 0.8
-    retainTokens: 20480
-    summarizationModel: ''
-    maxTokens: 8192
-    compactionRetries: 1
 
 # Expose fresh-child `spawn` and completed-prefix `fork` through independent
 # in-process backends. Each tool instance needs a distinct `toolName`; the registry

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

@@ -33,10 +33,15 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
     // Reasoning tokens require a larger generation cap than the retained checkpoint.
     ctx = await codingHarness(workdir, {
       persona: SYSTEM_PROMPT,
+      tokenMeter: {
+        models: {
+          'deepseek-v4-flash': { contextWindow: 2000 },
+        },
+      },
       compact: {
-        contextWindow: 2000,
-        thresholdRatio: 0.5,
-        retainTokens: 400,
+        models: {
+          'deepseek-v4-flash': { thresholdRatio: 0.5, retainTokens: 400 },
+        },
         summarizationModel: '',
         maxTokens: 1024,
         compactionRetries: 1,

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 ToolTodo from '@deepseek-ai/dsh-tool-todo'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import type { TokenMeterConfig } from '@deepseek-ai/dsh-token-meter'
 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'
@@ -46,6 +48,8 @@ export interface CodingHarnessOptions {
    * compaction plugin (the default suites run without it).
    */
   compact?: BasicCompactConfig
+  /** Optional meter profiles loaded before compact-basic. */
+  tokenMeter?: TokenMeterConfig
 }
 
 export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise<Context> {
@@ -60,9 +64,12 @@ export async function codingHarness(workdir: string, options: CodingHarnessOptio
   await ctx.plugin(LocalBashExecutor, { cwd: workdir, timeoutMs: 30_000 })
   await ctx.plugin(ToolBash)
   await ctx.plugin(ToolTodo)
-  // 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)
+  // Compaction is opt-in: only the compaction e2e loads the reusable meter and
+  // backend, with a lowered profile window so a short real session crosses the threshold.
+  if (options.compact !== undefined) {
+    await ctx.plugin(TokenMeterService, options.tokenMeter)
+    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.

packages/compact/README.md

@@ -5,7 +5,7 @@ A three-package capability seam (see [capability seams](../../docs/rfc/implement
 | Package | Role | ctx key |
 |---|---|---|
 | `compact/` | Abstract compaction seam (interface + `compact/*` events + `CompactionResult`) | `ctx.compact` |
-| `compact-basic/` | A backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization | (registers `ctx.compact`) |
+| `compact-basic/` | A backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization | (registers `ctx.compact`) |
 | `tool-compact/` (deferred) | Model-facing `/compact` tool over `ctx.compact` | (registers on `ctx.tools`) |
 
-The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`. Unlike the bash seam, it depends on `dsh-session` and `dsh-llm` — its verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so the contract cannot be expressed without naming them. 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). A tokenizer- or template-based backend would replace `compact-basic` without touching the interface or the tool.
+The interface lives at `compact/compact/`, the backend at `compact/compact-basic/`. Unlike the bash seam, it depends on `dsh-session` and `dsh-llm` — its verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so the contract cannot be expressed without naming them. 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). Token measurement is a reusable LLM-family service rather than a `CompactService` method; a template- or model-backed compactor can replace `compact-basic` without changing the meter or callers.

packages/compact/compact-basic/README.md

@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-compact-basic
 
-The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with a chars-per-token heuristic (the `charsPerToken` config, default 4), token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call (interceptable at `llm/stream`).
+The **basic compaction backend**: a `BasicCompactService` implementing the `@deepseek-ai/dsh-compact` seam with reusable `ctx.tokenMeter` pressure, token-budget retention, and summarization as a direct one-shot `ctx.llm.stream()` call (interceptable at `llm/stream`).
 
 This is the implementation tier of the compaction capability — see the [interface package](../compact/README.md) for the seam and the [capability-seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md) for the design.
 
@@ -8,7 +8,7 @@ This is the implementation tier of the compaction capability — see the [interf
 
 This backend owns the compaction policy:
 
-- **Estimation** — a configurable characters-per-token heuristic counts the current session prefix supplied to pre-step, derived history, and system prompt, matching the next request rather than stale logged prefix state.
+- **Measurement** — the effective conversation model's `ModelTokenMeter` prices the provisional request envelope and current surface at one consumed-log revision. The current prompt and prefix override their logged values; the pre-step boundary reuses logged tools and call config.
 - **Retention** — compact the oldest whole surface units while preserving a recent tail and balanced tool-call/result cuts through the [`dsh-compact` boundary helpers](../compact/README.md#tool-pairing-boundaries). Turn boundaries do not protect old steps inside a runaway turn. An open indivisible tail declines until it closes; a single unit larger than the budget remains out of scope.
 - **Convergence** — retry head-checkpoint compaction up to `compactionRetries`; reject a summary that does not shrink its source, and throw if retries cannot return below threshold.
 - **Summarization** — a direct `llm/stream` call uses the configured model and cap without running the loop-only `agent/request` seam. The input transcript preserves non-text blocks as tagged placeholders; only returned text enters the checkpoint, excluding reasoning and tool calls that would leak private reasoning or create an orphaned call.
@@ -16,41 +16,34 @@ This backend owns the compaction policy:
 - **Lifecycle** — `compactRegion()` records its start, summary, replacement, and end. The serial `agent/pre-step` listener checks pressure before every step, outside an open step, so a tool-heavy turn remains compactable and the loop derives history once after mutation.
 - **Failure handling** — an unmatched `compact/start` is an inert crash marker because no replacement landed. Recoverable failure records an error end and leaves the surface unchanged.
 
-`estimateContentTokens()` and `summarize()` are overridable hooks: a tokenizer-based or template-based backend can subclass `BasicCompactService` and override just those, reusing the retention walk and surface plumbing. `summarize()` returns the summary blocks together with the call envelope it actually used (`{ summary, model, maxTokens? }`) — the caller logs that envelope on the `compact/summary` provenance event, so an overriding backend reports its own envelope honestly.
+`summarize()` is the sole subclass hook. A template- or remote-summarizer subclass can override it while pressure, retention, provenance, shrink validation, and shadowed-token accounting stay on the conversation model's meter. The hook returns the summary blocks together with the call envelope it used (`{ summary, model, maxTokens? }`), which is logged on `compact/summary`.
 
 ## Config (`BasicCompactConfig`)
 
-Every knob is **required** except `auto` — there is no concrete data yet to justify default thresholds/budgets, so a consumer states each value explicitly rather than inherit a guessed default. `auto` alone defaults to `true`.
+Every common setting is optional. Every model known to `ctx.tokenMeter` receives the default compact policy lazily; named overrides merge only the fields supplied and must name a configured meter profile.
 
 | Key | Required | Meaning |
 |---|---|---|
-| `contextWindow` | yes | Context window size in tokens. |
-| `thresholdRatio` | yes | Compact when estimated usage exceeds this fraction of the window. |
-| `retainTokens` | yes | Tokens of recent context to keep intact. |
-| `summarizationModel` | yes | Model for summarization (`''` → use the agent's model). |
-| `maxTokens` | yes | Provider generation cap for the summarization call; may include reasoning tokens. |
-| `compactionRetries` | yes | Extra compaction attempts after the first if the compacted surface remains over threshold. |
-| `auto` | no (default `true`) | Register the `agent/pre-step` auto-compaction listener. Set `false` for manual-only. |
-| `charsPerToken` | no (default `4`) | Token-estimator text density (estimated tokens = chars / `charsPerToken`; may be fractional). The default suits English text; CJK-heavy deployments should set ~1-2 or the estimate undershoots several-fold and compaction fires too late. |
+| `models.<model>.thresholdRatio` | no (default `0.8`) | Compact at `floor(contextWindow × ratio)`. |
+| `models.<model>.retainTokens` | no (default `floor(contextWindow × 0.16)`) | Recent surface budget kept verbatim; must be below the threshold. |
+| `summarizationModel` | no (default `''`) | Empty resolves the latest logged routed model, then `AgentOptions.model`. |
+| `maxTokens` | no (default `8192`) | Provider generation cap for the summarization call; may include reasoning tokens. |
+| `compactionRetries` | no (default `1`) | Extra attempts after the first when pressure remains above threshold. |
+| `auto` | no (default `true`) | Register the `agent/pre-step` automatic listener. Set `false` for manual-only. |
 
 ## Usage
 
 ```ts
 import type { Context } from 'cordis'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 
 export const name = 'compact-basic'
 export const inject = ['llm']
 
 export function apply(ctx: Context): void {
-  ctx.plugin(BasicCompactService, {
-    contextWindow: 128000,
-    thresholdRatio: 0.8,
-    retainTokens: 20480,
-    summarizationModel: '',
-    maxTokens: 8192,
-    compactionRetries: 1,
-  })
+  ctx.plugin(TokenMeterService)
+  ctx.plugin(BasicCompactService)
 }
 ```
 
@@ -122,8 +115,8 @@ Rules:
 
 ## Known Limitations and Deferred Work
 
-- **Token estimation is the chars/`charsPerToken` heuristic** — a marked TODO schedules replacing it with an exact count (a real tokenizer, or provider `usage` fed back) so thresholds track the model's actual budget.
-- **`estimatePressure()` does not count the request's `tools` field** — pressure is underestimated by the size of the serialized tool schemas the request also carries.
+- **Pre-step sees a provisional request envelope** — the current prompt and prefix are exact, but routing and tool changes made later in `agent/request` are not logged yet. A router-only agent with no provisional model skips that check.
+- **Meter accuracy follows the selected profile** — missing provider usage falls back to the token meter's configured character density and structural overhead.
 - **`compactRegion` requires an open turn** — a manual call on a fully-closed session throws ("no open turn") rather than compacting.
 - **Summarization failure fails closed with full, over-budget history** — including truncation at the summarization `maxTokens`, which hidden reasoning tokens can consume; the auto path logs a warning and proceeds.
 - **The summarization call has no transcript-snapshot coverage** — `dsh-llm-replay` derives calls from `assistant/chunk` events, so this chunk-less direct `ctx.llm.stream()` call cannot replay (named deferred replay infrastructure in [the seam RFC](../../../docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md)).

packages/compact/compact-basic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-compact-basic",
-  "description": "Basic compaction backend (chars-per-token estimation + token-budget retention + llm.generate() summarization) for the DeepSeek Harness",
+  "description": "Token-meter-driven compaction policy and LLM summarization backend for the DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -26,9 +26,15 @@
     "@deepseek-ai/dsh-compact": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-token-meter": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
   "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-compact": "workspace:^",
@@ -36,6 +42,7 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-tools": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/compact/compact-basic/src/automatic.ts

@@ -0,0 +1,60 @@
+/**
+ * Automatic pre-step pressure listener for compact-basic.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/automatic
+ */
+
+import type { Context } from 'cordis'
+import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { Message } from '@deepseek-ai/dsh-llm'
+import {
+  TOKEN_METER_MODEL_UNCONFIGURED,
+  TokenMeterError,
+} from '@deepseek-ai/dsh-token-meter'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+
+interface AutomaticCompactor {
+  compactIfNeeded(
+    agent: Agent,
+    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
+    signal: AbortSignal,
+  ): Promise<CompactionResult | null>
+}
+
+/**
+ * Register the implementation-owned automatic compaction listener.
+ * @param ctx - context owning the listener effect and logger.
+ * @param service - compactor whose public methods remain dynamically dispatched.
+ */
+export function registerAutomaticCompaction(
+  ctx: Context,
+  service: AutomaticCompactor,
+): void {
+  ctx.on('agent/pre-step', async (
+    agent: Agent,
+    _turn: number,
+    _step: number,
+    fullSystemPrompt: string,
+    sessionPrefix: readonly Message[],
+    signal: AbortSignal,
+  ) => {
+    try {
+      const result = await service.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
+      if (result !== null) {
+        ctx.logger.info(
+          `compaction: shadowed ${result.shadowedSeqs.length} surface nodes `
+          + `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, `
+          + `~${result.shadowedTokenCount} tokens)`,
+        )
+      }
+    } catch (error: unknown) {
+      // A named routed model without a meter profile is configuration failure,
+      // not an optional operational compaction miss.
+      if (error instanceof TokenMeterError
+        && error.code === TOKEN_METER_MODEL_UNCONFIGURED) throw error
+      const message = error instanceof Error ? error.message : String(error)
+      ctx.logger.warn(`compaction failed: ${message}; proceeding with full history`)
+    }
+  })
+}

packages/compact/compact-basic/src/config.ts

@@ -0,0 +1,117 @@
+/**
+ * Runtime defaulting and per-model policy validation for compact-basic.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/config
+ */
+
+import { deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { ModelTokenMeter, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
+import type {
+  BasicCompactConfig,
+  ModelCompactConfig,
+  ResolvedConfig,
+  ResolvedModelCompactConfig,
+} from './types.ts'
+
+/** Default request-pressure fraction for every metered model. */
+const DEFAULT_THRESHOLD_RATIO = 0.8
+
+/** Default verbatim-tail fraction of a model's context window. */
+const DEFAULT_RETAIN_RATIO = 0.16
+
+/**
+ * Resolve common defaults and validate every named model override.
+ * @param config - raw compact-basic configuration.
+ * @param tokenMeter - owning meter service used to reject unknown override names.
+ * @returns a detached deeply immutable top-level configuration.
+ */
+export function resolveConfig(
+  config: BasicCompactConfig = {},
+  tokenMeter: TokenMeterService,
+): ResolvedConfig {
+  const configuredModels: unknown = config.models
+  const models = configuredModels === undefined ? {} : configuredModels
+  if (typeof models !== 'object' || models === null || Array.isArray(models)) {
+    throw new Error('BasicCompactConfig: models must be an object')
+  }
+
+  const detachedModels: Record<string, ModelCompactConfig> = {}
+  for (const [model, override] of Object.entries(models as Record<string, unknown>)) {
+    if (typeof override !== 'object' || override === null || Array.isArray(override)) {
+      throw new Error(`BasicCompactConfig: models.${model} must be an object`)
+    }
+    const meter = tokenMeter.resolve(model)
+    detachedModels[model] = { ...override as ModelCompactConfig }
+    resolveModelConfig({
+      models: detachedModels,
+      summarizationModel: '',
+      maxTokens: 8192,
+      compactionRetries: 1,
+      auto: true,
+    }, meter)
+  }
+
+  const resolved: ResolvedConfig = {
+    models: detachedModels,
+    summarizationModel: config.summarizationModel ?? '',
+    maxTokens: config.maxTokens ?? 8192,
+    compactionRetries: config.compactionRetries ?? 1,
+    auto: config.auto ?? true,
+  }
+  assertPositiveInteger('maxTokens', resolved.maxTokens)
+  assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
+  if (typeof resolved.summarizationModel !== 'string') {
+    throw new Error('BasicCompactConfig: summarizationModel must be a string')
+  }
+  if (typeof resolved.auto !== 'boolean') {
+    throw new Error('BasicCompactConfig: auto must be a boolean')
+  }
+  return deepFreeze(structuredClone(resolved))
+}
+
+/**
+ * Resolve one effective model's default policy plus optional field overrides.
+ * @param config - validated compact-basic configuration.
+ * @param meter - effective model's token-meter handle and context capacity.
+ * @returns a detached immutable model policy.
+ */
+export function resolveModelConfig(
+  config: ResolvedConfig,
+  meter: ModelTokenMeter,
+): ResolvedModelCompactConfig {
+  const override = config.models[meter.model]
+  const thresholdRatio = override?.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO
+  const retainTokens = override?.retainTokens ?? Math.floor(meter.contextWindow * DEFAULT_RETAIN_RATIO)
+  assertRatio(`models.${meter.model}.thresholdRatio`, thresholdRatio)
+  assertNonNegativeInteger(`models.${meter.model}.retainTokens`, retainTokens)
+  const thresholdTokens = Math.floor(meter.contextWindow * thresholdRatio)
+  if (retainTokens >= thresholdTokens) {
+    throw new Error(
+      `BasicCompactConfig: models.${meter.model}.retainTokens (${retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
+    )
+  }
+  return deepFreeze({
+    model: meter.model,
+    contextWindow: meter.contextWindow,
+    thresholdRatio,
+    retainTokens,
+  })
+}
+
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive integer`)
+  }
+}
+
+function assertNonNegativeInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a non-negative integer`)
+  }
+}
+
+function assertRatio(name: string, value: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a number in (0, 1]`)
+  }
+}

packages/compact/compact-basic/src/index.ts

@@ -1,286 +1,120 @@
 /**
- * Basic compaction backend. It estimates request pressure, retains a recent
- * tool-balanced surface tail, summarizes the older head through a one-shot model
- * call, and replaces that head with one checkpoint. Auto-compaction runs before
- * every step so a growing turn can compact its earlier closed steps.
+ * Basic replay-aware compaction backend.
+ *
  * @module @deepseek-ai/dsh-compact-basic
  */
 
 import { Context } from 'cordis'
-import { CompactService, renderTranscript, toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
+import z from 'schemastery'
+import { CompactService } from '@deepseek-ai/dsh-compact'
 import type { CompactionResult } from '@deepseek-ai/dsh-compact'
-import { BlockAssembler } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
-import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
+import type { ContentBlock, Message } from '@deepseek-ai/dsh-llm'
+import type { ModelTokenMeter } from '@deepseek-ai/dsh-token-meter'
 import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { BasicCompactConfig, ResolvedConfig } from './types.ts'
-import { resolveConfig } from './types.ts'
+import { registerAutomaticCompaction } from './automatic.ts'
+import { resolveConfig, resolveModelConfig } from './config.ts'
+import { compactSurfaceRegion, selectCompactableRange } from './region.ts'
+import { summarizeWithLlm } from './summarizer.ts'
+import type {
+  BasicCompactConfig,
+  ResolvedConfig,
+  ResolvedModelCompactConfig,
+} from './types.ts'
 
-export type { BasicCompactConfig, ResolvedConfig } from './types.ts'
-export { resolveConfig } from './types.ts'
+export { resolveConfig, resolveModelConfig } from './config.ts'
+export type {
+  BasicCompactConfig,
+  ModelCompactConfig,
+  ResolvedConfig,
+  ResolvedModelCompactConfig,
+} from './types.ts'
 
-/** Per-block structural overhead for JSON framing / type tag. */
-const BLOCK_OVERHEAD = 4
-
-/** Role-field framing overhead added per message in {@link BasicCompactService.estimateTokens}. */
-const ROLE_OVERHEAD = 4
-
-/** Tags wrapping the structured summary inside the landed checkpoint node. */
-const SUMMARY_OPEN_TAG = '<compacted-summary>'
-const SUMMARY_CLOSE_TAG = '</compacted-summary>'
-
-/**
- * Fixed summary structure for resumable checkpoints. A tagged prior checkpoint
- * is merged with newer history instead of copied forward verbatim.
- */
-const SUMMARIZE_SYSTEM_PROMPT = [
-  'You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.',
-  '',
-  'Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section.',
-  '',
-  '## Primary Request and Intent',
-  "- [the user's original and evolving goals; quote verbatim where the exact wording matters]",
-  '',
-  '## Key Technical Concepts',
-  '- [technologies, frameworks, patterns, and conventions in play]',
-  '',
-  '## Files and Code',
-  '- [exact path: why it matters, key changes or snippets]',
-  '',
-  '## Errors and Fixes',
-  '- [error: how it was resolved, plus any related user feedback]',
-  '',
-  '## Pending Tasks',
-  '- [explicitly requested work not yet completed]',
-  '',
-  '## Current Work',
-  '- [precisely what was in progress at this checkpoint]',
-  '',
-  '## Next Step',
-  '- [the single next action, directly in line with the most recent request, or "(none)"]',
-  '',
-  '## Critical Context',
-  '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
-  '',
-  'Rules:',
-  '- Preserve exact file paths, commands, error strings, identifiers, and function signatures.',
-  '- Capture user feedback and explicit instructions faithfully, especially corrections.',
-  '- Do NOT mention this summarization process or that the context was compacted.',
-  `- If the transcript already contains a ${SUMMARY_OPEN_TAG} block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.`,
-].join('\n')
-
-/** Framing that makes a landed summary established context rather than a new request. */
-const CHECKPOINT_PREAMBLE =
-  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.'
-
-/**
- * Map a terminal summary failure to an error. A max-token finish is rejected
- * because committing an incomplete checkpoint would shadow the full history.
- */
-function finishError(finish: FinishReason): Error | undefined {
-  switch (finish.kind) {
-    case 'error': {
-      const error = new Error(finish.message) as Error & { code?: string }
-      if (finish.code !== undefined) error.code = finish.code
-      return error
-    }
-    case 'aborted': {
-      const error = new Error('summarization stream aborted') as Error & { code?: string }
-      error.code = 'ABORTED'
-      return error
-    }
-    case 'max-tokens': {
-      const error = new Error('summarization truncated at the token cap (incomplete checkpoint)') as Error & { code?: string }
-      error.code = 'MAX_TOKENS'
-      return error
-    }
-    default:
-      return undefined
-  }
+/** Resolve the latest actual routed model, then the agent's configured fallback. */
+function effectiveModel(agent: Agent): string | undefined {
+  return agent.session.requestHeader()?.config.model ?? agent.options.model
 }
 
 /**
- * Basic, dependency-light compaction backend: estimates the surface's token
- * footprint, summarizes the stale prefix through the model, and shadows it
- * behind a durable checkpoint. Every threshold/budget knob is required config
- * ({@link BasicCompactConfig}); the estimator's text density is the
- * `charsPerToken` knob.
+ * Build the provisional pre-step request envelope. Prompt and prefix are exact;
+ * tools and non-model call config come from the latest logged request because
+ * later request middleware has not run yet.
+ */
+function provisionalHeader(
+  model: string,
+  session: Session,
+  fullSystemPrompt: string,
+  sessionPrefix: readonly Message[],
+): EpochHeader {
+  const latest = session.requestHeader()
+  return canonicalHeader({
+    config: latest === undefined ? { model } : { ...latest.config, model },
+    ...fullSystemPrompt.length === 0 ? {} : { system: fullSystemPrompt },
+    ...latest?.tools === undefined ? {} : { tools: latest.tools },
+    ...sessionPrefix.length === 0 ? {} : { messagePrefix: [...sessionPrefix] },
+  })
+}
+
+/**
+ * Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
+ * retention, provenance, and summary-convergence pricing.
+ *
+ * `summarize()` is the sole subclass customization hook; the replay and durable
+ * mutation strategy stays fixed so every pricing decision uses one effective
+ * conversation-model meter.
  */
 export class BasicCompactService extends CompactService {
-  static inject = ['llm']
+  static inject = ['llm', 'tokenMeter']
 
-  /** Resolved configuration (`auto` defaulted). */
+  static Config: z<BasicCompactConfig> = z.object({
+    models: z.dict(z.object({
+      thresholdRatio: z.number(),
+      retainTokens: z.number().step(1),
+    })),
+    summarizationModel: z.string().default(''),
+    maxTokens: z.number().step(1).min(1).default(8192),
+    compactionRetries: z.number().step(1).min(0).default(1),
+    auto: z.boolean().default(true),
+  })
+
+  /** Resolved and validated common configuration plus named partial overrides. */
   readonly config: ResolvedConfig
 
-  constructor(ctx: Context, config: BasicCompactConfig) {
+  private readonly modelConfigs = new Map<string, ResolvedModelCompactConfig>()
+
+  constructor(ctx: Context, config: BasicCompactConfig = {}) {
     super(ctx)
-    this.config = resolveConfig(config)
-
-    if (this.config.auto) {
-      // Check before every step so a single growing turn can compact earlier closed steps.
-      // This serial pre-step seam mutates the surface outside the pending step.
-      ctx.on('agent/pre-step', async (agent: Agent, _turn: number, _step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal) => {
-        try {
-          const result = await this.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
-          if (result) {
-            const after = this.estimatePressure(agent.session, fullSystemPrompt, sessionPrefix)
-            ctx.logger.info(
-              `compaction: shadowed ${result.shadowedSeqs.length} surface nodes ` +
-              `(seqs ${result.shadowedRange.start}-${result.shadowedRange.end}, ` +
-              `~${result.shadowedTokenCount} tokens) ` +
-              `→ ${after} estimated tokens after compaction`,
-            )
-          }
-        } catch (error: unknown) {
-          // A failed compaction must not prevent the model call — the surface is
-          // untouched on failure, so the loop derives the full history and the
-          // call proceeds.
-          const msg = error instanceof Error ? error.message : String(error)
-          ctx.logger.warn(`compaction failed: ${msg}; proceeding with full history`)
-        }
-      })
-    }
-  }
-
-  // ---- Token estimation (overridable hooks) ----
-
-  // TODO: chars/charsPerToken is a coarse heuristic. Replace with an exact
-  // count — a real tokenizer, or the provider's post-response `usage` (input
-  // tokens) fed back as a correction — so threshold decisions match the
-  // model's actual budget.
-  /**
-   * Estimate the token count of content blocks — chars divided by the
-   * `charsPerToken` config, with per-block overhead. Override in a subclass to
-   * plug in a real tokenizer.
-   *
-   * @param blocks - the blocks to estimate; `tool-result` blocks recurse into
-   *   their nested content, and unknown (merge-extended) types fall back to
-   *   their JSON-stringified length.
-   * @returns the estimated token count.
-   */
-  estimateContentTokens(blocks: readonly ContentBlock[]): number {
-    const { charsPerToken } = this.config
-    let tokens = 0
-    for (const block of blocks) {
-      switch (block.type) {
-        case 'text':
-        case 'reasoning':
-          tokens += Math.ceil(block.text.length / charsPerToken) + BLOCK_OVERHEAD
-          break
-        case 'tool-call':
-          tokens += Math.ceil(block.name.length / charsPerToken)
-            + Math.ceil(block.arguments.length / charsPerToken)
-            + BLOCK_OVERHEAD
-          break
-        case 'tool-result':
-          tokens += this.estimateContentTokens(block.content) + BLOCK_OVERHEAD
-          break
-        default:
-          // Unknown block types (merge-extensible ContentBlockMap):
-          // estimate conservatively via JSON stringify.
-          tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / charsPerToken)
-      }
-    }
-    return tokens
+    this.config = resolveConfig(config, ctx.tokenMeter)
+    if (this.config.auto) registerAutomaticCompaction(ctx, this)
   }
 
   /**
-   * Estimate token count for a single session event. Returns 0 for non-message
-   * event types (boundaries, chunks, usage, errors, compact markers).
-   *
-   * @param event - any session event; only the message-bearing types carry
-   *   content to count.
-   * @returns the estimated token count of the event's content, or 0 for a
-   *   non-message event.
-   */
-  estimateEventTokens(event: SessionEvent): number {
-    switch (event.type) {
-      case 'user/message':
-      case 'assistant/message':
-      case 'context/message':
-      case 'steering/message':
-      case 'tool/result':
-        return this.estimateContentTokens(event.data.content)
-      default:
-        return 0
-    }
-  }
-
-  /**
-   * Estimate total tokens across a list of messages plus optional system prompt.
-   *
-   * @param messages - the derived conversation messages; each adds a fixed
-   *   role-framing overhead on top of its content estimate.
-   * @param systemPrompt - counted at chars / `charsPerToken` when provided.
-   * @returns the estimated token footprint of the whole request.
-   */
-  estimateTokens(messages: readonly Message[], systemPrompt?: string): number {
-    let total = 0
-    for (const msg of messages) {
-      total += this.estimateContentTokens(msg.content)
-      total += ROLE_OVERHEAD
-    }
-    if (systemPrompt) total += Math.ceil(systemPrompt.length / this.config.charsPerToken)
-    return total
-  }
-
-  /**
-   * Summarize through a direct one-shot `ctx.llm.stream()` call, not an agent
-   * step or `agent/request` dispatch. Failure finishes and truncated summaries
-   * reject; the signal is forwarded and only text reaches the checkpoint.
-   *
-   * @param text - plain-text rendering of the conversation region to condense.
-   * @param agent - supplies the fallback model and the session id stamped on
-   *   the call; throws when neither it nor the config names a model.
-   * @param signal - optional abort signal, forwarded into the model call.
-   * @returns the text-only summary blocks plus the call envelope used
-   *   (`model`, and `maxTokens` when the summarizer has a cap).
+   * Summarize a rendered region through a direct one-shot `ctx.llm.stream()`
+   * call. Override this sole hook for a template or remote summarizer.
+   * @param text - plain-text conversation region to condense.
+   * @param agent - supplies routed-model history, fallback model, and session id.
+   * @param signal - optional cancellation forwarded to the adapter.
+   * @returns safe text summary blocks and exact auxiliary-call provenance.
    */
   async summarize(
-    text: string, agent: Agent, signal?: AbortSignal,
+    text: string,
+    agent: Agent,
+    signal?: AbortSignal,
   ): Promise<{ summary: ContentBlock[]; model: string; maxTokens?: number }> {
-    const assembler = new BlockAssembler()
-    const options: GenerateOptions = {
-      model: this.config.summarizationModel || agent.options.model || '',
-      messages: [{
-        role: 'user',
-        content: [{ type: 'text', text: `Summarize this conversation history:\n\n${text}\n\nSummary:` }],
-      }],
-      system: SUMMARIZE_SYSTEM_PROMPT,
-      maxTokens: this.config.maxTokens,
-      sessionId: agent.session.id,
-    }
-    // exactOptionalPropertyTypes: only set `signal` when present — assigning
-    // `undefined` to an optional `signal?: AbortSignal` is a type error.
-    if (signal) options.signal = signal
-    if (!options.model) {
-      throw new Error('no model available for summarization: set BasicCompactConfig.summarizationModel or AgentOptions.model')
-    }
-    for await (const chunk of this.ctx.llm.stream(options)) {
-      assembler.push(chunk)
-    }
-
-    const error = finishError(assembler.finish)
-    if (error) throw error
-
-    const summary = this._textOnly(assembler.message().content)
-    if (!summary.some(block => block.type === 'text' && block.text.trim().length > 0)) {
-      throw new Error('summarization produced no text summary content')
-    }
-
-    // config.maxTokens is required and validated positive, so this backend's
-    // envelope always carries the cap; the return type's optionality exists
-    // for overriding subclasses whose summarizer has none.
-    return { summary, model: options.model, maxTokens: this.config.maxTokens }
+    return summarizeWithLlm(this.ctx, this.config, text, agent, signal)
   }
 
-  // ---- Core API (implements the abstract contract) ----
-
   /**
-   * The sole pressure gate: count the next request's prefix, derived history,
-   * and system prompt. Above threshold, retain a recent tool-balanced tail and
-   * compact the head, reconsolidating any prior automatic checkpoint. Returns
-   * `null` when no safe or necessary range exists.
+   * Check replayed pressure for the provisional pre-step envelope and compact
+   * a tool-balanced head until it falls below the effective model threshold.
+   * A genuinely model-less router-first step skips this provisional check;
+   * naming an unconfigured model throws the token meter's typed error.
+   * @param agent - agent whose session and provisional model are measured.
+   * @param fullSystemPrompt - current assembled system prompt override.
+   * @param sessionPrefix - current request-only prefix override.
+   * @param signal - live step cancellation signal forwarded to summarization.
+   * @returns the latest compaction result, or `null` when no check/work applies.
    */
   override async compactIfNeeded(
     agent: Agent,
@@ -288,47 +122,51 @@ export class BasicCompactService extends CompactService {
     sessionPrefix: readonly Message[],
     signal: AbortSignal,
   ): Promise<CompactionResult | null> {
-    const session = agent.session
-    const threshold = Math.floor(this.config.contextWindow * this.config.thresholdRatio)
-    let result: CompactionResult | null = null
-    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt++) {
-      const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
-      if (totalTokens < threshold) return result
+    const model = effectiveModel(agent)
+    if (model === undefined || model.length === 0) return null
+    const meter = this.ctx.tokenMeter.resolve(model)
+    const policy = this._modelConfig(meter)
+    const requestHeader = provisionalHeader(model, agent.session, fullSystemPrompt, sessionPrefix)
+    const threshold = Math.floor(policy.contextWindow * policy.thresholdRatio)
+    let measurement = meter.measure(agent.session, requestHeader)
+    if (measurement.totalTokens < threshold) return null
 
-      const range = this._compactableRange(session)
+    let result: CompactionResult | null = null
+    for (let attempt = 0; attempt <= this.config.compactionRetries; attempt += 1) {
+      const surface = meter.measureSurface(agent.session)
+      if (surface.logRevision !== measurement.logRevision) {
+        throw new Error(
+          `compaction: pressure revision ${measurement.logRevision} does not match surface revision ${surface.logRevision}`,
+        )
+      }
+      const range = selectCompactableRange(agent.session, surface, policy.retainTokens)
       if (range === null) {
-        /* v8 ignore else -- defensive for non-standard subclass mutations; the concrete replace keeps a compactable head checkpoint. */
+        /* v8 ignore else -- concrete replacement preserves a compactable checkpoint; subclass hooks cannot mutate it. */
         if (result === null) return null
-        /* v8 ignore next -- paired with the ignored defensive branch above. */
+        /* v8 ignore next -- paired with the defensive post-success branch above. */
         break
       }
-
-      result = await this.compactRegion(session, range.start, range.end, agent, signal)
+      result = await this.compactRegion(agent.session, range.start, range.end, agent, signal)
+      measurement = meter.measure(agent.session, requestHeader)
+      if (measurement.totalTokens < threshold) return result
     }
 
-    const totalTokens = this.estimatePressure(session, fullSystemPrompt, sessionPrefix)
-    if (totalTokens < threshold) return result
-
     throw new Error(
       `compaction still above threshold after ${this.config.compactionRetries + 1} compaction attempts `
-      + `(${totalTokens} estimated tokens >= threshold ${threshold})`,
+      + `(${measurement.totalTokens} estimated tokens >= threshold ${threshold})`,
     )
   }
 
   /**
-   * Estimated token pressure of the NEXT request: the session prefix
-   * (`EpochHeader.messagePrefix` — request-only messages the loop sends in
-   * front of the derived history, composed before the pre-step seam and
-   * handed to the gate), the derived history, and the system prompt.
-   * @param session - the session whose next request is being estimated.
-   * @param fullSystemPrompt - the assembled system prompt (counts toward pressure).
-   * @param sessionPrefix - the instance's composed session prefix (counts toward pressure).
-   * @returns the estimated token total the next request will carry.
+   * Compact one inclusive positional surface range using the effective
+   * conversation model for all retention and shrink pricing.
+   * @param session - session whose surface is mutated.
+   * @param start - inclusive first surface-node seq.
+   * @param end - inclusive last surface-node seq.
+   * @param agent - agent used by the summarizer and model resolver.
+   * @param signal - optional summarization cancellation signal.
+   * @returns the successful durable compaction result.
    */
-  estimatePressure(session: Session, fullSystemPrompt: string, sessionPrefix: readonly Message[]): number {
-    return this.estimateTokens([...sessionPrefix, ...session.deriveMessages()], fullSystemPrompt)
-  }
-
   override async compactRegion(
     session: Session,
     start: number,
@@ -336,214 +174,26 @@ export class BasicCompactService extends CompactService {
     agent: Agent,
     signal?: AbortSignal,
   ): Promise<CompactionResult> {
-    // Resolve by surface position: a newer replacement seq may occupy an older slot.
-    const nodes = session.surface.nodes
-    const startIdx = nodes.findIndex(n => n.seq === start)
-    const endIdx = nodes.findIndex(n => n.seq === end)
-    if (startIdx === -1) throw new Error(`compactRegion: start seq ${start} not found in surface`)
-    if (endIdx === -1) throw new Error(`compactRegion: end seq ${end} not found in surface`)
-    if (startIdx > endIdx) {
-      throw new Error(`compactRegion: start seq ${start} (position ${startIdx}) is after end seq ${end} (position ${endIdx}) on the surface`)
-    }
-
-    // Both range edges must preserve assistant tool-call/result pairing.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const startNode = nodes[startIdx]!
-    if (!toolPairingBalancedBefore(session, startNode)) {
-      throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`)
-    }
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const endNode = nodes[endIdx]!
-    if (!toolPairingBalancedAfter(session, endNode)) {
-      throw new Error(`compactRegion: end seq ${end} is not a balanced boundary (would split a step, or the step is still open)`)
-    }
-
-    if (this._isCompactionInProgress(session)) {
-      throw new Error('compaction already in progress')
-    }
-
-    // Compaction's events (compact/* and the replacement user/message) must be turn-enclosed:
-    // the session-log contract rejects any plugin event appended outside an open turn.
-    const openTurn = this._openTurn(session)
-    if (openTurn === null) {
-      throw new Error('compactRegion: no open turn — compaction events must be enclosed in a turn')
-    }
-    // Slice the ordered surface nodes [startIdx, endIdx] inclusive — the
-    // shadowed range is positional, so this is the set the replace op covers.
-    const shadowedSeqs = nodes.slice(startIdx, endIdx + 1).map(n => n.seq)
-
-    // --- Acquire lock ---
-    const startEvent = session.append('compact/start', { turn: openTurn })
-
-    try {
-      // --- Extract text and summarize ---
-      const text = renderTranscript(session.events, shadowedSeqs)
-      const { summary, model, maxTokens } = await this.summarize(text, agent, signal)
-
-      // Estimate token count of the shadowed content for provenance.
-      let shadowedTokenCount = 0
-      for (const seq of shadowedSeqs) {
-        // seq comes from a surface node — always a valid log index by construction.
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-        shadowedTokenCount += this.estimateEventTokens(session.events[seq]!)
-      }
-      const framedSummary = this._frameSummary(summary)
-      const framedSummaryTokenCount = this.estimateContentTokens(framedSummary)
-      if (framedSummaryTokenCount >= shadowedTokenCount) {
-        throw new Error(
-          `summary is not smaller than the shadowed content (${framedSummaryTokenCount} estimated framed tokens >= ${shadowedTokenCount})`,
-        )
-      }
-      // --- Provenance record (log-only) ---
-      const summaryEvent = session.append('compact/summary', {
-        summary,
-        shadowedRange: { start, end },
-        shadowedSeqs,
-        shadowedTokenCount,
-        model,
-        ...maxTokens !== undefined ? { maxTokens } : {},
-      })
-
-      // --- Surface replacement --- The user/message directly shadows all compacted surface
-      // nodes with a single replace op.
-      session.append('user/message', {
-        content: framedSummary,
-        source: { kind: 'plugin', plugin: 'compact' },
-      }, {
-        surfaceOp: { op: 'replace', start, end },
-        sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
-      })
-
-      // --- Release lock (log-only) ---
-      // Appended LAST so the lock brackets the WHOLE operation: a crash between
-      // compact/start and here leaves a detectable orphaned lock (a compact/start
-      // with no matching compact/end) rather than a compact/end that falsely
-      // claims compaction finished before the surface replacement landed.
-      const endEvent = session.append('compact/end', { turn: openTurn })
-
-      return {
-        startSeq: startEvent.seq,
-        summarySeq: summaryEvent.seq,
-        endSeq: endEvent.seq,
-        summary,
-        shadowedRange: { start, end },
-        shadowedSeqs,
-        shadowedTokenCount,
-      }
-    } catch (error: unknown) {
-      // Always release the lock — append compact/end with the error so a
-      // wedged lock is impossible.
-      const msg = error instanceof Error ? error.message : String(error)
-      session.append('compact/end', { turn: openTurn, error: msg })
-      throw error
+    const model = effectiveModel(agent)
+    if (model === undefined || model.length === 0) {
+      throw new Error('compactRegion: no routed or configured conversation model is available for token pricing')
     }
+    const meter = this.ctx.tokenMeter.resolve(model)
+    this._modelConfig(meter)
+    return compactSurfaceRegion({
+      meter,
+      summarize: (text, owner, abort) => this.summarize(text, owner, abort),
+    }, session, start, end, agent, signal)
   }
 
-  // ---- Internal helpers ----
-
-  /**
-   * Frame the raw summary blocks into the content that lands on the surface:
-   * a checkpoint preamble (so a resuming model reads it as a checkpoint, not a
-   * fresh user request) followed by the summary wrapped in
-   * {@link SUMMARY_OPEN_TAG}/{@link SUMMARY_CLOSE_TAG}. The tags make a prior
-   * checkpoint detectable in the transcript on the next compaction cycle, which
-   * triggers the merge rule in the summarization prompt. The raw, unframed
-   * `summary` is preserved separately on the `compact/summary` provenance event.
-   */
-  private _frameSummary(summary: readonly ContentBlock[]): ContentBlock[] {
-    return [
-      { type: 'text', text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
-      ...summary,
-      { type: 'text', text: SUMMARY_CLOSE_TAG },
-    ]
-  }
-
-  /**
-   * Whether a compaction is currently in progress for `session` — an unmatched `compact/start`
-   * (no later `compact/end`) WITHIN the current turn.
-   */
-  private _isCompactionInProgress(session: Session): boolean {
-    const events = session.events
-    for (let i = events.length - 1; i >= 0; i--) {
-      // Index bounded by i >= 0 and i < events.length — never undefined.
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const e = events[i]!
-      if (e.type === 'compact/start') return true
-      if (e.type === 'compact/end') break
-      // A turn/end bounds the scan: anything before it belongs to a prior
-      // (closed) turn and cannot be an in-progress compaction of THIS turn.
-      if (e.type === 'turn/end') break
+  /** Resolve and memoize one lazy default/override model policy. */
+  private _modelConfig(meter: ModelTokenMeter): ResolvedModelCompactConfig {
+    let modelConfig = this.modelConfigs.get(meter.model)
+    if (modelConfig === undefined) {
+      modelConfig = resolveModelConfig(this.config, meter)
+      this.modelConfigs.set(meter.model, modelConfig)
     }
-    return false
-  }
-
-  /** Resolve the next head-anchored compactable surface range, or `null`. */
-  private _compactableRange(session: Session): { start: number; end: number } | null {
-    const nodes = session.surface.nodes
-    if (nodes.length === 0) return null
-
-    const events = session.events
-    const retainBudget = this.config.retainTokens
-
-    // Walk tail→head summing per-node token estimates. `keepFromIdx` is the
-    // index of the OLDEST node we retain verbatim; everything strictly older
-    // (`[0, keepFromIdx - 1]`) is the compactable range.
-    let accumulated = 0
-    let keepFromIdx = nodes.length // nothing retained yet
-    for (let i = nodes.length - 1; i >= 0; i--) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const node = nodes[i]!
-      const event = events[node.seq]
-      /* v8 ignore next -- node.seq is a surface-node seq, always a valid log index by construction */
-      if (event) accumulated += this.estimateEventTokens(event)
-      keepFromIdx = i
-      if (accumulated >= retainBudget) break
-    }
-
-    // The whole surface fits the retain budget — nothing to compact.
-    if (keepFromIdx === 0) return null
-
-    // Round the cutoff to a tool-pairing boundary: if the cut before `nodes[keepFromIdx]` is
-    // unbalanced (an unanswered tool-call sits before it — i.e. it is mid-step), extend the
-    // retained side head-ward until the cut is balanced, so the compacted range ends without
-    // splitting an assistant↔result pair.
-    while (keepFromIdx > 0) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      if (toolPairingBalancedBefore(session, nodes[keepFromIdx]!)) break
-      keepFromIdx -= 1
-    }
-    if (keepFromIdx === 0) return null
-
-    // The compacted range is [head … keepFromIdx - 1], anchored at the head.
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const firstSeq = nodes[0]!.seq
-    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-    const cutoffSeq = nodes[keepFromIdx - 1]!.seq
-    return { start: firstSeq, end: cutoffSeq }
-  }
-
-  /** Keep only text; checkpoints cannot contain reasoning or orphan tool calls. */
-  private _textOnly(blocks: readonly ContentBlock[]): ContentBlock[] {
-    return blocks.filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
-  }
-
-  /**
-   * The turn number of the currently OPEN turn — a `turn/start` not yet
-   * followed by its `turn/end` — or `null` if the session has no open turn.
-   *
-   * Compaction's events must be enclosed in a turn, so scanning back from the
-   * tail: a `turn/start` means that turn is open (return it); a `turn/end` means
-   * the most recent turn already closed (return null). The whole compaction
-   * sequence (compact/start … compact/end) is stamped with this turn.
-   */
-  private _openTurn(session: Session): number | null {
-    for (let i = session.events.length - 1; i >= 0; i--) {
-      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-      const e = session.events[i]!
-      if (e.type === 'turn/start') return e.data.turn
-      if (e.type === 'turn/end') return null
-    }
-    return null
+    return modelConfig
   }
 }
 

packages/compact/compact-basic/src/region.ts

@@ -0,0 +1,196 @@
+/**
+ * Surface retention selection and the log-recorded compaction transaction.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/region
+ */
+
+import {
+  renderTranscript,
+  toolPairingBalancedAfter,
+  toolPairingBalancedBefore,
+} from '@deepseek-ai/dsh-compact'
+import type { CompactionResult } from '@deepseek-ai/dsh-compact'
+import type { ModelTokenMeter, TokenSurfaceMeasurement } from '@deepseek-ai/dsh-token-meter'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { frameSummary } from './summarizer.ts'
+import type { SummaryResult } from './summarizer.ts'
+
+interface RegionDependencies {
+  readonly meter: ModelTokenMeter
+  summarize(text: string, agent: Agent, signal?: AbortSignal): Promise<SummaryResult>
+}
+
+/**
+ * Resolve the next head-anchored range while retaining a priced recent tail
+ * and never splitting an assistant tool-call/result pair.
+ * @param session - session supplying authoritative current surface positions.
+ * @param pricedSurface - same-revision surface measurement from the conversation meter.
+ * @param retainTokens - minimum recent tail budget retained verbatim.
+ * @returns the inclusive positional seq range to compact, or `null`.
+ */
+export function selectCompactableRange(
+  session: Session,
+  pricedSurface: TokenSurfaceMeasurement,
+  retainTokens: number,
+): { start: number; end: number } | null {
+  const pricedNodes = pricedSurface.nodes
+  if (pricedNodes.length === 0) return null
+
+  const surfaceNodes = session.surface.nodes
+  if (surfaceNodes.length !== pricedNodes.length
+    || surfaceNodes.some((node, index) => node.seq !== pricedNodes[index]?.seq)) {
+    throw new Error('compaction: token-meter surface does not match the current session surface')
+  }
+
+  let accumulated = 0
+  let keepFromIdx = pricedNodes.length
+  for (let index = pricedNodes.length - 1; index >= 0; index -= 1) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    accumulated += pricedNodes[index]!.tokens
+    keepFromIdx = index
+    if (accumulated >= retainTokens) break
+  }
+  if (keepFromIdx === 0) return null
+
+  while (keepFromIdx > 0) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    if (toolPairingBalancedBefore(session, surfaceNodes[keepFromIdx]!)) break
+    keepFromIdx -= 1
+  }
+  if (keepFromIdx === 0) return null
+
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const first = surfaceNodes[0]!
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const cutoff = surfaceNodes[keepFromIdx - 1]!
+  return { start: first.seq, end: cutoff.seq }
+}
+
+/**
+ * Validate and compact one positional surface span.
+ * @param dependencies - conversation meter and dynamically dispatched summarizer hook.
+ * @param session - session whose surface is mutated.
+ * @param start - inclusive first surface-node seq.
+ * @param end - inclusive last surface-node seq.
+ * @param agent - agent used by the summarizer.
+ * @param signal - optional summarization cancellation signal.
+ * @returns the successful durable compaction result.
+ */
+export async function compactSurfaceRegion(
+  dependencies: RegionDependencies,
+  session: Session,
+  start: number,
+  end: number,
+  agent: Agent,
+  signal?: AbortSignal,
+): Promise<CompactionResult> {
+  const nodes = session.surface.nodes
+  const startIdx = nodes.findIndex(node => node.seq === start)
+  const endIdx = nodes.findIndex(node => node.seq === end)
+  if (startIdx === -1) throw new Error(`compactRegion: start seq ${start} not found in surface`)
+  if (endIdx === -1) throw new Error(`compactRegion: end seq ${end} not found in surface`)
+  if (startIdx > endIdx) {
+    throw new Error(
+      `compactRegion: start seq ${start} (position ${startIdx}) is after end seq ${end} (position ${endIdx}) on the surface`,
+    )
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  if (!toolPairingBalancedBefore(session, nodes[startIdx]!)) {
+    throw new Error(`compactRegion: start seq ${start} is not a balanced boundary (would split a step's tool-call/result pair)`)
+  }
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  if (!toolPairingBalancedAfter(session, nodes[endIdx]!)) {
+    throw new Error(`compactRegion: end seq ${end} is not a balanced boundary (would split a step, or the step is still open)`)
+  }
+
+  const tail = inspectTurnTail(session.events)
+  if (tail.compactionInProgress) throw new Error('compaction already in progress')
+  if (tail.turn === null) {
+    throw new Error('compactRegion: no open turn — compaction events must be enclosed in a turn')
+  }
+
+  const shadowedSeqs = nodes.slice(startIdx, endIdx + 1).map(node => node.seq)
+  const startEvent = session.append('compact/start', { turn: tail.turn })
+  try {
+    // Capture after the lock event so any later durable append, including a
+    // log-only one, invalidates the async selection before replacement.
+    const lockedSurface = dependencies.meter.measureSurface(session)
+    const selected = lockedSurface.nodes.slice(startIdx, endIdx + 1)
+    if (selected.length !== shadowedSeqs.length
+      || selected.some((node, index) => node.seq !== shadowedSeqs[index])) {
+      throw new Error('compaction: selected surface changed before summarization began')
+    }
+    const shadowedTokenCount = selected.reduce((total, node) => total + node.tokens, 0)
+    const text = renderTranscript(session.events, shadowedSeqs)
+    const { summary, model, maxTokens } = await dependencies.summarize(text, agent, signal)
+
+    const currentSurface = dependencies.meter.measureSurface(session)
+    if (currentSurface.logRevision !== lockedSurface.logRevision) {
+      throw new Error('compaction: session log changed during summarization')
+    }
+    const framedSummary = frameSummary(summary)
+    const framedSummaryTokenCount = dependencies.meter.estimateMessage({
+      role: 'user',
+      content: framedSummary,
+    })
+    if (framedSummaryTokenCount >= shadowedTokenCount) {
+      throw new Error(
+        `summary is not smaller than the shadowed content (${framedSummaryTokenCount} estimated framed tokens >= ${shadowedTokenCount})`,
+      )
+    }
+
+    const summaryEvent = session.append('compact/summary', {
+      summary,
+      shadowedRange: { start, end },
+      shadowedSeqs,
+      shadowedTokenCount,
+      model,
+      ...maxTokens === undefined ? {} : { maxTokens },
+    })
+    session.append('user/message', {
+      content: framedSummary,
+      source: { kind: 'plugin', plugin: 'compact' },
+    }, {
+      surfaceOp: { op: 'replace', start, end },
+      sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
+    })
+    const endEvent = session.append('compact/end', { turn: tail.turn })
+    return {
+      startSeq: startEvent.seq,
+      summarySeq: summaryEvent.seq,
+      endSeq: endEvent.seq,
+      summary,
+      shadowedRange: { start, end },
+      shadowedSeqs,
+      shadowedTokenCount,
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error)
+    session.append('compact/end', { turn: tail.turn, error: message })
+    throw error
+  }
+}
+
+/** Inspect the current turn boundary and latest compaction bracket once. */
+function inspectTurnTail(
+  events: readonly SessionEvent[],
+): { turn: number | null; compactionInProgress: boolean } {
+  let compactionInProgress = false
+  let compactionStateKnown = false
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+    const event = events[index]!
+    if (!compactionStateKnown) {
+      if (event.type === 'compact/start') {
+        compactionInProgress = true
+        compactionStateKnown = true
+      } else if (event.type === 'compact/end') {
+        compactionStateKnown = true
+      }
+    }
+    if (event.type === 'turn/start') return { turn: event.data.turn, compactionInProgress }
+    if (event.type === 'turn/end') return { turn: null, compactionInProgress }
+  }
+  return { turn: null, compactionInProgress }
+}

packages/compact/compact-basic/src/summarizer.ts

@@ -0,0 +1,153 @@
+/**
+ * Default one-shot summarization and durable checkpoint framing.
+ *
+ * @module @deepseek-ai/dsh-compact-basic/summarizer
+ */
+
+import type { Context } from 'cordis'
+import { BlockAssembler } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, FinishReason, GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { ResolvedConfig } from './types.ts'
+
+/** Tags wrapping the structured summary inside the landed checkpoint node. */
+const SUMMARY_OPEN_TAG = '<compacted-summary>'
+const SUMMARY_CLOSE_TAG = '</compacted-summary>'
+
+/** Fixed structure required from the auxiliary summarization call. */
+const SUMMARIZE_SYSTEM_PROMPT = [
+  'You are a compaction engine for an AI coding assistant. Condense the conversation transcript into a structured checkpoint that lets another model resume the work with no loss of essential context.',
+  '',
+  'Output EXACTLY the Markdown structure below: keep every section, in order. Use terse bullets, not prose paragraphs. Write "(none)" for an empty section — never drop a section.',
+  '',
+  '## Primary Request and Intent',
+  "- [the user's original and evolving goals; quote verbatim where the exact wording matters]",
+  '',
+  '## Key Technical Concepts',
+  '- [technologies, frameworks, patterns, and conventions in play]',
+  '',
+  '## Files and Code',
+  '- [exact path: why it matters, key changes or snippets]',
+  '',
+  '## Errors and Fixes',
+  '- [error: how it was resolved, plus any related user feedback]',
+  '',
+  '## Pending Tasks',
+  '- [explicitly requested work not yet completed]',
+  '',
+  '## Current Work',
+  '- [precisely what was in progress at this checkpoint]',
+  '',
+  '## Next Step',
+  '- [the single next action, directly in line with the most recent request, or "(none)"]',
+  '',
+  '## Critical Context',
+  '- [decisions and their rationale, constraints, user preferences, open questions, data needed to continue]',
+  '',
+  'Rules:',
+  '- Preserve exact file paths, commands, error strings, identifiers, and function signatures.',
+  '- Capture user feedback and explicit instructions faithfully, especially corrections.',
+  '- Do NOT mention this summarization process or that the context was compacted.',
+  `- If the transcript already contains a ${SUMMARY_OPEN_TAG} block, it is a PRIOR checkpoint. Do not copy it forward verbatim: preserve still-true facts, drop stale ones, and merge newer information into a single consolidated summary under the same structure.`,
+].join('\n')
+
+/** Framing that makes the replacement user message established context. */
+const CHECKPOINT_PREAMBLE =
+  'This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.'
+
+/** Safe summary content plus the exact auxiliary call envelope recorded in provenance. */
+export interface SummaryResult {
+  summary: ContentBlock[]
+  model: string
+  maxTokens?: number
+}
+
+/**
+ * Run the default direct `ctx.llm.stream()` summarization call.
+ * @param ctx - context providing the LLM service.
+ * @param config - resolved backend configuration.
+ * @param text - rendered transcript region to summarize.
+ * @param agent - supplies routed-model history, fallback model, and session id.
+ * @param signal - optional cancellation forwarded to the adapter.
+ * @returns safe text-only summary blocks and exact call provenance.
+ */
+export async function summarizeWithLlm(
+  ctx: Context,
+  config: ResolvedConfig,
+  text: string,
+  agent: Agent,
+  signal?: AbortSignal,
+): Promise<SummaryResult> {
+  const latestModel = agent.session.requestHeader()?.config.model
+  const model = config.summarizationModel || latestModel || agent.options.model || ''
+  if (model.length === 0) {
+    throw new Error(
+      'no model available for summarization: set BasicCompactConfig.summarizationModel, route one request, or set AgentOptions.model',
+    )
+  }
+
+  const assembler = new BlockAssembler()
+  const options: GenerateOptions = {
+    model,
+    messages: [{
+      role: 'user',
+      content: [{ type: 'text', text: `Summarize this conversation history:\n\n${text}\n\nSummary:` }],
+    }],
+    system: SUMMARIZE_SYSTEM_PROMPT,
+    maxTokens: config.maxTokens,
+    sessionId: agent.session.id,
+    ...signal === undefined ? {} : { signal },
+  }
+  for await (const chunk of ctx.llm.stream(options)) assembler.push(chunk)
+  const error = finishError(assembler.finish)
+  if (error !== undefined) throw error
+
+  const summary = textOnly(assembler.message().content)
+  if (!summary.some(block => block.text.trim().length > 0)) {
+    throw new Error('summarization produced no text summary content')
+  }
+  return { summary, model, maxTokens: config.maxTokens }
+}
+
+/**
+ * Wrap raw summary blocks in the durable checkpoint framing.
+ * @param summary - safe text-only model output.
+ * @returns content for the synthesized replacement user message.
+ */
+export function frameSummary(summary: readonly ContentBlock[]): ContentBlock[] {
+  return [
+    { type: 'text', text: `${CHECKPOINT_PREAMBLE}\n\n${SUMMARY_OPEN_TAG}` },
+    ...summary,
+    { type: 'text', text: SUMMARY_CLOSE_TAG },
+  ]
+}
+
+/** Map a terminal summarization finish to its fail-closed error. */
+function finishError(finish: FinishReason): Error | undefined {
+  switch (finish.kind) {
+    case 'error': {
+      const error = new Error(finish.message) as Error & { code?: string }
+      if (finish.code !== undefined) error.code = finish.code
+      return error
+    }
+    case 'aborted': {
+      const error = new Error('summarization stream aborted') as Error & { code?: string }
+      error.code = 'ABORTED'
+      return error
+    }
+    case 'max-tokens': {
+      const error = new Error('summarization truncated at the token cap (incomplete checkpoint)') as Error & { code?: string }
+      error.code = 'MAX_TOKENS'
+      return error
+    }
+    default:
+      return undefined
+  }
+}
+
+/** Keep only text blocks before synthesizing a user message. */
+function textOnly(
+  blocks: readonly ContentBlock[],
+): Array<Extract<ContentBlock, { type: 'text' }>> {
+  return blocks.filter((block): block is Extract<ContentBlock, { type: 'text' }> => block.type === 'text')
+}

packages/compact/compact-basic/src/types.ts

@@ -1,94 +1,44 @@
 /**
- * Configuration vocabulary for the basic compaction backend.
- *
- * Every tunable lives here, in the implementation — the abstract contract
- * (`@deepseek-ai/dsh-compact`) carries no config, because thresholds and
- * retention policy are HOW decisions a different backend would make
- * differently.
+ * Configuration vocabulary for the replay-aware basic compaction backend.
  *
  * @module @deepseek-ai/dsh-compact-basic/types
  */
 
-/**
- * Backend configuration. Every knob is REQUIRED except `auto` and
- * `charsPerToken`: there is no concrete data yet to justify default
- * thresholds/budgets, so a consumer must state each value explicitly rather
- * than inherit a guessed default. `auto` alone defaults to `true`
- * (auto-compaction is the intended posture), and `charsPerToken` defaults to
- * the English-text heuristic its estimator was calibrated on.
- */
+/** Optional pressure and retention policy for one metered model. */
+export interface ModelCompactConfig {
+  /** Compact at this fraction of the model's configured context window. Defaults to `0.8`. */
+  thresholdRatio?: number
+  /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
+  retainTokens?: number
+}
+
+/** Basic compaction configuration; every common field has a deployment default. */
 export interface BasicCompactConfig {
-  /** Context window size in tokens. */
-  contextWindow: number
-  /** Compact when estimated token usage exceeds this fraction of context window. */
-  thresholdRatio: number
-  /** Number of tokens of recent context to retain during compaction. */
-  retainTokens: number
-  /** Model to use for summarization (`''` — uses the agent's model). */
-  summarizationModel: string
-  /** Provider generation cap for the summarization call. */
-  maxTokens: number
-  /** Extra compaction attempts when the first compacted surface is still over threshold. */
-  compactionRetries: number
-  /** Enable automatic compaction on the `agent/pre-step` seam (default true). */
+  /** Field-wise pressure/retention overrides keyed by configured token-meter model name. */
+  models?: Record<string, ModelCompactConfig>
+  /** Summary model; `''` resolves the latest routed model, then `AgentOptions.model`. Defaults to `''`. */
+  summarizationModel?: string
+  /** Provider generation cap for summarization. Defaults to `8192`. */
+  maxTokens?: number
+  /** Extra attempts after the first compaction when pressure remains above threshold. Defaults to `1`. */
+  compactionRetries?: number
+  /** Enable the automatic `agent/pre-step` pressure listener. Defaults to `true`. */
   auto?: boolean
-  /**
-   * Text density for the token estimator: estimated tokens = chars /
-   * `charsPerToken`. Defaults to 4 (typical English text). A CJK-heavy
-   * deployment should set ~1-2 — CJK runs at roughly 1-2 chars per token, so
-   * the default UNDERestimates several-fold and compaction fires far too late.
-   * May be fractional.
-   */
-  charsPerToken?: number
 }
 
-/** Resolved config with `auto` and `charsPerToken` defaulted. */
-export type ResolvedConfig = Required<BasicCompactConfig>
-
-/**
- * Default `auto`/`charsPerToken` when unset and reject nonsensical numeric knobs.
- *
- * @param config - the raw, unresolved backend config.
- * @returns the validated config with `auto` and `charsPerToken` defaulted.
- */
-export function resolveConfig(config: BasicCompactConfig): ResolvedConfig {
-  const resolved: ResolvedConfig = { auto: true, charsPerToken: 4, ...config }
-
-  assertPositiveInteger('contextWindow', resolved.contextWindow)
-  assertRatio('thresholdRatio', resolved.thresholdRatio)
-  assertNonNegativeInteger('retainTokens', resolved.retainTokens)
-  assertPositiveInteger('maxTokens', resolved.maxTokens)
-  assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
-  assertPositiveFinite('charsPerToken', resolved.charsPerToken)
-  if (typeof resolved.summarizationModel !== 'string') {
-    throw new Error('BasicCompactConfig: summarizationModel must be a string.')
-  }
-  if (typeof resolved.auto !== 'boolean') {
-    throw new Error('BasicCompactConfig: auto must be a boolean.')
-  }
-  return resolved
+/** Validated top-level defaults plus detached per-model partial overrides. */
+export interface ResolvedConfig {
+  readonly models: Readonly<Record<string, Readonly<ModelCompactConfig>>>
+  readonly summarizationModel: string
+  readonly maxTokens: number
+  readonly compactionRetries: number
+  readonly auto: boolean
 }
 
-function assertPositiveInteger(name: string, value: number): void {
-  if (!Number.isInteger(value) || value <= 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive integer.`)
-  }
-}
-
-function assertNonNegativeInteger(name: string, value: number): void {
-  if (!Number.isInteger(value) || value < 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a non-negative integer.`)
-  }
-}
-
-function assertPositiveFinite(name: string, value: number): void {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive finite number.`)
-  }
-}
-
-function assertRatio(name: string, value: number): void {
-  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
-    throw new Error(`BasicCompactConfig: ${name} (${value}) must be a number in (0, 1].`)
-  }
+/** Fully resolved pressure/retention policy for one effective model. */
+export interface ResolvedModelCompactConfig {
+  readonly model: string
+  readonly contextWindow: number
+  readonly thresholdRatio: number
+  readonly retainTokens: number
 }

packages/compact/compact-basic/tests/compact-loop-repro.spec.ts

@@ -11,6 +11,7 @@ import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent'
 import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop'
 import * as Invariants from '@deepseek-ai/dsh-invariants'
 import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
 import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
 
 /**
@@ -20,13 +21,7 @@ import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
  * surface-position semantics rather than raw-log scanning.
  */
 
-const TOKENS_PER_BLOCK = 10
-
 class ReproCompactService extends BasicCompactService {
-  override estimateContentTokens(blocks: readonly ContentBlock[]): number {
-    return blocks.length * TOKENS_PER_BLOCK
-  }
-
   override async summarize(): Promise<{ summary: ContentBlock[]; model: string }> {
     return { summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], model: 'stub' }
   }
@@ -67,6 +62,9 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
   await ctx.plugin(ToolRegistry)
   await ctx.plugin(AgentRegistry)
   await ctx.plugin(AgentLoop, { agents: [] })
+  await ctx.plugin(TokenMeterService, {
+    models: { mock: { contextWindow: 64, charsPerToken: 1_000 } },
+  })
   ctx.llm.registerAdapter(['mock'], new StepwiseToolAdapter(toolSteps))
   ctx.tools.register(defineTool({
     name: 'work',
@@ -80,9 +78,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
   // fires within the runaway turn.
   const compact = new ReproCompactService(ctx, {
     auto: true,
-    contextWindow: 64,
-    thresholdRatio: 0.5,
-    retainTokens: 20,
+    models: { mock: { thresholdRatio: 0.5, retainTokens: 20 } },
     summarizationModel: '',
     maxTokens: 8192,
     compactionRetries: 1,

packages/compact/compact-basic/tests/loader-composition.spec.ts

@@ -0,0 +1,66 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import LlmService from '@deepseek-ai/dsh-llm'
+import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import BasicCompactService from '@deepseek-ai/dsh-compact-basic'
+
+let root: string | undefined
+let context: Context | undefined
+
+afterEach(async () => {
+  await context?.fiber.dispose()
+  context = undefined
+  if (root !== undefined) await rm(root, { recursive: true, force: true })
+  root = undefined
+})
+
+describe('real Loader composition', () => {
+  it('loads the zero-config token-meter then compact-basic YAML pair', async () => {
+    root = await mkdtemp(join(tmpdir(), 'dsh-token-meter-loader-'))
+    const configPath = join(root, 'cordis.yml')
+    await writeFile(configPath, [
+      "- name: '@deepseek-ai/dsh-llm'",
+      "- name: '@deepseek-ai/dsh-token-meter'",
+      "- name: '@deepseek-ai/dsh-compact-basic'",
+      '',
+    ].join('\n'))
+
+    context = new Context()
+    context.baseUrl = pathToFileURL(root).href + '/'
+    await context.plugin(Loader)
+    context.loader.builtins.include = Include
+    const modules = new Map<string, unknown>([
+      ['@deepseek-ai/dsh-llm', LlmService],
+      ['@deepseek-ai/dsh-token-meter', TokenMeterService],
+      ['@deepseek-ai/dsh-compact-basic', BasicCompactService],
+    ])
+    context.loader.internal = {
+      version: 'v2',
+      async import(specifier: string) {
+        if (!modules.has(specifier)) throw new Error(`unexpected Loader import: ${specifier}`)
+        return modules.get(specifier)
+      },
+    } as unknown as NonNullable<typeof context.loader.internal>
+    await context.loader.create({
+      name: 'cordis:include',
+      config: { path: pathToFileURL(configPath).href },
+    })
+    await context.loader.await()
+
+    const unloaded = [...context.loader.entries()]
+      .filter(entry => entry.fiber === undefined && !entry.disabled)
+      .map(entry => entry.options.name)
+    expect(unloaded).toEqual([])
+    expect(context.tokenMeter.resolve('deepseek-v4-flash')).toMatchObject({
+      contextWindow: 128_000,
+      charsPerToken: 4,
+    })
+    expect(context.get('compact')).toBeInstanceOf(BasicCompactService)
+  })
+})

packages/compact/compact-basic/tsconfig.json

@@ -8,7 +8,9 @@
   "references": [
     { "path": "../../../vendor/cosmokit" },
     { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
     { "path": "../../llm/llm" },
+    { "path": "../../llm/token-meter" },
     { "path": "../../core/session" },
     { "path": "../../core/agent" },
     { "path": "../compact" }

packages/compact/compact/README.md

@@ -7,14 +7,14 @@ This package is the interface tier of the compaction capability, split so each c
 | Package | Role |
 |---|---|
 | `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + tool-pairing boundary helpers + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) |
-| `@deepseek-ai/dsh-compact-basic` | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization |
+| `@deepseek-ai/dsh-compact-basic` | a backend: `ctx.tokenMeter` pressure + token-budget retention + `llm.stream()` summarization |
 | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` |
 
 Unlike the bash seam, this interface depends on `@deepseek-ai/dsh-session` and `@deepseek-ai/dsh-llm` — the contract's verbs are defined over a `Session` and its output is the `ContentBlock` vocabulary, so they cannot be expressed without naming those packages. 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).
 
 ## Service API (`ctx.compact`)
 
-Both methods are **abstract** — the backend owns the entire strategy (token estimation, retention policy, event sequencing, summarization).
+Both methods are **abstract** — the backend owns trigger policy, retention, event sequencing, and summarization. Reusable request measurement is a separate service, [`ctx.tokenMeter`](../../llm/token-meter/README.md), rather than part of this interface.
 
 | Member | Semantics |
 |---|---|
@@ -53,7 +53,7 @@ The `compact/*` events extend `SessionEventMap` (merge-extensible) via declarati
 
 ## Implementing a backend
 
-Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. A tokenizer-, template-, or model-backed implementation can live as a sibling package without changing callers.
+Subclass `CompactService`, implement `compactIfNeeded` and `compactRegion`, and load the subclass as a plugin — it registers as `ctx.compact`. A template- or model-backed implementation can live as a sibling package without changing callers or the shared token meter.
 
 ## Model Experience
 

packages/compact/compact/src/index.ts

@@ -29,10 +29,11 @@ declare module 'cordis' {
 }
 
 /**
- * Abstract compaction service. Implementations own token estimation, retention,
- * and summarization, but a successful run must replace the selected surface span
- * with one summary node and prevent concurrent compaction of the same session.
- * Load one implementation per context as `ctx.compact`.
+ * Abstract compaction service. Implementations own trigger policy, retention,
+ * and summarization, and may consume a separate measurement service. A
+ * successful run replaces the selected surface span with one summary node and
+ * prevents concurrent compaction of the same session. Load one implementation
+ * per context as `ctx.compact`.
  */
 export abstract class CompactService extends Service {
   constructor(ctx: Context) {

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -214,6 +214,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
     ],
   },
+  {
+    key: 'tokenMeter',
+    summary: 'Concrete registry and replay owner for all configured model meters.',
+    methods: [
+      'resolve(model: string): ModelTokenMeter',
+    ],
+  },
   {
     key: 'tools',
     summary: 'Tool registry and execution pipeline.',
@@ -669,6 +676,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'DiffResultView',
     declaration: 'export interface DiffResultView {\n    card: \'diff\';\n    title?: string;\n    diffs: FileDiff[];\n}',
   },
+  {
+    name: 'EpochHeader',
+    declaration: 'export interface EpochHeader {\n    config: LlmCallConfig;\n    system?: string;\n    tools?: ToolSchema[];\n    messagePrefix?: Message[];\n}',
+  },
   {
     name: 'FileDiff',
     declaration: 'export interface FileDiff {\n    path: string;\n    oldText: string | null;\n    newText: string;\n}',
@@ -737,6 +748,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'HookContext',
     declaration: 'export interface HookContext {\n    content: ContentBlock[];\n    source: MessageSource;\n}',
   },
+  {
+    name: 'LlmCallConfig',
+    declaration: 'export interface LlmCallConfig {\n    model: string;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}',
+  },
   {
     name: 'Message',
     declaration: 'export interface Message {\n    role: \'system\' | \'user\' | \'assistant\';\n    content: ContentBlock[];\n}',
@@ -749,6 +764,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'MessageSourceMap',
     declaration: 'export interface MessageSourceMap {\n    user: {\n        kind: \'user\';\n    };\n    plugin: {\n        kind: \'plugin\';\n        plugin: string;\n    };\n}',
   },
+  {
+    name: 'ModelTokenMeter',
+    declaration: 'export interface ModelTokenMeter {\n    readonly model: string;\n    readonly contextWindow: number;\n    readonly charsPerToken: number;\n    measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement;\n    measureSurface(session: Session): TokenSurfaceMeasurement;\n    estimateMessage(message: Message): number;\n}',
+  },
   {
     name: 'OwnerToken',
     declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;',
@@ -941,6 +960,22 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TodoItem',
     declaration: 'export interface TodoItem {\n    content: string;\n    status: \'pending\' | \'in_progress\' | \'completed\';\n}',
   },
+  {
+    name: 'TokenMeasurement',
+    declaration: 'export interface TokenMeasurement {\n    readonly model: string;\n    readonly logRevision: number;\n    readonly baseline: TokenMeasurementBaseline;\n    readonly surfaceDeltaTokens: number;\n    readonly totalTokens: number;\n}',
+  },
+  {
+    name: 'TokenMeasurementBaseline',
+    declaration: 'export type TokenMeasurementBaseline = {\n    readonly kind: \'none\';\n    readonly tokens: 0;\n} | {\n    readonly kind: \'estimated\';\n    readonly tokens: number;\n} | {\n    readonly kind: \'usage\';\n    readonly tokens: number;\n    readonly usage: Readonly<TokenUsage>;\n};',
+  },
+  {
+    name: 'TokenSurfaceMeasurement',
+    declaration: 'export interface TokenSurfaceMeasurement {\n    readonly model: string;\n    readonly logRevision: number;\n    readonly totalTokens: number;\n    readonly nodes: readonly TokenSurfaceNode[];\n}',
+  },
+  {
+    name: 'TokenSurfaceNode',
+    declaration: 'export interface TokenSurfaceNode {\n    readonly seq: number;\n    readonly tokens: number;\n}',
+  },
   {
     name: 'TokenUsage',
     declaration: 'export interface TokenUsage {\n    inputTokens: number;\n    outputTokens: number;\n    cacheReadTokens?: number;\n    cacheWriteTokens?: number;\n    reasoningTokens?: number;\n}',

packages/core/agent-loop/README.md

@@ -50,6 +50,8 @@ Configured agents start automatically. `cwd` applies only to fresh sessions; `re
 
 The driver owns one agent for its lifetime. It records turn, step, request, stream, and tool boundaries in the session log; live extension events coordinate policy around those durable facts. The [architecture turn flow](../../../docs/architecture.md#turn-flow) and generated [event catalog](../../../docs/cordis-catalog/events.md) are the authoritative sequence and signatures.
 
+Every provider call that reaches a successful finish appends one `assistant/message` completion anchor after `agent/step-result`, including content-less calls and `max-tokens` finishes. The anchor records exact chunk provenance (`[]` for a stream with no chunks) and usage when available; empty content stays out of derived message history while those replay facts remain durable.
+
 Plugin failure ends the current turn, not the loop. Cancellation clears pending work and aborts the current step without leaking to the next prompt. Terminal continuation stops remain authoritative through turn close and durability flush.
 
 ### What belongs to plugins

packages/core/agent-loop/src/loop.ts

@@ -528,15 +528,14 @@ async function runStep(
   if (assembler.finish.kind === 'max-tokens') {
     let message: Message = withoutToolCalls(assembler.message())
     message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)))
-    // Preserve usage even when max-token truncation produced no content.
-    if (message.content.length > 0 || assembler.usage) {
-      // The finish chunk guarantees non-empty provenance here.
-      session.append(
-        'assistant/message',
-        { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-        { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
-      )
-    }
+    // Every successful call records its completion anchor. Empty content is
+    // skipped by deriveMessages(), while exact chunk provenance lets replay
+    // distinguish a known empty provider stream from unrecorded provenance.
+    session.append(
+      'assistant/message',
+      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+      { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+    )
     return { hadToolCalls: false, finish: assembler.finish }
   }
 
@@ -544,14 +543,14 @@ async function runStep(
   let message: Message = assembler.message()
   message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))
 
-  // Empty messages exist only to carry usage; omit empty provenance.
-  if (message.content.length > 0 || assembler.usage) {
-    session.append(
-      'assistant/message',
-      { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
-      { surfaceOp: 'append', ...(chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {}) },
-    )
-  }
+  // Every successful call records its completion anchor. A present empty
+  // source set means the provider stream was known to contain no chunks;
+  // omission remains the conservative legacy/unrecorded representation.
+  session.append(
+    'assistant/message',
+    { turn, step, content: message.content, ...(assembler.usage ? { usage: assembler.usage } : {}) },
+    { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+  )
 
   // Tool execution stays sequential; recheck abort around each normalized result.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -1075,9 +1075,10 @@ describe('tool result call identity', () => {
   })
 })
 
-describe('surface: assistant/message omits sourceEventSeqs when no chunks streamed', () => {
-  it('a step-result listener injecting content over an empty stream appends with surfaceOp but no sourceEventSeqs', async () => {
-    // Injected result content with no chunks must omit empty sourceEventSeqs.
+describe('surface: assistant/message records exact empty provenance when no chunks streamed', () => {
+  it('a step-result listener injecting content over an empty stream records sourceEventSeqs []', async () => {
+    // The explicit empty source set distinguishes a known empty provider
+    // stream from legacy events whose provenance was not recorded.
     const adapter = new MockAdapter([[]])
     const ctx = await harness(adapter)
     await ctx.plugin(Invariants)
@@ -1094,7 +1095,7 @@ describe('surface: assistant/message omits sourceEventSeqs when no chunks stream
     const recorded = agent.session.events.find(e => e.type === 'assistant/message')!
     expect(recorded.type).toBe('assistant/message')
     expect(recorded.surfaceOp).toBe('append')
-    expect(recorded.sourceEventSeqs).toBeUndefined()
+    expect(recorded.sourceEventSeqs).toEqual([])
     // The injected content reaches derived history.
     expect(JSON.stringify(agent.session.deriveMessages())).toContain('injected')
   })

packages/core/agent-loop/tests/loop.spec.ts

@@ -717,10 +717,9 @@ describe('agent loop', () => {
     })
   })
 
-  it('appends no assistant/message for a max-tokens step with empty content and no usage', async () => {
-    // A max-tokens step truncated to a dropped tool call AND with no usage chunk has nothing to
-    // record: empty content and no accounting → no assistant/message (the empty-content host
-    // exists only to carry usage).
+  it('appends an empty completion anchor for a max-tokens step with no usage', async () => {
+    // The truncated tool call is dropped from durable content, while the
+    // successful provider call still needs an exact replay anchor.
     const callId = CallId('c1')
     const adapter = new MockAdapter([[
       { type: 'block-start', index: 0, blockType: 'tool-call' },
@@ -744,14 +743,19 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'max-tokens' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+    })
+    expect(assistant.sourceEventSeqs?.length).toBeGreaterThan(0)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })
 
-  it('appends no assistant/message for a normal stop finish with empty content and no usage', async () => {
-    // A clean `stop` finish that streamed nothing assembled (no blocks) and
-    // carried no usage chunk has nothing to record: the content-or-usage guard
-    // on the normal step path suppresses a pure trace-only empty assistant/message.
+  it('appends an empty completion anchor for a normal stop with no usage', async () => {
+    // A clean content-less call stays absent from derived messages but remains
+    // a durable successful-call boundary for replay consumers.
     const adapter = new MockAdapter([[{ type: 'finish', reason: { kind: 'stop' } }]])
     const ctx = await harness(adapter)
     const agent = ctx.agentLoop.create(AgentId('a1'), { model: 'mock' })
@@ -763,7 +767,13 @@ describe('agent loop', () => {
     await waitForIdle(ctx, agent)
 
     expect(reasons).toEqual([{ kind: 'completed' }])
-    expect(agent.session.events.some(e => e.type === 'assistant/message')).toBe(false)
+    const assistant = agent.session.events.find(e => e.type === 'assistant/message')!
+    expect(assistant.type === 'assistant/message' && assistant.data).toEqual({
+      turn: 1,
+      step: 1,
+      content: [],
+    })
+    expect(assistant.sourceEventSeqs?.length).toBe(1)
     expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }])
   })
 

packages/core/session/README.md

@@ -66,7 +66,7 @@ Also defines `TurnTriggerMap` and `TurnEndReasonMap` (merge-extensible sum types
 
 Every `SessionEvent` carries two optional top-level fields (structural metadata):
 
-- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction replace node).
+- `sourceEventSeqs?: number[]` — seq numbers of provenance sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed nodes behind a compaction replace node). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means legacy or otherwise unrecorded provenance; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
 
 ### Metadata types (`types.ts`)

packages/core/session/src/types.ts

@@ -331,6 +331,12 @@ export type SurfaceOp =
  */
 export interface SurfaceIntent {
   surfaceOp: SurfaceOp
+  /**
+   * Complete known provenance source set. `assistant/message` may use a
+   * present empty array for a known empty provider stream; omission means its
+   * provenance was not recorded. Other surface events require a non-empty set
+   * when this field is present.
+   */
   sourceEventSeqs?: number[]
 }
 
@@ -359,7 +365,9 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     /**
      * Seq numbers of events that are provenance sources of this event
      * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
-     * or the surface nodes shadowed by a compaction replace node).
+     * or the surface nodes shadowed by a compaction replace node). An
+     * `assistant/message` may carry a present empty array for a known empty
+     * provider stream; omission means unrecorded provenance.
      */
     sourceEventSeqs?: number[]
     /** How this event entered the surface; absent for non-surface events. */

packages/llm/README.md

@@ -5,7 +5,8 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 | Package | Role | ctx key |
 |---|---|---|
 | `llm/` | Abstract LLM service + content-block vocabulary + chunk assembler | `ctx.llm` |
+| `token-meter/` | Replay-aware, per-model request and surface token measurement | `ctx.tokenMeter` |
 | `llm-deepseek/` | DeepSeek API adapter (hand-rolled fetch/SSE) | (registers on `ctx.llm`) |
 | `llm-pi-ai/` | DeepSeek adapter via `@earendil-works/pi-ai` (design twin) | (registers on `ctx.llm`) |
 
-The interface lives at `llm/llm/`; adapters are flat siblings under the group. A new provider adapter joins here and registers on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for why two adapters exist.
+The interface lives at `llm/llm/`; adapters and the reusable token meter are flat siblings under the group. A new provider adapter joins here and registers on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for why two adapters exist and the [replay token meter RFC](../../docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership.

packages/llm/token-meter/README.md

@@ -0,0 +1,57 @@
+# @deepseek-ai/dsh-token-meter
+
+Replay-aware token measurement through `ctx.tokenMeter`. The service binds one stable meter to each configured model and advances isolated per-model/per-session folds from the durable session log. Compaction consumes it today; other pressure-sensitive plugins can reuse the same accounting without depending on `CompactService`.
+
+## Profiles and configuration
+
+The built-in `deepseek-v4-flash` and `deepseek-v4-pro` profiles each use a 128,000-token context window and four characters per estimated token. `models` merges overrides field-by-field, so changing only density keeps the built-in window. A custom model requires `contextWindow`; its `charsPerToken` defaults to `4`.
+
+| Key | Default | Contract |
+|---|---:|---|
+| `models.<built-in>.contextWindow` | `128000` | Positive integer provider capacity. |
+| `models.<model>.charsPerToken` | `4` | Positive finite heuristic density. |
+
+Resolving an unknown model throws `TokenMeterError` with code `TOKEN_METER_MODEL_UNCONFIGURED` and preserves the exact model name. Direct-construction profile validation uses `TOKEN_METER_INVALID_CONFIG`; Loader mounts first apply the package's Schemastery shape validation. There is no universal fallback window.
+
+## Measurement contract
+
+`ctx.tokenMeter.resolve(model)` returns a `ModelTokenMeter` with three operations:
+
+- `measure(session, requestHeader?)` returns scalar request pressure at one consumed-log revision.
+- `measureSurface(session)` returns current surface nodes and their per-node prices at the same kind of revision.
+- `estimateMessage(message)` prices one detached message under that profile.
+
+Measurements are detached and deeply immutable. A caller that needs a consistent scalar/surface decision compares their `logRevision` values instead of copying the full history on every read.
+
+The fold tracks request headers and deltas, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and assistant-chunk provenance. Provider usage is reused only when the handle's model and the canonical request envelope match the successful-call anchor. Otherwise the complete current envelope and surface are repriced under the requested model. Surface changes remain signed relative to a matching anchor, including negative deltas after shrinking replacements.
+
+Usage accounting sums disjoint input, cache-read, cache-write, and output buckets; reasoning is not added again. Every successful call records an assistant anchor, including content-less calls. An explicit empty provenance list means a known empty provider stream, while absent legacy provenance conservatively treats the durable assistant output as provider output.
+
+## Composition
+
+```yaml
+- name: '@deepseek-ai/dsh-token-meter'
+- name: '@deepseek-ai/dsh-compact-basic'
+```
+
+Both plugins have usable defaults for the bundled DeepSeek profiles. Custom deployments can override only the fields that differ:
+
+```yaml
+- name: '@deepseek-ai/dsh-token-meter'
+  config:
+    models:
+      deepseek-v4-flash:
+        charsPerToken: 2
+      local-model:
+        contextWindow: 32768
+```
+
+## Model Experience
+
+Indirectly, through consumers such as `dsh-compact-basic`; the service itself adds no prompt, message, schema, tool, or model call.
+
+## Known Limitations and Deferred Work
+
+- **Heuristic density still needs maintenance** — message content without provider usage is priced by configured character density plus structural overhead, not an exact provider tokenizer. CJK-heavy or provider-specific formats may need profile overrides.
+- **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, or call-config changes deliberately fall back to full heuristic repricing.
+- **Legacy provenance is conservative** — assistant messages without `sourceEventSeqs` cannot distinguish provider output from listener rewrites, so the fold avoids claiming a known empty or exact chunk stream.

packages/llm/token-meter/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@deepseek-ai/dsh-token-meter",
+  "description": "Replay-aware per-model token measurement service (ctx.tokenMeter) for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

packages/llm/token-meter/src/index.ts

@@ -0,0 +1,193 @@
+/**
+ * Replay token-meter service with model-specific context capacity and pricing.
+ *
+ * @module @deepseek-ai/dsh-token-meter
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import { HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { Session } from '@deepseek-ai/dsh-session'
+import { ReplayModelTokenMeter } from './replay.ts'
+import type { ModelTokenProfile } from './replay.ts'
+import type {
+  ModelTokenMeter,
+  ModelTokenMeterConfig,
+  TokenMeterConfig,
+} from './types.ts'
+
+export type * from './types.ts'
+
+/** Exact error code for resolving a model without a configured profile. */
+export const TOKEN_METER_MODEL_UNCONFIGURED = 'TOKEN_METER_MODEL_UNCONFIGURED'
+
+/** Exact error code for invalid token-meter configuration. */
+export const TOKEN_METER_INVALID_CONFIG = 'TOKEN_METER_INVALID_CONFIG'
+
+/** Closed machine-routable token-meter failure taxonomy. */
+export type TokenMeterErrorCode =
+  | typeof TOKEN_METER_MODEL_UNCONFIGURED
+  | typeof TOKEN_METER_INVALID_CONFIG
+
+/** Built-in DeepSeek model profiles available with zero configuration. */
+const BUILTIN_TOKEN_PROFILES: Readonly<Record<string, Readonly<ModelTokenProfile>>> = deepFreeze({
+  'deepseek-v4-flash': {
+    model: 'deepseek-v4-flash',
+    contextWindow: 128_000,
+    charsPerToken: 4,
+  },
+  'deepseek-v4-pro': {
+    model: 'deepseek-v4-pro',
+    contextWindow: 128_000,
+    charsPerToken: 4,
+  },
+})
+
+/** Typed token-meter failure with the affected model preserved for callers. */
+export class TokenMeterError extends HarnessError {
+  declare readonly code: TokenMeterErrorCode
+  /** Exact model name involved in this error, when applicable. */
+  readonly model: string | undefined
+
+  constructor(message: string, code: TokenMeterErrorCode, model?: string, options?: ErrorOptions) {
+    super(message, code, options)
+    this.name = 'TokenMeterError'
+    this.model = model
+  }
+}
+
+declare module 'cordis' {
+  interface Context {
+    tokenMeter: TokenMeterService
+  }
+}
+
+/** Validate and detach all configured model profiles. */
+function resolveProfiles(config: TokenMeterConfig): readonly ModelTokenProfile[] {
+  const profiles = new Map<string, ModelTokenProfile>()
+  for (const profile of Object.values(BUILTIN_TOKEN_PROFILES)) {
+    profiles.set(profile.model, { ...profile })
+  }
+
+  const configuredValue: unknown = config.models
+  const configuredModels = configuredValue === undefined ? {} : configuredValue
+  if (typeof configuredModels !== 'object'
+    || configuredModels === null
+    || Array.isArray(configuredModels)) {
+    throw new TokenMeterError(
+      'TokenMeterConfig: models must be an object',
+      TOKEN_METER_INVALID_CONFIG,
+    )
+  }
+
+  for (const [model, override] of Object.entries(configuredModels as Record<string, unknown>)) {
+    if (model.length === 0) {
+      throw new TokenMeterError(
+        'TokenMeterConfig: model names must not be empty',
+        TOKEN_METER_INVALID_CONFIG,
+        model,
+      )
+    }
+    assertProfileObject(model, override)
+    const builtIn = profiles.get(model)
+    const contextWindow = override.contextWindow ?? builtIn?.contextWindow
+    const charsPerToken = override.charsPerToken ?? builtIn?.charsPerToken ?? 4
+    if (contextWindow === undefined) {
+      throw new TokenMeterError(
+        `TokenMeterConfig: custom model "${model}" requires contextWindow`,
+        TOKEN_METER_INVALID_CONFIG,
+        model,
+      )
+    }
+    assertPositiveInteger(model, 'contextWindow', contextWindow)
+    assertPositiveFinite(model, 'charsPerToken', charsPerToken)
+    profiles.set(model, { model, contextWindow, charsPerToken })
+  }
+
+  for (const profile of profiles.values()) {
+    assertPositiveInteger(profile.model, 'contextWindow', profile.contextWindow)
+    assertPositiveFinite(profile.model, 'charsPerToken', profile.charsPerToken)
+  }
+  return deepFreeze([...profiles.values()].map(profile => ({ ...profile })))
+}
+
+function assertProfileObject(model: string, value: unknown): asserts value is ModelTokenMeterConfig {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new TokenMeterError(
+      `TokenMeterConfig: profile "${model}" must be an object`,
+      TOKEN_METER_INVALID_CONFIG,
+      model,
+    )
+  }
+}
+
+function assertPositiveInteger(model: string, name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new TokenMeterError(
+      `TokenMeterConfig: ${model}.${name} (${value}) must be a positive integer`,
+      TOKEN_METER_INVALID_CONFIG,
+      model,
+    )
+  }
+}
+
+function assertPositiveFinite(model: string, name: string, value: number): void {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+    throw new TokenMeterError(
+      `TokenMeterConfig: ${model}.${name} (${value}) must be a positive finite number`,
+      TOKEN_METER_INVALID_CONFIG,
+      model,
+    )
+  }
+}
+
+/** Concrete registry and replay owner for all configured model meters. */
+export class TokenMeterService extends Service {
+  static Config: z<TokenMeterConfig> = z.object({
+    models: z.dict(z.object({
+      contextWindow: z.number(),
+      charsPerToken: z.number(),
+    })),
+  })
+
+  private readonly meters = new Map<string, ReplayModelTokenMeter>()
+
+  constructor(ctx: Context, config: TokenMeterConfig = {}) {
+    super(ctx, 'tokenMeter')
+    for (const profile of resolveProfiles(config)) {
+      this.meters.set(profile.model, new ReplayModelTokenMeter(profile))
+    }
+
+    // Readers catch up independently, while eager observation bounds ordinary
+    // read latency. A reader in an earlier listener consumes the new event;
+    // this listener then sees the same revision and performs no duplicate fold.
+    ctx.on('session/event', (session) => {
+      this._observe(session)
+    })
+  }
+
+  /**
+   * Resolve one stable model-bound replay handle.
+   * @param model - exact routed model name.
+   * @throws {@link TokenMeterError} with `TOKEN_METER_MODEL_UNCONFIGURED` when no profile exists.
+   * @returns the configured handle for this model.
+   */
+  resolve(model: string): ModelTokenMeter {
+    const meter = this.meters.get(model)
+    if (meter === undefined) {
+      throw new TokenMeterError(
+        `token meter has no profile for model "${model}"`,
+        TOKEN_METER_MODEL_UNCONFIGURED,
+        model,
+      )
+    }
+    return meter
+  }
+
+  /** Advance every configured model's isolated replay fold. */
+  private _observe(session: Session): void {
+    for (const meter of this.meters.values()) meter.observeIfActive(session)
+  }
+}
+
+export default TokenMeterService

packages/llm/token-meter/src/replay.ts

@@ -0,0 +1,367 @@
+/**
+ * Model-bound transactional replay of request headers, surface mutations, and
+ * successful-call token anchors.
+ *
+ * @module @deepseek-ai/dsh-token-meter/replay
+ */
+
+import { BlockAssembler, deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, Session, SessionEvent, SurfaceEvent } from '@deepseek-ai/dsh-session'
+import { applyHeaderDelta, canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session'
+import type {
+  ModelTokenMeter,
+  TokenMeasurement,
+  TokenMeasurementBaseline,
+  TokenSurfaceMeasurement,
+  TokenSurfaceNode,
+} from './types.ts'
+
+/** Internal validated pricing profile. */
+export interface ModelTokenProfile {
+  readonly model: string
+  readonly contextWindow: number
+  readonly charsPerToken: number
+}
+
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4
+
+/** Role-field framing overhead added to every priced message. */
+const ROLE_OVERHEAD = 4
+
+interface UsageAnchor {
+  readonly header: EpochHeader
+  readonly surfaceTokens: number
+  readonly baseline: Exclude<TokenMeasurementBaseline, { kind: 'none' }>
+}
+
+interface ReplayState {
+  consumedEvents: number
+  header: EpochHeader | undefined
+  surface: TokenSurfaceNode[]
+  surfaceTokens: number
+  stepStart: { turn: number; step: number; surfaceTokens: number } | undefined
+  anchor: UsageAnchor | undefined
+}
+
+interface PreparedSurfaceMutation {
+  readonly tokens: number
+  commit(state: ReplayState): void
+}
+
+/** Sum disjoint provider usage buckets without double-counting reasoning output. */
+function usageTokens(usage: TokenUsage): number {
+  return usage.inputTokens
+    + (usage.cacheReadTokens ?? 0)
+    + (usage.cacheWriteTokens ?? 0)
+    + usage.outputTokens
+}
+
+/** One configured model's replay fold, weakly isolated by session identity. */
+export class ReplayModelTokenMeter implements ModelTokenMeter {
+  readonly model: string
+  readonly contextWindow: number
+  readonly charsPerToken: number
+
+  private readonly states = new WeakMap<Session, ReplayState>()
+
+  constructor(profile: ModelTokenProfile) {
+    this.model = profile.model
+    this.contextWindow = profile.contextWindow
+    this.charsPerToken = profile.charsPerToken
+  }
+
+  /**
+   * Advance an already-read model/session fold without creating unused state.
+   * @param session - session whose durable tail advanced.
+   */
+  observeIfActive(session: Session): void {
+    if (this.states.has(session)) this._sync(session)
+  }
+
+  /** @inheritdoc */
+  estimateMessage(message: Message): number {
+    return this._estimateContent(message.content) + ROLE_OVERHEAD
+  }
+
+  /** @inheritdoc */
+  measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement {
+    const state = this._sync(session)
+    const header = requestHeader === undefined
+      ? state.header
+      : canonicalHeader(requestHeader)
+    const anchor = state.anchor
+
+    let baseline: TokenMeasurementBaseline
+    let surfaceDeltaTokens: number
+    if (anchor !== undefined && header !== undefined && headerEquals(anchor.header, header)) {
+      baseline = anchor.baseline
+      surfaceDeltaTokens = state.surfaceTokens - anchor.surfaceTokens
+    } else if (header === undefined && state.surfaceTokens === 0) {
+      baseline = { kind: 'none', tokens: 0 }
+      surfaceDeltaTokens = 0
+    } else {
+      baseline = {
+        kind: 'estimated',
+        tokens: this._estimateHeader(header) + state.surfaceTokens,
+      }
+      surfaceDeltaTokens = 0
+    }
+
+    return deepFreeze(structuredClone({
+      model: this.model,
+      logRevision: state.consumedEvents,
+      baseline,
+      surfaceDeltaTokens,
+      totalTokens: Math.max(0, baseline.tokens + surfaceDeltaTokens),
+    }))
+  }
+
+  /** @inheritdoc */
+  measureSurface(session: Session): TokenSurfaceMeasurement {
+    const state = this._sync(session)
+    return deepFreeze(structuredClone({
+      model: this.model,
+      logRevision: state.consumedEvents,
+      totalTokens: state.surfaceTokens,
+      nodes: state.surface,
+    }))
+  }
+
+  /** Catch one session's fold up to the current durable tail. */
+  private _sync(session: Session): ReplayState {
+    let state = this.states.get(session)
+    if (state === undefined) {
+      state = {
+        consumedEvents: 0,
+        header: undefined,
+        surface: [],
+        surfaceTokens: 0,
+        stepStart: undefined,
+        anchor: undefined,
+      }
+      this.states.set(session, state)
+    }
+
+    while (state.consumedEvents < session.events.length) {
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- contiguous session seqs index the durable log
+      const event = session.events[state.consumedEvents]!
+      this._foldEvent(session, state, event)
+      state.consumedEvents += 1
+    }
+    return state
+  }
+
+  /**
+   * Validate and prepare every fallible part before mutating replay state.
+   * A malformed event therefore remains the next unread event on every retry
+   * instead of applying a partial surface mutation twice.
+   */
+  private _foldEvent(session: Session, state: ReplayState, event: SessionEvent): void {
+    let nextHeader = state.header
+    let nextStepStart = state.stepStart
+    let nextAnchor = state.anchor
+
+    switch (event.type) {
+      case 'request/header':
+        nextHeader = canonicalHeader(event.data.header)
+        break
+      case 'request/header-delta':
+        if (state.header === undefined) {
+          throw new Error(`token meter: request/header-delta at seq ${event.seq} has no preceding header`)
+        }
+        nextHeader = applyHeaderDelta(state.header, event.data)
+        break
+      case 'step/start':
+        if (state.stepStart !== undefined) {
+          throw new Error(
+            `token meter: step/start at seq ${event.seq} arrived before turn ${state.stepStart.turn}/step ${state.stepStart.step} ended`,
+          )
+        }
+        nextStepStart = { ...event.data, surfaceTokens: state.surfaceTokens }
+        break
+      case 'step/end':
+        if (state.stepStart === undefined
+          || state.stepStart.turn !== event.data.turn
+          || state.stepStart.step !== event.data.step) {
+          throw new Error(`token meter: step/end at seq ${event.seq} has no matching step/start boundary`)
+        }
+        nextStepStart = undefined
+        break
+      default:
+        break
+    }
+
+    const surface = isSurfaceEvent(event)
+      ? this._prepareSurfaceMutation(session, state, event)
+      : undefined
+
+    if (event.type === 'assistant/message' && nextHeader?.config.model === this.model) {
+      const stepStart = state.stepStart
+      if (stepStart === undefined
+        || stepStart.turn !== event.data.turn
+        || stepStart.step !== event.data.step) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} has no matching step/start boundary`)
+      }
+
+      // assistant/message is surface-mandatory at every append/seed boundary.
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const eventTokens = surface!.tokens
+      if (event.data.usage !== undefined) {
+        const providerAssistantTokens = this._estimateProviderAssistant(
+          session,
+          event,
+          eventTokens,
+        )
+        nextAnchor = {
+          header: nextHeader,
+          surfaceTokens: stepStart.surfaceTokens + providerAssistantTokens,
+          baseline: {
+            kind: 'usage',
+            tokens: usageTokens(event.data.usage),
+            usage: event.data.usage,
+          },
+        }
+      } else {
+        const anchorSurfaceTokens = stepStart.surfaceTokens + eventTokens
+        nextAnchor = {
+          header: nextHeader,
+          surfaceTokens: anchorSurfaceTokens,
+          baseline: {
+            kind: 'estimated',
+            tokens: this._estimateHeader(nextHeader) + anchorSurfaceTokens,
+          },
+        }
+      }
+    }
+
+    state.header = nextHeader
+    state.stepStart = nextStepStart
+    if (surface !== undefined) surface.commit(state)
+    state.anchor = nextAnchor
+  }
+
+  /** Validate one surface operation and return its allocation-light commit. */
+  private _prepareSurfaceMutation(
+    session: Session,
+    state: ReplayState,
+    event: SurfaceEvent,
+  ): PreparedSurfaceMutation {
+    const tokens = this._estimateSurfaceEvent(session, event)
+    const op = event.surfaceOp
+    if (op === 'append') {
+      return {
+        tokens,
+        commit(target) {
+          target.surface.push({ seq: event.seq, tokens })
+          target.surfaceTokens += tokens
+        },
+      }
+    }
+
+    const startIdx = state.surface.findIndex(node => node.seq === op.start)
+    const endIdx = state.surface.findIndex(node => node.seq === op.end)
+    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+      throw new Error(
+        `token meter: replace at seq ${event.seq} has invalid current range ${op.start}-${op.end}`,
+      )
+    }
+    const removedTokens = state.surface
+      .slice(startIdx, endIdx + 1)
+      .reduce((total, node) => total + node.tokens, 0)
+    return {
+      tokens,
+      commit(target) {
+        target.surface.splice(startIdx, endIdx - startIdx + 1, { seq: event.seq, tokens })
+        target.surfaceTokens += tokens - removedTokens
+      },
+    }
+  }
+
+  /** Price one current surface event exactly as it projects to a request. */
+  private _estimateSurfaceEvent(session: Session, event: SurfaceEvent): number {
+    const message = session.deriveEventMessage(event)
+    return message === null ? 0 : this.estimateMessage(message)
+  }
+
+  /**
+   * Reassemble provider output from exact chunk provenance for a usage anchor.
+   * Missing legacy provenance conservatively treats the durable output as the
+   * provider output; explicit empty provenance prices a known empty stream.
+   */
+  private _estimateProviderAssistant(
+    session: Session,
+    event: SessionEvent<'assistant/message'>,
+    durableEventTokens: number,
+  ): number {
+    const sourceSeqs = event.sourceEventSeqs
+    if (sourceSeqs === undefined) return durableEventTokens
+
+    const assembler = new BlockAssembler()
+    const seen = new Set<number>()
+    for (const seq of sourceSeqs) {
+      if (seq >= event.seq) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not earlier`)
+      }
+      if (seen.has(seq)) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} repeats source seq ${seq}`)
+      }
+      seen.add(seq)
+      // Session construction validates contiguous seqs, and the explicit
+      // earlier-than-assistant check above therefore guarantees existence.
+      const source = session.events[seq]
+      // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+      const sourceEvent = source!
+      if (sourceEvent.type !== 'assistant/chunk') {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} is not assistant/chunk`)
+      }
+      if (sourceEvent.data.turn !== event.data.turn || sourceEvent.data.step !== event.data.step) {
+        throw new Error(`token meter: assistant/message at seq ${event.seq} source seq ${seq} belongs to another step`)
+      }
+      assembler.push(sourceEvent.data.chunk)
+    }
+    const providerMessage = assembler.message()
+    return providerMessage.content.length === 0 ? 0 : this.estimateMessage(providerMessage)
+  }
+
+  /** Price content blocks recursively under this model's density profile. */
+  private _estimateContent(blocks: readonly ContentBlock[]): number {
+    let tokens = 0
+    for (const block of blocks) {
+      switch (block.type) {
+        case 'text':
+        case 'reasoning':
+          tokens += Math.ceil(block.text.length / this.charsPerToken) + BLOCK_OVERHEAD
+          break
+        case 'tool-call':
+          tokens += Math.ceil(block.name.length / this.charsPerToken)
+            + Math.ceil(block.arguments.length / this.charsPerToken)
+            + BLOCK_OVERHEAD
+          break
+        case 'tool-result':
+          tokens += this._estimateContent(block.content) + BLOCK_OVERHEAD
+          break
+        default:
+          // ContentBlockMap is merge-extensible; unknown blocks retain a
+          // conservative structural JSON price under the selected profile.
+          tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / this.charsPerToken)
+      }
+    }
+    return tokens
+  }
+
+  /** Price the canonical non-surface request envelope. */
+  private _estimateHeader(header: EpochHeader | undefined): number {
+    if (header === undefined) return 0
+    let tokens = 0
+    for (const message of header.messagePrefix ?? []) tokens += this.estimateMessage(message)
+    if (header.system !== undefined) {
+      tokens += Math.ceil(header.system.length / this.charsPerToken) + ROLE_OVERHEAD
+    }
+    if (header.tools !== undefined && header.tools.length > 0) {
+      tokens += Math.ceil(JSON.stringify(header.tools).length / this.charsPerToken) + BLOCK_OVERHEAD
+    }
+    return tokens
+  }
+}

packages/llm/token-meter/src/types.ts

@@ -0,0 +1,101 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @deepseek-ai/dsh-token-meter/types
+ */
+
+import type { Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { EpochHeader, Session } from '@deepseek-ai/dsh-session'
+
+/** Optional pricing fields for one configured model. */
+export interface ModelTokenMeterConfig {
+  /** Provider context-window capacity in tokens. Required for a custom model. */
+  contextWindow?: number
+  /** Heuristic text density in characters per token. Defaults to `4`. */
+  charsPerToken?: number
+}
+
+/** Token-meter plugin configuration. */
+export interface TokenMeterConfig {
+  /** Built-in field overrides and custom model profiles, keyed by routed model name. */
+  models?: Record<string, ModelTokenMeterConfig>
+}
+
+/** The baseline from which a signed surface delta produces current pressure. */
+export type TokenMeasurementBaseline =
+  | { readonly kind: 'none'; readonly tokens: 0 }
+  | { readonly kind: 'estimated'; readonly tokens: number }
+  | { readonly kind: 'usage'; readonly tokens: number; readonly usage: Readonly<TokenUsage> }
+
+/** Detached immutable scalar pressure at one consumed session-log revision. */
+export interface TokenMeasurement {
+  /** Model profile used for every heuristic component. */
+  readonly model: string
+  /** Number of durable events consumed; equal to the next unread event seq. */
+  readonly logRevision: number
+  /** Provider or heuristic anchor used for this measurement. */
+  readonly baseline: TokenMeasurementBaseline
+  /** Signed repricing of current surface content relative to the baseline anchor. */
+  readonly surfaceDeltaTokens: number
+  /** Non-negative current request-and-response pressure. */
+  readonly totalTokens: number
+}
+
+/** One token-priced node in the current ordered session surface. */
+export interface TokenSurfaceNode {
+  /** Durable sequence number of the surface event. */
+  readonly seq: number
+  /** Heuristic tokens for the exact message projected by this node. */
+  readonly tokens: number
+}
+
+/** Detached immutable priced surface at one consumed session-log revision. */
+export interface TokenSurfaceMeasurement {
+  /** Model profile used to price every node. */
+  readonly model: string
+  /** Number of durable events consumed; equal to the next unread event seq. */
+  readonly logRevision: number
+  /** Total heuristic tokens across the current surface. */
+  readonly totalTokens: number
+  /** Current surface nodes in positional head-to-tail order. */
+  readonly nodes: readonly TokenSurfaceNode[]
+}
+
+/** A model-bound replay meter returned by {@link TokenMeterService.resolve}. */
+export interface ModelTokenMeter {
+  /** Routed model name bound to this handle. */
+  readonly model: string
+  /** Provider context-window capacity in tokens. */
+  readonly contextWindow: number
+  /** Heuristic text density in characters per token. */
+  readonly charsPerToken: number
+
+  /**
+   * Measure current request pressure through the session's durable tail.
+   *
+   * Provider usage is reused only when its routed model and canonical request
+   * envelope match `requestHeader`; otherwise the complete envelope and
+   * surface are heuristically repriced for this handle's model.
+   *
+   * @param session - session to replay through its current durable tail.
+   * @param requestHeader - optional effective request envelope replacing the latest logged header.
+   * @returns a detached deeply immutable pressure measurement.
+   */
+  measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
+
+  /**
+   * Price the current surface for retention and replacement decisions.
+   *
+   * @param session - session to replay through its current durable tail.
+   * @returns a detached deeply immutable positional surface measurement.
+   */
+  measureSurface(session: Session): TokenSurfaceMeasurement
+
+  /**
+   * Heuristically price one model-visible message.
+   *
+   * @param message - message to price without mutation.
+   * @returns content and role-framing tokens under this model profile.
+   */
+  estimateMessage(message: Message): number
+}

packages/llm/token-meter/tests/token-meter.spec.ts

@@ -0,0 +1,603 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
+import SessionStore, { Session, SessionId, canonicalHeader } from '@deepseek-ai/dsh-session'
+import type { EpochHeader } from '@deepseek-ai/dsh-session'
+import TokenMeterService, {
+  TOKEN_METER_INVALID_CONFIG,
+  TOKEN_METER_MODEL_UNCONFIGURED,
+  TokenMeterError,
+} from '@deepseek-ai/dsh-token-meter'
+import type { ModelTokenMeter, TokenMeterConfig } from '@deepseek-ai/dsh-token-meter'
+
+function header(model: string, extras: Omit<EpochHeader, 'config'> = {}): EpochHeader {
+  return canonicalHeader({ config: { model }, ...extras })
+}
+
+function textMessage(text: string, role: Message['role'] = 'user'): Message {
+  return { role, content: [{ type: 'text', text }] }
+}
+
+function appendHeader(session: Session, value: EpochHeader): void {
+  session.append('request/header', { header: value, reason: 'initial' })
+}
+
+interface SuccessfulCallOptions {
+  turn?: number
+  step?: number
+  providerText?: string
+  durableText?: string
+  usage?: TokenUsage
+  provenance?: 'exact' | 'empty' | 'absent'
+}
+
+function appendSuccessfulCall(
+  session: Session,
+  value: EpochHeader,
+  options: SuccessfulCallOptions = {},
+): void {
+  const turn = options.turn ?? 1
+  const step = options.step ?? 1
+  const providerText = options.providerText ?? 'provider answer'
+  const durableText = options.durableText ?? providerText
+  const provenance = options.provenance ?? 'exact'
+  session.append('step/start', { turn, step })
+  appendHeader(session, value)
+
+  const sources: number[] = []
+  if (provenance === 'exact') {
+    const chunks = [
+      { type: 'block-start' as const, index: 0, blockType: 'text' as const },
+      { type: 'text-delta' as const, index: 0, text: providerText },
+      { type: 'block-end' as const, index: 0, block: { type: 'text' as const, text: providerText } },
+      ...options.usage === undefined ? [] : [{ type: 'usage' as const, usage: options.usage }],
+      { type: 'finish' as const, reason: { kind: 'stop' as const } },
+    ]
+    for (const chunk of chunks) {
+      sources.push(session.append('assistant/chunk', { turn, step, chunk }).seq)
+    }
+  }
+
+  const intent = provenance === 'absent'
+    ? { surfaceOp: 'append' as const }
+    : { surfaceOp: 'append' as const, sourceEventSeqs: provenance === 'empty' ? [] : sources }
+  session.append('assistant/message', {
+    turn,
+    step,
+    content: durableText.length === 0 ? [] : [{ type: 'text', text: durableText }],
+    ...options.usage === undefined ? {} : { usage: options.usage },
+  }, intent)
+  session.append('step/end', { turn, step })
+}
+
+function meter(config: TokenMeterConfig = {}): TokenMeterService {
+  return new TokenMeterService(new Context(), config)
+}
+
+describe('TokenMeterService configuration and registration', () => {
+  it('provides immutable zero-config DeepSeek profiles', () => {
+    const service = meter()
+    expect(service.resolve('deepseek-v4-flash')).toMatchObject({
+      model: 'deepseek-v4-flash',
+      contextWindow: 128_000,
+      charsPerToken: 4,
+    })
+    expect(service.resolve('deepseek-v4-pro')).toMatchObject({
+      model: 'deepseek-v4-pro',
+      contextWindow: 128_000,
+      charsPerToken: 4,
+    })
+  })
+
+  it('merges built-in overrides field-wise and defaults custom density', () => {
+    const service = meter({
+      models: {
+        'deepseek-v4-flash': { charsPerToken: 2 },
+        custom: { contextWindow: 32_000 },
+      },
+    })
+    expect(service.resolve('deepseek-v4-flash')).toMatchObject({ contextWindow: 128_000, charsPerToken: 2 })
+    expect(service.resolve('deepseek-v4-pro')).toMatchObject({ contextWindow: 128_000, charsPerToken: 4 })
+    expect(service.resolve('custom')).toMatchObject({ contextWindow: 32_000, charsPerToken: 4 })
+  })
+
+  it('throws a typed exact-code error for unknown models', () => {
+    const service = meter()
+    let thrown: unknown
+    try {
+      service.resolve('unconfigured-model')
+    } catch (error: unknown) {
+      thrown = error
+    }
+    expect(thrown).toBeInstanceOf(TokenMeterError)
+    expect(thrown).toMatchObject({
+      code: TOKEN_METER_MODEL_UNCONFIGURED,
+      model: 'unconfigured-model',
+    })
+    expect((thrown as Error).message).toContain('unconfigured-model')
+  })
+
+  it.each([
+    [{ models: null }, /models must be an object/],
+    [{ models: [] }, /models must be an object/],
+    [{ models: { custom: {} } }, /requires contextWindow/],
+    [{ models: { '': { contextWindow: 1 } } }, /must not be empty/],
+    [{ models: { custom: { contextWindow: 0 } } }, /positive integer/],
+    [{ models: { custom: { contextWindow: 1.5 } } }, /positive integer/],
+    [{ models: { custom: { contextWindow: 1, charsPerToken: 0 } } }, /positive finite/],
+    [{ models: { custom: { contextWindow: 1, charsPerToken: Number.NaN } } }, /positive finite/],
+    [{ models: { custom: null } }, /must be an object/],
+    [{ models: { custom: [] } }, /must be an object/],
+  ] as unknown as Array<[TokenMeterConfig, RegExp]>)('rejects invalid profile config %#', (config, pattern) => {
+    let thrown: unknown
+    try {
+      meter(config)
+    } catch (error: unknown) {
+      thrown = error
+    }
+    expect(thrown).toBeInstanceOf(TokenMeterError)
+    expect(thrown).toMatchObject({ code: TOKEN_METER_INVALID_CONFIG })
+    expect((thrown as Error).message).toMatch(pattern)
+  })
+
+  it('registers and unregisters ctx.tokenMeter with its plugin fiber', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const fiber = await ctx.plugin(TokenMeterService)
+    expect(ctx.get('tokenMeter')).toBeInstanceOf(TokenMeterService)
+    await fiber.dispose()
+    expect(ctx.get('tokenMeter')).toBeUndefined()
+  })
+})
+
+describe('ModelTokenMeter pricing', () => {
+  it('prices every built-in content shape and merge-extended blocks', () => {
+    const handle = meter({ models: { custom: { contextWindow: 100, charsPerToken: 2 } } }).resolve('custom')
+    const blocks: ContentBlock[] = [
+      { type: 'text', text: 'abcd' },
+      { type: 'reasoning', text: 'ab' },
+      { type: 'tool-call', id: CallId('c'), name: 'read', arguments: '{"x":1}' },
+      {
+        type: 'tool-result',
+        toolCallId: CallId('c'),
+        content: [{ type: 'text', text: 'xy' }],
+        isError: false,
+      },
+      { type: 'future-block', payload: 'abcd' } as unknown as ContentBlock,
+    ]
+    const estimated = handle.estimateMessage({ role: 'assistant', content: blocks })
+    expect(estimated).toBeGreaterThan(30)
+    expect(handle.estimateMessage(textMessage('abcd'))).toBe(10)
+  })
+
+  it('returns a detached deeply immutable empty measurement', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('empty'))
+    const result = handle.measure(session)
+    expect(result).toEqual({
+      model: 'deepseek-v4-flash',
+      logRevision: 0,
+      baseline: { kind: 'none', tokens: 0 },
+      surfaceDeltaTokens: 0,
+      totalTokens: 0,
+    })
+    expect(Object.isFrozen(result)).toBe(true)
+    expect(Object.isFrozen(result.baseline)).toBe(true)
+    expect(() => {
+      ;(result as { totalTokens: number }).totalTokens = 1
+    }).toThrow(TypeError)
+  })
+
+  it('keeps earlier scalar and surface snapshots detached from later replay', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('detached'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'first' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const scalar = handle.measure(session)
+    const surface = handle.measureSurface(session)
+    const scalarCopy = structuredClone(scalar)
+    const surfaceCopy = structuredClone(surface)
+
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'second' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(handle.measure(session).logRevision).toBe(2)
+    expect(handle.measureSurface(session).nodes).toHaveLength(2)
+    expect(scalar).toEqual(scalarCopy)
+    expect(surface).toEqual(surfaceCopy)
+    expect(scalar.logRevision).toBe(1)
+    expect(surface.nodes).toHaveLength(1)
+  })
+
+  it('prices header, prefix, tools, and surface when no reusable usage exists', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('heuristic'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'question' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendHeader(session, header('deepseek-v4-flash', {
+      system: 'system',
+      messagePrefix: [textMessage('prefix')],
+      tools: [{ name: 'read', description: 'read', parameters: { type: 'object' } }],
+    }))
+    const result = handle.measure(session)
+    expect(result.baseline.kind).toBe('estimated')
+    expect(result.totalTokens).toBeGreaterThan(handle.measureSurface(session).totalTokens)
+    expect(result.logRevision).toBe(session.events.length)
+  })
+})
+
+describe('replay anchors and surface folds', () => {
+  const USAGE: TokenUsage = {
+    inputTokens: 20,
+    cacheReadTokens: 3,
+    cacheWriteTokens: 4,
+    outputTokens: 7,
+    reasoningTokens: 6,
+  }
+
+  it('uses disjoint provider usage and signed durable-output rewrites', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('usage'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'before' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendSuccessfulCall(session, header('deepseek-v4-flash'), {
+      providerText: 'short',
+      durableText: 'a much longer rewritten durable assistant answer',
+      usage: USAGE,
+    })
+    const result = handle.measure(session)
+    expect(result.baseline).toMatchObject({ kind: 'usage', tokens: 34, usage: USAGE })
+    expect(result.surfaceDeltaTokens).toBeGreaterThan(0)
+    expect(result.totalTokens).toBe(34 + result.surfaceDeltaTokens)
+    expect(() => {
+      ;((result.baseline as { usage: { inputTokens: number } }).usage.inputTokens) = 1
+    }).toThrow(TypeError)
+  })
+
+  it('uses an estimated anchor when provider usage is absent', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('missing-usage'))
+    appendSuccessfulCall(session, header('deepseek-v4-flash', { system: 's' }), {
+      providerText: 'provider',
+      durableText: 'rewritten',
+    })
+    const anchored = handle.measure(session)
+    expect(anchored.baseline.kind).toBe('estimated')
+    expect(anchored.surfaceDeltaTokens).toBe(0)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'later' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const advanced = handle.measure(session)
+    expect(advanced.surfaceDeltaTokens).toBeGreaterThan(0)
+  })
+
+  it('distinguishes explicit empty provenance from absent legacy provenance', () => {
+    const explicit = new Session(SessionId('explicit-empty'))
+    const legacy = new Session(SessionId('legacy-absent'))
+    appendSuccessfulCall(explicit, header('deepseek-v4-flash'), {
+      durableText: 'listener injected text',
+      providerText: '',
+      usage: USAGE,
+      provenance: 'empty',
+    })
+    appendSuccessfulCall(legacy, header('deepseek-v4-flash'), {
+      durableText: 'listener injected text',
+      providerText: '',
+      usage: USAGE,
+      provenance: 'absent',
+    })
+    const handle = meter().resolve('deepseek-v4-flash')
+    expect(handle.measure(explicit).surfaceDeltaTokens).toBeGreaterThan(0)
+    expect(handle.measure(legacy).surfaceDeltaTokens).toBe(0)
+  })
+
+  it('preserves one model anchor across another model success and reuses it after switching back', () => {
+    const service = meter({
+      models: {
+        alpha: { contextWindow: 1000 },
+        beta: { contextWindow: 1000, charsPerToken: 2 },
+      },
+    })
+    const alpha = service.resolve('alpha')
+    const beta = service.resolve('beta')
+    const session = new Session(SessionId('switch'))
+    const alphaHeader = header('alpha', { system: 'same envelope' })
+    appendSuccessfulCall(session, alphaHeader, { usage: USAGE, providerText: 'alpha' })
+    expect(alpha.measure(session).baseline.kind).toBe('usage')
+
+    appendSuccessfulCall(session, header('beta'), {
+      turn: 1,
+      step: 2,
+      usage: { inputTokens: 100, outputTokens: 50 },
+      providerText: 'beta response',
+    })
+    expect(alpha.measure(session).baseline.kind).toBe('estimated')
+    expect(beta.measure(session).baseline).toMatchObject({ kind: 'usage', tokens: 150 })
+
+    appendHeader(session, alphaHeader)
+    const switchedBack = alpha.measure(session)
+    expect(switchedBack.baseline).toMatchObject({ kind: 'usage', tokens: 34 })
+    expect(switchedBack.surfaceDeltaTokens).toBeGreaterThan(0)
+  })
+
+  it('invalidates usage for any canonical envelope change or explicit override', () => {
+    const handle = meter().resolve('deepseek-v4-flash')
+    const session = new Session(SessionId('envelope'))
+    const anchoredHeader = header('deepseek-v4-flash', { system: 'one' })
+    appendSuccessfulCall(session, anchoredHeader, { usage: USAGE })
+    expect(handle.measure(session, { ...anchoredHeader, tools: [] }).baseline.kind).toBe('usage')
+    expect(handle.measure(session, header('deepseek-v4-flash', { system: 'two' })).baseline.kind)
+      .toBe('estimated')
+    expect(handle.measure(session, header('deepseek-v4-pro', { system: 'one' })).baseline.kind)
+      .toBe('estimated')
+    expect(handle.measure(session, {
+      ...anchoredHeader,
+      config: { ...anchoredHeader.config, temperature: 0.2 },
+    }).baseline.kind).toBe('estimated')
+    expect(handle.measure(session, {
+      ...anchoredHeader,
+      messagePrefix: [textMessage('prefix')],
+    }).baseline.kind).toBe('estimated')
+    expect(handle.measure(session, {
+      ...anchoredHeader,
+      tools: [{ name: 'read', description: 'read', parameters: { type: 'object' } }],
+    }).baseline.kind).toBe('estimated')
+  })
+
+  it('folds valid header deltas into the effective envelope', () => {
+    const session = new Session(SessionId('header-delta'))
+    appendHeader(session, header('deepseek-v4-flash'))
+    session.append('request/header-delta', { config: { model: 'deepseek-v4-pro' } })
+    const result = meter().resolve('deepseek-v4-flash').measure(session)
+    expect(result.baseline.kind).toBe('estimated')
+    expect(result.logRevision).toBe(2)
+  })
+
+  it('replays seeded append and replace operations with signed deltas', () => {
+    const service = meter()
+    const original = new Session(SessionId('surface-original'))
+    appendSuccessfulCall(original, header('deepseek-v4-flash'), {
+      usage: USAGE,
+      providerText: 'long provider answer '.repeat(100),
+    })
+    original.append('user/message', {
+      content: [{ type: 'text', text: 'new tail' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    const seeded = new Session(SessionId('surface-seeded'), original.events)
+    const handle = service.resolve('deepseek-v4-flash')
+    const before = handle.measureSurface(seeded)
+    const beforeScalar = handle.measure(seeded)
+    expect(before.nodes).toHaveLength(2)
+    expect(beforeScalar.surfaceDeltaTokens).toBeGreaterThan(0)
+
+    const first = seeded.surface.nodes[0]!.seq
+    seeded.append('user/message', {
+      content: [{ type: 'text', text: 'replacement' }],
+      source: { kind: 'plugin', plugin: 'test' },
+    }, { surfaceOp: { op: 'replace', start: first, end: first }, sourceEventSeqs: [first] })
+    const after = handle.measureSurface(seeded)
+    const afterScalar = handle.measure(seeded)
+    expect(after.nodes).toHaveLength(2)
+    expect(after.nodes[0]!.seq).toBe(seeded.events.length - 1)
+    expect(after.logRevision).toBe(seeded.events.length)
+    expect(Object.isFrozen(after.nodes)).toBe(true)
+    expect(Object.isFrozen(after.nodes[0])).toBe(true)
+    expect(afterScalar.surfaceDeltaTokens).toBeLessThan(0)
+    expect(before.nodes).toHaveLength(2)
+    expect(before.logRevision).toBe(original.events.length)
+    expect(beforeScalar.surfaceDeltaTokens).toBeGreaterThan(0)
+  })
+
+  it('prices an empty assistant surface anchor as zero', () => {
+    const session = new Session(SessionId('empty-assistant'))
+    appendSuccessfulCall(session, header('deepseek-v4-flash'), {
+      providerText: '',
+      durableText: '',
+      provenance: 'empty',
+    })
+    const surface = meter().resolve('deepseek-v4-flash').measureSurface(session)
+    const assistant = session.events.find(event => event.type === 'assistant/message')!
+    expect(surface.nodes).toEqual([{ seq: assistant.seq, tokens: 0 }])
+    expect(surface.totalTokens).toBe(0)
+  })
+})
+
+describe('malformed replay and listener lifecycle', () => {
+  function expectRepeatedFailure(handle: ModelTokenMeter, session: Session, pattern: RegExp): void {
+    expect(() => handle.measure(session)).toThrow(pattern)
+    expect(() => handle.measure(session)).toThrow(pattern)
+  }
+
+  it('rejects a header delta before any snapshot transactionally', () => {
+    const session = new Session(SessionId('bad-delta'))
+    session.append('request/header-delta', { config: { model: 'deepseek-v4-flash' } })
+    expectRepeatedFailure(meter().resolve('deepseek-v4-flash'), session, /no preceding header/)
+  })
+
+  it('rejects a matching-model assistant without its step boundary transactionally', () => {
+    const session = new Session(SessionId('bad-step'))
+    appendHeader(session, header('deepseek-v4-flash'))
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'bad' }],
+    }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    expectRepeatedFailure(meter().resolve('deepseek-v4-flash'), session, /no matching step\/start/)
+  })
+
+  it('clears completed step boundaries and rejects overlapping or late step events', () => {
+    const overlapping = new Session(SessionId('overlapping-step'))
+    overlapping.append('step/start', { turn: 1, step: 1 })
+    overlapping.append('step/start', { turn: 1, step: 2 })
+    expectRepeatedFailure(
+      meter().resolve('deepseek-v4-flash'),
+      overlapping,
+      /arrived before turn 1\/step 1 ended/,
+    )
+
+    const late = new Session(SessionId('late-assistant'))
+    late.append('step/start', { turn: 1, step: 1 })
+    appendHeader(late, header('deepseek-v4-flash'))
+    late.append('step/end', { turn: 1, step: 1 })
+    late.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [],
+    }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    expectRepeatedFailure(
+      meter().resolve('deepseek-v4-flash'),
+      late,
+      /no matching step\/start/,
+    )
+
+    const mismatchedEnd = new Session(SessionId('mismatched-end'))
+    mismatchedEnd.append('step/start', { turn: 1, step: 1 })
+    mismatchedEnd.append('step/end', { turn: 1, step: 2 })
+    expectRepeatedFailure(
+      meter().resolve('deepseek-v4-flash'),
+      mismatchedEnd,
+      /step\/end .* no matching step\/start/,
+    )
+  })
+
+  it('rejects invalid assistant provenance', () => {
+    const cases: Array<{
+      name: string
+      appendSource(session: Session): number[]
+      pattern: RegExp
+    }> = [
+      {
+        name: 'non-chunk',
+        appendSource(session) {
+          return [session.append('user/message', {
+            content: [{ type: 'text', text: 'x' }],
+            source: { kind: 'user' },
+          }, { surfaceOp: 'append' }).seq]
+        },
+        pattern: /is not assistant\/chunk/,
+      },
+      {
+        name: 'wrong-step',
+        appendSource(session) {
+          return [session.append('assistant/chunk', {
+            turn: 1,
+            step: 2,
+            chunk: { type: 'finish', reason: { kind: 'stop' } },
+          }).seq]
+        },
+        pattern: /belongs to another step/,
+      },
+    ]
+    for (const testCase of cases) {
+      const session = new Session(SessionId(`bad-source-${testCase.name}`))
+      session.append('step/start', { turn: 1, step: 1 })
+      appendHeader(session, header('deepseek-v4-flash'))
+      const sourceEventSeqs = testCase.appendSource(session)
+      session.append('assistant/message', {
+        turn: 1,
+        step: 1,
+        content: [{ type: 'text', text: 'bad' }],
+        usage: { inputTokens: 1, outputTokens: 1 },
+      }, { surfaceOp: 'append', sourceEventSeqs })
+      expect(() => meter().resolve('deepseek-v4-flash').measure(session)).toThrow(testCase.pattern)
+    }
+  })
+
+  it('rejects repeated and non-earlier assistant provenance', () => {
+    const duplicate = new Session(SessionId('duplicate-source'))
+    duplicate.append('step/start', { turn: 1, step: 1 })
+    appendHeader(duplicate, header('deepseek-v4-flash'))
+    const source = duplicate.append('assistant/chunk', {
+      turn: 1,
+      step: 1,
+      chunk: { type: 'finish', reason: { kind: 'stop' } },
+    }).seq
+    duplicate.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [],
+      usage: { inputTokens: 1, outputTokens: 0 },
+    }, { surfaceOp: 'append', sourceEventSeqs: [source, source] })
+    expect(() => meter().resolve('deepseek-v4-flash').measure(duplicate)).toThrow(/repeats source seq/)
+
+    const future = new Session(SessionId('future-source'))
+    future.append('step/start', { turn: 1, step: 1 })
+    appendHeader(future, header('deepseek-v4-flash'))
+    future.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [],
+      usage: { inputTokens: 1, outputTokens: 0 },
+    }, { surfaceOp: 'append', sourceEventSeqs: [99] })
+    expect(() => meter().resolve('deepseek-v4-flash').measure(future)).toThrow(/is not earlier/)
+  })
+
+  it('does not partially apply a malformed assistant replacement', () => {
+    const session = new Session(SessionId('transactional-replace'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'head' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    appendHeader(session, header('deepseek-v4-flash'))
+    const head = session.events[0]!.seq
+    session.append('assistant/message', {
+      turn: 1,
+      step: 1,
+      content: [{ type: 'text', text: 'replacement' }],
+    }, { surfaceOp: { op: 'replace', start: head, end: head }, sourceEventSeqs: [head] })
+    expectRepeatedFailure(
+      meter().resolve('deepseek-v4-flash'),
+      session,
+      /no matching step\/start/,
+    )
+  })
+
+  it('rejects corrupt replacement ranges without advancing the replay cursor', () => {
+    const session = new Session(SessionId('bad-replace'))
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'head' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'bad' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: { op: 'replace', start: 99, end: 99 }, sourceEventSeqs: [0] })
+    expectRepeatedFailure(meter().resolve('deepseek-v4-flash'), session, /invalid current range/)
+  })
+
+  it('handles earlier-reader catch-up, eager observation, and service reload', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    let handle: ModelTokenMeter | undefined
+    const revisions: number[] = []
+    ctx.on('session/event', (session) => {
+      if (handle !== undefined) revisions.push(handle.measure(session).logRevision)
+    })
+    const firstFiber = await ctx.plugin(TokenMeterService)
+    handle = ctx.tokenMeter.resolve('deepseek-v4-flash')
+    const session = ctx.sessions.create(SessionId('listener-order'))
+    handle.measure(session)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'one' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    expect(revisions).toEqual([1])
+    expect(handle.measure(session).logRevision).toBe(1)
+
+    await firstFiber.dispose()
+    const secondFiber = await ctx.plugin(TokenMeterService)
+    handle = ctx.tokenMeter.resolve('deepseek-v4-flash')
+    expect(handle.measure(session).logRevision).toBe(1)
+    await secondFiber.dispose()
+  })
+})

packages/llm/token-meter/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    }
+  ]
+}

packages/support/invariants/README.md

@@ -32,6 +32,7 @@ Session log (per session):
 - **steps nest in turns** — `step/start` opens a step in the open turn; `step/end` closes the matching step.
 - **chunks belong to an open step** — `step/start` precedes its `assistant/chunk`s.
 - **a `tool/result` needs a prior `tool/call`** — but NOT the converse: a `tool/call` may have no result (a thrown tool-execution pipeline step ends the turn with no `tool/result`, which is legal).
+- **provenance sources are valid and unambiguous** — `sourceEventSeqs` contains unique earlier known seqs; only `assistant/message` may carry an explicit empty list, which denotes a known empty provider stream rather than absent legacy provenance.
 
 Agent status (per agent):
 

packages/support/invariants/src/index.ts

@@ -118,8 +118,8 @@ function validateEvent(trace: SessionTrace, event: SessionEvent): SessionTraceTr
     }
   }
   if (se.sourceEventSeqs !== undefined) {
-    if (se.sourceEventSeqs.length === 0) {
-      throw new InvariantError('sourceEventSeqs must not be empty when present')
+    if (se.sourceEventSeqs.length === 0 && event.type !== 'assistant/message') {
+      throw new InvariantError('sourceEventSeqs must not be empty except on assistant/message')
     }
     const unique = new Set(se.sourceEventSeqs)
     if (unique.size !== se.sourceEventSeqs.length) {

packages/support/invariants/tests/invariants.spec.ts

@@ -487,13 +487,17 @@ describe('surface invariants', () => {
     // no throw — well-formed replace op
   })
 
-  it('rejects empty sourceEventSeqs', async () => {
+  it('accepts known-empty assistant provenance and rejects empty provenance elsewhere', async () => {
     const { ctx } = await setup()
     const session = ctx.sessions.create()
     session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('step/start', { turn: 1, step: 1 })
     expect(() => {
       session.append('assistant/message', { turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [] })
-    }).toThrow(InvariantError)
+    }).not.toThrow()
+    expect(() => {
+      session.append('user/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append', sourceEventSeqs: [] })
+    }).toThrow(/must not be empty except on assistant\/message/)
   })
 
   it('rejects duplicate sourceEventSeqs', async () => {

pnpm-lock.yaml

@@ -217,7 +217,17 @@ importers:
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
   packages/compact/compact-basic:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
     devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
       '@deepseek-ai/dsh-agent':
         specifier: workspace:^
         version: link:../../core/agent
@@ -239,12 +249,15 @@ importers:
       '@deepseek-ai/dsh-system-prompt':
         specifier: workspace:^
         version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-token-meter':
+        specifier: workspace:^
+        version: link:../../llm/token-meter
       '@deepseek-ai/dsh-tools':
         specifier: workspace:^
         version: link:../../core/tools
       cordis:
         specifier: ^4.0.0-rc.7
-        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader)
 
   packages/context/time-context:
     dependencies:
@@ -724,6 +737,22 @@ importers:
         specifier: ^4.0.0-rc.7
         version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
 
+  packages/llm/token-meter:
+    dependencies:
+      schemastery:
+        specifier: ^3.18.0
+        version: 3.18.0
+    devDependencies:
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)
+
   packages/sandbox/sandbox:
     devDependencies:
       '@deepseek-ai/dsh-llm':
@@ -1856,6 +1885,9 @@ importers:
       '@deepseek-ai/dsh-timeout-policy':
         specifier: workspace:^
         version: link:../../packages/timeout/timeout-policy
+      '@deepseek-ai/dsh-token-meter':
+        specifier: workspace:^
+        version: link:../../packages/llm/token-meter
       '@deepseek-ai/dsh-tool-ask-user':
         specifier: workspace:^
         version: link:../../packages/ui/tool-ask-user

python/sdk-runtime/package.json

@@ -30,6 +30,7 @@
     "@deepseek-ai/dsh-jsonrpc": "workspace:^",
     "@deepseek-ai/dsh-jsonrpc-agent": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
     "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
     "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",

scripts/gen-doc-graphs.ts

@@ -84,6 +84,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['agent-loop', 'compact-basic'],
     note: 'Adapters register provider implementations; the loop and compaction call the provider-neutral stream service.',
   },
+  {
+    key: 'tokenMeter',
+    pkg: 'token-meter',
+    title: 'Replay token measurement',
+    mode: 'core',
+    consumers: ['compact-basic'],
+    note: 'Owns isolated per-model/session replay folds; pressure consumers share immutable revisioned measurements.',
+  },
   {
     key: 'sessions',
     pkg: 'session',
@@ -823,6 +831,8 @@ function renderLifecycle(): string {
     `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
     '```',
     '',
+    'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
+    '',
     'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),

scripts/type-equiv.manifest.json

@@ -30,6 +30,10 @@
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" },
 
+    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
+    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" },
+    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
+
     { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEventMap", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "EpochHeader", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "TodoItem", "source": "packages/core/session/src/types.ts" },

scripts/verify-package-readme-model-experience.ts

@@ -47,6 +47,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
   'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
   'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
+  'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
   'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },

tsconfig.build.json

@@ -13,6 +13,7 @@
     { "path": "./packages/util/brand" },
     { "path": "./packages/util/timeout" },
     { "path": "./packages/llm/llm" },
+    { "path": "./packages/llm/token-meter" },
     { "path": "./packages/core/session" },
     { "path": "./packages/core/scope" },
     { "path": "./packages/session-persistence/session-persistence" },

tsconfig.json

@@ -24,6 +24,7 @@
     { "path": "./packages/util/brand" },
     { "path": "./packages/util/timeout" },
     { "path": "./packages/llm/llm" },
+    { "path": "./packages/llm/token-meter" },
     { "path": "./packages/core/session" },
     { "path": "./packages/core/scope" },
     { "path": "./packages/session-persistence/session-persistence" },