diff --git a/.github/workflows/e2e.yml b/.github/workflows/e2e.yml index a2015696f4..dd3965f5cd 100644 --- a/.github/workflows/e2e.yml +++ b/.github/workflows/e2e.yml @@ -110,9 +110,14 @@ jobs: fi echo "DEEPSEEK_API_KEY present." + # The e2e suites boot the example bins in `lib` mode (DSH_EXAMPLE_MODE=lib): + # the built artifact under plain Node, resolving plugins through real package + # exports — the shape a real consumer runs. That requires a prior build. + - name: Build (lib for the e2e example bins) + run: pnpm run build + # Real-API end-to-end tests only. The keyless gates (lint/typecheck/ - # coverage/snapshot/build/etc.) already run in ci.yml on every push/PR; - # no need to repeat them or build first (tests run unbuilt via tsx). + # coverage/snapshot/etc.) already run in ci.yml on every push/PR. # DEEPSEEK_BASE_URL is pinned to the external API; the secret is scoped to # this step (and preflight) only — never exposed to checkout/setup/install. - name: E2E tests (real DeepSeek API) @@ -120,4 +125,5 @@ jobs: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }} DEEPSEEK_BASE_URL: https://api.deepseek.com DSH_E2E_MAX_WORKERS: 14 + DSH_EXAMPLE_MODE: lib run: pnpm run test:e2e diff --git a/AGENTS.md b/AGENTS.md index 21e9877e05..e551a7de10 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -99,7 +99,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, ## Conventions - Every npm package is `@deepseek-ai/dsh-`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package. -- ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only. +- ESM everywhere (`"type": "module"`). Cross-package imports use package names; in-package relative imports include `.ts`. CI subprocesses that boot examples or Cordis configs run built `lib/` under plain Node; only explicit source-path regressions use tsx ([testing policy](docs/testing.md#test-subprocess-launch-modes)). - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer. - **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns. - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default. diff --git a/docs/agent-lifecycle.md b/docs/agent-lifecycle.md index 99ca50bc11..c753f59992 100644 --- a/docs/agent-lifecycle.md +++ b/docs/agent-lifecycle.md @@ -54,6 +54,8 @@ sequenceDiagram Driver-->>SDK: 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. Maintenance mode: curated Mermaid sequence; exact event signatures live in the generated Cordis catalog. diff --git a/docs/architecture.md b/docs/architecture.md index 26f4979082..d4abf10283 100644 --- a/docs/architecture.md +++ b/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) | singleton replay-aware request/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 | @@ -81,13 +82,13 @@ forever: agent/request (config only) -> log request/header -> llm/stream (frozen) 'assistant/chunk' agent/step-result - 'assistant/message' + 'assistant/message' (transformed content or empty success anchor after step-result rejection) schedule tool calls by ctx.tools.executionMode: exclusive -> one-call barrier parallel -> rolling pool, <= maxParallelToolCalls in flight; reclassify before start each start -> 'tool/call' -> ordered tools/pre-execute -> concurrent tools/execute each model-order result -> ordered tools/post-execute -> 'tool/result' - append post-tool context (model order) and steering + append accepted tool-batch context after all recorded results, then steering 'step/end' agent/turn-continuation agent/turn-stop (terminal policy) @@ -98,7 +99,7 @@ forever: Each step assembles ordered prompt sections, tool schemas, and `{{name}}` variables; unknown or valueless references fail the turn. `dsh-system-prompt` owns the harness identity and default persona, which an agent scope may shadow. The loop supplies `model` and `cwd` ([prompt-ownership RFC](rfc/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)). -Post-tool context lands after all tool results so tool-call/result adjacency stays stable. Steering drains between steps; leftover ordinary steering becomes queued input. Terminal `agent/turn-stop` runs after continuation and steering folding, stays authoritative through turn close/flush, and discards later steering while preserving queued prompts. +Context accepted during tool execution—including async `agent.inject()` notices and post-tool `additionalContexts`—waits for settlement, then follows every recorded result. Successful batches preserve call/result adjacency; interrupted batches drain that context before turn closure. Steering drains between steps; ordinary leftover steering becomes queued input. Terminal `agent/turn-stop` runs after continuation and steering folding, stays authoritative through turn close and flush, and discards later steering while preserving queued prompts. ### Failure Boundaries @@ -126,7 +127,7 @@ Durability is a plugin concern. Persistence backends buffer synchronous `session ### Model Content -Messages contain typed blocks (`text`, `reasoning`, `tool-call`, `tool-result`) derived from merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types coordinate adapters, UI bridges, compaction pricing, and persistence as one repo-wide contract. +Messages contain typed blocks (`text`, `reasoning`, `tool-call`, `tool-result`) derived from merge-extensible `ContentBlockMap`; the same pattern types `MessageSource`, `FinishReason`, `TurnTrigger`, and `TurnEndReason`. New block types coordinate adapters, UI bridges, compaction pricing, token metering, and persistence as one repo-wide contract; replay measurement types live in [token-meter.md](core-data-structures/token-meter.md). Streaming uses raw chunks (`block-start` through `finish`) and `BlockAssembler`. The loop logs and assembles chunks, storing provider/model provenance plus replay state. An `LlmAdapter` implements `stream()`, registers provider routes, and may expose selector metadata; it resolves and validates model ids. Replay state reaches targets only when both routes map to one adapter instance, which owns validation and conversion. The contract lives in [llm-streaming.md](core-data-structures/llm-streaming.md). diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 9c650c9df1..1aafbb2817 100644 --- a/docs/capability-seams.md +++ b/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
Replay token measurement"] pkg_session["session"] svc_sessions["ctx.sessions
In-memory session store"] pkg_agent["agent"] @@ -131,6 +133,7 @@ flowchart LR pkg_subagent_spawn --> svc_subagents pkg_system_prompt --> svc_systemPrompt pkg_tasks --> svc_tasks + pkg_token_meter --> svc_tokenMeter pkg_tool_bash --> svc_bashEnv pkg_tools --> svc_tools pkg_user_interaction --> svc_userInteraction @@ -181,6 +184,7 @@ flowchart LR svc_tasks --> pkg_tool_bash svc_tasks --> pkg_tool_subagent svc_tasks --> pkg_tool_tasks + svc_tokenMeter --> pkg_compact_basic svc_tools --> pkg_acp svc_tools --> pkg_agent_loop svc_tools --> pkg_tool_ask_user @@ -202,6 +206,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-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), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`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 and relationship traces. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 9f27cfb91a..4cac932a6f 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -242,46 +242,29 @@ Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:21`](../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 - /** Provider to use for summarization (`''` with an empty model inherits the conversation target). */ - summarizationProvider: string - /** Model to use for summarization (`''` with an empty provider inherits the conversation target). */ - 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). */ + /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */ + thresholdRatio?: number + /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */ + retainTokens?: number + /** Summary provider; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */ + summarizationProvider?: string + /** Summary model; `''` resolves the latest routed pair, then the agent pair. 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 } ``` -Source: [`packages/compact/compact-basic/src/types.ts:20`](../packages/compact/compact-basic/src/types.ts) +Source: [`packages/compact/compact-basic/src/types.ts:8`](../packages/compact/compact-basic/src/types.ts) ## `@deepseek-ai/dsh-fs-local` @@ -991,6 +974,18 @@ export interface Config { Source: [`packages/context/time-context/src/index.ts:20`](../packages/context/time-context/src/index.ts) +## `@deepseek-ai/dsh-token-meter` + +```ts config-catalog +/** Token-meter plugin configuration. */ +export interface TokenMeterConfig { + /** Service-wide context-window capacity in tokens. Defaults to `128000`. */ + contextWindow?: number +} +``` + +Source: [`packages/llm/token-meter/src/types.ts:10`](../packages/llm/token-meter/src/types.ts) + ## `@deepseek-ai/dsh-tool-bash` Requires: `tools` · `bash` · `systemPrompt` diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 9cf51c1de3..6fbffc1798 100644 --- a/docs/cordis-catalog/events.md +++ b/docs/cordis-catalog/events.md @@ -23,7 +23,7 @@ A fully configured agent and live session were published. Setup is composition-o Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:153`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:154`](../../packages/core/agent/src/types.ts) ### `agent/disposed` — emit @@ -35,7 +35,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:162`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:163`](../../packages/core/agent/src/types.ts) ### `agent/error` — emit @@ -47,7 +47,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:297`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:298`](../../packages/core/agent/src/types.ts) ### `agent/pre-step` — serial @@ -59,7 +59,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:217`](../../packages/core/agent/src/types.ts) ### `agent/prompt-submit` — waterfall @@ -71,7 +71,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:227`](../../packages/core/agent/src/types.ts) ### `agent/queued` — emit @@ -83,7 +83,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:181`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:182`](../../packages/core/agent/src/types.ts) ### `agent/request` — waterfall @@ -95,7 +95,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:238`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts) ### `agent/session-prefix` — waterfall @@ -107,7 +107,7 @@ Compose request-only messages placed before derived history. The frozen result i Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:253`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:254`](../../packages/core/agent/src/types.ts) ### `agent/session-start` — emit @@ -119,7 +119,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:194`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:195`](../../packages/core/agent/src/types.ts) ### `agent/status` — emit @@ -131,7 +131,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:171`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:172`](../../packages/core/agent/src/types.ts) ### `agent/step-result` — waterfall @@ -143,7 +143,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:264`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:265`](../../packages/core/agent/src/types.ts) ### `agent/turn-continuation` — waterfall @@ -155,7 +155,7 @@ Override whether the turn continues. The default continues after tool calls or s Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:274`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:275`](../../packages/core/agent/src/types.ts) ### `agent/turn-stop` — serial @@ -167,7 +167,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a Types: [Agent](../core-data-structures/core.md) -Source: [`packages/core/agent/src/types.ts:284`](../../packages/core/agent/src/types.ts) +Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts) ## `approval/*` diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index d307a04a6c..b858cb6260 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -101,7 +101,7 @@ Source: [`packages/code-runtime/code-runtime/src/index.ts:30`](../../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 @@ -110,7 +110,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) @@ -220,7 +220,7 @@ list(): Session[] fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session ``` -Source: [`packages/core/session/src/index.ts:566`](../../packages/core/session/src/index.ts) +Source: [`packages/core/session/src/index.ts:580`](../../packages/core/session/src/index.ts) ## `ctx.skills` — `SkillService` @@ -296,6 +296,19 @@ Types: [Agent](../core-data-structures/core.md) Source: [`packages/tasks/tasks/src/index.ts:76`](../../packages/tasks/tasks/src/index.ts) +## `ctx.tokenMeter` — `TokenMeterService` + +Replay owner for one service-wide estimator and isolated per-session folds. + +```ts cordis-catalog +measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement +estimateMessage(message: Message): number +``` + +Types: [Message](../core-data-structures/core.md) + +Source: [`packages/llm/token-meter/src/index.ts:106`](../../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. diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md index 6087c954d5..45a0ac310e 100644 --- a/docs/core-data-structures/compaction.md +++ b/docs/core-data-structures/compaction.md @@ -50,8 +50,8 @@ 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: [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration. 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. -The seam exports `toolPairingBalancedBefore(session, node)` and `toolPairingBalancedAfter(session, node)` for those edge checks. Both validate current surface membership, reject stale or missing seqs and orphan results, and ignore a caller-retained `node.next`; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics. +The seam exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for those edge checks. Both validate current surface membership and reject missing seqs and orphan results; the [package contract](../../packages/compact/compact/README.md#tool-pairing-boundaries) owns their cache semantics. diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md index be33de3058..c1ecdcc6a5 100644 --- a/docs/core-data-structures/core.md +++ b/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` | @@ -237,7 +238,7 @@ The model-facing `ToolSchema` is the wire shape; the registered `ToolDefinition` ### The request envelope: `LlmCallConfig` and the logged header -The loop builds each request from logged state. `EpochHeader` records call config, rendered prompt, authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset), and session prefix through `request/header` snapshots and deltas. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-events-requestheader-and-requestheader-delta) and the [reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md). +The loop builds each request from logged state. `EpochHeader` records call config, rendered prompt, authoritative returned tool order (configured by `toolOrder`, or lexicographic when unset), and session prefix through full `request/header` snapshots. Together with derived history, this makes the request reconstructable from the session log. See [session.md](session.md#the-request-header-event-requestheader) and the [reconstructability RFC](../rfc/implemented/architecture/2026-07-05-reconstructable-requests.md). `agent/request` receives a frozen call-config seed and may return a replacement to switch provider, model, or sampling. `agent/session-prefix` composes request-only prefix messages once per loop instance, and the header records the exact result used. Requests reaching `llm/stream` are deep-frozen, so mutation throws. @@ -283,7 +284,7 @@ type SessionEvent = { }[T] ``` -The fifteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`, `request/header-delta`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**. +The fourteen event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `prompt/blocked`, `context/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the turn-enclosure invariant are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**. ## The agent handle @@ -341,6 +342,11 @@ interface Agent { * `options.envelope: 'raw'` preserves caller-owned framing. Does not run the * model. * + * In an open turn, inject appends at the current log position except while + * the current tool-call batch executes: accepted context waits FIFO until the + * batch settles, then appends after every recorded result and before turn + * close even when execution is interrupted. + * * Turn-enclosure (the turn-enclosure RFC): an inject while a turn is open joins that turn; * an inject while idle wraps its `context/message` in a one-shot `injection` * turn (`turn/start` → `context/message` → `turn/end`) and checkpoints it for diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md index 3cfe1b733d..0e882bae33 100644 --- a/docs/core-data-structures/session.md +++ b/docs/core-data-structures/session.md @@ -79,25 +79,14 @@ interface SessionEventMap { * Full snapshot of the {@link EpochHeader} the NEXT request is built under, * with the {@link RequestHeaderReason} it was recorded whole. Appended by * the loop inside the step, before dispatch, on a loop instance's first - * request-building step (`'initial'`/`'resume'`) or when a delta failed its - * round-trip guard (`'fallback'`); always records what the request actually - * used, post-`agent/request`. Anchors the header fold: reconstruction reads - * the latest snapshot and applies the deltas after it. NOT a + * request-building step (`'initial'`/`'resume'`) or when a later request's + * header changes (`'change'`); always records what the request actually + * used, post-`agent/request`. Reconstruction reads the latest snapshot. NOT a * {@link SurfaceEventType}: it produces no LLM message — it is the request * envelope, logged so every request is a pure function of the session log * (the reconstructability RFC). */ 'request/header': { header: EpochHeader; reason: RequestHeaderReason } - /** - * Amendment to the folded {@link EpochHeader}: system line-trim, name-keyed - * tools delta, whole replacement config, or whole replacement session - * prefix (an EMPTY array encodes the transition to "none"). The - * writer verifies `applyHeaderDelta(previous, delta)` reproduces the new - * header exactly and falls back to a `'fallback'` `request/header` snapshot - * when it cannot, so a logged delta ALWAYS round-trips. NOT a - * {@link SurfaceEventType}. - */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } } ``` @@ -112,9 +101,9 @@ export interface TodoItem { } ``` -### The request header events: `request/header` and `request/header-delta` +### The request header event: `request/header` -The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + the session prefix) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A `request/header` snapshot (reason `'initial' | 'resume' | 'fallback'`) anchors the fold at conversation birth, process boundaries, and delta-encoding fallbacks; `request/header-delta` events amend it mid-run. `foldRequestHeader(events)` reconstructs the header any request was built under; the writer round-trip-verifies every delta before logging it, so a well-formed log always folds. Neither is a `SurfaceEventType` — they produce no LLM message. +The request envelope — the `EpochHeader` (call config + rendered system prompt + assembled tool schemas + the session prefix) — is logged session state, so every conversation request is a pure function of the log (the reconstructability RFC). A full `request/header` snapshot with reason `'initial'` or `'resume'` records each loop-instance boundary; a later changed request records another full snapshot with reason `'change'`. `foldRequestHeader(events)` reconstructs the header by selecting the latest snapshot. The event is not a `SurfaceEventType`: it produces no LLM message. ```ts type-equiv export interface EpochHeader { @@ -135,7 +124,7 @@ export interface EpochHeader { } ``` -Canonical form: an empty system prompt, an empty tool list, and an empty session prefix are ABSENT fields, matching how requests are built. `messagePrefix` is the durable record of the `agent/session-prefix` waterfall's product (the request is `messagePrefix + derived history`); composed once per loop instance and anchored by that instance's snapshot, so the loop never produces a prefix delta in practice — the delta arm (whole-array replacement, an empty array encoding the transition back to absence) exists for codec totality. The other delta payloads (`SystemDelta` — a common-prefix/suffix line trim; `ToolsDelta` — name-keyed added/removed/changed) live beside the events in [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts). +Canonical form: an empty system prompt, an empty tool list, and an empty session prefix are absent fields, matching how requests are built. `messagePrefix` is the durable record of the `agent/session-prefix` waterfall's product (the request is `messagePrefix + derived history`); it is composed once per loop instance and included in every full snapshot that instance records. Legacy v0 logs containing the removed `request/header-delta` event or its full-snapshot `fallback` reason are rejected at seed, append, and persistence-load boundaries rather than replayed incompletely. ## `SessionEvent` — one log entry @@ -165,9 +154,11 @@ type SessionEvent = { `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). +The five message-producing types (`SurfaceEventType` — `user/message`, `assistant/message`, `tool/result`, `context/message`, `steering/message`) carry surface metadata declaring how they join the ordered derived surface. See the [session surface RFC](../rfc/implemented/architecture/2026-06-18-session-surface.md). ### `SurfaceEventType` — the message-producing subset of event types @@ -188,7 +179,7 @@ export type SurfaceOp = | { op: 'replace'; start: number; end: number } ``` -`'append'` is the normal tail-append path. `replace` shadows surface nodes from `start` through `end` inclusive (both must be valid surface node seqs; `start === end` replaces a single node) and inserts the new node in their place. +`'append'` is the normal tail-append path. `replace` shadows surface entries from `start` through `end` inclusive (both must be valid surface seqs; `start === end` replaces a single entry) and inserts the new event in their place. ### `SurfaceIntent` — the parameter to `session.append()` @@ -201,21 +192,11 @@ 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. -### `SurfaceNode` — a node in the surface linked list - -```ts type-equiv -export interface SurfaceNode { - seq: number - prev: number | null - next: number | null -} -``` - -`SurfaceNode` is positional state, not durable identity. A replacement can remove a caller-retained node or make a copied `next` stale; consumers that cross a surface mutation validate membership and answer positional queries from `Session.surface.nodes`. `SurfaceManager.replaceGeneration` increments for each replacement so incremental consumers can distinguish pure tail growth from a rewrite. +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. ### `SurfaceFoldReplacement` and `SurfaceFoldResult` — a complete surface replay -`foldSurface(events)` returns detached current nodes together with the actual node seqs shadowed by each declared replacement range. `SurfaceManager` uses the same transition functions for its incremental cache. +`foldSurface(events)` returns detached current event sequences together with the actual sequences shadowed by each declared replacement range. `SurfaceManager` uses the same transitions for its incremental cache without retaining replacement history. Its `replaceGeneration` increments for each replacement so incremental consumers can distinguish pure tail growth from a rewrite. ```ts type-equiv export interface SurfaceFoldReplacement { @@ -228,7 +209,7 @@ export interface SurfaceFoldReplacement { ```ts type-equiv export interface SurfaceFoldResult { - nodes: SurfaceNode[] + nodes: number[] replacements: SurfaceFoldReplacement[] } ``` diff --git a/docs/core-data-structures/token-meter.md b/docs/core-data-structures/token-meter.md new file mode 100644 index 0000000000..e082ea08a9 --- /dev/null +++ b/docs/core-data-structures/token-meter.md @@ -0,0 +1,39 @@ +# Token Meter + +`@deepseek-ai/dsh-token-meter` exposes one detached replay snapshot for request pressure and positional surface pricing. `logRevision` is the number of durable events consumed for every field in the measurement. + +Source: [`packages/llm/token-meter/src/types.ts`](../../packages/llm/token-meter/src/types.ts) + +## `TokenMeasurement` + +```ts type-equiv +interface TokenMeasurement { + /** 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 + /** Total heuristic tokens across the current surface. */ + readonly surfaceTokens: number + /** Current surface nodes in positional head-to-tail order. */ + readonly nodes: readonly TokenSurfaceNode[] +} +``` + +`baseline.kind === 'usage'` means the latest successful provider call has the same canonical request envelope and its total is no lower than that call's full heuristic anchor. `estimated` means no reusable conservative usage anchor exists, so the service priced the complete envelope and surface with its fixed heuristic. A later successful request replaces the earlier anchor; signed `surfaceDeltaTokens` preserves growth and shrinkage relative to a matching anchor. `totalTokens` remains request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of the node prices. + +## `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 +} +``` + +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. diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md index 82b4aa4acd..edb20586bc 100644 --- a/docs/core-data-structures/tools.md +++ b/docs/core-data-structures/tools.md @@ -180,11 +180,13 @@ interface ToolExecutionResult { error?: ToolErrorInfo /** * Extra model-facing contexts deferred by a composite tool or attached by - * `tools/post-execute` listeners for the NEXT request. They are NOT part of - * this call's `content`: the loop buffers every context and appends them only - * AFTER all `tool/result`s for the step, preserving tool-call/result - * adjacency. The array preserves each context's source, envelope, metadata, - * and production order instead of flattening mixed plugin provenance. + * `tools/post-execute` listeners for the NEXT request. They are not part of + * this call's `content`: the loop accepts them into the active-batch FIFO and + * appends them after every recorded `tool/result` when the batch settles, even + * when execution is interrupted. The array preserves each context's source, + * envelope, metadata, and production order. An accepted outer call keeps + * deferred contexts before decision contexts; a block retains only contexts + * supplied by the blocking decision. */ additionalContexts?: HookContext[] /** diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md index 60e65ef33f..acd90d4423 100644 --- a/docs/event-producer-consumer.md +++ b/docs/event-producer-consumer.md @@ -7,19 +7,19 @@ This matrix shows which packages dispatch each harness-owned event and which pac | Event | Mode | Declared in | Dispatchers | Listeners | | --- | --- | --- | --- | --- | -| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:153`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | -| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:162`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | -| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:297`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) | -| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:226`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | -| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:181`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | -| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:238`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp) | -| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:253`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | -| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:194`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:171`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | -| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:264`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | -| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:274`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | -| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:284`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | +| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:154`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`jsonrpc`](../packages/ui/jsonrpc), [`stdio`](../packages/ui/stdio) | +| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:163`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`stdio`](../packages/ui/stdio) | +| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:298`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/pre-step` | `serial` | [`packages/core/agent/src/types.ts:217`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`time-context`](../packages/context/time-context), [`user-approval`](../packages/ui/user-approval) | +| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:227`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | +| `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:182`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - | +| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`acp`](../packages/ui/acp) | +| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:254`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill), [`workspace-context`](../packages/context/workspace-context) | +| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:195`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:172`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio`](../packages/ui/stdio) | +| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:265`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - | +| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:275`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | +| `agent/turn-stop` | `serial` | [`packages/core/agent/src/types.ts:285`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:31`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/ui/acp) | | `fs/edit-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:61`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) | | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:70`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) | @@ -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:40`](../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-persistence`](../packages/session-persistence/session-persistence) | -| `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`](../packages/ui/stdio), [`workspace-context`](../packages/context/workspace-context) | +| `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`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter), [`workspace-context`](../packages/context/workspace-context) | | `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:108`](../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:82`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) | diff --git a/docs/module-graph.md b/docs/module-graph.md index a65c1bfa6f..8b67c73d27 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -18,6 +18,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"] @@ -163,6 +164,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 @@ -196,6 +199,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_spill_local --> pkg_spill pkg_hook_protocol --> pkg_bash pkg_hook_protocol --> pkg_session @@ -446,6 +450,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` | [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) | | [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) | @@ -461,7 +466,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) | | [`spill-local`](../packages/spill/spill-local) | `spill` | [`spill`](../packages/spill/spill) | | [`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) | diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md index c360c0644f..5484d0efe2 100644 --- a/docs/persistence-catalog.md +++ b/docs/persistence-catalog.md @@ -37,7 +37,7 @@ Source: [`packages/ui/user-approval/src/index.ts:56`](../packages/ui/user-approv #### `approval/policy` — log-only -The session's approval policy was switched — log-only, durable, replayable, never in the model transcript (the model learns the policy from the prompt section and the narrator's notices). The LAST such event is the session's override (effectiveApprovalPolicy); who asked for it is derivable from position (an event after the log's last `request/header*` was a runtime switch by the user). +The session's approval policy was switched — log-only, durable, replayable, never in the model transcript (the model learns the policy from the prompt section and the narrator's notices). The LAST such event is the session's override (effectiveApprovalPolicy); who asked for it is derivable from position (an event after the log's last `request/header` was a runtime switch by the user). ```ts persistence-catalog 'approval/policy': { policy: ApprovalPolicy } @@ -57,7 +57,7 @@ Raw stream chunk — token-level replay fidelity. Types: [StreamChunk](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:253`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:219`](../packages/core/session/src/types.ts) #### `assistant/message` — surface @@ -69,7 +69,7 @@ Assembled assistant message for one step (derived history uses this). Carries th Types: [ContentBlock](core-data-structures/core.md) · [TokenUsage](core-data-structures/llm-streaming.md) -Source: [`packages/core/session/src/types.ts:260`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:226`](../packages/core/session/src/types.ts) ### `bash/*` @@ -129,7 +129,7 @@ In-session context injection (file-change notices, subdir AGENTS.md, skill conte Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:212`](../packages/core/session/src/types.ts) ### `hook/*` @@ -177,29 +177,19 @@ Durable record of a prompt veto and its reason. It is log-only: the blocked prom Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:238`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:204`](../packages/core/session/src/types.ts) ### `request/*` #### `request/header` — log-only -Full EpochHeader for the next request, appended inside its step before dispatch. It is log-only and anchors subsequent deltas. +Full header for the next request, appended inside its step before dispatch. It is log-only; the latest snapshot reconstructs the request header. ```ts persistence-catalog 'request/header': { header: EpochHeader; reason: RequestHeaderReason } ``` -Source: [`packages/core/session/src/types.ts:288`](../packages/core/session/src/types.ts) - -#### `request/header-delta` — log-only - -Log-only amendment to the folded EpochHeader. System and tools use their delta codecs; config and prefix replace whole, with an empty prefix encoding removal. Writers verify round-trip equality or log a fallback snapshot. - -```ts persistence-catalog -'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } -``` - -Source: [`packages/core/session/src/types.ts:294`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:251`](../packages/core/session/src/types.ts) ### `steering/*` @@ -213,7 +203,7 @@ Steering content injected between steps of a running turn. Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:278`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:244`](../packages/core/session/src/types.ts) ### `step/*` @@ -225,7 +215,7 @@ Closes step `step` of turn `turn`. 'step/end': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:231`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:197`](../packages/core/session/src/types.ts) #### `step/start` — log-only @@ -235,13 +225,13 @@ Opens step `step` of turn `turn` — one model call plus the tool executions it 'step/start': { turn: number; step: number } ``` -Source: [`packages/core/session/src/types.ts:229`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:195`](../packages/core/session/src/types.ts) ### `todo/*` #### `todo/write` — log-only -Whole-list snapshot; the latest write wins on replay. It is log-only UI state and never enters derived model history. +Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. ```ts persistence-catalog 'todo/write': { todos: TodoItem[] } @@ -249,7 +239,7 @@ Whole-list snapshot; the latest write wins on replay. It is log-only UI state an Types: [TodoItem](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:246`](../packages/core/session/src/types.ts) ### `tool/*` @@ -263,7 +253,7 @@ The model requested one tool invocation: `name` with the raw `arguments` JSON st Types: [CallId](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:232`](../packages/core/session/src/types.ts) #### `tool/code-dispatch` — log-only @@ -287,7 +277,7 @@ A completed tool call's model-facing result, plus an optional tool-private `meta Types: [CallId](core-data-structures/core.md) · [ContentBlock](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:242`](../packages/core/session/src/types.ts) ### `turn/*` @@ -301,7 +291,7 @@ Closes turn `turn` with the TurnEndReason that ended it. The loop fires the awai Types: [TurnEndReason](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:227`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:193`](../packages/core/session/src/types.ts) #### `turn/start` — log-only @@ -313,7 +303,7 @@ Opens turn `turn`. `trigger` records what started it — a drained message batch Types: [TurnTrigger](core-data-structures/session.md) -Source: [`packages/core/session/src/types.ts:221`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:187`](../packages/core/session/src/types.ts) ### `user/*` @@ -327,4 +317,4 @@ A user-visible prompt (queued message drained at turn start). Types: [ContentBlock](core-data-structures/core.md) · [MessageSource](core-data-structures/core.md) -Source: [`packages/core/session/src/types.ts:233`](../packages/core/session/src/types.ts) +Source: [`packages/core/session/src/types.ts:199`](../packages/core/session/src/types.ts) diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index af5b2f259f..ecb66326b3 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -22,7 +22,6 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; |---|---| | [Unify the agent id and the session id](proposed/simplification/2026-06-20-unify-agent-and-session-id.md) | 2026-06-20 | | [Prune dead public and result surface](proposed/simplification/2026-07-04-prune-dead-core-spine-surface.md) | 2026-07-04 | -| [Simplify session-log representation](proposed/simplification/2026-07-12-simplify-session-log-representation.md) | 2026-07-12 | ### Architecture @@ -114,6 +113,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Trim unreachable ACP bridge surface — the branding knobs and the kind-sniffing fallback](implemented/simplification/2026-07-04-trim-acp-bridge-unreachable-surface.md) | 2026-07-04 | | [Drop unconsumed skill provider events](implemented/simplification/2026-07-12-drop-unconsumed-skill-provider-events.md) | 2026-07-12 | | [Prune unused web seam fields](implemented/simplification/2026-07-12-prune-unused-web-seam-fields.md) | 2026-07-12 | +| [Simplify session-log representation](implemented/simplification/2026-07-12-simplify-session-log-representation.md) | 2026-07-12 | ### Architecture @@ -133,7 +133,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Every session event is enclosed in a turn](implemented/architecture/2026-06-15-turn-enclosure-invariant.md) | 2026-06-15 | | [Filesystem capability seam — ctx.fs, local backend, and model-facing filesystem tools](implemented/architecture/2026-06-17-filesystem-capability-seam.md) | 2026-06-17 | | [Agent lifecycle and ownership seams](implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md) | 2026-06-18 | -| [Session surface — a linked list over the event log for LLM message derivation](implemented/architecture/2026-06-18-session-surface.md) | 2026-06-18 | +| [Session surface — an ordered projection over the event log](implemented/architecture/2026-06-18-session-surface.md) | 2026-06-18 | | [Shared persistence write coordinator](implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md) | 2026-06-18 | | [Branded IDs everywhere they belong](implemented/architecture/2026-06-20-branded-ids.md) | 2026-06-20 | | [Extract example apps into packages](implemented/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 | @@ -160,6 +160,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Agent-scope runtime design and correctness](implemented/architecture/2026-07-12-agent-scope-runtime-design.md) | 2026-07-12 | | [Provider-routed LLM adapters and a generic pi-ai backend](implemented/architecture/2026-07-14-provider-routed-llm-adapters.md) | 2026-07-14 | | [Advisory LLM catalogs and per-session ACP model selection](implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md) | 2026-07-15 | +| [Replay token meter service](implemented/architecture/2026-07-15-replay-token-meter-service.md) | 2026-07-15 | ### Process @@ -191,6 +192,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [A gated Known-Limitations section in every package README](implemented/process/2026-07-10-readme-known-limitations-gate.md) | 2026-07-10 | | [Package Model Experience contract](implemented/process/2026-07-12-package-model-experience-contract.md) | 2026-07-12 | | [TypeScript Program-backed semantic gates](implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md) | 2026-07-14 | +| [Run CI examples from built lib](implemented/process/2026-07-17-run-ci-examples-from-built-lib.md) | 2026-07-17 | ### Testing diff --git a/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md b/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md index e55cd0853e..a54f735219 100644 --- a/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md +++ b/docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md @@ -18,7 +18,7 @@ In case 2, if the injected `context/message` is the last event before a flush/di **Every session event lives inside a turn** — between a `turn/start` and its matching `turn/end`. Concretely: - The loop appends queued `user/message` events **after** `turn/start` (inside the turn), not before it. `turn/end` is therefore owed the moment those messages are recorded, and the existing finalizer guarantees it. -- An `agent.inject()` made while the agent is **running** appends its `context/message` into the already-open turn (unchanged). +- An `agent.inject()` made while the agent is **running** joins the already-open turn. While the current step executes assistant tool calls, accepted context waits in arrival order until that batch settles, then appends after every recorded result and before the turn closes even when execution is interrupted. - An `agent.inject()` made while **idle** wraps its `context/message` in a one-shot turn: `turn/start{trigger:{kind:'injection'}}` → `context/message` → `turn/end{completed}`. A new `injection` variant joins the merge-extensible `TurnTriggerMap`. - The loop derives the next turn number from the log each iteration (`lastTurnNumber(session) + 1`) instead of keeping a private counter, so an idle injection's one-shot turn cannot collide with the next real turn's number. - The `dsh-invariants` plugin **enforces** the invariant in dev: a `user/message` / `context/message` / `steering/message` appended while no turn is open throws an `InvariantError`. diff --git a/docs/rfc/implemented/architecture/2026-06-18-session-surface.md b/docs/rfc/implemented/architecture/2026-06-18-session-surface.md index 6ba0df41c4..7c6c5b00d0 100644 --- a/docs/rfc/implemented/architecture/2026-06-18-session-surface.md +++ b/docs/rfc/implemented/architecture/2026-06-18-session-surface.md @@ -1,4 +1,4 @@ -# RFC: Session surface — a linked list over the event log for LLM message derivation +# RFC: Session surface — an ordered projection over the event log Status: implemented @@ -8,13 +8,13 @@ The event log is authoritative, but history manipulation had no durable shared m ## Decision -Add a **surface** — a derived, cached linked list of "surface nodes" (the subset of events that produce LLM messages) — maintained by `surfaceOp` markers in the event log. +Add a **surface** — a derived, cached order of event sequences (the subset of events that produce LLM messages) — maintained by `surfaceOp` markers in the event log. ### Two new top-level fields on `SessionEvent` 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,13 +25,13 @@ 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 the new event seq 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. +2. **Replace** — remove entries from `start` through `end` (both inclusive) and insert the new event seq in their place. Both `start` and `end` must be present in the current surface; `start === end` replaces one entry. The event's `sourceEventSeqs` must contain every shadowed surface seq. The shadowed events remain in the log but are no longer on the surface. ### SurfaceManager: delta-based, not full rebuild -A `SurfaceManager` class (private to `Session`) maintains the cached linked list. It tracks `_lastProcessedSeq` and processes only the **delta** (new events since the last access) rather than rescanning the entire log. Because the log is append-only, prior events never change; a seeded log is simply the initial delta folded on first access. +A `SurfaceManager` class (private to `Session`) maintains one ordered `number[]` of event seqs. It tracks `_lastProcessedSeq` and processes only the new events since the last access rather than rescanning the entire log. Because the log is append-only, prior events never change; a seeded log is simply the initial suffix folded on first access. Replace locates its inclusive endpoints by array position and splices the replacement seq into that range; no link objects or seq-to-node map duplicate the order. Delta processing is O(1) when no new events and O(new events) when new events arrive. @@ -47,23 +47,24 @@ 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. ## Alternatives considered - **Per-plugin `agent/request` wrapping** (the pre-surface pattern for history manipulation) — listener-ordering fragility, no durable record of what was changed, and every new manipulation forces another change to core `deriveMessages()`. -- **Half-open `[start, endExclusive)` replace ranges** — rejected: the surface is a doubly-linked list whose ends are naturally named by node seqs, and single-node replacement (`start === end`) reads naturally with inclusive semantics. +- **Half-open `[start, endExclusive)` replace ranges** — rejected: endpoints are named by surface event seqs, and single-entry replacement (`start === end`) reads naturally with inclusive semantics. +- **Linked node objects plus a seq map** — rejected: production did not read predecessor links, the only successor use was the next array position, and replacement already required linear `indexOf` lookup. A single seq array preserves the same asymptotic behavior with one representation to validate. - **Full rebuild behind a dirty flag** instead of delta processing — O(N²) over a session's lifetime: every single-event append would rescan all prior events. ## Consequences -- **`packages/core/session`**: New `surface.ts` (`SurfaceManager`), new types (`SurfaceOp`, `SurfaceIntent`), new fields on `SessionEvent`, modified `append()` (third required `SurfaceIntent` param), refactored `deriveMessages()` (walks the surface as the sole derivation path), surface-aware `repair.ts`. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants). +- **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array; `SurfaceOp`/`SurfaceIntent` and the top-level session-event fields record how entries join it. `append()` requires a `SurfaceIntent` for surface events, `deriveMessages()` walks the surface as the sole derivation path, and `repair.ts` emits surface-aware closers. The seed constructor rejects a surface-eligible seed event missing its `surfaceOp` marker (see § Invariants). - **`packages/core/agent-loop`**: All surface-capable appends pass surface opts. Chunk seqs are collected for `assistant/message` provenance; `tool/call` seqs are captured for `tool/result` provenance. - **`packages/session-persistence/session-persistence-sqlite`**: Two new nullable TEXT columns (`source_event_seqs`, `surface_op`) on the `events` table; `SCHEMA_VERSION` bumped (bump-and-reject, no migration). - **`packages/support/invariants`**: Surface-related validation rules. - **`packages/session-persistence/session-persistence-jsonl`**: No changes required. - **`packages/session-persistence/session-persistence`**: Abstract interface unchanged. -The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed nodes — the new node takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically. +The surface is the foundation for future history manipulation. A compaction or tool-result-prune plugin appends one of the existing message-producing event types (a `user/message` carrying the summary, say) with `surfaceOp: { op: 'replace', start, end }` and `sourceEventSeqs` covering the shadowed entries — the new event takes the range's place on the surface while the plugin's own trace events (e.g. `compaction/start`, `compaction/end`) stay off it. Replay preserves the decision deterministically. diff --git a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md index 86b352c5b6..a084ba47a4 100644 --- a/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -18,13 +18,13 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro ### The mechanism -**Messages.** `Session.deriveMessages()` is cached: each surface node is projected exactly once, when first seen, through the public per-node function `deriveEventMessage(event)`; a surface rewrite (a compaction `replace` — `SurfaceManager.replaceGeneration`) rebuilds. Callers get a fresh array per call over shared, deep-frozen messages: mutating logged history through a projection is unrepresentable (it throws), replacing the old clone-per-call isolation. External reconstructors fold the same public function over a log prefix, so no two paths can disagree. +**Messages.** `Session.deriveMessages()` is cached: each surface entry is projected exactly once, when first seen, through the public per-event function `deriveEventMessage(event)`; a surface rewrite (a compaction `replace` — `SurfaceManager.replaceGeneration`) rebuilds. Callers get a fresh array per call over shared, deep-frozen messages: mutating logged history through a projection is unrepresentable (it throws), replacing the old clone-per-call isolation. External reconstructors fold the same public function over a log prefix, so no two paths can disagree. -`EpochHeader` records the request's non-history state: call config, rendered system prompt, tool schemas, and session prefix, with empty values canonicalized to absence. `request/header` writes a full initial, resume, or fallback snapshot. `request/header-delta` encodes system changes by common-prefix/suffix line trim, tools by name-keyed additions/removals/changes, and config or prefix by full replacement. `foldRequestHeader`, `diffHeader`, and `applyHeaderDelta` are the pure codec. Each loop instance writes a snapshot on its first request to anchor process boundaries. Deltas are only an optimization: the writer verifies round-trip equality and falls back to a full snapshot for unrepresentable changes such as pure tool reordering. +`EpochHeader` records the request's non-history state: call config, rendered system prompt, tool schemas, and session prefix, with empty values canonicalized to absence. `request/header` always writes a full snapshot: the first loop instance uses reason `initial`, later instances use `resume`, and an in-instance change uses `change`. `foldRequestHeader` selects the latest snapshot. Legacy `request/header-delta` events and the removed `fallback` reason are rejected when appended or loaded. Each step rebuilds prompt assembly. On the instance's first step, `agent/session-prefix` extends a frozen empty seed with request-only opener messages; the result is frozen and cached for that loop instance. `agent/pre-step` then receives the composed prefix before messages are snapshotted immediately ahead of `step/start`. The first call config starts from explicit `AgentOptions`, preserving fork overrides and resume reconfiguration; later calls start from the folded header. `agent/request` may replace only that frozen config seed, while model-visible content enters through logged channels. The loop records the owed header event—the prefix's only durable home—builds `GenerateOptions` from prefix, snapshot, and header, and deep-freezes it while leaving `AbortSignal` live. Per-instance state is only the cached prefix and whether its anchoring snapshot has been written. -**`step/start` is the reconstruction boundary.** A step derives messages from events before that sequence. Injection after the snapshot joins the next request, and reentrant appends are rejected during event publication. `agent/pre-step` is the seam for content needed by the current request. Header reconstruction folds through the step's own `request/header*` event, or carries the prior fold when no new header is written. +**`step/start` is the reconstruction boundary.** A step derives messages from events before that sequence. Injection after the snapshot joins the next request, and reentrant appends are rejected during event publication. `agent/pre-step` is the seam for content needed by the current request. Header reconstruction selects the step's `request/header`, or carries the prior snapshot when no new header is written. **Enforcement.** In development, `dsh-invariants` independently rebuilds each loop request through a fresh `Session`, so the live cache cannot vouch for itself, then compares messages and folded header fields at `llm/stream`. Loop requests are identified by their frozen shape and session id; direct one-shots are excluded. Correctness depends on sequence-bounded reconstruction rather than listener order. A with-key e2e requires positive cache-read tokens after the first request; per-step usage is the production signal, and a header change or compaction appears as a cache-read drop on the next step. @@ -39,15 +39,16 @@ Like MiniCode, the conversation advances append-only and resets only when model- - **Per-call request scalars** (a freely mutable config handed to each `agent/request` dispatch): a listener flips the model per call with zero accounting, silently abandoning the provider cache this design exists to protect. Config is per-conversation logged state; the waterfall proposes, the log records. - **Detect-and-report** (compare consecutive requests, warn on divergence): catches violations after the fact; a violating request is still constructible and ships. Rejected for interface-level unrepresentability. - **Event-driven assembly** (re-render only on change signals): a missed-signal bug class — a tool registered mid-session emits `tools/change`, not `system-prompt/change`, and a third-party provider may emit nothing. Per-step render + value compare is robust with zero signal discipline. -- **Narrative fields on the header events** (a `reason`/`changed` list on deltas): derivable by diffing consecutive events — one home per fact; snapshots carry a reason because an anchor's cause is NOT derivable from the data. +- **A custom header-delta codec** (system line edits, name-keyed tool edits, whole config/prefix replacements): reduced repeated bytes but duplicated the representation and its diff/apply/fallback machinery. Full snapshots retain one replay representation. +- **Narrative changed-field lists on header snapshots**: derivable by comparing consecutive snapshots. The `reason` remains because an instance boundary is not derivable from the snapshot values. ## Consequences - A request that is not explained by the log cannot be constructed by accident — not by the loop, not by a listener; mutating a built request throws; every header change is a durable, diffable log event. - Choosing between the advisory channels is a change-frequency decision, and the design makes the stable one structural: an `agent/session-prefix` contribution is composed once per loop instance and reused verbatim, so it extends the cacheable prefix at zero marginal cost and CANNOT bust the provider cache mid-session; content that changes mid-session flows through the append-only history channels — `agent.inject()` and tool/prompt-submit `additionalContexts` — each a durable `context/message` paid once and prefix-cached thereafter, at the price of accumulating in history and the log. Route session-frozen openers to the prefix and change notices to the history channels; a per-step request-only tail slot was deliberately dropped (no consumer, and a durable append covers every current update pattern). -- What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replace node), a real prompt/tool change (`request/header-delta`), a config switch (ditto), a process boundary with drift (`'resume'` snapshot differing from its predecessor). The provider's own reasoning-content exclusion is managed server-side. +- What still costs full price at the provider is inherent and logged: compaction (its `compact/*` events and replacement entry), a real prompt, tool, or config change (`request/header` with reason `change`), or a process boundary with drift (a differing `resume` snapshot). The provider's own reasoning-content exclusion is managed server-side. - The `step/start`-listener behavior change (above) is the one observable semantics change for plugins; `agent/pre-step` is the current-request seam. -- Tool-result trimming (planned) needs no new mechanism: a logged single-node surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic. -- Session logs grow one `request/header` snapshot per conversation (system + tool schemas: the dominant term), plus deltas on real changes — small next to `assistant/chunk` volume; `SESSION_FORMAT_VERSION` stays `0` (pre-release churn is absorbed, backends reject-not-migrate). +- Tool-result trimming (planned) needs no new mechanism: a logged single-entry surface replace (`start === end`) carrying a trimmed `tool/result` under the same `callId` — compaction-family, replay-correct, cache-bust batched by the same pressure logic. +- Session logs grow one `request/header` snapshot per loop instance plus snapshots on real changes. This is larger than a delta codec but small beside chunk-heavy logs and retains one replay representation. `SESSION_FORMAT_VERSION` stays `0`; legacy delta events are rejected rather than migrated. - Snapshot goldens changed once (every transcript gains its header events); the fs-writing fixtures are stored in the normalized authored form with cwd-relative tool arguments, because replay only round-trips cwd-independent argument paths. - FIXME(call-config-shape): revisit `LlmCallConfig`'s exact field set — which fields are genuinely epoch-level for cache purposes (`model` certainly; the sampling scalars sit there out of caution), and where provider-specific extras (reasoning options, extra body params) belong when an adapter needs them. diff --git a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml index c2fb5daa62..d1756c9186 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml +++ b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.i18n.yaml @@ -2,5 +2,5 @@ # 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-llm-model-catalog-and-acp-selection.md: bacfe180faf4d600d027a7aab6073130012b6022 -2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 7e4bbf835a50c31c28bc40e3030425455390b598 +2026-07-15-llm-model-catalog-and-acp-selection.md: d84fe9fdb75bd2d28a00269c84d29c4223798253 +2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 019819c4aa5ab4ad281b5b32daa76a004c9d6466 diff --git a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md index bacfe180fa..d84fe9fdb7 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md +++ b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md @@ -36,7 +36,7 @@ The session's current target is added to the displayed options when its adapter Agent setup installs scoped `system-prompt/assemble` and `agent/request` listeners. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched. -The request header remains the durable source of truth. When a selected target is actually used, the existing `request/header` or `request/header-delta` event records it. `session/load` initializes the ACP selection from the folded last request header before falling back to bridge config. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state. +The request header remains the durable source of truth. When a selected target is actually used, the existing full `request/header` snapshot records it. `session/load` initializes the ACP selection from the folded last request header before falling back to bridge config. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state. ACP's experimental `providers/*` capability is not used. That draft surface configures provider base URLs, protocols, and headers, including secrets; it does not enumerate models and would give the UI authority to rewrite deployment-owned adapter configuration. diff --git a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md index 7e4bbf835a..019819c4aa 100644 --- a/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md +++ b/docs/rfc/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md @@ -36,7 +36,7 @@ ACP 选择还必须保留提供方维度。同一个模型 ID 可能存在于多 Agent setup 会安装作用域内的 `system-prompt/assemble` 与 `agent/request` 监听器。Prompt 组装为每个 step 只快照一次选中的字段组合，在下游 prompt 监听器完成后覆盖组装结果中的 `provider` 与 `model` 变量；请求监听器则在下游请求监听器完成后应用同一个快照。因此，异步组装期间发生的选择会从下一个 step 生效，不会导致 prompt 文本与路由分裂。其他调用配置字段保持不变。 -请求头仍是持久化事实来源。当选中目标被实际使用时，现有 `request/header` 或 `request/header-delta` 事件会记录它。`session/load` 先从折叠后的最后请求头初始化 ACP 选择，再回退到 bridge 配置。一个从未被请求使用的选择只保留在内存中，因为它从未成为模型可见状态。 +请求头仍是持久化事实来源。当选中目标被实际使用时，现有的完整 `request/header` 快照会记录它。`session/load` 先从折叠后的最后请求头初始化 ACP 选择，再回退到 bridge 配置。一个从未被请求使用的选择只保留在内存中，因为它从未成为模型可见状态。 本功能不使用 ACP 的实验性 `providers/*` 能力。该草案接口配置提供方 base URL、协议和 headers，其中可能包含密钥；它不枚举模型，并且会赋予 UI 改写部署所有的适配器配置的权力。 diff --git a/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml b/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml new file mode 100644 index 0000000000..e1d17fef0b --- /dev/null +++ b/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: 34df0383d1b8ae8047c4283eef3800de772c3cae +2026-07-15-replay-token-meter-service.zh.md: 51f319f3c473fe247791e69133eef4280b768002 diff --git a/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md b/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md new file mode 100644 index 0000000000..34df0383d1 --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md @@ -0,0 +1,60 @@ +# 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 the configured context 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 stale accounting. + +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 providers and models, old logs can lack chunk provenance, and usage fields separate input, cache-read, cache-write, output, and reasoning counts. A useful service therefore combines the latest exact anchor with conservative heuristic 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. `TokenMeterService` itself exposes `contextWindow`, `measure(session, requestHeader?)`, and `estimateMessage(message)`; consumers call the singleton service directly. + +The service has one `contextWindow`, defaulting to 128,000 tokens and configurable as a positive integer. Estimation uses a fixed four-characters-per-token heuristic plus structural overhead. There are no model profiles, density settings, tokenizer backends, or language-specific strategies. + +### Per-session replay folds + +Each session owns one 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 full request-header snapshots, 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?)` synchronizes the fold once and returns scalar pressure together with positional per-node prices. `totalTokens` remains request-and-response pressure; `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override changes pressure pricing only, while the surface fields always describe the current session. `estimateMessage(message)` applies the fixed heuristic without session state. Each result is one detached, deeply immutable snapshot carrying one `logRevision`. Every measurement clones the current nodes and is therefore O(surface). + +Provider usage is reused only when the measured canonical request envelope equals the latest successful-call anchor. Any provider, model, system, prefix, tool, or call-config change causes complete heuristic repricing. Surface changes remain a signed delta from a matching anchor, including negative values after a shrinking replacement. A later successful request replaces the earlier anchor, including across provider or model switches. + +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 singleton service consistently prices pressure, retention, shadowed content, provenance, and non-shrinking-summary rejection. + +Automatic compaction uses one unified measurement for each threshold-and-retention decision. The region transaction measures after appending its durable `compact/start` lock and again after asynchronous summarization; any intervening durable append changes `logRevision` and prevents replacement. + +Compact policy has service-wide defaults: threshold ratio `0.8`, retained tail `floor(contextWindow × 0.16)`, empty summarization provider/model, maximum summary output `8192`, one extra compaction attempt, and automatic triggering enabled. Top-level `thresholdRatio` and `retainTokens` override the pressure policy; retention must remain below the resulting threshold. `summarizationProvider` and `summarizationModel` must both be set or both be empty; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. + +The pre-step trigger measures a provisional envelope: the current prompt and prefix override logged values, while the latest logged header supplies provider, model, tools, and other call config. A router-only agent without a complete provider/model pair skips that provisional check because `agent/request` can route later; any routed target can use the singleton estimator. + +## Testing + +Unit coverage pins service configuration, fixed estimation, envelope invalidation, latest-anchor replacement across provider/model switches, usage and missing-usage paths, seeded append/replace replay, signed deltas, provenance modes, malformed boundaries, unified snapshot detachment and deep immutability, surface-total equality, listener ordering, reload, compact defaults, routing fallback, one-call automatic decisions, retention, convergence, and log-revision 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. +- **Keep model-keyed windows and density profiles** — rejected because the deployment currently has one context policy and one estimator. Model registries, unknown-model failures, and configurable density add branches without a second behavior to select. +- **Keep separate scalar and surface measurements** — rejected because callers would need two reads and revision matching for one decision. A scalar-only read could avoid cloning nodes below threshold, but the split API introduces a caller-side race window; the unified snapshot accepts O(surface) cloning in exchange for coherence. +- **Treat provider usage as portable between envelopes** — rejected because model, tools, prefixes, and call config are request facts. Mismatch reprices the whole current request. + +## Consequences + +- Token pressure has one replay-aware owner that compaction and future plugins can share. +- The default makes the bundled composition usable with two zero-config plugin entries; deployments override one context capacity when needed. +- Fixed heuristic pricing remains an estimate of provider behavior and is not an exact tokenizer or request serializer. +- Every measurement clones the current positional surface and therefore costs O(surface), including pressure checks that finish below threshold. +- 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. diff --git a/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md b/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md new file mode 100644 index 0000000000..51f319f3c4 --- /dev/null +++ b/docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md @@ -0,0 +1,60 @@ +# RFC: 回放式 token 计量服务 + +Status: implemented + +[English](2026-07-15-replay-token-meter-service.md) | 中文 + +## 问题 + +上下文压力并不只对压缩有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求占用了已配置上下文窗口的多少容量？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现回放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方复用陈旧的核算结果。 + +提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少分片来源，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。 + +## 决策 + +### 一个具体的 LLM 家族服务 + +`@deepseek-ai/dsh-token-meter` 是 `packages/llm/` 下的单个具体包，并注册 `ctx.tokenMeter`。在第二种实现出现之前，它不会被拆成接口与后端。`TokenMeterService` 本身公开 `contextWindow`、`measure(session, requestHeader?)` 与 `estimateMessage(message)`；消费方直接调用这个单例服务。 + +服务只有一个 `contextWindow`，默认值为 128,000 token，并允许配置为正整数。估算采用固定的每 token 四个字符启发式规则，并加上结构开销。服务不提供模型 profile、密度设置、分词器后端或语言专用策略。 + +### 逐会话回放折叠 + +每个会话都有一个隔离的增量折叠。活跃折叠通过 `session/event` 前进；每次读取都会追到持久日志尾部，因此监听器顺序、种子会话与服务重载不会改变答案。折叠跟踪规范的完整请求头快照、步骤边界、表层追加与替换、assistant usage，以及 assistant 分片来源。下一个畸形事件会以事务方式失败并保持未读，不会让状态只修改一半。 + +`measure(session, requestHeader?)` 只同步一次折叠，并在返回标量压力的同时给出逐位置节点价格。`totalTokens` 仍表示请求与响应压力；`surfaceTokens` 是仅针对表层的启发式总量，并等于 `nodes[].tokens` 之和。`requestHeader` 覆盖只改变压力定价，表层字段始终描述当前会话。`estimateMessage(message)` 不依赖会话状态，直接应用固定启发式规则。每个结果都是一个分离且深度不可变的快照，只携带一个 `logRevision`。每次计量都会复制当前节点，因此成本为 O(surface)。 + +只有当待计量的规范请求信封等于最近一次成功调用的锚点时，服务才复用提供方 usage。提供方、模型、系统提示词、前缀、工具或调用配置任一变化都会触发完整的启发式重新定价。表层变化相对匹配锚点保留有符号增量，包括缩小替换后的负值。后续成功请求会替换先前锚点，提供方或模型切换时也一样。 + +Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket 求和，不会再次加入推理计数。每次成功模型调用都会记录 `assistant/message`，包括无内容调用与达到 token 上限的调用，并带上精确的更早分片 seq。显式空来源列表表示已知为空的提供方流；旧日志中缺失的来源则保守地把持久 assistant 输出视为提供方输出。 + +### compact-basic 消费计量，但不拥有计量 + +`dsh-compact-basic` 要求 `ctx.tokenMeter`；`CompactService` 不增加 token 方法或类型。后端拆分为配置、自动触发、区域事务与摘要器模块，而 `summarize()` 仍是唯一的子类 hook。单例服务一致用于压力、保留、被遮蔽内容、来源以及非缩小摘要拒绝的定价。 + +自动压缩的每次阈值与保留联合决策只使用一次统一计量。区域事务先追加持久 `compact/start` 锁，再执行一次计量，并在异步摘要完成后再次计量；期间任何持久追加都会改变 `logRevision`，从而阻止替换。 + +压缩策略采用服务级默认值：阈值比例 `0.8`、保留尾部 `floor(contextWindow × 0.16)`、空的摘要提供方/模型、摘要最大输出 `8192`、一次额外压缩尝试，以及启用自动触发。顶层 `thresholdRatio` 与 `retainTokens` 覆盖压力策略；保留值必须小于最终阈值。`summarizationProvider` 与 `summarizationModel` 必须同时设置或同时为空；空组合先解析最近记录的请求目标，再使用 `AgentOptions` 中的组合。 + +pre-step 触发器计量临时请求信封：当前提示词与前缀覆盖日志值，最近记录的请求头给出提供方、模型、工具及其他调用配置。没有完整提供方/模型组合的纯路由 agent（智能体）会跳过该临时检查，因为 `agent/request` 仍可稍后路由；任意已路由目标都可使用这个单例估算器。 + +## 测试 + +单元覆盖固定服务配置、固定估算、信封失效、提供方/模型切换时替换最新锚点、有无 usage 的路径、种子追加/替换回放、有符号增量、来源模式、畸形边界、统一快照的分离性与深度不可变性、表层总量相等性、监听器顺序、重载、压缩默认值、路由回退、自动决策单次调用、保留、收敛与日志修订回滚。真实 Loader/Include YAML fixture 按依赖顺序加载精确的零配置 token-meter 与 compact-basic 包名称。 + +## 考虑过的替代方案 + +- **把估算保留在 `CompactService` 内**——不予采纳，因为计量拥有独立于压缩的消费方与回放语义；它还会强迫每个压缩器暴露同一套无关 API。 +- **立即把 token meter 拆成接口与启发式后端**——不予采纳，因为目前只有一种实现。单个具体服务保留未来接缝，同时避免推测性的包与配置。 +- **保留模型键控的窗口与密度 profile**——不予采纳，因为当前部署只有一种上下文策略与一个估算器。模型注册表、未知模型错误和可配置密度只增加分支，却没有第二种行为可供选择。 +- **保留独立的标量与表层计量**——不予采纳，因为消费方必须为一次决策执行两次读取并匹配修订号。仅读取标量可以避免在低于阈值时复制节点，但拆分 API 会在消费方引入竞态窗口；统一快照接受 O(surface) 复制成本，以换取结果一致性。 +- **在不同信封之间移用提供方 usage**——不予采纳，因为模型、工具、前缀与调用配置都是请求事实。不匹配时会重新定价完整当前请求。 + +## 后果 + +- Token 压力拥有一个可供压缩与未来插件共享的回放感知所有者。 +- 默认值让内置组合只需两个零配置插件条目即可使用；部署需要时只覆盖一个上下文容量。 +- 固定启发式定价仍然只是提供方行为的估计，并不是精确分词器或请求序列化器。 +- 每次计量都会复制当前的位置表层，因此成本为 O(surface)，低于阈值即可结束的压力检查也不例外。 +- 遇到畸形持久边界时，计量会明确失败。这会把损坏的回放转化为具名集成错误，而不是让压力静默漂移。 +- pre-step 压缩集成可能跳过纯路由的首次检查，也可能错过请求中间件稍后应用的工具或路由变化。 diff --git a/docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md b/docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md index 75eaf3207f..864428bc58 100644 --- a/docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md +++ b/docs/rfc/implemented/feature/2026-06-18-compaction-capability-seam.md @@ -6,9 +6,9 @@ Status: implemented A long-running agent conversation grows without bound. As the event log accumulates turns, the derived message history eventually approaches the model's context window — the model then truncates mid-response (`max-tokens`) or degrades. **Compaction** is the mitigation: replace a run of older history with a concise summary, keeping recent context intact. -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*. +The [session surface](../../implemented/architecture/2026-06-18-session-surface.md) was built as the foundation for exactly this — an ordered projection over the event log with a `surfaceOp: { op: 'replace', start, end }` operation purpose-built to shadow a range of entries 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 singleton service lets multiple consumers share one per-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 and requires `session === agent.session`; implementations reject mismatch before model resolution, lock acquisition, summarization, or log mutation. 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) @@ -56,7 +56,7 @@ Auto-compaction fires before **every** step, not once per turn. This is **load-b A runaway turn thus compacts exactly like any other history: its early *closed* steps get summarized while its recent steps stay verbatim. When the only compactable content left is an un-splittable open tail step (its tool-calls have no results yet), compaction declines (`null`) and retries once that step closes. -**Single-unit overflow is out of scope, by design.** If a single retained unit — one closed step, or a large free node such as a pasted `user/message` — *alone* exceeds the budget, compaction cannot help and the next model call may go out over-budget. Bounding an individual unit's size is a separate concern (output truncation), handled elsewhere; compaction makes no promise about it, and the harness without such a mechanism can still break on a single oversized unit. This is named honestly rather than papered over. +**Single-unit overflow is out of scope, by design.** If a single retained unit — one closed step, or a large free entry such as a pasted `user/message` — *alone* exceeds the budget, compaction cannot help and the next model call may go out over-budget. Bounding an individual unit's size is a separate concern (output truncation), handled elsewhere; compaction makes no promise about it, and the harness without such a mechanism can still break on a single oversized unit. This is named honestly rather than papered over. ### Head-anchoring: one auto checkpoint, always at the head @@ -64,11 +64,11 @@ 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 defaults: threshold ratio `0.8`, retained tail `floor(contextWindow × 0.16)`, empty summarization-model override, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`. Optional top-level `thresholdRatio` and `retainTokens` override the policy for the token meter's single context window; retention must remain 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 -Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed nodes *and* the bookkeeping events. The `compact/*` events are pure log records (lock + provenance). The surface mutation sits **inside** the lock — `compact/end` is the last event appended: +Because `SurfaceEventType` is closed, the summary cannot ride on a `compact/*` event. The backend instead appends a **single `user/message`** with `surfaceOp: { op: 'replace', start, end }` whose `content` is the (framed) summary and whose `sourceEventSeqs` covers the shadowed entries *and* the bookkeeping events. The `compact/*` events are pure log records (lock + provenance). The surface mutation sits **inside** the lock — `compact/end` is the last event appended: ``` compact/start → log-only. Acquires the lock. @@ -79,7 +79,7 @@ user/message → surfaceOp { op:'replace', start, end }. THE surface mutatio compact/end → log-only. Releases the lock (carries `error` on a recoverable failure). ``` -`deriveMessages()` then yields `[summary_as_user_message, ...retained_nodes]`. Reusing `user/message` is honest rather than a workaround: a summary genuinely *is* user-role context. +`deriveMessages()` then yields `[summary_as_user_message, ...retained_entries]`. Reusing `user/message` is honest rather than a workaround: a summary genuinely *is* user-role context. ### Checkpoint framing + incremental merge (backend-private) @@ -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 answers both edges from one per-cut balance sequence 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). +- **`dsh-compact`** owns `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)`, 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 answers both edges from one per-cut balance sequence; stale or missing seqs and orphan results reject. `dsh-session` continues to own the surface `replace` operation, ordered event sequences, and rewrite generation. +- **`dsh-invariants`** drops its `surface replace: start must be <= end` assertion: a head-anchored compaction lands a high-seq replacement entry 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**: `examples/coding-agent/cordis.yml` loads zero-config `dsh-token-meter` before `dsh-compact-basic`; the service-wide window and compact defaults make the pair usable without repeated numeric policy. ## Testing diff --git a/docs/rfc/implemented/feature/2026-06-29-todo-write-tool.md b/docs/rfc/implemented/feature/2026-06-29-todo-write-tool.md index 126c69f1c0..06bc6daf6a 100644 --- a/docs/rfc/implemented/feature/2026-06-29-todo-write-tool.md +++ b/docs/rfc/implemented/feature/2026-06-29-todo-write-tool.md @@ -20,7 +20,7 @@ The list is appended as a `todo/write` event carrying the full `{ todos }` snaps ### NOT a surface event -`todo/write` is deliberately excluded from `SurfaceEventType`. The surface is the projection that produces the LLM message history (`deriveMessages()`); a todo write produces no conversation message. So it carries no `surfaceOp`, never joins the surface linked list, and never reaches `deriveMessages()` — it is durable, replayable *UI* state that travels alongside the conversation without being part of it. (The dev-mode invariants still require it to sit inside an open turn, which it always does: it is appended mid-step during a tool call.) +`todo/write` is deliberately excluded from `SurfaceEventType`. The surface is the projection that produces the LLM message history (`deriveMessages()`); a todo write produces no conversation message. So it carries no `surfaceOp`, never joins the ordered surface, and never reaches `deriveMessages()` — it is durable, replayable *UI* state that travels alongside the conversation without being part of it. (The dev-mode invariants still require it to sit inside an open turn, which it always does: it is appended mid-step during a tool call.) ### Priority synthesized only at the ACP boundary diff --git a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md index 8a2af04494..1356afa06b 100644 --- a/docs/rfc/implemented/feature/2026-06-30-interception-seams.md +++ b/docs/rfc/implemented/feature/2026-06-30-interception-seams.md @@ -36,7 +36,7 @@ Core dispatch and the tool body sit inside normalization boundaries, so tool, li 1. **Open the turn before prompt policy.** A fully blocked batch becomes a zero-step `rejected` turn, preserving enclosure and giving ACP a durable terminal event. Every veto also records `prompt/blocked` with the original prompt and reason, so mixed batches retain blocked inputs. Every allowed `additionalContexts` entry is injected into the open turn. -2. **Post-tool `additionalContexts` are buffered and appended AFTER all `tool/result`s.** `content`/`feedback` shape the result `execute()` returns, but each context is a SEPARATE `context/message`, and a single step or composite tool can produce many. Appending context immediately would interleave `result(c1) → context → result(c2)` or place nested context before its outer result, breaking tool-call/result adjacency. `ToolRunContext.deferContext()` therefore collects nested-dispatch context through failures, `execute()` surfaces the ordered array on `ToolExecutionResult`, and the loop appends every entry only after every `tool/result` in the step. An accepted outer call preserves deferred contexts before decision contexts; an outer block discards deferred contexts and exposes only contexts explicitly supplied by the blocking decision. +2. **Post-tool `additionalContexts` and asynchronous injections enter the active-batch FIFO and append when that batch settles.** `content`/`feedback` shape the result `execute()` returns, but each context is a separate `context/message`, and a single step or composite tool can produce many. Appending context immediately would interleave `result(c1) → context → result(c2)` or place nested context before its outer result, breaking tool-call/result adjacency. `ToolRunContext.deferContext()` therefore collects nested-dispatch context through failures, `execute()` surfaces the ordered array on `ToolExecutionResult`, and the loop accepts it into the same FIFO as `agent.inject()` calls made during execution. The FIFO appends after every recorded result when the batch settles, including before an interrupted turn closes. An accepted outer call preserves deferred contexts before decision contexts; an outer block discards deferred contexts and exposes only contexts explicitly supplied by the blocking decision. 3. **A forced `continue` `reason` is enqueued through the steering channel**, so the next step's top-of-loop drain records it as steering for the continued turn — next-*step* steering within the SAME turn, not a next-*turn* prompt (matching the existing `hasSteering` force-continue override). diff --git a/docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md b/docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md index c56e1eb0ba..e841de8973 100644 --- a/docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md +++ b/docs/rfc/implemented/feature/2026-07-06-explicit-tool-order.md @@ -38,7 +38,8 @@ Config plumbing follows the `persona` precedent, and `toolOrder` sits beside it: - Every registry-built assembly starts with a deterministic tool order on every host; absent an expert listener that deliberately changes it, every `request/header` event and model request inherits that order. The CI-vs-local registration-order flip is structurally gone, and the default is lexicographic. - The initial `PromptAssembly.tools` is canonical, so waterfall listeners start from the model-facing order; provider registration order is observable nowhere before that cooperative seam. -- A pure tool reordering between steps is representable only as a `request/header` `'fallback'` snapshot (the name-keyed `ToolsDelta` cannot express it); with a stable canonical order such reorders no longer occur in practice, so the fallback path stays a safety valve. +- The snapshot suite's single pinned request-header fixture (`text-turn`) carries the new canonical tool order; every other ACP snapshot keeps the header bulk scrubbed as `{{system}}`/`{{tools}}`, per the pinned-header design. +- A pure tool reordering between steps is logged like any other header change: a full `request/header` snapshot with reason `'change'`. Stable canonical order prevents registration timing from creating such changes in the ordinary path. - The `toolOrder` key rides the app → `agent-core` → `SystemPrompt` forwarding chain, so deployments set it next to `persona` in the app config; `dsh-llm` and the agent loop are untouched. - A misspelled or unloaded tool name in `toolOrder` fails the turn at prompt assembly, not the boot: the loop assembles inside the turn (after `turn/start`, before `step/start`), so the rejection reaches the turn's outer catch — the turn closes balanced with an `error` reason carrying the message, `agent/error` mirrors it, no step opens, no `request/header` is logged, no request reaches the adapter, and the agent returns to idle. Every turn fails identically until the config is fixed; the process itself stays up (matching the repo rule that explicit config references must not be silently ignored — the enforcement point is the assembly because no earlier universal moment exists). - A tool provider that returns the reserved rest-entry name has the same prompt-assembly failure shape as an unknown listed name. This keeps the sentinel from becoming an ambiguous real tool and preserves the "never drops a tool" ordering contract. diff --git a/docs/rfc/implemented/feature/2026-07-06-sandbox.md b/docs/rfc/implemented/feature/2026-07-06-sandbox.md index 68208b1d66..e236154cdc 100644 --- a/docs/rfc/implemented/feature/2026-07-06-sandbox.md +++ b/docs/rfc/implemented/feature/2026-07-06-sandbox.md @@ -155,7 +155,7 @@ Each phase gets its full design when picked up, validated against the code at th - **A generic `env/state` facts map with an owner service** — rejected: approval and sandbox compose independently, so neither's state may drag in a third package; single-key folds are one `findLast` each, dissolving the owner service; no invariant spans the knobs, so atomic multi-key patches bought nothing. - **Narrate via `agent/user-message` + a bus event** — rejected: it presupposes a turn-entry seam that does not exist (the real seam is `agent/prompt-submit`), and pre-step's position serves both the coalesced turn-entry notice and the mid-turn immediacy bound with one listener. - **A standing prompt statement of the sandbox mode (+ a switch narrator)** — shipped first, then removed on live evidence: with `Bash commands run under the "read-only" file sandbox.` in every request, the model refused to ATTEMPT denied-then-escalatable work (five of twelve turns in the first manual session ended with zero tool calls), turning the sandbox into a soft lockout. The denial marker names the mode at the moment it matters and the escalation fields carry the recovery; the approval knob keeps its statement because an auto-rejection is behaviorally indistinguishable from a human "no". -- **Track "last told" with its own bookkeeping events** — rejected: the `request/header*` fold already records the exact prompt the model saw; parsing the closed candidate sentences back replaces a second bookkeeping stream — events are needed only where they ARE the store. +- **Track "last told" with its own bookkeeping events** — rejected: the `request/header` fold already records the exact prompt the model saw; parsing the closed candidate sentences back replaces a second bookkeeping stream — events are needed only where they ARE the store. - **ACP session modes instead of config options** — rejected: the preset is already one deployment-defined config-option select, and modes are slated for removal in ACP v2. ## Consequences diff --git a/docs/rfc/implemented/feature/2026-07-07-session-prefix.md b/docs/rfc/implemented/feature/2026-07-07-session-prefix.md index 34cdb8789d..05f254a21e 100644 --- a/docs/rfc/implemented/feature/2026-07-07-session-prefix.md +++ b/docs/rfc/implemented/feature/2026-07-07-session-prefix.md @@ -22,21 +22,20 @@ Because composition runs before the boundary snapshot, a composing listener's se ## Testing -[Interception tests](../../../../packages/core/agent-loop/tests/interception.spec.ts) pin compose-once reuse with no header deltas, prepend order, empty-prefix omission, immutability, and composition before pre-step; [cancellation tests](../../../../packages/core/agent-loop/tests/cancel.spec.ts) pin discard and recomposition. Session codec, invariant, and compaction tests cover header round trips, request reconstruction, and prefix-aware pressure accounting. Snapshot normalization preserves prefix counts, while the [pinned-header scenario](../testing/2026-07-06-pin-request-header-content-in-one-scenario.md) owns content and the default example remains prefix-free. No prefix-specific e2e is needed because the seam is deterministic and provider-independent; the with-key [request-cache e2e](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts) covers its cache economics. +**Unit** — [interception.spec.ts](../../../../packages/core/agent-loop/tests/interception.spec.ts) pins compose-once across turns and steps (one composition and no changed headers), canonical prepend ordering, empty-prefix omission from the header, the frozen seed (in-place push throws), held-reference mutation immunity, and composition-precedes-pre-step with the seam receiving the composed value; [cancel.spec.ts](../../../../packages/core/agent-loop/tests/cancel.spec.ts) pins cancel/dispose landing inside the composition window and the discard-and-recompose stale-cache guard; dsh-session header tests cover canonical prefix snapshots and latest-snapshot folding; dsh-invariants tests pin the `messagePrefix + derivation` equation; dsh-compact-basic tests pin that the pressure estimate counts the handed prefix. **Snapshot** — the acp-snapshot normalizer scrubs header prefixes to count-preserving `{{messagePrefix}}` tokens (unit-covered in dsh-acp-snapshot); header content itself is pinned per [the pinned-header scenario RFC](../testing/2026-07-06-pin-request-header-content-in-one-scenario.md), and the example tree loads no prefix contributor, so live goldens stay prefix-free. **e2e** — none prefix-specific: the seam is provider-independent and deterministic; the with-key cache measurement in [request-cache.e2e.ts](../../../../packages/core/agent-loop/tests/request-cache.e2e.ts) already proves the cacheable-prefix economics the design rests on. ## Alternatives considered -- **Per-request `before`/`after` slots recomputed every step** (the shape first proposed: a waterfall firing on every request, contributing frozen `before` messages ahead of the history and fresh `after` messages behind it) — rejected. A per-step `before` recompose invites silent drift — nothing anchors it to the log short of logging a header delta per step — and an `after` slot sits behind the growing history, so its tokens re-pay on every request and everything after it is uncacheable. Measured against the alternatives, every current update pattern is served cheaper by a durable append (paid once, cache-read thereafter), and the only content with no home was the session-stable opener — which wants freezing, not recomputation. -- **A system-prompt section** (`system-prompt/assemble`) — rejected for this content: the assembly renders to the single `system` string, so message-shaped openers do not fit, and the system prompt is deliberately re-assembled per step (with header deltas when it changes) while the opener wants instance-frozen semantics. +- **Per-request `before`/`after` slots recomputed every step** (the shape first proposed: a waterfall firing on every request, contributing frozen `before` messages ahead of the history and fresh `after` messages behind it) — rejected. A per-step `before` recompose invites drift that must be logged as a full changed header, and an `after` slot sits behind the growing history, so its tokens re-pay on every request and everything after it is uncacheable. Measured against the alternatives, every current update pattern is served cheaper by a durable append (paid once, cache-read thereafter), and the only content with no home was the session-stable opener — which wants freezing, not recomputation. +- **A system-prompt section** (`system-prompt/assemble`) — rejected for this content: the assembly renders to the single `system` string, so message-shaped openers do not fit, and the system prompt is deliberately re-assembled per step (with a full changed header when it changes) while the opener wants instance-frozen semantics. - **A durable history opener** (`inject()` at session start) — rejected: permanent history is the failure mode in the problem statement — replayed everywhere, compactable, stale across resumes. -- **Compose per turn instead of per instance** — rejected: a turn-boundary recompose either desyncs silently from the log or forces a header delta per change, and it busts the provider cache exactly as often as it fires; the legitimate refresh point is the instance boundary, where the `'resume'` snapshot already records drift attributably. +- **Compose per turn instead of per instance** — rejected: a turn-boundary recompose either desyncs silently from the log or forces a full changed header, and it busts the provider cache exactly as often as it fires; the legitimate refresh point is the instance boundary, where the `'resume'` snapshot already records drift attributably. - **Compose lazily at the first request and let compaction read the folded header** (the shape as first merged) — superseded in review: the fold matches the live prefix only from the instance's second request on, so on a resumed/forked instance's first step the pressure gate read the PREVIOUS instance's prefix and could under-gate. Composing before the first pre-step and handing the live value through the seam makes the estimate exact at every step. -- **A dedicated session event carrying the prefix** — rejected: the header events are the request's non-history record by design; a second event would be a second home for the same fact and another codec to keep total. +- **A dedicated session event carrying the prefix** — rejected: request headers are the request's non-history record by design; a second event would be a second home for the same fact. ## Consequences - `agent/pre-step` and `CompactService.compactIfNeeded` carry a `sessionPrefix` parameter: every pre-step listener and compaction backend sees the real per-instance value (all in-repo implementations updated in the same change, per the pre-release stance). - A contributor whose content changes mid-session is not re-read until the next instance — by design. A deployment needing mid-session catalog updates routes the change notice through the append-only history channels and pays one durable `context/message`. - The dropped `after` slot leaves no request-only channel near the request tail; nothing in the repo needs one, and adding it back would re-open the every-step re-pay cost the design exists to avoid. -- The `request/header-delta` `messagePrefix` arm (whole-array replacement, empty array encoding transition to absence) exists for codec totality; the loop never exercises it, because the cached prefix cannot change within an instance. - An empty composition is canonical absence: no-contributor deployments log no extra header bytes and their requests are the bare derivation. diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 7ea5f4390e..4d592af42b 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -52,7 +52,7 @@ Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` ( The plugin exposes one config field, validated by schemastery and documented in [the config catalog](../../../config-catalog.md): `vmTimeoutMs` (default 5000), the millisecond bound on the synchronous portion of mount-code evaluation. Tool names, the `cordis-dynamic` group name, and the `dyn-` id prefix are structural vocabulary and stay fixed. All three tools render as `generic` cards per [the tool cookbook](../../../cookbook/adding-a-tool.md) (`cordis_inspect` a `read`, `cordis_mount` an `execute` carrying the code as `rawInput`, `cordis_unmount` a `delete`), with no `presentResult` overrides. -Model-visible ⟺ logged holds with no new session event type: a mount or unmount is visible only through its own `tool/call` / `tool/result` pair, which the loop logs, and the changed tool set a mount induces is logged by the request-header delta the loop already emits when schemas change between steps. There is deliberately no `cordis/mount` provenance event — it would duplicate what the tool-call pair records. Dynamic mounts are process-lifetime, not session state: resuming a persisted session rehydrates the conversation but does not re-mount plugins. +Model-visible ⟺ logged holds with no new session event type: a mount or unmount is visible only through its own `tool/call` / `tool/result` pair, which the loop logs, and the changed tool set a mount induces is logged by the full changed request header the loop emits when schemas change between steps. There is deliberately no `cordis/mount` provenance event — it would duplicate what the tool-call pair records. Dynamic mounts are process-lifetime, not session state: resuming a persisted session rehydrates the conversation but does not re-mount plugins. ## Alternatives considered @@ -71,7 +71,7 @@ The correctness investment therefore goes where it pays for every capability at **A hand-maintained service/event reference in the tool.** The first cut of the inspect tool carried a hand-written table of service method signatures. It was replaced by the generated `api-catalog.ts` because a hand table drifts from the JSDoc the moment a signature changes and nothing gates the drift, whereas the generated artifact is freshness-checked against the same AST the docs use. -**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a request-header delta, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. +**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a full changed request header, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. **A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. diff --git a/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md index 3746e2c64c..90fbc1cfb4 100644 --- a/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md +++ b/docs/rfc/implemented/feature/2026-07-10-parallel-tool-call-execution.md @@ -44,7 +44,7 @@ Only dispatch and the tool body overlap. `tools/pre-execute` and `tools/post-exe Each started call appends `tool/call` immediately before its pre-execute gate. Completed dispatches occupy model-order slots, and a commit cursor appends `tool/result` and collects `additionalContexts` only when the next slot is ready. Live surfaces may show several pending calls, but results and post-tool context remain model-ordered. -An abort before a group starts records no calls from that group. An abort during a group stops replenishment, waits for already-started calls, commits their results in order, drops their buffered additional context, and then ends the step through the existing abort path. Calls that never start have no audit event. +An abort before a group starts records no calls from that group. An abort during a group stops replenishment, waits for already-started calls, commits their results in order, drains accepted batch context after those results, and then ends the step through the existing abort path. Calls that never start have no audit event. Code Mode remains outside this scheduler because the model emits one native `run_code` call. `run_code` and its internal dispatch queue remain serial; native sibling calls in `mode: 'both'` use the normal scheduler. diff --git a/docs/rfc/implemented/feature/2026-07-10-session-query-service.md b/docs/rfc/implemented/feature/2026-07-10-session-query-service.md index ebc201f102..ee2acc62e1 100644 --- a/docs/rfc/implemented/feature/2026-07-10-session-query-service.md +++ b/docs/rfc/implemented/feature/2026-07-10-session-query-service.md @@ -18,7 +18,7 @@ An exact target read first checks the live store and snapshots the live header a ## Surface semantics -`dsh-session` exports `foldSurface(events)`, and `SurfaceManager` uses the same transition functions for its incremental cache. The fold returns detached current nodes and each replacement's actual removed seqs. `listEvents()` and `traceEvent()` use that result to classify every raw event, so inspection cannot disagree with model-history derivation about positional replacement semantics. +`dsh-session` exports `foldSurface(events)`, and `SurfaceManager` uses the same transition functions for its incremental cache. The fold returns detached current event sequences and each replacement's actual removed seqs. `listEvents()` and `traceEvent()` use that result to classify every raw event, so inspection cannot disagree with model-history derivation about positional replacement semantics. `readEvent()` returns the complete target plus raw neighbors by contiguous seq. `before` and `after` default to zero and are independently bounded by `readWindowMax`, default 50. The result carries a cloned `SessionHeader`, not a source-availability record, because determining a live target's persisted flag would violate the guarantee that live exact reads do not depend on persistence health. diff --git a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.i18n.yaml b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.i18n.yaml index c7984ee20a..f1d38d7d95 100644 --- a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.i18n.yaml +++ b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.i18n.yaml @@ -2,5 +2,5 @@ # 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-14-time-context-plugin.md: aa24c6246718cfe0bb3ed63d0791cf890514d9fe -2026-07-14-time-context-plugin.zh.md: e939ff1d0cb250f3fa7a7db34b50d92760e3374d +2026-07-14-time-context-plugin.md: b8b54156e08aa1212866d46500ad1ca65b4f4f14 +2026-07-14-time-context-plugin.zh.md: 0af261c66a9b52cdf250294b4bfdc240176c8434 diff --git a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md index aa24c62467..b8b54156e0 100644 --- a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md +++ b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md @@ -32,11 +32,11 @@ When `timeZone` is omitted, `Intl.DateTimeFormat` resolves the Node process's sy ### Logging and token shape -The loop records the temporal block through `request/header` and `request/header-delta` before transmission, satisfying the [reconstructable-requests contract](../architecture/2026-07-05-reconstructable-requests.md). Each request carries one current block; earlier readings do not remain in conversation history. The plugin owns the fact and contributes it through the prompt registry, following the [prompt-variables RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) without a loop special case. +The loop records the temporal block in full `request/header` snapshots before transmission, satisfying the [reconstructable-requests contract](../architecture/2026-07-05-reconstructable-requests.md). Each request carries one current block; earlier readings do not remain in conversation history. The plugin owns the fact and contributes it through the prompt registry, following the [prompt-variables RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md) without a loop special case. ## Testing -Unit tests pin formatting, baselines, refresh policy, validation, per-agent state, disposal, and load-time system-zone capture. A real agent-loop test pins the transmitted prompt and `request/header-delta`. A keyless subprocess e2e boots a test-only `cordis.yml` through the real Loader and stdio app, omits `timeZone` under a controlled `TZ`, drives two turns, and verifies the persisted request headers externally. Default snapshot compositions omit the plugin, so their transcript fixtures contain no temporal block. +Unit tests pin formatting, baselines, refresh policy, validation, per-agent state, disposal, and load-time system-zone capture. A real agent-loop test pins the transmitted prompt and full `request/header` snapshots. A keyless subprocess e2e boots a test-only `cordis.yml` through the real Loader and stdio app, omits `timeZone` under a controlled `TZ`, drives two turns, and verifies the persisted request headers externally. Default snapshot compositions omit the plugin, so their transcript fixtures contain no temporal block. ## Alternatives considered @@ -54,6 +54,6 @@ Unit tests pin formatting, baselines, refresh policy, validation, per-agent stat - Opted-in models receive a zoned clock and inter-turn duration without a tool call. The system-prompt cost is fixed per request instead of growing with the session. - An omitted `timeZone` follows the process's `TZ`, host, or container zone as observed at plugin load. Operators must configure an explicit zone when the deployment environment does not represent the intended user. -- A refresh changes the request header and can add a `request/header-delta`. `refreshIntervalMs` trades freshness against durable deltas; `0` records a new value on every step whose whole-second rendering changes. +- A refresh changes the request header and can add a full `request/header` snapshot with reason `change`. `refreshIntervalMs` trades freshness against the number and size of durable full snapshots; `0` records a new value on every step whose whole-second rendering changes. - No request exists solely to refresh time. A long-running tool leaves the prior reading until the next step assembles. - Duration reflects harness processing time at durable append boundaries, not client-network latency before logging. Preserving a client-origin timestamp requires a separate durable input contract. diff --git a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.zh.md b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.zh.md index e939ff1d0c..0af261c66a 100644 --- a/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.zh.md +++ b/docs/rfc/implemented/feature/2026-07-14-time-context-plugin.zh.md @@ -32,11 +32,11 @@ Status: implemented ### 日志与 token 形态 -agent loop（智能体循环）会在发送前通过 `request/header` 和 `request/header-delta` 记录时间区块，从而满足[可重建请求契约](../architecture/2026-07-05-reconstructable-requests.md)。每个请求只携带一个当前区块；先前的读数不会保留在会话历史中。该插件拥有时间信息，并按照[提示词变量 RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)通过提示词注册表贡献该信息，无需为循环添加特殊分支。 +agent loop（智能体循环）会在发送前通过完整的 `request/header` 快照记录时间区块，从而满足[可重建请求契约](../architecture/2026-07-05-reconstructable-requests.md)。每个请求只携带一个当前区块；先前的读数不会保留在会话历史中。该插件拥有时间信息，并按照[提示词变量 RFC](../architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)通过提示词注册表贡献该信息，无需为循环添加特殊分支。 ## 测试 -单元测试固定格式化、基线、刷新策略、校验、逐 agent 状态、资源释放行为，以及系统时区在加载时的捕获行为。使用真实 agent loop 的测试固定实际发送的提示词和 `request/header-delta`。无密钥子进程端到端测试通过真实 Loader 和 stdio 应用启动测试专用 `cordis.yml`，在受控 `TZ` 下省略 `timeZone`，驱动两个轮次，并从外部校验持久请求头。默认快照组合不包含该插件，因此其中的 transcript（文本记录）fixture（测试前置数据）不包含时间区块。 +单元测试固定格式化、基线、刷新策略、校验、逐 agent 状态、资源释放行为，以及系统时区在加载时的捕获行为。使用真实 agent loop 的测试固定实际发送的提示词和完整的 `request/header` 快照。无密钥子进程端到端测试通过真实 Loader 和 stdio 应用启动测试专用 `cordis.yml`，在受控 `TZ` 下省略 `timeZone`，驱动两个轮次，并从外部校验持久请求头。默认快照组合不包含该插件，因此其中的 transcript（文本记录）fixture（测试前置数据）不包含时间区块。 ## 考虑过的替代方案 @@ -54,6 +54,6 @@ agent loop（智能体循环）会在发送前通过 `request/header` 和 `reque - 选择加入的模型无需调用工具，即可获得分区时钟和轮次间隔时长。每个请求的系统提示词成本固定，不会随会话增长。 - 省略 `timeZone` 时，插件采用加载时观察到的进程 `TZ`、主机或容器时区。当部署环境不能代表目标用户时，运维方必须显式配置时区。 -- 刷新会改变请求头，并可能新增 `request/header-delta`。`refreshIntervalMs` 用新鲜度换取持久增量记录的数量；设为 `0` 时，每个整秒渲染结果发生变化的步骤都会记录新值。 +- 刷新会改变请求头，并可能新增一份 reason 为 `change` 的完整 `request/header` 快照。`refreshIntervalMs` 用新鲜度换取完整持久快照的数量与大小；设为 `0` 时，每个整秒渲染结果发生变化的步骤都会记录新值。 - 系统不会仅为刷新时间而创建请求。长时间运行的工具会保留先前读数，直至下一步骤开始组装。 - 时长反映持久追加边界处的 harness 处理时间，不包含消息进入日志之前的客户端网络延迟。若要保留客户端来源时间戳，需要单独的持久输入契约。 diff --git a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml index a89248ac6f..ce964f71da 100644 --- a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml +++ b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.i18n.yaml @@ -2,5 +2,5 @@ # 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-16-durable-per-step-time-context.md: 12d8191eb72b3fabd3164f13a77d9944631b906e -2026-07-16-durable-per-step-time-context.zh.md: 977ffb7276011ac9ae9b8a72a726bb23baba0a2d +2026-07-16-durable-per-step-time-context.md: 4a0828111faf9f787c2d338024c42680a4a697e2 +2026-07-16-durable-per-step-time-context.zh.md: f745cf7da7c38f9682abf9d8f210bcba328c8a51 diff --git a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.md b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.md index 12d8191eb7..4a0828111f 100644 --- a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.md +++ b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.md @@ -44,7 +44,7 @@ Their baseline is the durable event timestamp of the preceding time-context mess Each reading remains a normal surface node until compaction shadows it; positive interval scheduling never removes existing readings. A later request therefore sees the cumulative unshadowed readings that affected earlier preparation and steps, rather than a system-prompt value rewritten in place. -The plugin contributes nothing to system-prompt assembly. `request/header` and `request/header-delta` contain no time-context text; request reconstruction obtains the complete durable surface prefix at each `step/start`. Readings and requests need not map one-to-one because a failed preparation can leave a reading while interval suppression can prepare a request without appending one. The plugin depends on the agent registry for its lifecycle listener and does not require the system-prompt service at runtime. +The plugin contributes nothing to system-prompt assembly. `request/header` contains no time-context text; request reconstruction obtains the complete durable surface prefix at each `step/start`. Readings and requests need not map one-to-one because a failed preparation can leave a reading while interval suppression can prepare a request without appending one. The plugin depends on the agent registry for its lifecycle listener and does not require the system-prompt service at runtime. ## Testing diff --git a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md index 977ffb7276..f745cf7da7 100644 --- a/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md +++ b/docs/rfc/implemented/feature/2026-07-16-durable-per-step-time-context.zh.md @@ -44,7 +44,7 @@ Elapsed since the preceding step context: . 每个读数都作为普通表层节点保留，直至压缩将其隐藏；正数间隔调度绝不会移除已有读数。因此，后续请求会看到影响先前准备过程和步骤且尚未被隐藏的累计读数，而不是一个被原地改写的系统提示词值。 -插件不向系统提示词组装贡献任何内容。`request/header` 和 `request/header-delta` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为失败的准备过程可能留下读数，而间隔抑制也可能使请求准备过程不追加读数。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。 +插件不向系统提示词组装贡献任何内容。`request/header` 不包含时间上下文文本；请求重建从每个 `step/start` 取得完整的持久表层前缀。读数与请求无需一一对应，因为失败的准备过程可能留下读数，而间隔抑制也可能使请求准备过程不追加读数。插件通过 agent 注册表使用生命周期监听器，运行时不需要系统提示词服务。 ## 测试 diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.i18n.yaml b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.i18n.yaml new file mode 100644 index 0000000000..9424f2aa24 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.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-17-run-ci-examples-from-built-lib.md: aae88ee965b4e2211f3a53aeb9c0ee4944d95c2a +2026-07-17-run-ci-examples-from-built-lib.zh.md: 0cd3822a71b8f7399be93beaac74b2177fcbe7ca diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md new file mode 100644 index 0000000000..aae88ee965 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.md @@ -0,0 +1,42 @@ +# RFC: Run CI examples from built lib + +Status: implemented + +English | [中文](2026-07-17-run-ci-examples-from-built-lib.zh.md) + +## Problem + +CI boots examples and Cordis-backed test projects through `node --import tsx` and the root tsconfig `paths` map. This adds TypeScript transformation cost and changes package resolution: imports resolve to workspace source instead of following package `exports` into built `lib/`. + +These runs therefore do not test the same code or resolution behavior as an installed consumer. A package can pass CI while its built export graph is incomplete or resolves differently. + +## Decision + +Execution has two modes. `src` is the default local-development mode and uses tsx; `lib` is the strict CI mode and starts built bins with plain Node, without tsx or tsconfig path mapping. + +- CI subprocesses that boot an example or a checked-in `cordis.yml` use `lib` mode. +- TypeScript fixtures that only implement an ACP or MCP peer and do not load Cordis run directly with Node. An explicit source-path regression may remain in `src` mode. + +### Resolution topology + +Every test Cordis config must resolve its bare modules by walking upward from the config directory. + +- `examples/` is one pnpm workspace member and provides the shared `examples/node_modules` resolution root. +- Every checked-in test Cordis config, including snapshot configs and package-owned fixtures, lives under its corresponding `examples//` tree. A config owned by `packages///` maps to `examples//tests/fixtures///cordis.yml`; the test driver and assertions remain package-local. +- Every package named by an example Cordis config is declared in both `examples/package.json` for `lib` resolution and the root `tsconfig.json` references for `src` mode. + +### Launch policy + +The shared Loader test harness selects `src` or `lib` from `DSH_EXAMPLE_MODE`. CI builds first and selects `lib`; an unset mode keeps the fast local source loop. + +## Alternatives considered + +- **Keep CI on tsx** — rejected because it preserves transformation overhead and source-only resolution behavior. +- **Use lib everywhere** — rejected because local development would require a build before every run. Dual mode keeps that cost out of the development loop. +- **Build a private `node_modules` tree per test** — rejected because it duplicates consumer scaffolding. The `examples/` workspace root gives every Cordis config one real and declared resolution path. + +## Consequences + +- CI validates built package exports without tsx changing module resolution; local development retains the no-build source loop. +- CI must build before these tests, and manual `lib` runs can observe stale local artifacts. +- Cordis config dependencies are not visible to normal TypeScript import analysis, so `examples/package.json` and the root tsconfig references must stay synchronized with the configs. diff --git a/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md new file mode 100644 index 0000000000..0cd3822a71 --- /dev/null +++ b/docs/rfc/implemented/process/2026-07-17-run-ci-examples-from-built-lib.zh.md @@ -0,0 +1,42 @@ +# RFC: 在 CI 中从构建后的 lib 运行示例 + +Status: implemented + +[English](2026-07-17-run-ci-examples-from-built-lib.md) | 中文 + +## 问题 + +CI 通过 `node --import tsx` 和根 tsconfig 的 `paths` 映射启动示例与加载 Cordis 配置的测试项目。这种方式既增加了 TypeScript 转换开销，也改变了包解析行为：import 会解析到 workspace 源码，而不是经包的 `exports` 进入构建后的 `lib/`。 + +因此，这些测试没有覆盖已安装消费方实际运行的代码和解析路径。即使包的构建导出图不完整或解析结果不同，CI 仍可能通过。 + +## 决策 + +执行机制包含两种模式。`src` 是本地开发的默认模式并使用 tsx；`lib` 是严格的 CI 模式，通过 plain Node 启动构建后的 bin，不加载 tsx，也不使用 tsconfig 路径映射。 + +- CI 中启动示例或签入仓库的 `cordis.yml` 的子进程使用 `lib` 模式。 +- 仅实现 ACP 或 MCP 对端、且不加载 Cordis 的 TypeScript fixture（测试前置数据）直接由 Node 运行。只有显式验证源码路径的回归测试可以保留 `src` 模式。 + +### 解析拓扑 + +每个测试 Cordis 配置都必须能从配置文件所在目录向上解析裸模块。 + +- `examples/` 作为一个 pnpm workspace 成员，提供统一的 `examples/node_modules` 解析根目录。 +- 所有签入仓库的测试 Cordis 配置，包括快照配置和包内测试 fixture，都放在对应的 `examples//` 目录树下。归属 `packages///` 的配置映射到 `examples//tests/fixtures///cordis.yml`；测试驱动和断言仍留在包内。 +- 示例 Cordis 配置中引用的每个包都同时登记在 `examples/package.json` 和根 `tsconfig.json` 的 references 中，分别支持 `lib` 与 `src` 解析。 + +### 启动策略 + +共享 Loader 测试 harness 通过 `DSH_EXAMPLE_MODE` 选择 `src` 或 `lib`。CI 先构建再选择 `lib`；未设置模式时保留快速的本地源码开发回路。 + +## 曾考虑的替代方案 + +- **CI 继续使用 tsx**：不予采纳，因为它会保留转换开销和仅适用于源码的解析行为。 +- **所有环境只使用 lib**：不予采纳，因为本地开发每次运行前都必须构建。双模式避免把这项成本带入开发回路。 +- **每个测试单独构造 `node_modules`**：不予采纳，因为它会重复消费方脚手架。以 `examples/` 作为 workspace 根，可让每个 Cordis 配置通过同一条真实且显式声明的路径解析模块。 + +## 后果 + +- CI 可以验证构建后的包导出，不再受 tsx 模块解析影响；本地开发仍保留免构建的源码回路。 +- CI 必须先构建再运行这些测试；手动执行 `lib` 模式时可能读取陈旧的本地产物。 +- 常规 TypeScript import 分析无法识别 Cordis 配置依赖，因此 `examples/package.json`、根 tsconfig references 与配置文件必须保持同步。 diff --git a/docs/rfc/implemented/simplification/2026-07-12-simplify-session-log-representation.md b/docs/rfc/implemented/simplification/2026-07-12-simplify-session-log-representation.md new file mode 100644 index 0000000000..7bf44c6c06 --- /dev/null +++ b/docs/rfc/implemented/simplification/2026-07-12-simplify-session-log-representation.md @@ -0,0 +1,33 @@ +# RFC: Simplify session-log representation + +Status: implemented + +## Problem + +The session log maintains two representations that cost more machinery than their consumers require: a pseudo-linked surface and custom request-header deltas. + +`SurfaceManager` stores the same order in an array, a seq map, and mutable `prev`/`next` links. Production never reads either link: compact's tool-pairing balance answers from per-cut balances cached in surface order. Replacement already uses `indexOf`, so the links do not make its dominant operation constant-time. A seq array with linear replacement lookup has the same asymptotic replacement cost and one representation to validate. + +The request-header subsystem implements a custom system/tool delta codec and transmission-decision layer even though its contract says deltas are an encoding optimization, not a reconstructability requirement. Retaining the initial/resume full snapshot at each loop-instance boundary, then writing a canonical full `request/header` whenever that instance's assembled header changes, preserves replay while deleting `SystemDelta`, `ToolsDelta`, round-trip fallback, and the durable `request/header-delta` variant. Codec-only vocabulary disappears with the codec, not because its individual arms were invalid. + +The implementation retains append and replacement `sourceEventSeqs`, crash-repair provenance, and all `SessionStartSource` variants because those fields have an audit/interception role that zero current readers does not overturn. + +## Decision + +`SurfaceManager.nodes` is a `readonly number[]` of event sequences; the public `SurfaceNode` shape, node links, and seq-to-node map are removed. The internal replace-generation signal remains. The complete `foldSurface()` read used by session-query returns the same number-array representation plus replacement metadata without making the incremental manager retain history. Tool-pairing balance and compaction use event sequences and surface positions; the compact-owned per-cut balance cache does not depend on node links. + +Request headers use canonical full snapshots only. Initial and resume anchors remain full snapshots even when unchanged; an in-instance change appends another full `request/header` with reason `change`. The delta event, codec types, diff/apply helpers, and codec-only `fallback` reason are removed. Request reconstruction selects the latest snapshot. + +`SESSION_FORMAT_VERSION` remains pinned at `0`, so seed, append, and persistence-load validation explicitly reject old v0 `request/header-delta` events and full snapshots carrying the removed `fallback` reason. There is no compatibility fold or migration. JSONL and SQLite tests pin this fail-loud boundary, and the ACP snapshot harness represents legitimate mid-session changes as full pinned headers and full readable prompts. + +## Alternatives considered + +**Keep linked nodes and compact deltas for possible scale.** Links could help a future cursor API, and deltas can reduce logs when large tool schemas change by a small amount. No shipped cursor uses the links, while full snapshots trade disk size for substantially simpler correctness. If header volume proves material, compression or a measured canonical-delta scheme can be designed around real traces. + +## Verification + +Unit coverage pins ordered-surface append/replace behavior, tool pairing, compaction, full-header folding/logging, request reconstruction, and dev invariants. Seed validation plus JSONL and SQLite load tests reject the legacy event before replay. The keyless ACP suite exercises record, refresh, replay, changed-header pinning, and the sandbox mode-switch fixture in the new shape. + +## Consequences + +Full headers increase log volume, and linear replacement lookup could be slower on very large surfaces. Replacements were already linear because the prior implementation called `indexOf`; benchmarks are deferred until real traces show the simpler array is a bottleneck. The format version remains `0`, so explicit legacy-event rejection is a permanent part of the pre-release format boundary. In return, surface order and request-header state each have one representation, deleting link maintenance, maps, codec arms, round-trip fallback, and delta-aware snapshot normalization. diff --git a/docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md b/docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md index 42c67320f6..69af84b0f0 100644 --- a/docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md +++ b/docs/rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md @@ -8,11 +8,11 @@ An ACP snapshot suite needs to prove the exact composed system prompt and tool-s ## Decision -Exactly one scenario per header-composition class is flagged `pinsHeader`. Its directory splits the pin by review format: `system-prompt.golden.md` contains the normalized composed prompt as ordinary Markdown, `tool-schemas.golden.json` contains the complete initial schemas and later schema edits as structured JSON, and `session.jsonl` retains config, reason, and any model-visible prefix while storing `header.system` and `header.tools` as `"{{system}}"` / `"{{tools}}"`. Every other JSONL uses the same prompt and tool tokens and also tokenizes session-prefix content. The pin mechanics live in [`dsh-acp-snapshot`](../../../../packages/support/acp-snapshot/README.md), whose suite factory enforces one pin per class. +Exactly one scenario per header-composition class is flagged `pinsHeader`. Its directory splits the pin by review format: `system-prompt.golden.md` contains the normalized full prompt sequence as ordinary Markdown, `tool-schemas.golden.json` contains the corresponding complete schema sequence as structured JSON, and `session.jsonl` retains config, reason, and any model-visible prefix while storing `header.system` and `header.tools` as `"{{system}}"` / `"{{tools}}"`. Every other JSONL uses the same prompt and tool tokens and also tokenizes session-prefix content. The pin mechanics live in [`dsh-acp-snapshot`](../../../../packages/support/acp-snapshot/README.md), whose suite factory enforces one pin per class. -The pure `scrubSystemPrompts` and `scrubToolSchemas` normalizers apply to every stored session fixture and independently tokenize initial-header content plus header-delta bulk. `scrubRequestHeaders` also tokenizes session-prefix content for non-pinning scenarios while retaining structural facts: system-delta positions and arity, added/removed/changed tool names, prefix message count, field presence, config, and reason. Record and refresh write-back apply the appropriate scrub before writing JSONL and regenerate both sidecars from the normalized live header and deltas, so neither path can reintroduce prompt/schema bulk into JSONL or leave a review artifact stale. +The pure `scrubSystemPrompts` and `scrubToolSchemas` normalizers independently tokenize every stored full header. `scrubRequestHeaders` also tokenizes session-prefix content for non-pinning scenarios while retaining header count, field presence, config, reason, and prefix message count. Record and refresh write-back apply the appropriate scrub before writing JSONL and regenerate both sidecars from the normalized live full-header sequence, so neither path can reintroduce prompt/schema bulk into JSONL or leave a review artifact stale. -Guards make the split self-enforcing. On disk, every `session*.jsonl` is a fixed point of both prompt and schema scrubbers, only non-pinning fixtures must be fixed points of the full header scrub, both sidecars exist exactly beside pinning fixtures in canonical newline-terminated formats, and each class has one pin. Live, every `request/header` produced by a parent, spawn child, fork child, initial request, or resume must match the reconstructed pin after volatile-value normalization; the pinning run's prompt and schema deltas must also match their sidecars. A header without a string prompt, without an array-valued tool list, or with an undeclared `request/header-delta` fails loud. +Guards make the split self-enforcing. On disk, every `session*.jsonl` is a fixed point of both prompt and schema scrubbers, only non-pinning fixtures must be fixed points of the full header scrub, both sidecars exist exactly beside pinning fixtures in canonical newline-terminated formats, and each class has one pin. Live, every `request/header` produced by a parent, spawn child, fork child, initial request, resume, or in-instance change must match the reconstructed class sequence after volatile-value normalization. A header without a string prompt, without an array-valued tool list, or beyond the pin's declared changed-header count fails loud. One pin covers the whole suite because every session — parent, spawn child, fork child — composes the identical tool list and the identical prompt modulo cwd, and the uniformity guard fails the suite the moment that stops holding. If header composition ever becomes session-dependent by design (a restricted subagent toolset, say), the divergent shape gets its own pinning scenario. @@ -26,7 +26,7 @@ One pin covers the whole suite because every session — parent, spawn child, fo ## Verification -The suite replays every scenario against the split pins. Unit coverage exercises the independent and full scrubbers, both sidecar formats, record/refresh regeneration, normalized prompt/schema extraction, fixed-point enforcement, required-file symmetry, reconstructed-header uniformity, and delta rejection. +The suite replays every scenario against the split pins. Unit coverage exercises the independent and full scrubbers, both full-header sidecar formats, record/refresh regeneration, normalized prompt/schema extraction, fixed-point enforcement, required-file symmetry, reconstructed-header uniformity, and changed-header count rejection. ## Consequences diff --git a/docs/rfc/implemented/testing/2026-07-08-shared-acp-snapshot-package.md b/docs/rfc/implemented/testing/2026-07-08-shared-acp-snapshot-package.md index 1fb887db52..b854f3443b 100644 --- a/docs/rfc/implemented/testing/2026-07-08-shared-acp-snapshot-package.md +++ b/docs/rfc/implemented/testing/2026-07-08-shared-acp-snapshot-package.md @@ -16,7 +16,7 @@ The machinery lives in [`packages/support/acp-snapshot`](../../../../packages/su **`src/normalize.ts`** — the pure normalizers, hook-free by policy: when a future event carries a new volatile field (an approval duration, say), the shared normalizer learns it in the same change, keeping one home for what "normalized" means rather than per-suite scrub extensions. -**`src/suite.ts`** — the `Scenario` type and `defineAcpSnapshotSuite(options)`, registering the per-scenario compares, record/refresh fixture write-back, the header pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL a `scrubSystemPrompts` fixed point, non-pinning fixtures also `scrubRequestHeaders` fixed points). The pinned-header contract ([pinned-header RFC](2026-07-06-pin-request-header-content-in-one-scenario.md)) is per-suite: each header class flags exactly one `pinsHeader` scenario, whose `system-prompt.golden.md` and JSONL tool list split the composed header into reviewable artifacts; the uniformity guard compares both against every live header in that class. The pure helpers (`childFixturePaths`, `fixtureContext`, `normalizedHeaders`, `normalizedSystemPrompts`, `formatSystemPromptSnapshot`, `headerDeltaCount`) are exported from the module for direct unit coverage. +**`src/suite.ts`** — the `Scenario` type and `defineAcpSnapshotSuite(options)`, registering the per-scenario compares, record/refresh fixture write-back, the header pin with its live uniformity guard, and the fixture guard block (no orphan scenario dirs, required files present, exactly one pin per class, every JSONL a `scrubSystemPrompts` fixed point, non-pinning fixtures also `scrubRequestHeaders` fixed points). The pinned-header contract ([pinned-header RFC](2026-07-06-pin-request-header-content-in-one-scenario.md)) is per-suite: each header class flags exactly one `pinsHeader` scenario, whose `system-prompt.golden.md` and JSONL tool list split the composed header into reviewable artifacts; the uniformity guard compares both against every live header in that class. A pinning scenario declares any legitimate changed-header count, and its Markdown artifact records every full changed prompt. The pure helpers (`childFixturePaths`, `fixtureContext`, `normalizedHeaders`, `normalizedSystemPrompts`, `formatSystemPromptSnapshot`, `headerChangeCount`) are exported from the module for direct unit coverage. ## Alternatives considered diff --git a/docs/rfc/proposed/feature/2026-07-06-recallable-compaction.md b/docs/rfc/proposed/feature/2026-07-06-recallable-compaction.md index 1de660ac31..6e28e8a31e 100644 --- a/docs/rfc/proposed/feature/2026-07-06-recallable-compaction.md +++ b/docs/rfc/proposed/feature/2026-07-06-recallable-compaction.md @@ -16,7 +16,7 @@ Split the checkpoint into two classes and make shadowed history reachable. ### Frozen index checkpoints -Newly stale history splits into chunks by deterministic policy: accumulate toward `chunkTokens`, snap edges to balanced tool-pairing cuts (`isToolPairingBalanced`), prefer turn boundaries, and place the final boundary as close to the retain boundary as balance allows, so the trailing slice shrinks to roughly one turn. Each chunk is compacted by one `compactRegion` call into an **index stub** (`stubTokens`, ~100–200 tokens): +Newly stale history splits into chunks by deterministic policy: accumulate toward `chunkTokens`, snap edges with `toolPairingBalancedBefore` / `toolPairingBalancedAfter`, prefer turn boundaries, and place the final boundary as close to the retain boundary as balance allows, so the trailing slice shrinks to roughly one turn. Each chunk is compacted by one `compactRegion` call into an **index stub** (`stubTokens`, ~100–200 tokens): - two or three lines of what happened; - a keyword line of low-frequency literal anchors — exact error strings, values, config keys — grouped by kind; diff --git a/docs/rfc/proposed/simplification/2026-07-12-simplify-session-log-representation.md b/docs/rfc/proposed/simplification/2026-07-12-simplify-session-log-representation.md deleted file mode 100644 index 1cb8d5708a..0000000000 --- a/docs/rfc/proposed/simplification/2026-07-12-simplify-session-log-representation.md +++ /dev/null @@ -1,36 +0,0 @@ -# RFC: Simplify session-log representation - -Status: proposed - -## Problem - -The session log maintains two representations that cost more machinery than their consumers require: a pseudo-linked surface and custom request-header deltas. - -`SurfaceManager` stores the same order in an array, a seq map, and mutable `prev`/`next` links. Production never reads either link: compact's tool-pairing balance answers from per-cut balances cached in surface order. Replacement already uses `indexOf`, so the links do not make its dominant operation constant-time. A seq array with linear replacement lookup has the same asymptotic replacement cost and one representation to validate. - -The request-header subsystem implements a custom system/tool delta codec and transmission-decision layer even though its contract says deltas are an encoding optimization, not a reconstructability requirement. Retaining the initial/resume full snapshot at each loop-instance boundary, then writing a canonical full `request/header` whenever that instance's assembled header changes, preserves replay while deleting `SystemDelta`, `ToolsDelta`, round-trip fallback, and the durable `request/header-delta` variant. Codec-only vocabulary disappears with the codec, not because its individual arms were invalid. - -This proposal deliberately retains append and replacement `sourceEventSeqs`, crash-repair provenance, and all `SessionStartSource` variants: implemented RFCs give those fields an audit/interception role that zero current readers does not overturn. - -## Proposal - -Make `SurfaceManager.nodes` a `readonly number[]` of event sequences and remove the public `SurfaceNode` shape. Keep the internal replace-generation signal; update tool-pairing balance and compaction callers to use array values/indices for predecessor, successor, and replacement ranges, removing node links and the seq-to-node map. Replace post-anchor header deltas with canonical full changed-header snapshots and remove the delta codec/event/tests; initial and resume anchors remain full snapshots even when the folded header is unchanged. - -Amend the session-surface and reconstructable-request RFCs where they describe the removed encoding. Update event types/invariants, request logging/replay, persistence fixtures, generated catalogs, package docs, and snapshots. Replace the codec-only `fallback` reason with an explicit `change` reason for post-anchor full snapshots, distinguishing them from the retained `initial` and `resume` anchors. - -`SESSION_FORMAT_VERSION` is deliberately pinned at `0`, so an old v0 log containing `request/header-delta` would otherwise pass the version check and silently lose header changes after the delta fold is deleted. Seed/load validation must reject that legacy event fail-loud at the format boundary; no compatibility fold or migration is added. - -## Alternatives considered - -**Keep linked nodes and compact deltas for possible scale.** Links could help a future cursor API, and deltas can reduce logs when large tool schemas change by a small amount. No shipped cursor uses the links, while full snapshots trade disk size for substantially simpler correctness. If header volume proves material, compression or a measured canonical-delta scheme can be designed around real traces. - -## Acceptance criteria - -- `SurfaceManager.nodes` is one ordered seq array with no `SurfaceNode`, link fields, or seq-to-node map; incremental append processing and the internal replace-generation signal remain. -- Replaying full changed-header snapshots reconstructs exactly the same requests; no header-delta event/type/codec remains. -- A v0 seed or persisted log containing legacy `request/header-delta` is rejected before replay, with coverage for JSONL and SQLite load paths. -- New-shape v0 JSONL/SQLite replay, provenance, crash repair, compaction, snapshots, invariants, typecheck, coverage, doc-sync, build, and hygiene pass. - -## Risks - -Full headers increase log volume, and linear replacement lookup could be slower on very large surfaces. Replacements are already linear because the implementation calls `indexOf`; benchmarks should be added only if real traces show the simpler array is a bottleneck. Because the format version remains `0`, forgetting the explicit legacy-event rejection would be silent data corruption rather than a type error; the fail-loud load test is therefore part of the proposal, not optional cleanup. diff --git a/docs/testing.md b/docs/testing.md index d4acdc33c4..8d4f0f554f 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -26,7 +26,12 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword - Product-visible plugins require a non-unit REAL-composition test. Hand-built `ctx.plugin(...)` suites are insufficient: boot test-only `cordis.yml` through Loader and app/process, mock only external/nondeterministic boundaries, and assert model-visible request/log, durable state, or user-visible output. Keep opt-ins out of shipped defaults. - A guard only guards if the regression actually fails it. For a plugin without `inject` (bundle/composition plugins), a Loader smoke stays green under a broken export shape — add an explicit `expect('default' in mod).toBe(false)` plus an `unwrapExports` round-trip assertion, and prove it: introduce the regression, watch red, revert. - "Real entry path" means the published artifact: the package `bin` points at built `lib/bin.js` under plain `node`, which tsx masks (settle races, module resolution, a swallowed load failure exiting 0). The same applies to any non-index runtime entry the built package resolves at run time (the worker-thread runtime's sibling `lib/worker.cjs`). Keep the built-artifact smokes green (`packages/ui/*/tests/built-bin.e2e.ts`, `packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts`), and assert a genuinely-missing config exits non-zero. -- An e2e that spawns an example from a temp cwd sets `TSX_TSCONFIG_PATH` to the repo-root tsconfig, or it silently falls back to stale built `lib/` ([examples/AGENTS.md](../examples/AGENTS.md)). + +## Test subprocess launch modes + +- CI and build-having test lanes run every example or Cordis-config subprocess from built `lib/` through the shared dual-mode launcher. Do not hand-write `--import tsx` for these subprocesses. +- Protocol and operating-system fixtures that do not load Cordis run erasable `.ts` directly with Node, without tsx or the root paths map. +- Only a test whose subject is source-path resolution may select `src`; state that contract in the test. ## When a snapshot test is required diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 4dac505d4c..f6a2e0625f 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -18,7 +18,7 @@ This table connects model-visible tool names to the plugin package and service s | `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`, `ctx.userInteraction` | `tool/call`, `tool/result after a UI/provider answers the question` | - | ask_user_question pauses the tool call until the active UI provider returns a human answer. | | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`, `ctx.codeRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/code-dispatch per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode RFC). Under `code` it is the registry's only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through serialized bindings that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. | | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`, `ctx.bash`, `ctx.tasks at call time for run_in_background` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. A `run_in_background` run registers with the generic `ctx.tasks` runtime and is collected/stopped through the `task_*` tools from `@deepseek-ai/dsh-tool-tasks`; the `enableRunInBackground` config (default true) removes the parameter entirely when disabled. | -| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. | +| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | | `@deepseek-ai/dsh-tool-fs-search` | `glob`, `grep` | `ctx.tools`, `ctx.bash`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | glob and grep are bash-backed discovery tools: they run fixed ripgrep commands through ctx.bash as ordinary foreground calls (never background tasks). Capped results save the complete formatted list through the optional ctx.spillStore backend; returned locators are follow-up-readable/searchable when the backend exposes local paths in co-located deployments. | | `@deepseek-ai/dsh-tool-skill` | `skill` | `ctx.tools`, `ctx.skills` | `tool/call`, `tool/result` | - | - | @@ -235,7 +235,7 @@ Dispose a plugin previously mounted with cordis_mount, by id. All its registrati Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) -Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. +Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes. ## `@deepseek-ai/dsh-tool-fs` diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md index 8db1a68099..5fc21db2f5 100644 --- a/docs/tool-execution-pipeline.md +++ b/docs/tool-execution-pipeline.md @@ -20,9 +20,9 @@ flowchart TD owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result, tool/code-dispatch"] post["tools/post-execute waterfall
accept, block, replace, add context"] final["tools/result synchronous notification
frozen authoritative outcome"] - context["Buffered additionalContexts
context/message after all tool results"] + context["Active-batch additionalContexts FIFO
context/message after recorded tool results"] toolResult["Session event: tool/result
single model-facing outcome"] - allResults["All calls in the step settled
and tool/result events recorded"] + allResults["Tool batch settled
recorded tool/result events complete"] presentResult["UI completed card
presentResult(args, result)"] model --> toolCall toolCall --> presentCall diff --git a/examples/AGENTS.md b/examples/AGENTS.md index df330de838..6b820368e4 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — Examples -Runnable harness compositions. **Examples are NOT workspaces**: their private `package.json` files are dependency-free stubs, and the cordis Loader boots each `cordis.yml` unbuilt through `tsx` plus the root tsconfig paths. +Runnable harness compositions. `examples/` is one workspace member and the module-resolution root for runnable and test Cordis configs; it is not a build target. [package.json](package.json) declares the packages loaded by those configs, while each leaf's private `package.json` remains metadata only. Extract reusable logic into `packages/`, where per-file coverage and README gates apply. Examples keep only `cordis.yml` wiring, demo artifacts, and e2e/snapshot scenarios; app package bins own boot glue. @@ -13,7 +13,7 @@ Each example has both: Mock-only examples require only the keyless tier; state that exception in the test. -Keyless stdio smokes use `@deepseek-ai/dsh-loader-smoke` for isolation, root-tsconfig loading, subprocess lifecycle, diagnostics, EOF, and cleanup; tests supply paths, environment, input, and assertions. +Keyless stdio smokes use `@deepseek-ai/dsh-loader-smoke`; tests supply paths, environment, input, and assertions. Every checked-in test Cordis config lives under its corresponding `examples//` leaf. Map a package-owned config to `examples//tests/fixtures///cordis.yml`, keep its driver and assertions package-local, and declare every package it names in both root `tsconfig.json` references and `examples/package.json`. Do not inventory example tests here; the `tests/` trees and root scripts are authoritative. diff --git a/examples/acp-agent/tests/acp.e2e.ts b/examples/acp-agent/tests/acp.e2e.ts index 23c6f58301..b19bc9bfb1 100644 --- a/examples/acp-agent/tests/acp.e2e.ts +++ b/examples/acp-agent/tests/acp.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * Boots examples/acp-agent as an ACP subprocess. The key-gated prompt leg @@ -25,8 +26,6 @@ import { // The child runs from a temp cwd, so its bin and config path are absolute. const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -// Resolve tsx absolutely because the subprocess runs outside the repo. -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) // The root tsconfig supplies unbuilt workspace `paths`; making it explicit // avoids accidental resolution through stale built output. const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) @@ -38,24 +37,21 @@ interface Spawned { stderr: string[] } -// TODO(acp-test-harness): this subprocess/client boot glue is duplicated with -// hooks.e2e.ts and partly with dsh-acp-snapshot's harness. Migrate both e2e -// files onto that launcher before the TSX/env/permission-stub details drift. function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawned { - const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { - cwd, - env: { - ...env, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - }, - stdio: ['pipe', 'pipe', 'pipe'], + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + env: { + DSH_PERMISSION_MODE: 'danger-full-access', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, + }) + const child = spawn( + launch.command, + launch.args, + { cwd, env: { ...env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') @@ -138,16 +134,20 @@ describe('acp-agent over real stdio (no key required)', () => { workdir = await mkdtemp(join(tmpdir(), 'acp-e2e-')) // Collect raw stdout bytes directly (bypass the SDK framing) to inspect. // A dummy key boots the adapter; this purity test sends no prompt and makes no model call. - const child = spawn(process.execPath, ['--import', tsxLoader, binScript, '--config', configPath], { - cwd: workdir, + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, env: { - ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', - TSX_TSCONFIG_PATH: repoTsconfig, DSH_PERMISSION_MODE: 'danger-full-access', DSH_HOME: join(workdir, '.dsh'), DSH_AGENTS_HOME: join(workdir, '.agents'), }, + }) + const child = spawn(launch.command, launch.args, { + cwd: workdir, + env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'], }) const out: string[] = [] diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts index 267a307463..e190163a18 100644 --- a/examples/acp-agent/tests/acp.snapshot.ts +++ b/examples/acp-agent/tests/acp.snapshot.ts @@ -74,13 +74,13 @@ const SCENARIOS: Scenario[] = [ { name: 'multi-turn', hasModelTurn: true, recorded: true }, // ACP exposes the adapter catalog as a session-scoped model select. This // scenario pins the default flash request, the switch response, and the - // resulting request-header delta to pro. + // resulting changed request-header snapshot for pro. { name: 'model-switching', hasModelTurn: true, recorded: true, pinsHeader: true, - expectedHeaderDeltas: 1, + expectedHeaderChanges: 1, headerClass: 'model-switching', }, { name: 'error-finish', hasModelTurn: true, recorded: false, overridden: true }, @@ -168,7 +168,7 @@ const SCENARIOS: Scenario[] = [ // Real-kernel confinement remains in escalation.e2e.ts and the sandbox // packages' e2e suites. { name: 'config-options', hasModelTurn: false, recorded: false, headerClass: 'sandbox' }, - { name: 'permission-switching', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderDeltas: 1, headerClass: 'sandbox' }, + { name: 'permission-switching', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderChanges: 1, headerClass: 'sandbox' }, { name: 'escalation-approved', hasModelTurn: true, recorded: true, headerClass: 'sandbox' }, { name: 'escalation-rejected', hasModelTurn: true, recorded: true, headerClass: 'sandbox' }, ] diff --git a/examples/acp-agent/tests/escalation.e2e.ts b/examples/acp-agent/tests/escalation.e2e.ts index e18ecd2f4c..7e1024c23f 100644 --- a/examples/acp-agent/tests/escalation.e2e.ts +++ b/examples/acp-agent/tests/escalation.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * Exercises the default ACP composition through the real bin and Loader. The @@ -28,9 +29,8 @@ import { const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) // The subprocess runs from a temp cwd outside the repo; point tsx at the repo -// tsconfig so the unbuilt `paths` map resolves (see examples/AGENTS.md). +// tsconfig so the unbuilt `paths` map resolves in src mode (see examples/AGENTS.md). const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) // Without a usable bwrap/Seatbelt runner, the strict attempt fails closed with @@ -55,17 +55,19 @@ interface Spawned { /** Boot the example as an ACP subprocess; the scripted client answers every permission prompt with `answer`. */ function spawnAcpAgent(cwd: string, answer: 'allow-once' | 'reject-once'): Spawned { + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + // A dummy key lets the deepseek adapter boot keyless (presence-checked at + // apply, used only on a real model call); the with-key tests carry the + // real key, so the fallback is inert there. + env: { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY || 'sk-dummy-for-boot' }, + }) const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { - cwd, - // A dummy key lets the deepseek adapter boot keyless (presence-checked at - // apply, used only on a real model call); the with-key tests carry the - // real key, so the fallback is inert there. - env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY || 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig }, - stdio: ['pipe', 'pipe', 'pipe'], - }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') diff --git a/examples/acp-agent/tests/hooks.e2e.ts b/examples/acp-agent/tests/hooks.e2e.ts index 99cebb907e..68dc2648bf 100644 --- a/examples/acp-agent/tests/hooks.e2e.ts +++ b/examples/acp-agent/tests/hooks.e2e.ts @@ -15,6 +15,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * With-key e2e for the Claude hook bridge. The process-level `./hooks.json` is @@ -25,7 +26,6 @@ import { const binScript = fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)) const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) interface Spawned { @@ -36,10 +36,16 @@ interface Spawned { } function spawnAcpAgent(cwd: string): Spawned { + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', configPath], + tsconfigPath: repoTsconfig, + env: { DSH_PERMISSION_MODE: 'danger-full-access' }, + }) const child = spawn( - process.execPath, - ['--import', tsxLoader, binScript, '--config', configPath], - { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig, DSH_PERMISSION_MODE: 'danger-full-access' }, stdio: ['pipe', 'pipe', 'pipe'] }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) const stderr: string[] = [] child.stderr.setEncoding('utf8') diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json index 0ca11765c0..57e78b6345 100644 --- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json @@ -342,5 +342,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl b/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl index d045e50c48..ddd1f06a55 100644 --- a/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl +++ b/examples/acp-agent/tests/snapshots/bash-spill/session.jsonl @@ -10,7 +10,7 @@ {"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"call_spill","name":"bash","arguments":"{\"command\":\"node -e \\\"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\\\"\",\"description\":\"Print large deterministic output\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":10,"outputTokens":5}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"} {"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","name":"bash","arguments":"{\"command\":\"node -e \\\"process.stdout.write('SPILL_START-' + 'x'.repeat(2000) + '-SPILL_END')\\\"\",\"description\":\"Print large deterministic output\"}"}} -{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","content":[{"type":"text","text":"SPILL_START-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-SPILL_END\n\n(Omitted 1417 bytes. Full formatted result stored at: /tmp/dsh-acp-snapshot-spill/session-e2a13560e58a/f7e08c805fe9-bash.txt. Use read with offset/limit, or grep this path to search within it.)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} +{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"call_spill","content":[{"type":"text","text":"SPILL_START-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx-SPILL_END\n\n(Omitted 1417 bytes. Full formatted result stored at: /tmp/dsh-acp-snapshot-spill/session-ad78080217cd/dccd97e3c558-bash.txt. Use read with offset/limit, or grep this path to search within it.)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} {"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}} {"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}} {"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} diff --git a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json index b625462818..edf1a7c001 100644 --- a/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/both-mode-turn/tool-schemas.golden.json @@ -289,5 +289,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/code-mode-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/code-mode-turn/tool-schemas.golden.json index 61875ceb85..c2289b4e19 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-turn/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/code-mode-turn/tool-schemas.golden.json @@ -17,5 +17,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/tool-schemas.golden.json index 61875ceb85..c2289b4e19 100644 --- a/examples/acp-agent/tests/snapshots/code-mode-workspace-context/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/code-mode-workspace-context/tool-schemas.golden.json @@ -17,5 +17,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl index e202575a3b..b420fac975 100644 --- a/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl +++ b/examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl @@ -131,8 +131,8 @@ {"type":"assistant/chunk","seq":129,"time":1783962245385,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":130,"time":1783962245385,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a command with sandbox_permissions set to danger-full-access, no prior run needed, justified as instructed."},{"type":"tool-call","id":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":1501,"outputTokens":174,"cacheReadTokens":0,"reasoningTokens":28}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129],"surfaceOp":"append"} {"type":"tool/call","seq":131,"time":1783962245385,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write file outside workspace and verify\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}} -{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"23c17684-b99e-4c10-9c54-ff96ab5d7b89","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} -{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"23c17684-b99e-4c10-9c54-ff96ab5d7b89","outcome":"allowed-once"}} +{"type":"approval/asked","seq":132,"time":1783962245386,"data":{"id":"19974166-a6ad-4f46-bef8-ce7d6bda3214","toolName":"bash","callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} +{"type":"approval/decided","seq":133,"time":1783962245387,"data":{"id":"19974166-a6ad-4f46-bef8-ce7d6bda3214","outcome":"allowed-once"}} {"type":"tool/result","seq":134,"time":1783962245399,"data":{"turn":1,"step":1,"callId":"call_00_d0sAHpJ9mYOJi0z7KNy30441","content":[{"type":"text","text":"escalated\n"}],"isError":false},"sourceEventSeqs":[131],"surfaceOp":"append"} {"type":"step/end","seq":135,"time":1783962245400,"data":{"turn":1,"step":1}} {"type":"step/start","seq":136,"time":1783962245400,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl index 1d6854a0cf..4b45911a66 100644 --- a/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl +++ b/examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl @@ -155,8 +155,8 @@ {"type":"assistant/chunk","seq":153,"time":1783962246274,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}} {"type":"assistant/message","seq":154,"time":1783962246274,"data":{"turn":1,"step":1,"content":[{"type":"reasoning","text":"The user wants me to run a specific command with `sandbox_permissions` set to `danger-full-access` and a specific justification. They explicitly said NOT to run it without sandbox_permissions first. Let me do exactly that."},{"type":"tool-call","id":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":1509,"outputTokens":198,"cacheReadTokens":0,"reasoningTokens":48}},"sourceEventSeqs":[7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49,50,51,52,53,54,55,56,57,58,59,60,61,62,63,64,65,66,67,68,69,70,71,72,73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130,131,132,133,134,135,136,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153],"surfaceOp":"append"} {"type":"tool/call","seq":155,"time":1783962246274,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","name":"bash","arguments":"{\"command\": \"printf 'escalated\\\\n' > /tmp/dsh-escalated.txt && cat /tmp/dsh-escalated.txt && rm /tmp/dsh-escalated.txt\", \"description\": \"Write to /tmp and verify, then clean up\", \"sandbox_permissions\": \"danger-full-access\", \"justification\": \"the user asked to write a file outside the workspace\"}"}} -{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"ebd9ad34-7da0-4417-afa3-a011affc96fd","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} -{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"ebd9ad34-7da0-4417-afa3-a011affc96fd","outcome":"rejected"}} +{"type":"approval/asked","seq":156,"time":1783962246275,"data":{"id":"564d6e1b-4330-42bd-a646-461e7a6c2d1a","toolName":"bash","callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","reason":"escalate sandbox to danger-full-access: the user asked to write a file outside the workspace"}} +{"type":"approval/decided","seq":157,"time":1783962246275,"data":{"id":"564d6e1b-4330-42bd-a646-461e7a6c2d1a","outcome":"rejected"}} {"type":"tool/result","seq":158,"time":1783962246275,"data":{"turn":1,"step":1,"callId":"call_00_WB1vnPomi8yr6MlcFKTj7912","content":[{"type":"text","text":"Error: the user rejected escalating this command to \"danger-full-access\""}],"isError":true},"sourceEventSeqs":[155],"surfaceOp":"append"} {"type":"step/end","seq":159,"time":1783962246276,"data":{"turn":1,"step":1}} {"type":"step/start","seq":160,"time":1783962246276,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl index cbfb635dab..3da0d9171e 100644 --- a/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl +++ b/examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl @@ -55,8 +55,8 @@ {"type":"tool/call","seq":53,"time":1783352172557,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","name":"bash","arguments":"{\"command\": \"echo HELLO\", \"description\": \"Echo HELLO\"}"}} {"type":"hook/invoked","seq":54,"time":1783352172558,"data":{"turn":1,"point":"PreToolUse","dialect":"claude","handlerId":"claude:PreToolUse:1","matcher":"bash"}} {"type":"hook/result","seq":55,"time":1783352172573,"data":{"turn":1,"point":"PreToolUse","handlerId":"claude:PreToolUse:1","decision":"ask","exitCode":0,"durationMs":14.113374999999905}} -{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"b00e28dd-7349-480d-bc56-454247365ca8","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}} -{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"b00e28dd-7349-480d-bc56-454247365ca8","outcome":"rejected"}} +{"type":"approval/asked","seq":56,"time":1783962235813,"data":{"id":"281bce21-7aee-4642-88a9-56917e50829c","toolName":"bash","callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","reason":"bash requires manual approval in this session"}} +{"type":"approval/decided","seq":57,"time":1783962235813,"data":{"id":"281bce21-7aee-4642-88a9-56917e50829c","outcome":"rejected"}} {"type":"tool/result","seq":58,"time":1783962235814,"data":{"turn":1,"step":1,"callId":"call_00_6k0oGSliVHxGSgqBmMEO4311","content":[{"type":"text","text":"Error: the user rejected tool \"bash\""}],"isError":true},"sourceEventSeqs":[53],"surfaceOp":"append"} {"type":"step/end","seq":59,"time":1783962235814,"data":{"turn":1,"step":1}} {"type":"step/start","seq":60,"time":1783962235814,"data":{"turn":1,"step":2}} diff --git a/examples/acp-agent/tests/snapshots/model-switching/session.jsonl b/examples/acp-agent/tests/snapshots/model-switching/session.jsonl index 7fa970f7a1..1f04eca07d 100644 --- a/examples/acp-agent/tests/snapshots/model-switching/session.jsonl +++ b/examples/acp-agent/tests/snapshots/model-switching/session.jsonl @@ -37,7 +37,7 @@ {"type":"turn/start","seq":35,"time":1784086276811,"data":{"turn":2,"trigger":{"kind":"message","source":{"kind":"user"}}}} {"type":"user/message","seq":36,"time":1784086276812,"data":{"content":[{"type":"text","text":"Without using tools, reply with exactly PRO and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"step/start","seq":37,"time":1784086276812,"data":{"turn":2,"step":1}} -{"type":"request/header-delta","seq":38,"time":1784086276813,"data":{"system":{"keepStart":2,"keepEnd":12,"insert":["{{system}}"]},"config":{"provider":"deepseek","model":"deepseek-v4-pro"}}} +{"type":"request/header","seq":38,"time":1784298376621,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-pro"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}} {"type":"assistant/chunk","seq":39,"time":1784086278053,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":40,"time":1784086278053,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":41,"time":1784086278242,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/model-switching/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/model-switching/system-prompt.golden.md index 0b95f67225..b9701e538c 100644 --- a/examples/acp-agent/tests/snapshots/model-switching/system-prompt.golden.md +++ b/examples/acp-agent/tests/snapshots/model-switching/system-prompt.golden.md @@ -14,6 +14,20 @@ Approval prompts are disabled in this session: actions that require approval are Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls. - + + +You are an AI agent powered by the DeepSeek Harness SDK. You are a coding assistant powered by the deepseek-v4-pro model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug. + +Verify your work by running the code or tests. Keep answers brief and factual. + + +Check the [exit code: N] marker on every bash result; investigate failures before moving on. + +Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering. + +Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`). + + +Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls. diff --git a/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.golden.json index f0415911be..7c814257fb 100644 --- a/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/model-switching/tool-schemas.golden.json @@ -273,5 +273,280 @@ } } ], - "deltas": [] + "changes": [ + [ + { + "name": "bash", + "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.", + "parameters": { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "The bash command to execute." + }, + "description": { + "type": "string", + "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"." + }, + "timeoutMs": { + "type": "number", + "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry." + }, + "workdir": { + "type": "string", + "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it." + }, + "run_in_background": { + "type": "boolean", + "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access." + } + }, + "required": [ + "command", + "description" + ] + } + }, + { + "name": "skill", + "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The exact skill name from the available skills list." + } + }, + "required": [ + "name" + ] + } + }, + { + "name": "subagent", + "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "subagent_fork", + "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "task_kill", + "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "reason": { + "type": "string", + "description": "Optional short reason, recorded in the log and forwarded to the task." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "task_list", + "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.", + "parameters": { + "type": "object", + "properties": {} + } + }, + { + "name": "task_output", + "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "wait": { + "type": "boolean", + "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive." + }, + "timeout_ms": { + "type": "number", + "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "todo_write", + "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).", + "parameters": { + "type": "object", + "properties": { + "todos": { + "type": "array", + "description": "The COMPLETE task list, replacing any previous list.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "What the task is — a short imperative line." + }, + "status": { + "type": "string", + "description": "pending (not started) | in_progress (now) | completed (done).", + "enum": [ + "pending", + "in_progress", + "completed" + ] + } + }, + "required": [ + "content", + "status" + ] + } + } + }, + "required": [ + "todos" + ] + } + }, + { + "name": "workflow", + "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.", + "parameters": { + "type": "object", + "properties": { + "script": { + "type": "string", + "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)." + }, + "meta": { + "type": "object", + "description": "The workflow identity block (plain JSON — never code).", + "properties": { + "name": { + "type": "string", + "description": "Short kebab-case workflow name." + }, + "description": { + "type": "string", + "description": "One-line description of what the workflow does." + }, + "whenToUse": { + "type": "string", + "description": "Optional guidance on when this workflow applies." + }, + "phases": { + "type": "array", + "description": "Optional phase declarations matched by phase() calls.", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The phase title phase() calls match by exact string." + }, + "detail": { + "type": "string", + "description": "Optional one-line description of the phase." + }, + "provider": { + "type": "string", + "description": "Optional provider override this phase is expected to use." + }, + "model": { + "type": "string", + "description": "Optional model override this phase is expected to use." + } + }, + "required": [ + "title" + ] + } + } + }, + "required": [ + "name", + "description" + ] + }, + "args": { + "type": "object", + "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})." + } + }, + "required": [ + "script", + "meta" + ] + } + } + ] + ] } diff --git a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl index 965d2de16f..4a62de6642 100644 --- a/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl +++ b/examples/acp-agent/tests/snapshots/permission-switching/session.jsonl @@ -107,7 +107,7 @@ {"type":"user/message","seq":105,"time":1783962244624,"data":{"content":[{"type":"text","text":"Use the bash tool to run exactly: cat out.txt. Then reply with the single word DONE and stop."}],"source":{"kind":"user"}},"surfaceOp":"append"} {"type":"context/message","seq":106,"time":1783962244624,"data":{"content":[{"type":"text","text":"The approval policy changed from \"ask\" to \"never\" (changed by the user)."}],"source":{"kind":"plugin","plugin":"user-approval"}},"surfaceOp":"append"} {"type":"step/start","seq":107,"time":1783962244624,"data":{"turn":2,"step":1}} -{"type":"request/header-delta","seq":108,"time":1783962244624,"data":{"system":{"keepStart":11,"keepEnd":2,"insert":["{{system}}","{{system}}"]}}} +{"type":"request/header","seq":108,"time":1784000791271,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"change"}} {"type":"assistant/chunk","seq":109,"time":1783860671025,"data":{"turn":2,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"reasoning"}}} {"type":"assistant/chunk","seq":110,"time":1783860671026,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":"The"}}} {"type":"assistant/chunk","seq":111,"time":1783860671026,"data":{"turn":2,"step":1,"chunk":{"type":"reasoning-delta","index":0,"text":" user"}}} diff --git a/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md index 95f9bdb600..622bc4e23a 100644 --- a/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md +++ b/examples/acp-agent/tests/snapshots/permission-switching/system-prompt.golden.md @@ -13,7 +13,20 @@ Track every background task id you start. You are notified in-session when a tas Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls. - + + +You are an AI agent powered by the DeepSeek Harness SDK. + +You are a coding assistant powered by the deepseek-v4-flash model. Your working directory is {{cwd}}. Your bash tool runs under a file sandbox — a `[sandbox: file access denied …]` result is policy, not a command bug. + +Verify your work by running the code or tests. Keep answers brief and factual. + + +Check the [exit code: N] marker on every bash result; investigate failures before moving on. + +Track every background task id you start. You are notified in-session when a task finishes — do not busy-poll or sleep on one; keep working on independent steps and do not duplicate a running task's work. Before giving a final answer, collect every still-relevant task with task_output (set wait: true only when you are genuinely blocked on it), and task_kill tasks that stopped mattering. Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`). + +Use the workflow tool ONLY when the user explicitly asks for a workflow or for large multi-agent orchestration: you write a JavaScript script (the tool description documents the exact format) that fans work out across many subagents with phases and structured results. For one or two delegations, prefer plain subagent calls. diff --git a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json index f0415911be..7c814257fb 100644 --- a/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/permission-switching/tool-schemas.golden.json @@ -273,5 +273,280 @@ } } ], - "deltas": [] + "changes": [ + [ + { + "name": "bash", + "description": "Execute a bash command (`bash -c`) and return its stdout/stderr. Each call runs in a fresh shell: no state (cwd, variables, functions) persists between calls — pass `workdir` instead of using `cd`. Non-zero exits are reported as `[exit code: N]`. Current harness environment facts are exposed through managed `$DSH_*` variables; inspect them when needed. Commands may run under a file sandbox; a blocked file operation is reported as `[sandbox: file access denied under mode]` — a policy denial, not a bug in the command; do not retry another way. Long output is truncated to its tail; the full output is saved to a file whose path is reported when available. Set `run_in_background: true` for long-running commands: the call returns a task id immediately; read its output with `task_output` and stop it with `task_kill`. Attempting a command the sandbox may deny is safe and expected: run it and read the marker rather than assuming the denial. When a command is denied and a wider mode would let it succeed, escalate immediately in the same turn — the one sanctioned exception to a denial: retry the exact same command once with `sandbox_permissions` (the narrowest wider mode that suffices) plus a one-sentence `justification`. Do not detour through chat to ask permission first — the approval prompt raised by that retry is how the user consents. If the session states approval prompts are disabled, there is no exception: a denial is final — do not set `sandbox_permissions`. Never escalate speculatively: ground the request in a real denial — normally the one this command just hit; escalating up front is fine only when this session already denied the same access. A rejected escalation is final for that command — stop and explain, never work around it — but it does not forbid attempting or escalating other commands later.", + "parameters": { + "type": "object", + "properties": { + "command": { + "type": "string", + "description": "The bash command to execute." + }, + "description": { + "type": "string", + "description": "Clear, concise description of what this command does in active voice, 5-10 words (shown in the UI). Examples: \"ls\" → \"List files in current directory\"; \"git status\" → \"Show working tree status\"; \"npm install\" → \"Install package dependencies\"." + }, + "timeoutMs": { + "type": "number", + "description": "Timeout in milliseconds. The executor applies its configured default and cap, and kills the command on expiry." + }, + "workdir": { + "type": "string", + "description": "Working directory for this command. Defaults to the session workspace; a relative path is resolved against it." + }, + "run_in_background": { + "type": "boolean", + "description": "Run in the background and return a task id immediately (collect with task_output, stop with task_kill). No timeout applies." + }, + "sandbox_permissions": { + "type": "string", + "description": "The wider sandbox mode this command needs. Only valid as a one-shot retry of a command the sandbox just denied; requires justification and user approval.", + "enum": [ + "workspace-write", + "danger-full-access" + ] + }, + "justification": { + "type": "string", + "description": "Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access." + } + }, + "required": [ + "command", + "description" + ] + } + }, + { + "name": "skill", + "description": "Load the full instructions for an available skill. Call this with the exact skill name from the session skill catalog before acting on a task that names or clearly matches that skill.", + "parameters": { + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "The exact skill name from the available skills list." + } + }, + "required": [ + "name" + ] + } + }, + { + "name": "subagent", + "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) and return its final result. Use this to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent runs to completion and you receive only its final answer, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "subagent_fork", + "description": "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn), returning only its final result. Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive only its final answer, not its intermediate steps. Set `run_in_background: true` to return a task id; collect with `task_output` and stop with `task_kill`.", + "parameters": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "A short (3-5 word) description of the delegated task, for display." + }, + "prompt": { + "type": "string", + "description": "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new." + }, + "run_in_background": { + "type": "boolean", + "description": "Run as a background task and return its id; collect with task_output or stop with task_kill." + } + }, + "required": [ + "description", + "prompt" + ] + } + }, + { + "name": "task_kill", + "description": "Request cancellation of a running background task by task id. Returns immediately; the task settles as killed once its work actually stops.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "reason": { + "type": "string", + "description": "Optional short reason, recorded in the log and forwarded to the task." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "task_list", + "description": "List your background tasks (running and finished) with their ids, kinds, and statuses.", + "parameters": { + "type": "object", + "properties": {} + } + }, + { + "name": "task_output", + "description": "Read a background task. Stream tasks return only output since the previous read; final-output tasks return their result after settlement. Every response ends with `[status: ...]`. Reads are non-blocking unless `wait: true`, which waits up to the configured cap.", + "parameters": { + "type": "object", + "properties": { + "task_id": { + "type": "string", + "description": "Task id returned by the tool that started the background work." + }, + "wait": { + "type": "boolean", + "description": "Block until the task reaches a terminal status or the timeout expires. A timed-out wait returns [status: running] and leaves the task alive." + }, + "timeout_ms": { + "type": "number", + "description": "Max wait in milliseconds (only meaningful with wait: true). Defaults to the configured wait timeout; capped by the configured maximum." + } + }, + "required": [ + "task_id" + ] + } + }, + { + "name": "todo_write", + "description": "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).", + "parameters": { + "type": "object", + "properties": { + "todos": { + "type": "array", + "description": "The COMPLETE task list, replacing any previous list.", + "items": { + "type": "object", + "properties": { + "content": { + "type": "string", + "description": "What the task is — a short imperative line." + }, + "status": { + "type": "string", + "description": "pending (not started) | in_progress (now) | completed (done).", + "enum": [ + "pending", + "in_progress", + "completed" + ] + } + }, + "required": [ + "content", + "status" + ] + } + } + }, + "required": [ + "todos" + ] + } + }, + { + "name": "workflow", + "description": "Run a JavaScript workflow script that orchestrates subagents at scale. Use this for work that fans out across many independent pieces — an audit over many files, a migration, multi-angle research, adversarial verification of findings — where you write the orchestration as a script instead of delegating turn by turn.\n\nThe workflow's identity rides the `meta` parameter as JSON: required `name` (short kebab-case) and `description` strings, optional `whenToUse` string and `phases` array (`{title, detail?, provider?, model?}`). The `script` parameter is the plain JavaScript body ONLY (NOT TypeScript, and NO `export const meta` statement — meta is a parameter, not code), running with top-level await; end with `return ` — the value must be JSON-serializable and is this tool's result.\n\nScript-body hooks:\n- `agent(prompt, opts?): Promise` — run one subagent to completion. Without `opts.schema` it resolves to the child's final text; with `opts.schema` (an object-rooted JSON Schema using ONLY type/properties/required/additionalProperties/items/enum/const — no oneOf/pattern/format/numeric bounds) it resolves to the validated object. Resolves `null` when the child fails (filter with `.filter(Boolean)`). Other opts: `label` (display), `phase` (progress group), and independent `provider`/`model` LLM target overrides (either may be provided alone). Anything else (`effort`/`isolation`/`agentType`) is rejected loudly.\n- `pipeline(items, ...stages): Promise` — run each item through the stages independently with NO barrier between stages (prefer this for multi-stage work). Each stage receives `(prev, item, index)`. An ordinary stage throw drops that ITEM to `null` and skips its remaining stages.\n- `parallel(thunks): Promise` — run zero-argument functions concurrently and await ALL of them (a barrier; use only when a stage genuinely needs every prior result together). A throwing thunk resolves to `null`.\n- `phase(title)` — start a progress phase; `log(message)` — narrate progress; `args` — the tool call's `args` input, verbatim.\n\nMisused hooks (bad arguments, unknown options, unsupported schemas, tripped caps) throw errors that ALWAYS kill the script — they never dissolve into a per-item `null`.\n\nConstraints: concurrency and total-agent caps apply; no filesystem, network, timers, or Node.js APIs are provided — the agents do the work, the script only coordinates them. The run executes in the foreground: this call returns when the whole script finishes.", + "parameters": { + "type": "object", + "properties": { + "script": { + "type": "string", + "description": "The plain-JS workflow script body (top-level await allowed; NO `export const meta` statement; end with `return `)." + }, + "meta": { + "type": "object", + "description": "The workflow identity block (plain JSON — never code).", + "properties": { + "name": { + "type": "string", + "description": "Short kebab-case workflow name." + }, + "description": { + "type": "string", + "description": "One-line description of what the workflow does." + }, + "whenToUse": { + "type": "string", + "description": "Optional guidance on when this workflow applies." + }, + "phases": { + "type": "array", + "description": "Optional phase declarations matched by phase() calls.", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "The phase title phase() calls match by exact string." + }, + "detail": { + "type": "string", + "description": "Optional one-line description of the phase." + }, + "provider": { + "type": "string", + "description": "Optional provider override this phase is expected to use." + }, + "model": { + "type": "string", + "description": "Optional model override this phase is expected to use." + } + }, + "required": [ + "title" + ] + } + } + }, + "required": [ + "name", + "description" + ] + }, + "args": { + "type": "object", + "description": "Optional JSON input exposed to the script as the `args` global (wrap a bare list as a field, e.g. {\"files\": [...]})." + } + }, + "required": [ + "script", + "meta" + ] + } + } + ] + ] } diff --git a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json index f0415911be..e422a063da 100644 --- a/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/skill-load/tool-schemas.golden.json @@ -273,5 +273,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json index f0415911be..e422a063da 100644 --- a/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/text-turn/tool-schemas.golden.json @@ -273,5 +273,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.golden.json index ac6cf51216..4b08a1e365 100644 --- a/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.golden.json @@ -348,5 +348,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json index ac6cf51216..4b08a1e365 100644 --- a/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json +++ b/examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.golden.json @@ -348,5 +348,5 @@ } } ], - "deltas": [] + "changes": [] } diff --git a/examples/coding-agent/composition.md b/examples/coding-agent/composition.md index 52c81b5089..cc71975961 100644 --- a/examples/coding-agent/composition.md +++ b/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
@deepseek-ai/dsh-token-meter"] + cfg --> plugin_coding_token_meter plugin_coding_compact_basic["compact-basic
@deepseek-ai/dsh-compact-basic"] cfg --> plugin_coding_compact_basic plugin_coding_subagent["subagent
@deepseek-ai/dsh-subagent"] @@ -63,6 +65,7 @@ flowchart LR | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | | `bash` | `@deepseek-ai/dsh-bash-local` | | `stdio-agent` | `@deepseek-ai/dsh-stdio-demo` | +| `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` | diff --git a/examples/coding-agent/cordis.yml b/examples/coding-agent/cordis.yml index 44cb31185c..bc3b542592 100644 --- a/examples/coding-agent/cordis.yml +++ b/examples/coding-agent/cordis.yml @@ -45,18 +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 with one service-wide context window. +- id: token-meter + name: '@deepseek-ai/dsh-token-meter' + +# Summarize an older range when measured history approaches the context window. +# Service-wide policy provides the ordinary threshold and retained-tail defaults. - id: compact-basic name: '@deepseek-ai/dsh-compact-basic' - config: - contextWindow: 128000 - thresholdRatio: 0.8 - retainTokens: 20480 - summarizationProvider: '' - 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 diff --git a/examples/coding-agent/tests/compaction.e2e.ts b/examples/coding-agent/tests/compaction.e2e.ts index 720165d753..6ba2908ad3 100644 --- a/examples/coding-agent/tests/compaction.e2e.ts +++ b/examples/coding-agent/tests/compaction.e2e.ts @@ -33,8 +33,10 @@ 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, - compact: { + tokenMeter: { contextWindow: 2000, + }, + compact: { thresholdRatio: 0.5, retainTokens: 400, summarizationProvider: '', diff --git a/examples/coding-agent/tests/harness.ts b/examples/coding-agent/tests/harness.ts index 6448b87cdd..944d01a0b9 100644 --- a/examples/coding-agent/tests/harness.ts +++ b/examples/coding-agent/tests/harness.ts @@ -6,6 +6,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' @@ -42,6 +44,8 @@ export interface CodingHarnessOptions { * compaction plugin (the default suites run without it). */ compact?: BasicCompactConfig + /** Optional token-meter capacity loaded before compact-basic. */ + tokenMeter?: TokenMeterConfig } export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise { @@ -54,9 +58,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 lower context 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. diff --git a/packages/context/time-context/tests/fixtures/cordis.yml b/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml similarity index 88% rename from packages/context/time-context/tests/fixtures/cordis.yml rename to examples/echo-agent/tests/fixtures/context/time-context/cordis.yml index 480a93c39b..9b59e2ded9 100644 --- a/packages/context/time-context/tests/fixtures/cordis.yml +++ b/examples/echo-agent/tests/fixtures/context/time-context/cordis.yml @@ -1,6 +1,6 @@ # Test-only composition: keep time-context opt-in while exercising its real Loader/app path. - id: mock-llm - name: '../../../../../examples/echo-agent/src/mock-llm.ts' + name: '../../../../src/mock-llm.ts' - id: bash name: '@deepseek-ai/dsh-bash-local' diff --git a/examples/package.json b/examples/package.json new file mode 100644 index 0000000000..8d77731a05 --- /dev/null +++ b/examples/package.json @@ -0,0 +1,46 @@ +{ + "name": "dsh-examples", + "private": true, + "version": "0.0.1", + "type": "module", + "description": "Workspace umbrella for runnable demos and example-owned test compositions: declares their cordis.yml packages so plain Node resolves real exports→lib. Not a build target.", + "dependencies": { + "@cordisjs/plugin-hmr": "workspace:*", + "@cordisjs/plugin-include": "workspace:*", + "@deepseek-ai/dsh-acp-demo": "workspace:*", + "@deepseek-ai/dsh-bash-local": "workspace:*", + "@deepseek-ai/dsh-bash-sandbox": "workspace:*", + "@deepseek-ai/dsh-code-runtime-worker": "workspace:*", + "@deepseek-ai/dsh-compact-basic": "workspace:*", + "@deepseek-ai/dsh-fs-local": "workspace:*", + "@deepseek-ai/dsh-fs-policy": "workspace:*", + "@deepseek-ai/dsh-hooks-claude": "workspace:*", + "@deepseek-ai/dsh-hooks-codex": "workspace:*", + "@deepseek-ai/dsh-llm": "workspace:*", + "@deepseek-ai/dsh-llm-deepseek": "workspace:*", + "@deepseek-ai/dsh-llm-replay": "workspace:*", + "@deepseek-ai/dsh-permission": "workspace:*", + "@deepseek-ai/dsh-repeat-tool-guard": "workspace:*", + "@deepseek-ai/dsh-sandbox-local": "workspace:*", + "@deepseek-ai/dsh-spill-local": "workspace:*", + "@deepseek-ai/dsh-spill-policy": "workspace:*", + "@deepseek-ai/dsh-stdio-demo": "workspace:*", + "@deepseek-ai/dsh-subagent": "workspace:*", + "@deepseek-ai/dsh-subagent-fork": "workspace:*", + "@deepseek-ai/dsh-subagent-spawn": "workspace:*", + "@deepseek-ai/dsh-time-context": "workspace:*", + "@deepseek-ai/dsh-timeout-policy": "workspace:*", + "@deepseek-ai/dsh-token-meter": "workspace:*", + "@deepseek-ai/dsh-tool-cordis": "workspace:*", + "@deepseek-ai/dsh-tool-fs": "workspace:*", + "@deepseek-ai/dsh-tool-fs-search": "workspace:*", + "@deepseek-ai/dsh-tool-subagent": "workspace:*", + "@deepseek-ai/dsh-tool-todo": "workspace:*", + "@deepseek-ai/dsh-tool-workflow": "workspace:*", + "@deepseek-ai/dsh-tools": "workspace:*", + "@deepseek-ai/dsh-user-approval": "workspace:*", + "@deepseek-ai/dsh-web": "workspace:*", + "@deepseek-ai/dsh-web-fetch-local": "workspace:*", + "@deepseek-ai/dsh-workflow-workerthread": "workspace:*" + } +} diff --git a/knip.json b/knip.json index 9c644cebb7..ad83bbbd2e 100644 --- a/knip.json +++ b/knip.json @@ -5,15 +5,16 @@ "ignoreWorkspaces": ["vendor/*", "python/sdk-runtime", "website"], "workspaces": { ".": { + "project": ["scripts/**/*.ts"] + }, + "examples": { "entry": [ - "examples/echo-agent/src/*.ts", - "examples/echo-agent/tests/**/*.e2e.ts", - "examples/coding-agent/tests/**/*.e2e.ts", - "examples/cordis-agent/tests/**/*.e2e.ts", - "examples/acp-agent/tests/**/*.e2e.ts", - "examples/*/tests/**/*.snapshot.ts" + "echo-agent/src/*.ts", + "*/tests/**/*.e2e.ts", + "*/tests/**/*.snapshot.ts" ], - "project": ["scripts/**/*.ts", "examples/**/*.ts"] + "project": ["**/*.ts"], + "ignoreDependencies": ["@deepseek-ai/.+", "@cordisjs/.+"] }, "packages/*/*": { "entry": ["tests/**/*.spec.ts"], @@ -52,8 +53,7 @@ }, "packages/support/acp-snapshot": { "entry": ["tests/**/*.spec.ts", "tests/fixtures/fake-acp-agent.ts"], - "project": ["src/**/*.ts", "tests/**/*.ts"], - "ignoreDependencies": ["cordis"] + "project": ["src/**/*.ts", "tests/**/*.ts"] }, "packages/support/loader-smoke": { "entry": ["tests/**/*.spec.ts", "tests/fixtures/*.ts"], diff --git a/packages/compact/README.md b/packages/compact/README.md index 08c3ddd707..b5f5987571 100644 --- a/packages/compact/README.md +++ b/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. diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md index 3d5be638c7..937120eebe 100644 --- a/packages/compact/compact-basic/README.md +++ b/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,51 +8,43 @@ 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 singleton `ctx.tokenMeter` 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 provider/model pair and cap, falling back to the latest logged request target and then the agent target, 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. - **Framing** — the replacement user message marks established checkpoint context with `` tags. The raw summary remains on the provenance event, and later automatic cycles merge the prior checkpoint. -- **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. +- **Lifecycle** — `compactRegion()` requires its agent to own the exact target session and rejects mismatch before resolution or mutation; a valid call 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, provider, 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 `ctx.tokenMeter`. The hook returns the summary blocks together with the call envelope it used (`{ summary, provider, 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 setting is optional. The pressure and retention policy applies to the token meter's single context window. Unrecognized top-level keys are rejected. | 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. | -| `summarizationProvider` | yes | Provider for summarization (`''` together with an empty model → use the latest logged request pair, then the agent pair). | -| `summarizationModel` | yes | Model for summarization (`''` together with an empty provider → use the latest logged request pair, then the agent pair). | -| `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. | +| `thresholdRatio` | no (default `0.8`) | Compact at `floor(contextWindow × ratio)`. | +| `retainTokens` | no (default `floor(contextWindow × 0.16)`) | Recent surface budget kept verbatim; must be below the threshold. | +| `summarizationProvider` | no (default `''`) | Set together with `summarizationModel`; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. | +| `summarizationModel` | no (default `''`) | Set together with `summarizationProvider`; an empty pair resolves the latest logged request target, then the `AgentOptions` pair. | +| `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, - summarizationProvider: '', - summarizationModel: '', - maxTokens: 8192, - compactionRetries: 1, - }) + ctx.plugin(TokenMeterService) + ctx.plugin(BasicCompactService) } ``` @@ -124,8 +116,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 provider/model pair skips that check. +- **Meter accuracy follows the fixed heuristic** — missing reusable provider usage falls back to character count plus structural overhead rather than exact tokenization. - **`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)). diff --git a/packages/compact/compact-basic/package.json b/packages/compact/compact-basic/package.json index fae0af5c62..a0ee2b4036 100644 --- a/packages/compact/compact-basic/package.json +++ b/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-agent-loop-testkit": "workspace:^", @@ -36,6 +42,7 @@ "@deepseek-ai/dsh-invariants": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-token-meter": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", "cordis": "^4.0.0-rc.7" } diff --git a/packages/compact/compact-basic/src/automatic.ts b/packages/compact/compact-basic/src/automatic.ts new file mode 100644 index 0000000000..edb317d270 --- /dev/null +++ b/packages/compact/compact-basic/src/automatic.ts @@ -0,0 +1,52 @@ +/** + * 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 type { Agent } from '@deepseek-ai/dsh-agent' + +interface AutomaticCompactor { + compactIfNeeded( + agent: Agent, + fullSystemPrompt: string, + sessionPrefix: readonly Message[], + signal: AbortSignal, + ): Promise +} + +/** + * 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) { + const message = error instanceof Error ? error.message : String(error) + ctx.logger.warn(`compaction failed: ${message}; proceeding with full history`) + } + }) +} diff --git a/packages/compact/compact-basic/src/config.ts b/packages/compact/compact-basic/src/config.ts new file mode 100644 index 0000000000..30241987a4 --- /dev/null +++ b/packages/compact/compact-basic/src/config.ts @@ -0,0 +1,107 @@ +/** + * Runtime defaulting and policy validation for compact-basic. + * + * @module @deepseek-ai/dsh-compact-basic/config + */ + +import { deepFreeze } from '@deepseek-ai/dsh-llm' +import type { TokenMeterService } from '@deepseek-ai/dsh-token-meter' +import type { BasicCompactConfig, ResolvedConfig } from './types.ts' + +/** Default request-pressure fraction of the token meter's context window. */ +const DEFAULT_THRESHOLD_RATIO = 0.8 + +/** Default verbatim-tail fraction of the token meter's context window. */ +const DEFAULT_RETAIN_RATIO = 0.16 + +/** Complete public configuration key set. */ +const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet = new Set([ + 'thresholdRatio', + 'retainTokens', + 'summarizationProvider', + 'summarizationModel', + 'maxTokens', + 'compactionRetries', + 'auto', +]) + +/** Reject stale or misspelled keys before defaults can hide them. */ +function validateConfigKeys(config: BasicCompactConfig): void { + for (const key of Object.keys(config)) { + if (!BASIC_COMPACT_CONFIG_KEYS.has(key)) { + throw new Error( + `BasicCompactConfig: unknown key "${key}" ` + + '(allowed: thresholdRatio, retainTokens, summarizationProvider, summarizationModel, maxTokens, compactionRetries, auto)', + ) + } + } +} + +/** + * Resolve defaults and validate the service-wide compaction policy. + * @param config - raw compact-basic configuration. + * @param tokenMeter - token meter supplying the context capacity. + * @returns a detached deeply immutable configuration. + */ +export function resolveConfig( + config: BasicCompactConfig = {}, + tokenMeter: TokenMeterService, +): ResolvedConfig { + validateConfigKeys(config) + const thresholdRatio = config.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO + const retainTokens = config.retainTokens + ?? Math.floor(tokenMeter.contextWindow * DEFAULT_RETAIN_RATIO) + const resolved: ResolvedConfig = { + thresholdRatio, + retainTokens, + summarizationProvider: config.summarizationProvider ?? '', + summarizationModel: config.summarizationModel ?? '', + maxTokens: config.maxTokens ?? 8192, + compactionRetries: config.compactionRetries ?? 1, + auto: config.auto ?? true, + } + + assertRatio('thresholdRatio', resolved.thresholdRatio) + assertNonNegativeInteger('retainTokens', resolved.retainTokens) + const thresholdTokens = Math.floor(tokenMeter.contextWindow * resolved.thresholdRatio) + if (resolved.retainTokens >= thresholdTokens) { + throw new Error( + `BasicCompactConfig: retainTokens (${resolved.retainTokens}) must be less than threshold tokens ${thresholdTokens}`, + ) + } + assertPositiveInteger('maxTokens', resolved.maxTokens) + assertNonNegativeInteger('compactionRetries', resolved.compactionRetries) + if (typeof resolved.summarizationProvider !== 'string') { + throw new Error('BasicCompactConfig: summarizationProvider must be a string') + } + if (typeof resolved.summarizationModel !== 'string') { + throw new Error('BasicCompactConfig: summarizationModel must be a string') + } + if ((resolved.summarizationProvider.length === 0) !== (resolved.summarizationModel.length === 0)) { + throw new Error( + 'BasicCompactConfig: summarizationProvider and summarizationModel must both be set or both be empty', + ) + } + if (typeof resolved.auto !== 'boolean') { + throw new Error('BasicCompactConfig: auto must be a boolean') + } + return deepFreeze(resolved) +} + +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]`) + } +} diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 520ee67358..60452581c5 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -1,291 +1,118 @@ /** - * 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 { 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 } from './config.ts' +import { compactSurfaceRegion, selectCompactableRange } from './region.ts' +import { summarizeWithLlm } from './summarizer.ts' +import type { + BasicCompactConfig, + ResolvedConfig, +} from './types.ts' -export type { BasicCompactConfig, ResolvedConfig } from './types.ts' -export { resolveConfig } from './types.ts' +export { resolveConfig } from './config.ts' +export type { + BasicCompactConfig, + ResolvedConfig, +} 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 = '' -const SUMMARY_CLOSE_TAG = '' - -/** - * 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 provider/model, then the complete agent fallback pair. */ +function effectiveTarget(agent: Agent): { provider: string; model: string } | undefined { + const latest = agent.session.requestHeader()?.config + if (latest !== undefined) return { provider: latest.provider, model: latest.model } + const { provider, model } = agent.options + if (provider === undefined || provider.length === 0 || model === undefined || model.length === 0) { + return undefined } + return { provider, 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( + target: { provider: string; model: string }, + session: Session, + fullSystemPrompt: string, + sessionPrefix: readonly Message[], +): EpochHeader { + const latest = session.requestHeader() + return canonicalHeader({ + config: latest === undefined ? target : { ...latest.config, ...target }, + ...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 the singleton + * token meter. */ export class BasicCompactService extends CompactService { - static inject = ['llm'] + static inject = ['llm', 'tokenMeter'] - /** Resolved configuration (`auto` defaulted). */ + static Config: z = z.object({ + thresholdRatio: z.number().default(0.8), + retainTokens: z.number().step(1), + summarizationProvider: z.string().default(''), + 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 compaction configuration. */ readonly config: ResolvedConfig - constructor(ctx: Context, config: BasicCompactConfig) { + 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, only text reaches the checkpoint, and the - * returned envelope identifies the provider/model actually used. - * - * @param text - plain-text rendering of the conversation region to condense. - * @param agent - supplies the request-header/creation fallback target and the - * session id stamped on the call; throws when no complete target exists. - * @param signal - optional abort signal, forwarded into the model call. - * @returns the text-only summary blocks plus the call envelope used - * (`provider`, `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[]; provider: string; model: string; maxTokens?: number }> { - const assembler = new BlockAssembler() - const logged = agent.session.requestHeader()?.config - const provider = this.config.summarizationProvider || logged?.provider || agent.options.provider || '' - const model = this.config.summarizationModel || logged?.model || agent.options.model || '' - const options: GenerateOptions = { - provider, - 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.provider || !options.model) { - throw new Error('no provider/model available for summarization: set both summarization fields or provide a logged/agent target') - } - 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, provider: options.provider, 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 service-wide threshold. + * A genuinely model-less router-first step skips this provisional check. + * @param agent - agent whose session and provisional provider/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, @@ -293,47 +120,45 @@ export class BasicCompactService extends CompactService { sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise { - 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 target = effectiveTarget(agent) + if (target === undefined) return null + const meter = this.ctx.tokenMeter + const requestHeader = provisionalHeader(target, agent.session, fullSystemPrompt, sessionPrefix) + const threshold = Math.floor(meter.contextWindow * this.config.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 range = selectCompactableRange(agent.session, measurement, this.config.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 + * token meter for all retention and shrink pricing. Reject an agent that does + * not own the exact target before any mutation. + * @param session - session whose surface is mutated; must equal `agent.session`. + * @param start - inclusive first surface-node seq. + * @param end - inclusive last surface-node seq. + * @param agent - owner of the target session, used by the summarizer. + * @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, @@ -341,215 +166,13 @@ export class BasicCompactService extends CompactService { agent: Agent, signal?: AbortSignal, ): Promise { - // 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`) + if (session !== agent.session) { + throw new Error('compactRegion: agent.session must be the exact target session') } - - // 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, provider, 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, - provider, - 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 - } - } - - // ---- 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 - } - 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 => 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 compactSurfaceRegion({ + meter: this.ctx.tokenMeter, + summarize: (text, owner, abort) => this.summarize(text, owner, abort), + }, session, start, end, agent, signal) } } diff --git a/packages/compact/compact-basic/src/region.ts b/packages/compact/compact-basic/src/region.ts new file mode 100644 index 0000000000..ac1ee260b1 --- /dev/null +++ b/packages/compact/compact-basic/src/region.ts @@ -0,0 +1,197 @@ +/** + * 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 { TokenMeasurement, TokenMeterService } 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: TokenMeterService + summarize(text: string, agent: Agent, signal?: AbortSignal): Promise +} + +/** + * 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 measurement - unified pressure and 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, + measurement: TokenMeasurement, + retainTokens: number, +): { start: number; end: number } | null { + const pricedNodes = measurement.nodes + if (pricedNodes.length === 0) return null + + const surfaceNodes = session.surface.nodes + if (surfaceNodes.length !== pricedNodes.length + || surfaceNodes.some((seq, index) => 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, end: cutoff } +} + +/** + * 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 { + const nodes = session.surface.nodes + const startIdx = nodes.indexOf(start) + const endIdx = nodes.indexOf(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) + 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 lockedMeasurement = dependencies.meter.measure(session) + const selected = lockedMeasurement.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, provider, model, maxTokens } = await dependencies.summarize(text, agent, signal) + + const currentMeasurement = dependencies.meter.measure(session) + if (currentMeasurement.logRevision !== lockedMeasurement.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, + provider, + 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 } +} diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts new file mode 100644 index 0000000000..c814c7ecc8 --- /dev/null +++ b/packages/compact/compact-basic/src/summarizer.ts @@ -0,0 +1,169 @@ +/** + * 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 = '' +const SUMMARY_CLOSE_TAG = '' + +/** 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[] + provider: string + 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 { + const latest = agent.session.requestHeader()?.config + const configured = config.summarizationProvider.length === 0 + ? undefined + : { provider: config.summarizationProvider, model: config.summarizationModel } + const agentTarget = agent.options.provider !== undefined + && agent.options.provider.length > 0 + && agent.options.model !== undefined + && agent.options.model.length > 0 + ? { provider: agent.options.provider, model: agent.options.model } + : undefined + const target = configured ?? latest ?? agentTarget + if (target === undefined) { + throw new Error( + 'no provider/model available for summarization: set both BasicCompactConfig summarization fields, route one request, or set both AgentOptions fields', + ) + } + + const assembler = new BlockAssembler() + const options: GenerateOptions = { + provider: target.provider, + model: target.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, + provider: target.provider, + model: target.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> { + return blocks.filter((block): block is Extract => block.type === 'text') +} diff --git a/packages/compact/compact-basic/src/types.ts b/packages/compact/compact-basic/src/types.ts index 7678418793..8145ce164e 100644 --- a/packages/compact/compact-basic/src/types.ts +++ b/packages/compact/compact-basic/src/types.ts @@ -1,102 +1,34 @@ /** - * 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. - */ +/** 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 - /** Provider to use for summarization (`''` with an empty model inherits the conversation target). */ - summarizationProvider: string - /** Model to use for summarization (`''` with an empty provider inherits the conversation target). */ - 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). */ + /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */ + thresholdRatio?: number + /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */ + retainTokens?: number + /** Summary provider; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */ + summarizationProvider?: string + /** Summary model; `''` resolves the latest routed pair, then the agent pair. 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 - -/** - * 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.summarizationProvider !== 'string') { - throw new Error('BasicCompactConfig: summarizationProvider must be a string.') - } - if ((resolved.summarizationProvider.length === 0) !== (resolved.summarizationModel.length === 0)) { - throw new Error('BasicCompactConfig: summarizationProvider and summarizationModel must both be empty or both be set.') - } - if (typeof resolved.auto !== 'boolean') { - throw new Error('BasicCompactConfig: auto must be a boolean.') - } - return resolved -} - -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].`) - } +/** Validated and detached compaction configuration. */ +export interface ResolvedConfig { + readonly thresholdRatio: number + readonly retainTokens: number + readonly summarizationProvider: string + readonly summarizationModel: string + readonly maxTokens: number + readonly compactionRetries: number + readonly auto: boolean } diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index 4581e46043..2d315293ed 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -1,1688 +1,790 @@ -import { describe, expect, it } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import { Context } from 'cordis' -import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic' +import BasicCompactService, { resolveConfig } from '@deepseek-ai/dsh-compact-basic' import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic' +import { selectCompactableRange } from '@deepseek-ai/dsh-compact-basic/src/region.ts' +import type { CompactionResult } from '@deepseek-ai/dsh-compact' +import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm' import type { ContentBlock, GenerateOptions, Message, StreamChunk } from '@deepseek-ai/dsh-llm' -import { CallId, LlmAdapter, LlmService } from '@deepseek-ai/dsh-llm' -import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session' -import type { SessionEvent, SurfaceEvent } from '@deepseek-ai/dsh-session' -import * as Invariants from '@deepseek-ai/dsh-invariants' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import TokenMeterService from '@deepseek-ai/dsh-token-meter' import type { Agent } from '@deepseek-ai/dsh-agent' -/** A never-aborted signal for the required `compactIfNeeded`/listener arg. */ const SIGNAL = new AbortController().signal +const MODEL = 'test-model' -/** - * Baseline config with every required knob set. `BasicCompactConfig` has no - * defaults for the numeric/model knobs (only `auto` defaults), so each test - * builds a complete config via `cfg()` and overrides only the knob under test. - */ -const TEST_CONFIG: BasicCompactConfig = { - contextWindow: 128000, - thresholdRatio: 0.8, - retainTokens: 20480, - summarizationProvider: '', - summarizationModel: '', - maxTokens: 8192, - compactionRetries: 1, -} - -/** A complete config with `overrides` applied over the baseline. */ -function cfg(overrides: Partial = {}): BasicCompactConfig { - return { ...TEST_CONFIG, ...overrides } -} - -/** Long enough that the real checkpoint preamble is smaller than two fixture messages. */ -const LONG_FIXTURE_TEXT = ' Detailed fixture context that makes framed checkpoint compaction genuinely shrinking.'.repeat(20) - -/** - * A BasicCompactService with summarize() stubbed (no real model call) and a - * predictable token estimate, for deterministic unit tests of the algorithm. - */ -class TestCompactService extends BasicCompactService { - private readonly summaryOutputs = new WeakSet() - /** Boundary/unit tests use tiny fixtures; keep framing from dominating them unless a test opts out. */ - estimateFramedSummariesCheaply = true - /** Track calls to summarize for test assertions. */ - summarizeCalls: { text: string; model: string }[] = [] - /** The fixed summary to return. */ - mockSummary: ContentBlock[] = [{ type: 'text', text: 'Test summary of compacted content.' }] - /** Per-call summaries; when set, each summarize() call shifts one value. */ - mockSummaryQueue: ContentBlock[][] = [] - /** If set, summarize() throws this error. */ - summarizeError: Error | null = null - - override estimateContentTokens(blocks: readonly ContentBlock[]): number { - if (this.summaryOutputs.has(blocks)) return blocks.length * 2 - if (this.estimateFramedSummariesCheaply && isFramedCheckpoint(blocks)) return blocks.length * 2 - // 10 tokens per block — predictable for retention/threshold math. - return blocks.length * 10 - } - - override async summarize( - text: string, - agent: Agent, - ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> { - const provider = this.config.summarizationProvider || agent.options.provider || '' - const model = this.config.summarizationModel || agent.options.model || '' - this.summarizeCalls.push({ text, model }) - if (this.summarizeError) throw this.summarizeError - const summary = this.mockSummaryQueue.shift() ?? this.mockSummary - this.summaryOutputs.add(summary) - return { summary, provider, model } - } -} - -function isFramedCheckpoint(blocks: readonly ContentBlock[]): boolean { - const first = blocks[0] - const last = blocks[blocks.length - 1] - return first?.type === 'text' - && first.text.includes('') - && last?.type === 'text' - && last.text === '' -} - -/** Create a test service with a throwaway context (auto disabled — no model). */ -function createTestService(overrides: Partial = {}): TestCompactService { - return new TestCompactService(new Context(), cfg({ auto: false, ...overrides })) -} - -/** Build closed turns plus an open compaction turn unless `leaveOpen` is false. */ -function multiTurnSession(turns: number, messagesPerTurn: number = 2, opts: { leaveOpen?: boolean } = {}): Session { - const leaveOpen = opts.leaveOpen ?? true - const s = new Session(SessionId('test')) - for (let t = 1; t <= turns; t++) { - s.append('turn/start', { turn: t, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: t, step: 1 }) - for (let m = 0; m < messagesPerTurn; m++) { - s.append('user/message', { - content: [{ type: 'text', text: `turn ${t} user message ${m + 1}.${LONG_FIXTURE_TEXT}` }], - source: { kind: 'user' }, - }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: t, step: 1, - content: [{ type: 'text', text: `turn ${t} assistant response ${m + 1}.${LONG_FIXTURE_TEXT}` }], - }, { surfaceOp: 'append' }) - } - s.append('step/end', { turn: t, step: 1 }) - s.append('turn/end', { turn: t, reason: { kind: 'completed' } }) - } - // Open one more turn so compaction's events are turn-enclosed, as they are - // when the loop runs the auto-compaction listener mid-turn. - if (leaveOpen) { - s.append('turn/start', { turn: turns + 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - } - return s -} - -/** Build a session with tool calls for richer extraction tests. */ -function sessionWithTools(): Session { - const s = new Session(SessionId('tools')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('user/message', { - content: [{ type: 'text', text: 'read file x' }], - source: { kind: 'user' }, - }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [ - { type: 'text', text: 'Let me read that file.' }, - { type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{"command":"cat x"}' }, - ], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'bash', arguments: '{"command":"cat x"}' }) - s.append('tool/result', { - turn: 1, step: 1, callId: CallId('c1'), - content: [{ type: 'text', text: 'hello world' }], - isError: false, - }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [{ type: 'text', text: 'The file contains: hello world' }], - }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - // Open a trailing turn so compaction's events are turn-enclosed (as they are - // when the loop runs the auto-compaction listener mid-turn). - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - return s -} - -/** - * Build a session of `turns` turns, each a SINGLE step containing an - * assistant/message that issues a tool-call plus its tool/result — the real - * multi-node-step shape (a step is two surface nodes: the assistant and the - * result). Each turn is preceded by a user/message. Used to exercise - * step-alignment: a region boundary must not fall between the assistant and its - * result. - */ -function toolTurnSession(turns: number): Session { - const s = new Session(SessionId('tools-multi')) - for (let t = 1; t <= turns; t++) { - s.append('turn/start', { turn: t, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('user/message', { - content: [{ type: 'text', text: `turn ${t} request` }], - source: { kind: 'user' }, - }, { surfaceOp: 'append' }) - s.append('step/start', { turn: t, step: 1 }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: t, step: 1, - content: [ - { type: 'text', text: `turn ${t} calling tool` }, - { type: 'tool-call', id: CallId(`c${t}`), name: 'bash', arguments: '{"command":"ls"}' }, - ], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: t, step: 1, callId: CallId(`c${t}`), name: 'bash', arguments: '{"command":"ls"}' }) - s.append('tool/result', { - turn: t, step: 1, callId: CallId(`c${t}`), - content: [{ type: 'text', text: `turn ${t} output` }], - isError: false, - }, { surfaceOp: 'append' }) - s.append('step/end', { turn: t, step: 1 }) - s.append('turn/end', { turn: t, reason: { kind: 'completed' } }) - } - // Open a trailing turn so compaction's events are turn-enclosed. - s.append('turn/start', { turn: turns + 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - return s -} - -/** - * Assert the derived transcript has NO orphaned tool-result: every - * `tool-result` block's `toolCallId` must be matched by a preceding `tool-call` - * block in an earlier (assistant) message. A dangling tool-result is exactly - * what splitting a step at compaction produces, and every provider rejects it. - */ -function expectNoOrphanToolResults(messages: Message[]): void { - const seenCallIds = new Set() - for (const msg of messages) { - for (const block of msg.content) { - if (block.type === 'tool-call') seenCallIds.add(block.id) - if (block.type === 'tool-result') { - expect(seenCallIds.has(block.toolCallId), - `orphaned tool-result for callId ${block.toolCallId} (no preceding tool-call)`).toBe(true) - } - } - } -} - -describe('BasicCompactService step-alignment (never split a tool-call/result pair)', () => { - it('compactIfNeeded rounds the retained boundary head-ward to keep a whole step (no orphaned tool-result)', async () => { - // Retain the recent tail while the older assistant/result pairs compact as - // whole units; no boundary may orphan a result. - const svc = createTestService({ contextWindow: 280, thresholdRatio: 0.5, retainTokens: 55 }) - const session = toolTurnSession(3) - - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) - expect(result).not.toBeNull() - expect(result!.shadowedSeqs.length).toBeGreaterThan(0) - // No dangling tool-result: every compacted/retained step stayed whole. - expectNoOrphanToolResults(session.deriveMessages()) - // The most-recent step's result is retained verbatim (still on the surface). - const lastResultSeq = session.events.findLast(e => e.type === 'tool/result')!.seq - expect(result!.shadowedSeqs).not.toContain(lastResultSeq) - }) - - it('compactIfNeeded returns null when the only compactable region is an un-splittable single step', async () => { - // The only candidate cut is inside one assistant/result pair; with no safe - // compactable prefix, decline rather than split it. - const s = new Session(SessionId('one-step')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [{ type: 'text', text: 'calling' }, { type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'bash', arguments: '{}' }) - s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'out' }], isError: false }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - // Turn stays open. - - const svc = createTestService({ contextWindow: 100, thresholdRatio: 0.1, retainTokens: 5 }) - const result = await compactIfNeeded(svc, s, '', 'm', SIGNAL) - expect(result).toBeNull() - expect(s.events.some(e => e.type === 'compact/start')).toBe(false) - }) - - it('compactRegion rejects a start that splits a step (unbalanced boundary)', async () => { - const svc = createTestService() - const session = toolTurnSession(1) - const nodes = session.surface.nodes // [user, asst(tool-call), result] - const userSeq = nodes[0]!.seq - const resultSeq = nodes[2]!.seq - // start = the tool/result: its issuing assistant precedes it IN THE SAME STEP, - // so starting here would orphan that assistant's tool-call. end is fine (user). - await expect(compactRegion(svc, session, resultSeq, resultSeq, 'm')) - .rejects.toThrow(/start seq .* is not a balanced boundary/) - expect(userSeq).toBeLessThan(resultSeq) // sanity: ordering as expected - }) - - it('compactRegion rejects an end that splits a step (unbalanced boundary)', async () => { - const svc = createTestService() - const session = toolTurnSession(1) - const nodes = session.surface.nodes - const userSeq = nodes[0]!.seq - const asstSeq = nodes[1]!.seq - // end = the assistant/message: its tool/result follows IN THE SAME STEP, so - // ending here would strand that result. start is fine (the pre-step user). - await expect(compactRegion(svc, session, userSeq, asstSeq, 'm')) - .rejects.toThrow(/end seq .* is not a balanced boundary/) - }) - - it('compactRegion rejects an end inside an open tail step', async () => { - const svc = createTestService() - const s = new Session(SessionId('open-tail')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('user/message', { content: [{ type: 'text', text: 'go' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [{ type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }], - }, { surfaceOp: 'append' }) - const nodes = s.surface.nodes // [user, asst] - const userSeq = nodes[0]!.seq - const asstSeq = nodes[1]!.seq - await expect(compactRegion(svc, s, userSeq, asstSeq, 'm')) - .rejects.toThrow(/end seq .* is not a balanced boundary/) - }) - - it('compactRegion accepts step-aligned boundaries (pre-step user → last result of a closed step)', async () => { - const svc = createTestService() - const session = toolTurnSession(2) - const nodes = session.surface.nodes // [user1, asst1, res1, user2, asst2, res2] - const startSeq = nodes[0]!.seq // pre-step user1 (free boundary) - const endSeq = nodes[2]!.seq // res1 = last node of turn 1's closed step - const result = await compactRegion(svc, session, startSeq, endSeq, 'm') - expect(result.shadowedRange).toEqual({ start: startSeq, end: endSeq }) - expectNoOrphanToolResults(session.deriveMessages()) - }) - - it('compactRegion accepts a single inter-step node (start === end on a pre-step user/message)', async () => { - const svc = createTestService() - const session = toolTurnSession(1) - const nodes = session.surface.nodes - const userSeq = nodes[0]!.seq // pre-step user: free boundary both ways - const result = await compactRegion(svc, session, userSeq, userSeq, 'm') - expect(result.shadowedRange).toEqual({ start: userSeq, end: userSeq }) - }) - - it('compactRegion accepts an injection-turn context node (no step at all)', async () => { - const svc = createTestService() - const s = new Session(SessionId('inject')) - // An idle inject(): turn/start → context/message, NO step. A later turn is - // open so compaction's events are turn-enclosed. - s.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: { kind: 'user' } } }) - s.append('context/message', { content: [{ type: 'text', text: 'ctx' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - const nodes = s.surface.nodes - const ctxSeq = nodes[0]!.seq - const result = await compactRegion(svc, s, ctxSeq, ctxSeq, 'm') - expect(result.shadowedRange).toEqual({ start: ctxSeq, end: ctxSeq }) - }) -}) - -describe('BasicCompactService.estimateEventTokens', () => { - it('returns 0 for non-message events (boundary, chunk, step/end, tool/call)', () => { - const svc = createTestService() - expect(svc.estimateEventTokens({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } })).toBe(0) - expect(svc.estimateEventTokens({ type: 'step/start', seq: 1, time: 2, data: { turn: 1, step: 1 } })).toBe(0) - expect(svc.estimateEventTokens({ type: 'assistant/chunk', seq: 2, time: 3, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } } })).toBe(0) - expect(svc.estimateEventTokens({ type: 'step/end', seq: 3, time: 4, data: { turn: 1, step: 1 } })).toBe(0) - expect(svc.estimateEventTokens({ type: 'tool/call', seq: 4, time: 5, data: { turn: 1, step: 1, callId: CallId('c1'), name: 'read', arguments: '{}' } })).toBe(0) - }) - - it('returns estimate for message-producing events', () => { - const svc = createTestService() - const userEvent: SessionEvent = { type: 'user/message', seq: 0, time: 1, data: { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } } } - expect(svc.estimateEventTokens(userEvent)).toBe(10) - - const asstEvent: SessionEvent = { type: 'assistant/message', seq: 1, time: 2, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }, { type: 'text', text: 'b' }], provenance: { provider: 'mock', model: 'mock' } } } - expect(svc.estimateEventTokens(asstEvent)).toBe(20) - - const toolEvent: SessionEvent = { type: 'tool/result', seq: 2, time: 3, data: { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'output' }], isError: false } } - expect(svc.estimateEventTokens(toolEvent)).toBe(10) - }) -}) - -describe('BasicCompactService.estimateTokens', () => { - it('sums token estimates across messages', () => { - const svc = createTestService() - const messages: Message[] = [ - { role: 'user', content: [{ type: 'text', text: 'hello' }] }, - { role: 'assistant', content: [{ type: 'text', text: 'hi' }, { type: 'text', text: 'there' }] }, - ] - // 1 block * 10 + 4 (role) + 2 blocks * 10 + 4 (role) = 10 + 4 + 20 + 4 = 38 - expect(svc.estimateTokens(messages)).toBe(38) - }) - - it('includes system prompt in the estimate', () => { - const svc = createTestService() - const messages: Message[] = [ - { role: 'user', content: [{ type: 'text', text: 'hi' }] }, - ] - const systemPrompt = 'You are a helpful assistant.' - // 1 block * 10 + 4 (role) + ceil(28/4) = 10 + 4 + 7 = 21 - expect(svc.estimateTokens(messages, systemPrompt)).toBe(21) - }) -}) - -describe('BasicCompactService.compactRegion', () => { - it('shadows surface nodes and inserts a summary via user/message', async () => { - const svc = createTestService() - const session = multiTurnSession(3, 1) // 3 turns, 2 surface nodes each = 6 nodes - - const nodes = session.surface.nodes - expect(nodes.length).toBe(6) - - const firstSeq = nodes[0]!.seq - const secondSeq = nodes[1]!.seq - const result = await compactRegion(svc, session, firstSeq, secondSeq, 'test-model') - - expect(result.shadowedSeqs).toEqual([firstSeq, secondSeq]) - expect(result.shadowedRange.start).toBe(firstSeq) - expect(result.shadowedRange.end).toBe(secondSeq) - expect(result.summary).toEqual(svc.mockSummary) - - const events = session.events - const startEvent = events.findLast(e => e.type === 'compact/start') - const summaryEvent = events.findLast(e => e.type === 'compact/summary') - const endEvent = events.findLast(e => e.type === 'compact/end') - expect(startEvent).toBeDefined() - expect(summaryEvent).toBeDefined() - expect(endEvent).toBeDefined() - // The provenance record carries the summarize call's envelope, so "which - // model wrote this summary" is answerable from the log alone. - expect(summaryEvent?.type === 'compact/summary' && summaryEvent.data.model).toBe('test-model') - - // compact/* events are log-only — no surfaceOp (type system enforces this). - const startRaw = startEvent as unknown as { surfaceOp?: unknown } - expect(startRaw.surfaceOp).toBeUndefined() - - // The user/message carries the replace surfaceOp. - const userMsg = events.findLast(e => e.type === 'user/message')! - const surfaceUserMsg = userMsg as SurfaceEvent - expect(surfaceUserMsg.surfaceOp).toEqual({ op: 'replace', start: firstSeq, end: secondSeq }) - expect(surfaceUserMsg.sourceEventSeqs).toContain(startEvent!.seq) - expect(surfaceUserMsg.sourceEventSeqs).toContain(summaryEvent!.seq) - expect(surfaceUserMsg.sourceEventSeqs).toContain(firstSeq) - expect(surfaceUserMsg.sourceEventSeqs).toContain(secondSeq) - // compact/end is appended AFTER the replacement (the lock brackets the whole - // op), so the replacement cannot reference it — sourceEventSeqs may only - // reference earlier seqs. - expect(surfaceUserMsg.sourceEventSeqs).not.toContain(endEvent!.seq) - expect(endEvent!.seq).toBeGreaterThan(userMsg.seq) - - // Surface now has: summary user/message + retained 4 nodes = 5 nodes. - const newNodes = session.surface.nodes - expect(newNodes.length).toBe(5) - expect(newNodes[0]!.seq).toBe(userMsg.seq) - - // deriveMessages() produces the framed summary as a user-role message: - // a checkpoint preamble + tag-wrapped summary blocks. - const derived = session.deriveMessages() - expect(derived.length).toBe(5) - expect(derived[0]!.role).toBe('user') - const framed = derived[0]!.content - expect(framed[0]).toMatchObject({ type: 'text' }) - expect((framed[0] as { text: string }).text).toContain('') - expect(framed).toContainEqual(svc.mockSummary[0]) - expect((framed[framed.length - 1] as { text: string }).text).toBe('') - }) - - it('throws when start or end are not surface nodes', async () => { - const svc = createTestService() - const session = multiTurnSession(1, 1) - await expect(compactRegion(svc, session, 999, 1000, 'm')) - .rejects.toThrow(/start seq 999 not found in surface/) - }) - - it('throws when start is positioned after end on the surface', async () => { - const svc = createTestService() - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - await expect(compactRegion(svc, session, nodes[1]!.seq, nodes[0]!.seq, 'm')) - .rejects.toThrow(/is after end seq .* on the surface/) - }) - - it('throws when compaction is already in progress', async () => { - const svc = createTestService() - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - session.append('compact/start', { turn: 2 }) - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow(/compaction already in progress/) - }) - - it('appends compact/end with error on summarize failure', async () => { - const svc = createTestService() - svc.summarizeError = new Error('model unavailable') - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow('model unavailable') - - const endEvent = session.events.findLast(e => e.type === 'compact/end') - expect(endEvent).toBeDefined() - // multiTurnSession(2,…) closes turns 1-2 and leaves turn 3 open; compaction - // stamps the open turn. - expect(endEvent!.data).toMatchObject({ turn: 3, error: 'model unavailable' }) - - // No replace-op user/message was appended (summarize failed). - const userMsgsAfter = session.events.filter(e => e.type === 'user/message') - const replaceMsgs = userMsgsAfter.filter((e) => { - const se = e as unknown as { surfaceOp?: unknown } - return se.surfaceOp !== undefined && typeof se.surfaceOp !== 'string' - }) - expect(replaceMsgs.length).toBe(0) - }) - - it('extracts conversation text for summarization', async () => { - const svc = createTestService() - const session = multiTurnSession(1, 2) - const nodes = session.surface.nodes - - await compactRegion(svc, session, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - - expect(svc.summarizeCalls.length).toBe(1) - const { text, model } = svc.summarizeCalls[0]! - expect(model).toBe('m') - expect(text).toContain('User: turn 1 user message 1') - expect(text).toContain('Assistant: turn 1 assistant response 1') - }) - - it('frames the landed summary with a checkpoint preamble and tags, keeping raw provenance', async () => { - const svc = createTestService() - svc.mockSummary = [{ type: 'text', text: 'STRUCTURED SUMMARY' }] - const session = multiTurnSession(3, 1) - const nodes = session.surface.nodes - - const result = await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm') - - // Provenance (compact/summary) carries the RAW, unframed summary. - expect(result.summary).toEqual([{ type: 'text', text: 'STRUCTURED SUMMARY' }]) - const summaryEvent = session.events.findLast(e => e.type === 'compact/summary')! - expect(summaryEvent.data).toMatchObject({ summary: [{ type: 'text', text: 'STRUCTURED SUMMARY' }] }) - - // The landed surface node is framed: preamble + tag-wrapped summary. - const landed = session.deriveMessages()[0]!.content - expect((landed[0] as { text: string }).text).toContain('checkpoint') - expect((landed[0] as { text: string }).text).toContain('') - expect(landed).toContainEqual({ type: 'text', text: 'STRUCTURED SUMMARY' }) - expect((landed[landed.length - 1] as { text: string }).text).toBe('') - }) - - it('extracts tool-call and tool-result context', async () => { - const svc = createTestService() - const session = sessionWithTools() - const nodes = session.surface.nodes - - const firstSeq = nodes[0]!.seq - const lastSeq = nodes[nodes.length - 1]!.seq - await compactRegion(svc, session, firstSeq, lastSeq, 'm') - - expect(svc.summarizeCalls.length).toBe(1) - const { text } = svc.summarizeCalls[0]! - expect(text).toContain('read file x') - expect(text).toContain('bash') - expect(text).toContain('Tool result') - }) -}) - -describe('BasicCompactService.compactIfNeeded', () => { - it('returns null when tokens are under threshold', async () => { - const svc = createTestService({ contextWindow: 128000, thresholdRatio: 0.8 }) - const session = multiTurnSession(1, 1) - expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() - }) - - it('compacts when tokens exceed threshold', async () => { - const svc = createTestService({ contextWindow: 100, thresholdRatio: 0.5, retainTokens: 10 }) - const session = multiTurnSession(3, 1) // 6 surface nodes, 10 tokens each = 60 - - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) - expect(result).not.toBeNull() - expect(result!.shadowedSeqs.length).toBeGreaterThan(0) - }) - - it('counts the session prefix toward pressure (every request carries it in front of the history)', async () => { - const svc = createTestService({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 10 }) - const session = multiTurnSession(3, 1) // 6 derived messages ≈ 84 estimated tokens — under the 100 threshold alone - expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() - - // The loop composes the agent/session-prefix product before the pre-step - // seam and hands it to the gate; it rides every request, so pressure must - // include it — the same history now crosses the threshold. - const sessionPrefix: Message[] = [ - { role: 'user', content: [{ type: 'text', text: `opener one.${LONG_FIXTURE_TEXT}` }] }, - { role: 'user', content: [{ type: 'text', text: `opener two.${LONG_FIXTURE_TEXT}` }] }, - ] - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL, sessionPrefix) - expect(result).not.toBeNull() - // The prefix itself is NOT history: compaction shadowed surface nodes only. - expect(sessionPrefix).toHaveLength(2) - }) - - it('returns the first compaction result when a zero-retry pass converges after the loop', async () => { - // With compactionRetries=0 there is no next-loop threshold check after the - // first mutation, so the success path is the post-loop `return result`. - const svc = createTestService({ - contextWindow: 100, - thresholdRatio: 0.7, - retainTokens: 10, - compactionRetries: 0, - }) - const session = multiTurnSession(3, 1) // 6 derived messages = 84 estimated tokens. - - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) - - expect(result).not.toBeNull() - expect(session.events.filter(e => e.type === 'compact/summary')).toHaveLength(1) - expect(svc.estimateTokens(session.deriveMessages(), '')).toBeLessThan(70) - }) - - it('walks tail→head and retains nodes within token budget', async () => { - const svc = createTestService({ contextWindow: 350, thresholdRatio: 0.2, retainTokens: 15 }) - const session = multiTurnSession(5, 1) // 10 surface nodes = ~100 tokens - - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) - expect(result).not.toBeNull() - const nodes = session.surface.nodes - expect(result!.shadowedSeqs.length).toBeGreaterThan(0) - expect(result!.shadowedSeqs).not.toContain(nodes[nodes.length - 1]!.seq) - }) - - it('returns null when the whole surface fits the retain budget (over threshold by role/system overhead)', async () => { - // Role overhead pushes the request above its 48-token threshold, but the - // raw four-node retention walk remains below retainTokens=45, so all fit. - const svc = createTestService({ contextWindow: 480, thresholdRatio: 0.1, retainTokens: 45 }) - const session = multiTurnSession(2, 1) - expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() - }) - - it('compacts a runaway turn: its early CLOSED steps summarize while recent steps stay verbatim', async () => { - // Completed early steps of the open turn remain eligible; protecting the - // whole turn would make a runaway turn impossible to compact. - const svc = createTestService({ contextWindow: 800, thresholdRatio: 0.1, retainTokens: 25 }) - const s = new Session(SessionId('runaway')) - // ONE open turn with 5 closed steps; each step is [asst(tool-call), result]. - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('user/message', { content: [{ type: 'text', text: 'do a big multi-step task' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - for (let step = 1; step <= 5; step++) { - s.append('step/start', { turn: 1, step }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step, - content: [{ type: 'text', text: `step ${step}` }, { type: 'tool-call', id: CallId(`c${step}`), name: 'bash', arguments: '{}' }], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: 1, step, callId: CallId(`c${step}`), name: 'bash', arguments: '{}' }) - s.append('tool/result', { turn: 1, step, callId: CallId(`c${step}`), content: [{ type: 'text', text: `out ${step}` }], isError: false }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step }) - } - // The turn stays OPEN (no turn/end) — the model is mid-turn, about to run - // step 6. Surface: user + 5×[asst, result] = 11 nodes. - const nodesBefore = s.surface.nodes.length - expect(nodesBefore).toBe(11) - - const result = await compactIfNeeded(svc, s, '', 'm', SIGNAL) - expect(result).not.toBeNull() - // Early steps of the SAME open turn were shadowed (impossible under layer 2). - expect(result!.shadowedSeqs.length).toBeGreaterThan(0) - // The most-recent step's tool result is retained verbatim (still on surface). - const lastResultSeq = s.events.findLast(e => e.type === 'tool/result')!.seq - expect(result!.shadowedSeqs).not.toContain(lastResultSeq) - expect(s.surface.nodes.some(n => n.seq === lastResultSeq)).toBe(true) - // No orphaned tool-result survives (whole-step boundaries respected). - expectNoOrphanToolResults(s.deriveMessages()) - }) - - it('returns null for an empty surface', async () => { - const svc = createTestService({ contextWindow: 100, thresholdRatio: 0.5, retainTokens: 10 }) - const session = new Session(SessionId('empty')) - expect(await compactIfNeeded(svc, session, '', 'm', SIGNAL)).toBeNull() - }) - - it('compacts again after a prior summary node heads the surface (the summary stays eligible)', async () => { - // Head-anchored recompaction must include the previous summary and retained context. - const svc = createTestService({ contextWindow: 800, thresholdRatio: 0.1, retainTokens: 25 }) - const s = multiTurnSession(4, 1) // turns 1-4 closed, turn 5 open (no surface yet) - - const first = await compactIfNeeded(svc, s, '', 'm', SIGNAL) - expect(first).not.toBeNull() - // The summary node now heads the surface with a fresh high seq. - const summaryHeadSeq = s.surface.nodes[0]!.seq - const turn5StartSeq = s.events.filter(e => e.type === 'turn/start').at(-1)!.seq - expect(summaryHeadSeq).toBeGreaterThan(turn5StartSeq) - - // Append a verbatim node in the open turn (a step's output), still over - // threshold, then compact again — the older summary + closed turns compact, - // the fresh nodes are retained. - s.append('step/start', { turn: 5, step: 1 }) - s.append('user/message', { content: [{ type: 'text', text: 'turn 5 work' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 5, step: 1, content: [{ type: 'text', text: 'reply 5' }] }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 5, step: 1 }) - - const second = await compactIfNeeded(svc, s, '', 'm', SIGNAL) - expect(second).not.toBeNull() - expect(second!.shadowedSeqs.length).toBeGreaterThan(0) - // The fresh open-turn nodes were NOT compacted. - const turn5UserSeq = s.events.find(e => e.type === 'user/message' && e.data.content.some(b => b.type === 'text' && b.text === 'turn 5 work'))!.seq - expect(second!.shadowedSeqs).not.toContain(turn5UserSeq) - }) - - it('re-compacts smaller summaries until the post-compaction surface drops below threshold', async () => { - const svc = createTestService({ - contextWindow: 100, - thresholdRatio: 0.5, - retainTokens: 10, - compactionRetries: 2, - }) - svc.estimateFramedSummariesCheaply = false - svc.mockSummaryQueue = [ - Array.from({ length: 4 }, (_, index) => ({ type: 'text', text: `first ${index}` })), - [{ type: 'text', text: 'second' }], - ] - const session = multiTurnSession(4, 1) - - const result = await compactIfNeeded(svc, session, '', 'm', SIGNAL) - - expect(result).not.toBeNull() - expect(svc.summarizeCalls).toHaveLength(2) - expect(session.events.filter(e => e.type === 'compact/summary')).toHaveLength(2) - expect(svc.estimateTokens(session.deriveMessages(), '')).toBeLessThan(50) - }) - - it('throws after the configured re-compaction attempts still leave the surface above threshold', async () => { - const svc = createTestService({ - contextWindow: 100, - thresholdRatio: 0.5, - retainTokens: 10, - compactionRetries: 1, - }) - svc.estimateFramedSummariesCheaply = false - svc.mockSummaryQueue = [ - Array.from({ length: 4 }, (_, index) => ({ type: 'text', text: `first ${index}` })), - Array.from({ length: 3 }, (_, index) => ({ type: 'text', text: `second ${index}` })), - ] - const session = multiTurnSession(4, 1) - - await expect(compactIfNeeded(svc, session, '', 'm', SIGNAL)) - .rejects.toThrow(/still above threshold after 2 compaction attempts/) - expect(svc.summarizeCalls).toHaveLength(2) - }) -}) - -describe('BasicCompactService replay equivalence', () => { - it('produces identical deriveMessages() after seeding from compacted log', async () => { - const svc = createTestService() - const session = multiTurnSession(3, 1) - const nodes = session.surface.nodes - - await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm') - const derived = session.deriveMessages() - - const replayed = new Session(SessionId('replay'), [...session.events]) - expect(replayed.deriveMessages()).toEqual(derived) - }) -}) - -describe('BasicCompactService blocking (compaction in progress)', () => { - it('detects in-progress compaction from unmatched compact/start', async () => { - const svc = createTestService() - const session = multiTurnSession(1, 1) - session.append('compact/start', { turn: 1 }) - const nodes = session.surface.nodes - // Whole step (user → assistant) is a step-aligned region, so the call reaches - // the in-progress check rather than being rejected for splitting a step. - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow(/compaction already in progress/) - }) - - it('allows compaction after compact/end is appended', async () => { - const svc = createTestService() - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - session.append('compact/start', { turn: 1 }) - session.append('compact/end', { turn: 1 }) - const result = await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm') - expect(result).toBeDefined() - }) - - it('is not wedged by an orphaned compact/start from a prior (now-closed) turn', async () => { - // An orphaned start in a closed repaired turn is stale; only the current - // turn participates in the in-progress lock. - const svc = createTestService() - const s = new Session(SessionId('stale-lock')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('user/message', { content: [{ type: 'text', text: 'turn 1' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'reply 1' }] }, { surfaceOp: 'append' }) - s.append('compact/start', { turn: 1 }) // ← orphaned: no matching compact/end - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) // repair closed the turn - // A new open turn. - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - const nodes = s.surface.nodes - - // The stale start is before the turn/end, so it is NOT seen as in-progress. - const result = await compactRegion(svc, s, nodes[0]!.seq, nodes[1]!.seq, 'm') - expect(result).toBeDefined() - }) -}) - -describe('BasicCompactService token estimation (char/4 heuristic)', () => { - it('estimates text blocks with char/4 + overhead', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - // 'this is a somewhat longer text block' = 36 → ceil(36/4)+4 = 13; 'short' = 5 → 2+4 = 6 - const blocks: ContentBlock[] = [ - { type: 'text', text: 'this is a somewhat longer text block' }, - { type: 'text', text: 'short' }, - ] - expect(svc.estimateContentTokens(blocks)).toBe(19) - }) - - it('estimates reasoning blocks same as text', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - // 'thinking about this...' = 22 → ceil(22/4)+4 = 10 - expect(svc.estimateContentTokens([{ type: 'reasoning', text: 'thinking about this...' }])).toBe(10) - }) - - it('estimates tool-call blocks from name + arguments', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - // 'bash' = 4 → 1; '{"command":"ls"}' = 16 → 4; + 4 overhead = 9 - expect(svc.estimateContentTokens([ - { type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{"command":"ls"}' }, - ])).toBe(9) - }) - - it('estimates tool-result blocks recursively', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - // inner text 5 → 2+4 = 6; outer 6 + 4 overhead = 10 - expect(svc.estimateContentTokens([ - { type: 'tool-result', toolCallId: CallId('c1'), content: [{ type: 'text', text: 'hello' }], isError: false }, - ])).toBe(10) - }) - - it('returns 0 for empty content blocks', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - expect(svc.estimateContentTokens([])).toBe(0) - }) - - it('honors a configured charsPerToken (fractional densities included)', () => { - // 'this is a somewhat longer text block' = 36 chars. - const blocks: ContentBlock[] = [{ type: 'text', text: 'this is a somewhat longer text block' }] - // charsPerToken 2: ceil(36/2)+4 = 22 — a CJK-density config doubles the estimate. - const dense = new BasicCompactService(new Context(), cfg({ auto: false, charsPerToken: 2 })) - expect(dense.estimateContentTokens(blocks)).toBe(22) - // Fractional density is legal: ceil(36/1.5)+4 = 28. - const fractional = new BasicCompactService(new Context(), cfg({ auto: false, charsPerToken: 1.5 })) - expect(fractional.estimateContentTokens(blocks)).toBe(28) - // The system-prompt term scales with the same knob: 36-char prompt at density 2 → ceil(36/2) = 18. - expect(dense.estimateTokens([], 'this is a somewhat longer text block')).toBe(18) - }) -}) - -describe('BasicCompactService HMR safety', () => { - it('registers as ctx.compact', () => { - const ctx = new Context() - void new BasicCompactService(ctx, cfg({ auto: false })) - expect(ctx.compact).toBeDefined() - expect(ctx.compact).toBeInstanceOf(BasicCompactService) - }) - - it('disposing the plugin fiber unregisters ctx.compact', async () => { - // Mount through the real plugin fiber (the Loader path), then dispose it and confirm the - // service registration is torn down. - const ctx = new Context() - await ctx.plugin(LlmService) - const fiber = await ctx.plugin(BasicCompactService, cfg({ auto: false })) - expect(ctx.get('compact')).toBeInstanceOf(BasicCompactService) - - await fiber.dispose() - expect(ctx.get('compact')).toBeUndefined() - }) -}) - -describe('BasicCompactService config validation', () => { - it('rejects invalid numeric config values', () => { - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, contextWindow: 0 }))) - .toThrow(/contextWindow .* positive integer/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, thresholdRatio: 0 }))).toThrow(/thresholdRatio .* \(0, 1\]/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, thresholdRatio: 1.1 }))).toThrow(/thresholdRatio .* \(0, 1\]/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, retainTokens: -1 }))) - .toThrow(/retainTokens .* non-negative integer/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, maxTokens: 0 }))).toThrow(/maxTokens .* positive integer/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, compactionRetries: -1 }))) - .toThrow(/compactionRetries .* non-negative integer/) - expect(() => new BasicCompactService( - new Context(), cfg({ auto: false, summarizationModel: 1 } as unknown as Partial), - )).toThrow(/summarizationModel must be a string/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: 'no' } as unknown as Partial))) - .toThrow(/auto must be a boolean/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, charsPerToken: 0 }))) - .toThrow(/charsPerToken .* positive finite number/) - expect(() => new BasicCompactService(new Context(), cfg({ auto: false, charsPerToken: Number.NaN }))) - .toThrow(/charsPerToken .* positive finite number/) - }) - - it('accepts a large retain budget because convergence is enforced dynamically', () => { - expect(() => new BasicCompactService(new Context(), cfg({ - auto: false, - contextWindow: 1000, - thresholdRatio: 0.5, - retainTokens: 900, - }))).not.toThrow() - }) - - it('the default config is valid', () => { - expect(() => new BasicCompactService(new Context(), cfg({ auto: false }))).not.toThrow() - }) -}) - -/** An adapter that emits a fixed summary text, for exercising the real summarize() path. */ -class ScriptedAdapter extends LlmAdapter { - lastOptions: GenerateOptions | null = null - constructor(private summaryText: string) { - super() - } - - async * stream(options: GenerateOptions): AsyncIterable { - this.lastOptions = options - yield { type: 'block-start', index: 0, blockType: 'text' } - yield { type: 'text-delta', index: 0, text: this.summaryText } - yield { type: 'finish', reason: { kind: 'stop' } } - } -} - -/** An adapter that emits arbitrary content blocks, preserving reasoning/text shape. */ -class BlocksAdapter extends LlmAdapter { - lastOptions: GenerateOptions | null = null - constructor(private blocks: readonly ContentBlock[]) { - super() - } - - async * stream(options: GenerateOptions): AsyncIterable { - this.lastOptions = options - for (const [index, block] of this.blocks.entries()) { - yield { type: 'block-start', index, blockType: block.type } - switch (block.type) { - case 'text': - yield { type: 'text-delta', index, text: block.text } - break - case 'reasoning': - yield { type: 'reasoning-delta', index, text: block.text } - break - default: - yield { type: 'block-end', index, block } - } - } - yield { type: 'finish', reason: { kind: 'stop' } } - } -} - -/** Wire a real LlmService + arbitrary-block adapter into a context. */ -async function ctxWithBlocks(blocks: readonly ContentBlock[], model = 'test-model'): Promise<{ ctx: Context; adapter: BlocksAdapter }> { +function createContext(contextWindow = 1_000): Context { const ctx = new Context() - await ctx.plugin(LlmService) - const adapter = new BlocksAdapter(blocks) - ctx.llm.registerAdapter([model], adapter) - return { ctx, adapter } -} - -/** Wire a real LlmService + scripted adapter into a context. */ -async function ctxWithModel(summaryText: string, model = 'test-model'): Promise<{ ctx: Context; adapter: ScriptedAdapter }> { - const ctx = new Context() - await ctx.plugin(LlmService) - const adapter = new ScriptedAdapter(summaryText) - ctx.llm.registerAdapter([model], adapter) - return { ctx, adapter } -} - -/** An adapter whose stream ends with a finish chunk of the given reason (no content). */ -class FinishOnlyAdapter extends LlmAdapter { - constructor(private reason: StreamChunk & { type: 'finish' }) { - super() - } - - async * stream(): AsyncIterable { - yield this.reason - } -} - -/** Wire a real LlmService + finish-only adapter into a context. */ -async function ctxWithFinish(reason: (StreamChunk & { type: 'finish' })['reason'], model = 'test-model'): Promise { - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter([model], new FinishOnlyAdapter({ type: 'finish', reason })) + void new TokenMeterService(ctx, { contextWindow }) return ctx } -/** A minimal Agent stub carrying just session + options (enough for the listeners). */ -function stubAgent(session: Session, model?: string): Agent { - return { session, options: { provider: model, model } } as unknown as Agent +function agent(session: Session, model?: string): Agent { + return { session, options: model === undefined ? {} : { provider: model, model } } as Agent } -function compactIfNeeded( - svc: BasicCompactService, - session: Session, - fullSystemPrompt: string, - model: string, - signal: AbortSignal, - sessionPrefix: readonly Message[] = [], -) { - return svc.compactIfNeeded(stubAgent(session, model), fullSystemPrompt, sessionPrefix, signal) -} - -function compactRegion( - svc: BasicCompactService, - session: Session, - start: number, - end: number, - model: string, - signal?: AbortSignal, -) { - return svc.compactRegion(session, start, end, stubAgent(session, model), signal) -} - -function summarize(svc: BasicCompactService, text: string, model: string) { - return svc.summarize(text, stubAgent(new Session(SessionId('summary')), model)) -} - -describe('BasicCompactService.summarize (real ctx.llm.stream)', () => { - it('summarizes via the registered adapter and returns its content', async () => { - const { ctx, adapter } = await ctxWithModel('SUMMARY TEXT') - const svc = new BasicCompactService(ctx, cfg({ auto: false, maxTokens: 512 })) - - const { summary, model, maxTokens } = await summarize(svc, 'User: hi\n\nAssistant: hello', 'test-model') - expect(summary).toEqual([{ type: 'text', text: 'SUMMARY TEXT' }]) - // The returned envelope reports what the call actually used — the caller - // logs it on compact/summary (the reconstructability RFC). - expect(model).toBe('test-model') - expect(maxTokens).toBe(512) - // The fixed system prompt and maxTokens flow through. - expect(adapter.lastOptions!.system).toContain('compaction engine') - expect(adapter.lastOptions!.system).toContain('## Next Step') - expect(adapter.lastOptions!.maxTokens).toBe(512) - expect(adapter.lastOptions!.sessionId).toBe(SessionId('summary')) - expect(adapter.lastOptions!.messages[0]!.content[0]).toMatchObject({ type: 'text' }) - }) - - it('uses maxTokens as the summarization provider cap', async () => { - const { ctx, adapter } = await ctxWithModel('SUMMARY TEXT') - const svc = new BasicCompactService(ctx, cfg({ - auto: false, - maxTokens: 50, - })) - - await summarize(svc, 'User: hi', 'test-model') - - expect(adapter.lastOptions!.maxTokens).toBe(50) - }) - - it('keeps only text blocks in the stored summary (drops reasoning and tool-call)', async () => { - const { ctx } = await ctxWithBlocks([ - { type: 'reasoning', text: 'private chain of thought' }, - { type: 'text', text: 'PUBLIC SUMMARY' }, - // A model reply can carry a tool-call; it must not survive into the - // synthesized user/message summary as an orphaned call. - { type: 'tool-call', id: CallId('c1'), name: 'bash', arguments: '{}' }, - ]) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - - const { summary } = await summarize(svc, 'User: hi', 'test-model') - - expect(summary).toEqual([{ type: 'text', text: 'PUBLIC SUMMARY' }]) - }) - - it('throws when no text block remains after filtering', async () => { - const { ctx } = await ctxWithBlocks([{ type: 'reasoning', text: 'private only' }]) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - - await expect(summarize(svc, 'User: hi', 'test-model')).rejects.toThrow(/no text summary content/) - }) - - it('throws when no model is provided', async () => { - const { ctx } = await ctxWithModel('x') - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - await expect(summarize(svc, 'text', '')).rejects.toThrow(/no provider\/model available/) - }) - - it('rethrows when the stream ends with a finish-error chunk', async () => { - const ctx = await ctxWithFinish({ kind: 'error', message: 'provider 401', code: 'UNAUTHORIZED' }) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - await expect(summarize(svc, 'text', 'test-model')).rejects.toMatchObject({ message: 'provider 401', code: 'UNAUTHORIZED' }) - }) - - it('rethrows a finish-error chunk without a code (code stays undefined)', async () => { - const ctx = await ctxWithFinish({ kind: 'error', message: 'opaque failure' }) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - const error = await summarize(svc, 'text', 'test-model').then(() => null, (e: unknown) => e as Error & { code?: string }) - expect(error?.message).toBe('opaque failure') - expect(error?.code).toBeUndefined() - }) - - it('rethrows when the stream ends with a finish-aborted chunk', async () => { - const ctx = await ctxWithFinish({ kind: 'aborted' }) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - await expect(summarize(svc, 'text', 'test-model')).rejects.toMatchObject({ message: 'summarization stream aborted', code: 'ABORTED' }) - }) - - it('fails closed on a max-tokens finish (an incomplete checkpoint must not commit)', async () => { - const ctx = await ctxWithFinish({ kind: 'max-tokens' }) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - await expect(summarize(svc, 'text', 'test-model')).rejects.toMatchObject({ code: 'MAX_TOKENS' }) - }) - - it('compactRegion leaves the surface intact when summarization hits max-tokens', async () => { - const ctx = await ctxWithFinish({ kind: 'max-tokens' }) - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - const session = multiTurnSession(2, 1) - const before = [...session.surface.nodes] - const nodes = session.surface.nodes - - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'test-model')) - .rejects.toMatchObject({ code: 'MAX_TOKENS' }) - - // No replacement landed — the surface is byte-identical, and the lock was - // released with the error (compact/end carries it). - expect(session.surface.nodes).toEqual(before) - const endEvent = session.events.findLast(e => e.type === 'compact/end')! - const endData = endEvent.data as { error?: string } - expect(endData.error).toContain('truncated') - }) - - it('compactRegion uses the real summarizer end-to-end', async () => { - const { ctx } = await ctxWithModel('CONDENSED') - const svc = new BasicCompactService(ctx, cfg({ auto: false })) - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - - const result = await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'test-model') - expect(result.summary).toEqual([{ type: 'text', text: 'CONDENSED' }]) - // The raw summary is wrapped in the checkpoint framing on the surface. - expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'CONDENSED' }) - }) - - it('rejects a summary that is not smaller than the shadowed content', async () => { - const svc = createTestService({ auto: false }) - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - svc.mockSummary = Array.from({ length: 20 }, (_, index) => ({ type: 'text', text: `large ${index}` })) - - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow(/summary is not smaller than the shadowed content/) - expect(session.events.some(e => e.type === 'compact/summary')).toBe(false) - }) - - it('rejects when the framed checkpoint is not smaller than the shadowed content', async () => { - const svc = createTestService({ auto: false }) - svc.estimateFramedSummariesCheaply = false - const session = new Session(SessionId('framed-nonshrinking')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - session.append('step/start', { turn: 1, step: 1 }) - session.append('user/message', { content: [{ type: 'text', text: 'tiny user' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'tiny assistant' }] }, { surfaceOp: 'append' }) - session.append('step/end', { turn: 1, step: 1 }) - session.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - const before = [...session.surface.nodes] - const nodes = session.surface.nodes - - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow(/summary is not smaller than the shadowed content/) - expect(session.events.some(e => e.type === 'compact/summary')).toBe(false) - expect(session.surface.nodes).toEqual(before) - }) -}) - -describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => { - /** Fire the agent/pre-step serial checkpoint as the loop does. */ - function firePreStep(ctx: Context, agent: Agent, step: number, fullSystemPrompt: string): Promise { - return ctx.serial('agent/pre-step', agent, 1, step, fullSystemPrompt, [], SIGNAL) - } - - it('compacts (mutating the surface) when over threshold', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - void new BasicCompactService(ctx, cfg({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 20 })) - const session = multiTurnSession(5, 1) // 10 surface nodes - const agent = stubAgent(session, 'test-model') - const before = session.surface.nodes.length - - await firePreStep(ctx, agent, 1, '') - - // The surface shrank in place, and a summary checkpoint landed. - expect(session.surface.nodes.length).toBeLessThan(before) - expect(session.events.some(e => e.type === 'compact/summary')).toBe(true) - // The re-derived head message is the framed summary checkpoint. - expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'SUMMARY' }) - }) - - it('logs compaction details when auto-compaction returns a converged result', async () => { - const ctx = new Context() - const infos: string[] = [] - ctx.logger.info = ((msg: string) => void infos.push(msg)) as typeof ctx.logger.info - void new TestCompactService(ctx, cfg({ - contextWindow: 100, - thresholdRatio: 0.7, - retainTokens: 10, - compactionRetries: 0, - })) - const session = multiTurnSession(3, 1) - const agent = stubAgent(session, 'test-model') - - await firePreStep(ctx, agent, 1, '') - - expect(session.events.filter(e => e.type === 'compact/summary')).toHaveLength(1) - expect(infos.some(msg => msg.includes('compaction: shadowed'))).toBe(true) - expect(infos.some(msg => msg.includes('estimated tokens after compaction'))).toBe(true) - }) - - it('compacts mid-turn on steps after the first (the surface grows within a turn)', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - void new BasicCompactService(ctx, cfg({ contextWindow: 100, thresholdRatio: 0.5, retainTokens: 10 })) - const session = multiTurnSession(3, 1) // over the 0.5 threshold - const agent = stubAgent(session, 'test-model') - - // A step-2 checkpoint (a tool-heavy turn's later step) must still compact — - // the surface accumulated assistant/message + tool/result nodes since step 1. - await firePreStep(ctx, agent, 2, '') - expect(session.events.some(e => e.type === 'compact/start')).toBe(true) - }) - - it('does nothing when under threshold', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - void new BasicCompactService(ctx, cfg({ contextWindow: 128000, thresholdRatio: 0.8 })) - const session = multiTurnSession(1, 1) - const agent = stubAgent(session, 'test-model') - - await firePreStep(ctx, agent, 1, '') - expect(session.events.some(e => e.type === 'compact/start')).toBe(false) - }) - - it('leaves the surface intact when compaction fails (summarize rejects)', async () => { - // No adapter registered for this model → summarize() rejects → caught, the - // surface is untouched (the loop derives the full history). - const ctx = new Context() - await ctx.plugin(LlmService) - void new BasicCompactService(ctx, cfg({ contextWindow: 300, thresholdRatio: 0.1, retainTokens: 10 })) - const session = multiTurnSession(3, 1) - const agent = stubAgent(session, 'missing-model') - const before = session.surface.nodes.length - - await firePreStep(ctx, agent, 1, '') - // No summary landed; the surface is unchanged. - expect(session.events.some(e => e.type === 'compact/summary')).toBe(false) - expect(session.surface.nodes.length).toBe(before) - }) - - it('does not register the listener when auto is false', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - void new BasicCompactService(ctx, cfg({ auto: false, contextWindow: 100, thresholdRatio: 0.1, retainTokens: 5 })) - const session = multiTurnSession(3, 1) - const agent = stubAgent(session, 'test-model') - - await firePreStep(ctx, agent, 1, '') - expect(session.events.some(e => e.type === 'compact/start')).toBe(false) - }) - - it('summarization is interceptable at llm/stream (model routing for direct calls)', async () => { - const { ctx, adapter } = await ctxWithModel('ROUTED SUMMARY', 'routed-model') - // One-shot summaries bypass agent/request but remain mutable at llm/stream; - // adapter selection happens after the waterfall rewrite. - ctx.on('llm/stream', (options, next) => { - options.provider = 'routed-model' - options.model = 'routed-model' - return next() - }) - void new BasicCompactService(ctx, cfg({ contextWindow: 200, thresholdRatio: 0.5, retainTokens: 20 })) - const session = multiTurnSession(5, 1) - const agent = stubAgent(session, 'agent-model') - - await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) - - expect(adapter.lastOptions?.model).toBe('routed-model') - expect(session.events.some(e => e.type === 'compact/summary')).toBe(true) - expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'ROUTED SUMMARY' }) - }) - - it('removes the auto pre-step listener when the plugin fiber is disposed', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - const fiber = await ctx.plugin(BasicCompactService, cfg({ - contextWindow: 200, - thresholdRatio: 0.5, - retainTokens: 20, - })) - const session = multiTurnSession(5, 1) - const agent = stubAgent(session, 'test-model') - - await fiber.dispose() - await firePreStep(ctx, agent, 1, '') - - expect(session.events.some(e => e.type === 'compact/start')).toBe(false) - expect(ctx.get('compact')).toBeUndefined() - }) -}) - -describe('BasicCompactService transcript rendering (delegated to dsh-compact)', () => { - it('renders reasoning, context, and steering messages', async () => { - const svc = createTestService() - const s = new Session(SessionId('rich')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('context/message', { - content: [{ type: 'text', text: 'project context here' }], - source: { kind: 'user' }, - }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [{ type: 'reasoning', text: 'thinking hard' }, { type: 'text', text: 'answer' }], - }, { surfaceOp: 'append' }) - s.append('steering/message', { - turn: 1, - content: [{ type: 'text', text: 'steer this way' }], - source: { kind: 'user' }, - }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - - const nodes = s.surface.nodes - await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - - const { text } = svc.summarizeCalls[0]! - expect(text).toContain('[Context: project context here]') - expect(text).toContain('[reasoning: thinking hard]') - expect(text).toContain('[Steering: steer this way]') - }) - - it('labels tool errors distinctly from tool results', async () => { - const svc = createTestService() - const s = new Session(SessionId('toolerr')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('user/message', { content: [{ type: 'text', text: 'run it' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [{ type: 'tool-call', id: CallId('c9'), name: 'bash', arguments: '{}' }], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: 1, step: 1, callId: CallId('c9'), name: 'bash', arguments: '{}' }) - s.append('tool/result', { - turn: 1, step: 1, callId: CallId('c9'), - content: [{ type: 'text', text: 'boom failure' }], - isError: true, - }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - - const nodes = s.surface.nodes - await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - expect(svc.summarizeCalls[0]!.text).toContain('Tool error (call c9): boom failure') - }) -}) - -describe('BasicCompactService edge cases', () => { - it('renders bare and nested tool-result placeholders and unknown blocks', async () => { - const svc = createTestService() - const s = new Session(SessionId('toolresult')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - // assistant/message carrying a nested tool-result block, an unknown block, - // and the tool-call that the following tool/result answers (so the surface - // is tool-pairing balanced). - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [ - { type: 'tool-result', toolCallId: CallId('n1'), content: [{ type: 'chart', data: 'x' } as unknown as ContentBlock] }, - { type: 'custom-widget', payload: 'x' } as unknown as ContentBlock, - { type: 'tool-call', id: CallId('b1'), name: 'bash', arguments: '{}' }, - ], - }, { surfaceOp: 'append' }) - // tool/result whose content is itself only non-text → bare '[tool-result]'. - s.append('tool/call', { turn: 1, step: 1, callId: CallId('b1'), name: 'bash', arguments: '{}' }) - s.append('tool/result', { - turn: 1, step: 1, callId: CallId('b1'), - content: [{ type: 'tool-result', toolCallId: CallId('inner'), content: [] }], - isError: false, - }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - - const nodes = s.surface.nodes - await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - const { text } = svc.summarizeCalls[0]! - expect(text).toContain('[tool-result: [chart]]') // nested tool-result with content - expect(text).toContain('[custom-widget]') // unknown block placeholder - expect(text).toContain('Tool result (call b1): [tool-result]') // empty nested → bare placeholder - }) - - it('estimates unknown block types via JSON length (default branch)', () => { - const svc = new BasicCompactService(new Context(), cfg({ auto: false })) - // A block whose type is none of the known kinds — exercises the default arm. - const unknown = { type: 'custom-widget', payload: 'some data' } as unknown as ContentBlock - expect(svc.estimateContentTokens([unknown])).toBeGreaterThan(0) - }) - - it('auto-compaction reports bounded retry exhaustion after committing a smaller summary', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - const warnings: string[] = [] - ctx.logger.warn = ((msg: string) => void warnings.push(msg)) as typeof ctx.logger.warn - void new BasicCompactService(ctx, cfg({ - contextWindow: 300, - thresholdRatio: 0.1, - retainTokens: 5, - compactionRetries: 0, - })) - const session = multiTurnSession(4, 1) - const agent = stubAgent(session, 'test-model') - - await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) - expect(session.events.some(e => e.type === 'compact/summary')).toBe(true) - // The surface was mutated; the head message is the framed summary checkpoint. - expect(session.deriveMessages()[0]!.content).toContainEqual({ type: 'text', text: 'SUMMARY' }) - expect(warnings.some(w => w.includes('still above threshold after 1 compaction attempts'))).toBe(true) - }) - - it('rejects compaction when no turn is open (compaction events must be turn-enclosed)', async () => { - const svc = createTestService() - // A session whose only turn has CLOSED — scanning back from the tail hits - // turn/end before any turn/start, so there is no open turn to enclose - // compaction's compact/* + replacement events, which the log contract forbids. - const s = new Session(SessionId('noturn')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('user/message', { content: [{ type: 'text', text: 'orphan' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'reply' }] }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - const nodes = s.surface.nodes - - await expect(compactRegion(svc, s, nodes[0]!.seq, nodes[1]!.seq, 'm')) - .rejects.toThrow(/no open turn/) - // The lock was never acquired — no compact/start landed. - expect(s.events.some(e => e.type === 'compact/start')).toBe(false) - }) - - it('rejects compaction on a session with no turn boundaries at all', async () => { - const svc = createTestService() - // No turn events whatsoever — the open-turn scan falls through to the end - // of the log and finds none, so compaction is rejected (its events have no - // turn to enclose them). - const s = new Session(SessionId('turnless')) - s.append('user/message', { content: [{ type: 'text', text: 'orphan' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - const nodes = s.surface.nodes - - await expect(compactRegion(svc, s, nodes[0]!.seq, nodes[0]!.seq, 'm')) - .rejects.toThrow(/no open turn/) - expect(s.events.some(e => e.type === 'compact/start')).toBe(false) - }) - - it('compactIfNeeded returns null for empty surface even when over threshold', async () => { - const svc = createTestService({ contextWindow: 1000, thresholdRatio: 0.1, retainTokens: 5 }) - const session = new Session(SessionId('empty-but-pressured')) - // No surface nodes, but a large system prompt pushes the estimate over threshold. - const bigPrompt = 'x'.repeat(800) // ceil(800/4) = 200 tokens >> threshold 100 - expect(await compactIfNeeded(svc, session, bigPrompt, 'm', SIGNAL)).toBeNull() - }) - - it('compactRegion throws when end is not a surface node (start valid)', async () => { - const svc = createTestService() - const session = multiTurnSession(1, 1) - const nodes = session.surface.nodes - await expect(compactRegion(svc, session, nodes[0]!.seq, 9999, 'm')) - .rejects.toThrow(/end seq 9999 not found in surface/) - }) - - it('compactRegion stringifies a non-Error thrown by summarize', async () => { - const svc = createTestService() - // Throw a non-Error value to exercise the String(error) branch in the catch. - svc.summarizeError = 'plain string failure' as unknown as Error - const session = multiTurnSession(1, 1) - const nodes = session.surface.nodes - - // Whole step (user → assistant): a step-aligned region that reaches summarize. - await expect(compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'm')).rejects.toBe('plain string failure') - const endEvent = session.events.findLast(e => e.type === 'compact/end')! - expect(endEvent.data).toMatchObject({ error: 'plain string failure' }) - }) - - it('auto-compaction listener stringifies a non-Error and proceeds', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - const warnings: string[] = [] - ctx.logger.warn = ((msg: string) => void warnings.push(msg)) as typeof ctx.logger.warn - const svc = new TestCompactService(ctx, cfg({ contextWindow: 300, thresholdRatio: 0.1, retainTokens: 10 })) - svc.summarizeError = 'boom' as unknown as Error - const session = multiTurnSession(3, 1) - const agent = stubAgent(session, 'test-model') - const before = session.surface.nodes.length - - await ctx.serial('agent/pre-step', agent, 1, 1, '', [], SIGNAL) - // The failure was swallowed; the surface is untouched and a warning logged. - expect(session.surface.nodes.length).toBe(before) - expect(session.events.some(e => e.type === 'compact/summary')).toBe(false) - expect(warnings.some(w => w.includes('compaction failed: boom'))).toBe(true) - }) - - it('auto-compaction listener takes the result-null branch (nothing to compact)', async () => { - const { ctx } = await ctxWithModel('SUMMARY') - // A large system prompt pushes the listener's estimate over threshold, but - // retainTokens is huge so compactIfNeeded walks everything and returns null. - // threshold = floor(2000*0.1) = 200; invariant: 5 + 150 = 155 ≤ 200. - const svc = new TestCompactService(ctx, cfg({ contextWindow: 2000, thresholdRatio: 0.1, retainTokens: 150 })) - const session = multiTurnSession(2, 1) - const agent = stubAgent(session, 'test-model') - const bigSystem = 'x'.repeat(900) // ceil(900/4)=225 > threshold 200 - - await ctx.serial('agent/pre-step', agent, 1, 1, bigSystem, [], SIGNAL) - expect(session.events.some(e => e.type === 'compact/start')).toBe(false) - expect(svc.summarizeCalls.length).toBe(0) - }) - - it('skips messages whose extracted text is empty across all kinds', async () => { - const svc = createTestService() - const s = new Session(SessionId('empties')) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - s.append('user/message', { content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'reasoning', text: '' }] }, { surfaceOp: 'append' }) - s.append('context/message', { content: [], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('steering/message', { turn: 1, content: [{ type: 'text', text: '' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - // Keep the log pairing-valid while the empty result covers the final message kind. - s.append('step/start', { turn: 1, step: 2 }) - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 2, - content: [{ type: 'tool-call', id: CallId('z1'), name: 'bash', arguments: '{}' }], - }, { surfaceOp: 'append' }) - s.append('tool/call', { turn: 1, step: 2, callId: CallId('z1'), name: 'bash', arguments: '{}' }) - s.append('tool/result', { turn: 1, step: 2, callId: CallId('z1'), content: [], isError: false }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 2 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - - const nodes = s.surface.nodes - await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - expect(svc.summarizeCalls[0]!.text).toBe('Assistant: [tool-call: bash({})]') - }) - - it('renders non-text blocks as type-tagged placeholders across all message kinds', async () => { - const svc = createTestService() - const s = new Session(SessionId('placeholders')) - // A plugin-added block type (merge-extensible ContentBlockMap) — the - // placeholder path must cover every message kind, not just assistant. - const chart = (id: string): ContentBlock => ({ type: 'chart', data: id } as unknown as ContentBlock) - s.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - s.append('step/start', { turn: 1, step: 1 }) - // user/message with only a plugin-added block → '[chart]' placeholder. - s.append('user/message', { content: [chart('y')], source: { kind: 'user' } }, { surfaceOp: 'append' }) - // assistant/message with a plugin-added block AND the tool-call its - // tool/result answers (so the surface is tool-pairing balanced). - s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, - turn: 1, step: 1, - content: [ - chart('z'), - { type: 'tool-call', id: CallId('e1'), name: 'bash', arguments: '{}' }, - ], - }, { surfaceOp: 'append' }) - // tool/result with a plugin-added block → '[chart]' placeholder. - s.append('tool/call', { turn: 1, step: 1, callId: CallId('e1'), name: 'bash', arguments: '{}' }) - s.append('tool/result', { turn: 1, step: 1, callId: CallId('e1'), content: [chart('r')], isError: false }, { surfaceOp: 'append' }) - // context/message and steering/message with plugin-added content. - s.append('context/message', { content: [chart('c')], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('steering/message', { turn: 1, content: [chart('s')], source: { kind: 'user' } }, { surfaceOp: 'append' }) - s.append('step/end', { turn: 1, step: 1 }) - s.append('turn/end', { turn: 1, reason: { kind: 'completed' } }) - s.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }) - - const nodes = s.surface.nodes - await compactRegion(svc, s, nodes[0]!.seq, nodes[nodes.length - 1]!.seq, 'm') - const { text } = svc.summarizeCalls[0]! - // Every non-text block surfaces as a placeholder rather than being dropped. - expect(text).toContain('User: [chart]') - expect(text).toContain('Assistant: [chart]') - expect(text).toContain('Tool result (call e1): [chart]') - expect(text).toContain('[Context: [chart]]') - expect(text).toContain('[Steering: [chart]]') - }) - -}) - -describe('BasicCompactService positional range (surface seqs are not monotonic after a replace)', () => { - it('compacts a second region after the first replace lands a high-seq summary at the head position', async () => { - // Replacement makes surface seqs non-monotonic. The next region is a - // positional span even when startSeq > endSeq. - const svc = createTestService({ auto: false }) - const session = multiTurnSession(4, 1) - - // A replacement puts its high-seq summary at the surface head. - const nodes0 = session.surface.nodes - const first = await compactRegion(svc, session, nodes0[0]!.seq, nodes0[1]!.seq, 'm') - - const nodes1 = session.surface.nodes - expect(nodes1[0]!.seq).toBeGreaterThanOrEqual(first.summarySeq) - expect(nodes1[0]!.seq).toBeGreaterThan(nodes1[1]!.seq) - - const startSeq = nodes1[0]!.seq - const endSeq = nodes1[2]!.seq - expect(startSeq).toBeGreaterThan(endSeq) - const second = await compactRegion(svc, session, startSeq, endSeq, 'm') - - // Selection follows surface positions, not sequence-number order. - expect(second.shadowedSeqs).toEqual([nodes1[0]!.seq, nodes1[1]!.seq, nodes1[2]!.seq]) - const finalNodes = session.surface.nodes - expect(finalNodes[0]!.seq).toBeGreaterThanOrEqual(second.summarySeq) - expect(session.deriveMessages().length).toBe(finalNodes.length) - }) - - it('extracts the second-compaction transcript in surface order, not log-seq order', async () => { - const svc = createTestService({ auto: false }) - const session = multiTurnSession(3, 1) - - // Put a high-seq summary at the head; log order would place retained older nodes first. - const n0 = session.surface.nodes - await compactRegion(svc, session, n0[0]!.seq, n0[1]!.seq, 'm') - - const n1 = session.surface.nodes - svc.summarizeCalls = [] - await compactRegion(svc, session, n1[0]!.seq, n1[2]!.seq, 'm') - - // Extraction must match surface and `deriveMessages()` order. - const { text } = svc.summarizeCalls[0]! - const checkpointIdx = text.indexOf('compacted-summary') - const olderIdx = text.indexOf('turn 2 user') - expect(checkpointIdx).toBeGreaterThanOrEqual(0) - expect(olderIdx).toBeGreaterThan(checkpointIdx) - }) -}) - -describe('BasicCompactService llm inject (real plugin-load path)', () => { - it('declares llm in static inject so a sibling fiber can resolve ctx.llm', () => { - // summarize() reads ctx.llm; the inject lets the cordis ctx proxy resolve a sibling - // LlmService when this service is mounted as its own plugin fiber. - expect(BasicCompactService.inject).toContain('llm') - }) - - it('resolves ctx.llm and summarizes when mounted as a sibling plugin of LlmService', async () => { - const ctx = new Context() - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter('CONDENSED')) - // Mount the service through its real plugin fiber (NOT new …(rootCtx)), so - // the sibling-fiber ctx.llm resolution actually exercises the inject. - const fiber = await ctx.plugin(BasicCompactService, cfg({ auto: false })) - - const svc = ctx.compact as BasicCompactService - const session = multiTurnSession(2, 1) - const nodes = session.surface.nodes - const result = await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'test-model') - expect(result.summary).toEqual([{ type: 'text', text: 'CONDENSED' }]) - - // Tear the fiber down so this test owns no leaked registration; the - // dedicated cleanup assertion lives in the "HMR safety" suite. - await fiber.dispose() - expect(ctx.get('compact')).toBeUndefined() - }) -}) - -describe('BasicCompactService under the real invariants plugin', () => { - /** - * Drive compaction through a session whose `session/event` listeners include - * the real dev-mode invariants plugin (as a real app loads it via agent-core). - * The invariants throw on append, so a passing run proves the compaction - * sequence is contract-valid: every event is turn-enclosed, and the positional - * replace op is accepted even when the surface is no longer seq-ordered. - */ - async function setup(): Promise<{ ctx: Context; session: Session; svc: BasicCompactService }> { - const ctx = new Context() - await ctx.plugin(SessionStore) - await ctx.plugin(Invariants) - await ctx.plugin(LlmService) - ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter('CONDENSED')) - await ctx.plugin(BasicCompactService, cfg({ auto: false })) - const session = ctx.sessions.create() - return { ctx, session, svc: ctx.compact as BasicCompactService } - } - - /** Append one closed turn of [user, assistant] surface nodes via the store. */ - function closedTurn(session: Session, turn: number): void { +/** Closed two-message turns followed by one open turn for durable compaction events. */ +function conversation(turns = 4, text = 'fixture '.repeat(40).trim()): Session { + const session = new Session(SessionId(`conversation-${turns}`)) + for (let turn = 1; turn <= turns; turn += 1) { session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('user/message', { + content: [{ type: 'text', text: `${text} user ${turn}` }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) session.append('step/start', { turn, step: 1 }) - session.append('user/message', { content: [{ type: 'text', text: `turn ${turn} user.${LONG_FIXTURE_TEXT}` }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn, step: 1, content: [{ type: 'text', text: `turn ${turn} assistant.${LONG_FIXTURE_TEXT}` }] }, { surfaceOp: 'append' }) + session.append('assistant/message', { + provenance: { provider: MODEL, model: MODEL }, + turn, + step: 1, + content: [{ type: 'text', text: `${text} assistant ${turn}` }], + }, { surfaceOp: 'append' }) session.append('step/end', { turn, step: 1 }) session.append('turn/end', { turn, reason: { kind: 'completed' } }) } + session.append('turn/start', { + turn: turns + 1, + trigger: { kind: 'message', source: { kind: 'user' } }, + }) + return session +} - it('runs a turn-enclosed compaction whose positional replace the invariants accept', async () => { - const { session, svc } = await setup() - closedTurn(session, 1) - closedTurn(session, 2) - // Open turn 3, as the loop has when the auto-compaction listener fires. - session.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }) +function toolConversation(): Session { + const session = new Session(SessionId('tools')) + for (let turn = 1; turn <= 3; turn += 1) { + const callId = CallId(`call-${turn}`) + session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('user/message', { + content: [{ type: 'text', text: `request ${turn} `.repeat(300) }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + session.append('step/start', { turn, step: 1 }) + session.append('assistant/message', { + provenance: { provider: MODEL, model: MODEL }, + turn, + step: 1, + content: [ + { type: 'text', text: `calling ${turn} `.repeat(300) }, + { type: 'tool-call', id: callId, name: 'read', arguments: '{}' }, + ], + }, { surfaceOp: 'append' }) + session.append('tool/call', { turn, step: 1, callId, name: 'read', arguments: '{}' }) + session.append('tool/result', { + turn, + step: 1, + callId, + content: [{ type: 'text', text: `result ${turn} `.repeat(300) }], + isError: false, + }, { surfaceOp: 'append' }) + session.append('step/end', { turn, step: 1 }) + session.append('turn/end', { turn, reason: { kind: 'completed' } }) + } + session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } }) + return session +} - const nodes = session.surface.nodes - // No invariant throws here: compact/* + the replacement are all in turn 3. - const result = await compactRegion(svc, session, nodes[0]!.seq, nodes[1]!.seq, 'test-model') - expect(result.shadowedSeqs.length).toBe(2) - expect(session.surface.nodes[0]!.seq).toBeGreaterThan(session.surface.nodes[1]!.seq) +class TestCompactService extends BasicCompactService { + summary: ContentBlock[] = [{ type: 'text', text: 'small checkpoint' }] + summaryProvider = 'summary-provider' + summaryModel = 'summary-model' + error: unknown + mutateDuringSummary: (() => void) | undefined + calls: Array<{ text: string; signal: AbortSignal | undefined }> = [] + + override async summarize( + text: string, + _agent: Agent, + signal?: AbortSignal, + ): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> { + this.calls.push({ text, signal }) + this.mutateDuringSummary?.() + if (this.error !== undefined) throw this.error + return { + summary: this.summary, + provider: this.summaryProvider, + model: this.summaryModel, + maxTokens: 123, + } + } +} + +function service( + config: BasicCompactConfig = { auto: false }, + ctx = createContext(), +): TestCompactService { + return new TestCompactService(ctx, config) +} + +async function compactIfNeeded( + compact: BasicCompactService, + session: Session, + model: string | undefined = MODEL, + system = '', + prefix: readonly Message[] = [], +): Promise { + return compact.compactIfNeeded(agent(session, model), system, prefix, SIGNAL) +} + +describe('compact configuration and defaults', () => { + it('uses low-friction service-wide defaults', () => { + const ctx = createContext() + const resolved = resolveConfig({}, ctx.tokenMeter) + + expect(resolved).toEqual({ + thresholdRatio: 0.8, + retainTokens: 160, + summarizationProvider: '', + summarizationModel: '', + maxTokens: 8192, + compactionRetries: 1, + auto: true, + }) + expect(Object.isFrozen(resolved)).toBe(true) }) - it('accepts a second compaction over the non-monotonic surface left by the first', async () => { - const { session, svc } = await setup() - closedTurn(session, 1) - closedTurn(session, 2) - closedTurn(session, 3) - session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: { kind: 'user' } } }) + it('resolves threshold and retention overrides independently', () => { + const ctx = createContext() + const thresholdOnly = resolveConfig({ + thresholdRatio: 0.5, + }, ctx.tokenMeter) + expect(thresholdOnly).toMatchObject({ + thresholdRatio: 0.5, + retainTokens: 160, + }) - const n0 = session.surface.nodes - await compactRegion(svc, session, n0[0]!.seq, n0[1]!.seq, 'test-model') + const retentionOnly = resolveConfig({ + retainTokens: 70, + }, ctx.tokenMeter) + expect(retentionOnly).toMatchObject({ + thresholdRatio: 0.8, + retainTokens: 70, + }) + }) - // Surface head now carries a higher seq than the older retained nodes. A - // second compaction spanning [head … a later closed-step end] must pass the - // invariants' positional replace check even though startSeq > endSeq. - const n1 = session.surface.nodes - expect(n1[0]!.seq).toBeGreaterThan(n1[2]!.seq) - const second = await compactRegion(svc, session, n1[0]!.seq, n1[2]!.seq, 'test-model') - expect(second.shadowedSeqs).toEqual([n1[0]!.seq, n1[1]!.seq, n1[2]!.seq]) + it('validates common values and pressure-policy invariants', () => { + const ctx = createContext() + const bad = [ + [{ maxTokens: 0 }, /maxTokens/], + [{ compactionRetries: -1 }, /compactionRetries/], + [{ auto: 'yes' }, /auto must be a boolean/], + [{ summarizationProvider: 1 }, /summarizationProvider must be a string/], + [{ summarizationModel: 1 }, /summarizationModel must be a string/], + [{ summarizationProvider: MODEL }, /must both be set or both be empty/], + [{ summarizationModel: MODEL }, /must both be set or both be empty/], + [{ thresholdRatio: 0 }, /number in \(0, 1\]/], + [{ thresholdRatio: 1.1 }, /number in \(0, 1\]/], + [{ retainTokens: -1 }, /non-negative integer/], + [{ thresholdRatio: 0.5, retainTokens: 500 }, /less than threshold/], + [{ models: { [MODEL]: { retainTokens: 10 } } }, /BasicCompactConfig: unknown key "models"/], + [{ thresholdRato: 0.5 }, /BasicCompactConfig: unknown key "thresholdRato"/], + ] as Array<[unknown, RegExp]> + + for (const [config, pattern] of bad) { + expect(() => resolveConfig(config as BasicCompactConfig, ctx.tokenMeter)).toThrow(pattern) + } + }) +}) + +describe('pressure measurement and retention', () => { + const compactConfig: BasicCompactConfig = { + auto: false, + thresholdRatio: 0.5, + retainTokens: 180, + } + + it('skips the provisional check only when no routed or fallback model exists', async () => { + const compact = service(compactConfig) + const session = conversation() + expect(await compact.compactIfNeeded(agent(session), '', [], SIGNAL)).toBeNull() + expect(compact.calls).toHaveLength(0) + }) + + it('meters any routed model without profile resolution', async () => { + const compact = service(compactConfig) + await expect(compactIfNeeded(compact, conversation(), 'unlisted-model')) + .resolves.not.toBeNull() + }) + + it('does nothing below threshold and compacts a priced head above threshold', async () => { + const compact = service(compactConfig) + expect(await compactIfNeeded(compact, conversation(2))).toBeNull() + + const session = conversation(4) + const result = await compactIfNeeded(compact, session) + expect(result).not.toBeNull() + expect(result?.shadowedSeqs.length).toBeGreaterThan(2) + expect(session.surface.nodes.length).toBeLessThan(8) + }) + + it('counts the current prompt and request prefix without putting either on the surface', async () => { + const compact = service({ + auto: false, + thresholdRatio: 0.7, + retainTokens: 50, + }) + const session = conversation(2, 'x'.repeat(200)) + expect(await compactIfNeeded(compact, session)).toBeNull() + + const prefix: Message[] = [{ + role: 'user', + content: [{ type: 'text', text: 'p'.repeat(1_000) }], + }] + const result = await compactIfNeeded(compact, session, MODEL, 's'.repeat(1_000), prefix) + expect(result).not.toBeNull() + expect(prefix).toHaveLength(1) + expect(session.events.some(event => event.type === 'context/message')).toBe(false) + }) + + it('uses the latest logged routed model in the provisional request envelope', async () => { + const ctx = createContext() + const compact = service({ + auto: false, + thresholdRatio: 0.5, + retainTokens: 180, + }, ctx) + const session = conversation(4) + session.append('request/header', { + header: { config: { provider: 'actual', model: 'actual' } }, + reason: 'initial', + }) + const measure = vi.spyOn(ctx.tokenMeter, 'measure') + + const result = await compactIfNeeded(compact, session, 'fallback') + expect(result).not.toBeNull() + expect(measure.mock.calls[0]?.[1]?.config.provider).toBe('actual') + expect(measure.mock.calls[0]?.[1]?.config.model).toBe('actual') + }) + + it('declines when envelope pressure is high but the surface has no compactable range', async () => { + const compact = service(compactConfig) + const empty = new Session(SessionId('empty')) + expect(await compactIfNeeded(compact, empty, MODEL, 'x'.repeat(100_000))).toBeNull() + + const retained = conversation(1) + expect(await compactIfNeeded(compact, retained, MODEL, 'x'.repeat(100_000))).toBeNull() + }) + + it('uses one unified measurement for each pressure-and-retention decision', async () => { + const ctx = createContext() + const compact = service(compactConfig, ctx) + const measure = vi.spyOn(ctx.tokenMeter, 'measure') + const stop = new Error('stop after first decision') + vi.spyOn(compact, 'compactRegion').mockRejectedValueOnce(stop) + + await expect(compactIfNeeded(compact, conversation(4))).rejects.toBe(stop) + expect(measure).toHaveBeenCalledTimes(1) + }) + + it('bounds retries when a shrinking checkpoint remains above threshold', async () => { + const compact = service({ + auto: false, + compactionRetries: 0, + thresholdRatio: 0.3, + retainTokens: 180, + }) + compact.summary = Array.from({ length: 7 }, (_, index) => ({ + type: 'text', + text: `summary ${index}`, + })) + + await expect(compactIfNeeded(compact, conversation(4))) + .rejects.toThrow(/still above threshold after 1 compaction attempts/) + }) + + it('rounds a retention cut head-ward to preserve tool-call/result pairing', async () => { + const compact = service({ + auto: false, + thresholdRatio: 0.8, + retainTokens: 80, + }, createContext(4_000)) + const session = toolConversation() + const result = await compactIfNeeded(compact, session) + expect(result).not.toBeNull() + + const messages = session.deriveMessages() + const calls = new Set() + for (const message of messages) { + for (const block of message.content) { + if (block.type === 'tool-call') calls.add(block.id) + if (block.type === 'tool-result') expect(calls.has(block.toolCallId)).toBe(true) + } + } + }) + + it('rejects a priced surface that is not the current positional surface', () => { + const ctx = createContext() + const session = conversation(2) + const priced = ctx.tokenMeter.measure(session) + expect(() => selectCompactableRange(session, { + ...priced, + nodes: priced.nodes.slice(1), + }, 1)).toThrow(/does not match/) + }) + + it('declines when rounding a cut would consume the only tool pair', () => { + const ctx = createContext() + const session = new Session(SessionId('one-tool-pair')) + const callId = CallId('only') + session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) + session.append('step/start', { turn: 1, step: 1 }) + session.append('assistant/message', { + provenance: { provider: MODEL, model: MODEL }, + turn: 1, + step: 1, + content: [{ type: 'tool-call', id: callId, name: 'read', arguments: '{}' }], + }, { surfaceOp: 'append' }) + session.append('tool/call', { turn: 1, step: 1, callId, name: 'read', arguments: '{}' }) + session.append('tool/result', { + turn: 1, + step: 1, + callId, + content: [{ type: 'text', text: 'result' }], + isError: false, + }, { surfaceOp: 'append' }) + session.append('step/end', { turn: 1, step: 1 }) + + const priced = ctx.tokenMeter.measure(session) + expect(selectCompactableRange(session, priced, 1)).toBeNull() + }) +}) + +describe('compaction region transaction', () => { + it('rejects an agent that does not own the exact target session before mutation', async () => { + const compact = service() + const target = conversation(2) + const owner = conversation(1) + const targetEvents = [...target.events] + const ownerEvents = [...owner.events] + const nodes = target.surface.nodes + + await expect(compact.compactRegion( + target, + nodes[0]!, + nodes[1]!, + agent(owner), + )).rejects.toThrow('compactRegion: agent.session must be the exact target session') + + expect(target.events).toEqual(targetEvents) + expect(owner.events).toEqual(ownerEvents) + expect(compact.calls).toEqual([]) + }) + + it('lands a framed, replayable checkpoint with exact pricing provenance', async () => { + const compact = service() + const session = conversation(3) + const before = session.surface.nodes + const result = await compact.compactRegion( + session, + before[0]!, + before[3]!, + agent(session, MODEL), + SIGNAL, + ) + + expect(result.shadowedSeqs).toEqual(before.slice(0, 4)) + expect(result.shadowedTokenCount).toBeGreaterThan(0) + expect(compact.calls[0]).toMatchObject({ signal: SIGNAL }) + expect(compact.calls[0]?.text).toContain('fixture user 1') + const summary = session.events.findLast(event => event.type === 'compact/summary') + expect(summary?.data).toMatchObject({ + shadowedSeqs: result.shadowedSeqs, + shadowedTokenCount: result.shadowedTokenCount, + provider: 'summary-provider', + model: 'summary-model', + maxTokens: 123, + }) + const head = session.deriveMessages()[0]! + expect(head.content[0]?.type).toBe('text') + expect(head.content[0]?.type === 'text' ? head.content[0].text : '').toContain('') + expect(head.content.at(-1)).toEqual({ type: 'text', text: '' }) + + const replay = new Session(SessionId('replay'), [...session.events]) + expect(replay.deriveMessages()).toEqual(session.deriveMessages()) + }) + + it.each([ + ['start missing', 9_001, undefined, /start seq 9001 not found/], + ['end missing', undefined, 9_002, /end seq 9002 not found/], + ])('rejects %s', async (_label, startOverride, endOverride, pattern) => { + const compact = service() + const session = conversation(2) + const nodes = session.surface.nodes + await expect(compact.compactRegion( + session, + startOverride ?? nodes[0]!, + endOverride ?? nodes[1]!, + agent(session, MODEL), + )).rejects.toThrow(pattern) + }) + + it('rejects reversed and tool-unbalanced positional boundaries', async () => { + const compact = service() + const plain = conversation(2) + const nodes = plain.surface.nodes + await expect(compact.compactRegion( + plain, + nodes[2]!, + nodes[1]!, + agent(plain, MODEL), + )).rejects.toThrow(/is after end/) + + const tools = toolConversation() + const toolNodes = tools.surface.nodes + await expect(compact.compactRegion( + tools, + toolNodes[2]!, + toolNodes[4]!, + agent(tools, MODEL), + )).rejects.toThrow(/start seq .* not a balanced boundary/) + await expect(compact.compactRegion( + tools, + toolNodes[0]!, + toolNodes[1]!, + agent(tools, MODEL), + )).rejects.toThrow(/end seq .* not a balanced boundary/) + }) + + it('requires an open turn and an idle compaction bracket', async () => { + const compact = service() + const closed = conversation(1) + closed.append('turn/end', { turn: 2, reason: { kind: 'completed' } }) + const nodes = closed.surface.nodes + await expect(compact.compactRegion( + closed, + nodes[0]!, + nodes[1]!, + agent(closed, MODEL), + )).rejects.toThrow(/no open turn/) + + const locked = conversation(1) + locked.append('compact/start', { turn: 2 }) + const lockedNodes = locked.surface.nodes + await expect(compact.compactRegion( + locked, + lockedNodes[0]!, + lockedNodes[1]!, + agent(locked, MODEL), + )).rejects.toThrow(/already in progress/) + }) + + it('rejects a session with no turn boundary at all', async () => { + const compact = service() + const session = new Session(SessionId('turnless')) + session.append('user/message', { + content: [{ type: 'text', text: 'orphan' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const node = session.surface.nodes[0]! + + await expect(compact.compactRegion( + session, + node, + node, + agent(session, MODEL), + )).rejects.toThrow(/no open turn/) + }) + + it('rejects a meter snapshot that changed before summarization began', async () => { + const ctx = createContext() + const meter = ctx.tokenMeter + const original = meter.measure.bind(meter) + vi.spyOn(meter, 'measure').mockImplementationOnce((session) => { + const measurement = original(session) + return { ...measurement, nodes: measurement.nodes.slice(1) } + }) + const compact = service({ auto: false }, ctx) + const session = conversation(2) + const nodes = session.surface.nodes + + await expect(compact.compactRegion( + session, + nodes[0]!, + nodes[2]!, + agent(session, MODEL), + )).rejects.toThrow(/selected surface changed/) + }) + + it('records summarizer failures without mutating the surface', async () => { + const compact = service() + compact.error = new Error('summary unavailable') + const session = conversation(2) + const before = session.surface.nodes + + await expect(compact.compactRegion( + session, + before[0]!, + before[2]!, + agent(session, MODEL), + )).rejects.toThrow('summary unavailable') + expect(session.surface.nodes).toEqual(before) + expect(session.events.findLast(event => event.type === 'compact/end')?.data) + .toMatchObject({ error: 'summary unavailable' }) + }) + + it('stringifies non-Error failures in the durable end bracket', async () => { + const compact = service() + compact.error = 'plain failure' + const session = conversation(2) + const nodes = session.surface.nodes + await expect(compact.compactRegion( + session, + nodes[0]!, + nodes[2]!, + agent(session, MODEL), + )).rejects.toBe('plain failure') + expect(session.events.findLast(event => event.type === 'compact/end')?.data) + .toMatchObject({ error: 'plain failure' }) + }) + + it('rejects concurrent durable appends before committing the replacement', async () => { + const compact = service() + const session = conversation(2) + compact.mutateDuringSummary = () => { + session.append('request/header', { + header: { config: { provider: MODEL, model: MODEL } }, + reason: 'initial', + }) + } + const nodes = session.surface.nodes + + await expect(compact.compactRegion( + session, + nodes[0]!, + nodes[2]!, + agent(session, MODEL), + )).rejects.toThrow(/session log changed/) + expect(session.events.some(event => event.type === 'compact/summary')).toBe(false) + }) + + it('rejects a non-shrinking framed summary under the conversation meter', async () => { + const compact = service() + compact.summary = Array.from({ length: 100 }, (_, index) => ({ + type: 'text', + text: `verbose ${index}`, + })) + const session = conversation(2) + const nodes = session.surface.nodes + + await expect(compact.compactRegion( + session, + nodes[0]!, + nodes[2]!, + agent(session, MODEL), + )).rejects.toThrow(/summary is not smaller/) + expect(session.events.some(event => event.type === 'compact/summary')).toBe(false) + }) + + it('lets a model-independent custom summarizer compact without a conversation model', async () => { + const compact = service() + const session = conversation(1) + const nodes = session.surface.nodes + await expect(compact.compactRegion( + session, + nodes[0]!, + nodes[1]!, + agent(session), + )).resolves.toMatchObject({ shadowedSeqs: [nodes[0]!, nodes[1]!] }) + }) +}) + +class ScriptedAdapter extends LlmAdapter { + lastOptions: GenerateOptions | undefined + + constructor( + private readonly blocks: readonly ContentBlock[], + private readonly finish: (StreamChunk & { type: 'finish' })['reason'] = { kind: 'stop' }, + ) { + super() + } + + override async * stream(options: GenerateOptions): AsyncIterable { + this.lastOptions = options + for (const [index, block] of this.blocks.entries()) { + yield { type: 'block-start', index, blockType: block.type } + if (block.type === 'text') { + yield { type: 'text-delta', index, text: block.text } + } else if (block.type === 'reasoning') { + yield { type: 'reasoning-delta', index, text: block.text } + } else { + yield { type: 'block-end', index, block } + } + } + yield { type: 'finish', reason: this.finish } + } +} + +async function summarizerHarness( + blocks: readonly ContentBlock[], + finish?: (StreamChunk & { type: 'finish' })['reason'], + model = MODEL, + config: BasicCompactConfig = { auto: false }, +): Promise<{ ctx: Context; adapter: ScriptedAdapter; compact: BasicCompactService }> { + const ctx = new Context() + await ctx.plugin(LlmService) + void new TokenMeterService(ctx, { contextWindow: 1_000 }) + const adapter = new ScriptedAdapter(blocks, finish) + ctx.llm.registerAdapter([model], adapter) + const compact = new BasicCompactService(ctx, config) + return { ctx, adapter, compact } +} + +describe('default one-shot summarizer', () => { + it('uses configured model/default cap, forwards cancellation, and keeps only safe text', async () => { + const { adapter, compact } = await summarizerHarness([ + { type: 'reasoning', text: 'private' }, + { type: 'text', text: 'public summary' }, + { type: 'tool-call', id: CallId('unexpected'), name: 'x', arguments: '{}' }, + ], undefined, MODEL, { + auto: false, + summarizationProvider: MODEL, + summarizationModel: MODEL, + maxTokens: 321, + }) + const session = conversation(1) + const output = await compact.summarize('transcript', agent(session, 'fallback'), SIGNAL) + + expect(output).toEqual({ + summary: [{ type: 'text', text: 'public summary' }], + provider: MODEL, + model: MODEL, + maxTokens: 321, + }) + expect(adapter.lastOptions).toMatchObject({ + provider: MODEL, + model: MODEL, + maxTokens: 321, + signal: SIGNAL, + sessionId: session.id, + }) + expect(adapter.lastOptions?.system).toContain('## Primary Request and Intent') + }) + + it('resolves the latest routed provider/model before the AgentOptions pair', async () => { + const { adapter, compact } = await summarizerHarness([{ type: 'text', text: 'summary' }], undefined, 'routed') + const session = conversation(1) + session.append('request/header', { + header: { config: { provider: 'routed', model: 'routed' } }, + reason: 'initial', + }) + const output = await compact.summarize('history', agent(session, 'fallback')) + expect(output.provider).toBe('routed') + expect(output.model).toBe('routed') + expect(adapter.lastOptions?.provider).toBe('routed') + expect(adapter.lastOptions?.model).toBe('routed') + }) + + it('fails clearly when no complete summarization target can be resolved', async () => { + const ctx = new Context() + await ctx.plugin(LlmService) + void new TokenMeterService(ctx) + const compact = new BasicCompactService(ctx, { auto: false }) + await expect(compact.summarize('history', agent(new Session(SessionId('model-less'))))) + .rejects.toThrow(/no provider\/model available for summarization/) + }) + + it.each([ + [{ kind: 'error', message: 'provider failed', code: 'PROVIDER' }, 'PROVIDER', /provider failed/], + [{ kind: 'error', message: 'opaque' }, undefined, /opaque/], + [{ kind: 'aborted' }, 'ABORTED', /aborted/], + [{ kind: 'max-tokens' }, 'MAX_TOKENS', /token cap/], + ] as Array<[(StreamChunk & { type: 'finish' })['reason'], string | undefined, RegExp]>) ( + 'rejects terminal finish %#', + async (finish, code, pattern) => { + const { compact } = await summarizerHarness([], finish) + let thrown: unknown + try { + await compact.summarize('history', agent(conversation(1), MODEL)) + } catch (error: unknown) { + thrown = error + } + expect(thrown).toBeInstanceOf(Error) + expect((thrown as Error).message).toMatch(pattern) + expect((thrown as Error & { code?: string }).code).toBe(code) + }, + ) + + it('rejects empty or reasoning-only successful output', async () => { + const { compact } = await summarizerHarness([{ type: 'reasoning', text: 'private' }]) + await expect(compact.summarize('history', agent(conversation(1), MODEL))) + .rejects.toThrow(/no text summary content/) + }) +}) + +describe('automatic listener and loader composition', () => { + function preStep(ctx: Context, owner: Agent): Promise { + return ctx.serial('agent/pre-step', owner, 1, 1, '', [], SIGNAL) + } + + it('compacts above threshold and remains idle below it', async () => { + const ctx = createContext() + const compact = new TestCompactService(ctx, { + thresholdRatio: 0.5, + retainTokens: 180, + }) + const pressured = conversation(4) + await preStep(ctx, agent(pressured, MODEL)) + expect(pressured.events.some(event => event.type === 'compact/summary')).toBe(true) + + const small = conversation(1) + await preStep(ctx, agent(small, MODEL)) + expect(small.events.some(event => event.type === 'compact/start')).toBe(false) + expect(compact.calls).toHaveLength(1) + }) + + it('warns and continues after operational failures, including non-Errors', async () => { + const ctx = createContext() + const warnings: string[] = [] + ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn + const compact = new TestCompactService(ctx, { + thresholdRatio: 0.5, + retainTokens: 180, + }) + compact.error = 'temporary failure' + const session = conversation(4) + + await expect(preStep(ctx, agent(session, MODEL))).resolves.toBeUndefined() + expect(warnings).toContainEqual(expect.stringContaining('temporary failure')) + expect(session.events.some(event => event.type === 'compact/summary')).toBe(false) + }) + + it('auto:false installs no listener', async () => { + const ctx = createContext() + void new TestCompactService(ctx, { + auto: false, + thresholdRatio: 0.5, + retainTokens: 180, + }) + const session = conversation(4) + await preStep(ctx, agent(session, MODEL)) + expect(session.events.some(event => event.type === 'compact/start')).toBe(false) + }) + + it('loads and disposes the real zero-config service stack', async () => { + const ctx = new Context() + await ctx.plugin(LlmService) + const meterFiber = await ctx.plugin(TokenMeterService) + const compactFiber = await ctx.plugin(BasicCompactService, { auto: false }) + + expect(ctx.tokenMeter.contextWindow).toBe(128_000) + expect(ctx.get('compact')).toBeInstanceOf(BasicCompactService) + await compactFiber.dispose() + expect(ctx.get('compact')).toBeUndefined() + await meterFiber.dispose() + expect(ctx.get('tokenMeter')).toBeUndefined() + }) + + it('removes its automatic listener with the plugin fiber', async () => { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(TokenMeterService, { contextWindow: 1_000 }) + const fiber = await ctx.plugin(TestCompactService, { + thresholdRatio: 0.5, + retainTokens: 180, + }) + await fiber.dispose() + + const session = conversation(4) + await preStep(ctx, agent(session, MODEL)) + expect(session.events.some(event => event.type === 'compact/start')).toBe(false) }) }) diff --git a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts index 1724e3d639..d163d84804 100644 --- a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts +++ b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts @@ -9,6 +9,7 @@ import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit' 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' /** @@ -18,15 +19,13 @@ 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[]; provider: string; model: string }> { - return { summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], provider: 'mock', model: 'stub' } + return { + summary: [{ type: 'text', text: 'CHECKPOINT SUMMARY' }], + provider: 'mock', + model: 'stub', + } } } @@ -61,6 +60,7 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr await mountAgentLoopTestDependencies(ctx) await ctx.plugin(Invariants) await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(TokenMeterService, { contextWindow: 400 }) ctx.llm.registerAdapter(['mock'], new StepwiseToolAdapter(toolSteps)) ctx.tools.register(defineTool({ name: 'work', @@ -70,14 +70,12 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr return [{ type: 'text', text: 'work result' }] }, })) - // Tiny window so a couple of tool steps cross the threshold and compaction - // fires within the runaway turn. + // Small window so several tool steps cross the threshold and compaction + // fires within the runaway turn after enough history can shrink. const compact = new ReproCompactService(ctx, { auto: true, - contextWindow: 64, thresholdRatio: 0.5, - retainTokens: 20, - summarizationProvider: '', + retainTokens: 50, summarizationModel: '', maxTokens: 8192, compactionRetries: 1, @@ -117,12 +115,12 @@ describe('CBR-001: a real-loop checkpoint is a valid boundary on both sides', () // its start and end cuts are balanced in surface order. const nodes = agent.session.surface.nodes for (const cp of checkpoints) { - const node = nodes.find(n => n.seq === cp.seq) - if (!node) continue // shadowed by a later checkpoint — no longer an edge. - expect(toolPairingBalancedBefore(agent.session, node), - `checkpoint seq ${node.seq} must be a balanced region START`).toBe(true) - expect(toolPairingBalancedAfter(agent.session, node), - `checkpoint seq ${node.seq} must be a balanced region END`).toBe(true) + const index = nodes.indexOf(cp.seq) + if (index === -1) continue // shadowed by a later checkpoint — no longer an edge. + expect(toolPairingBalancedBefore(agent.session, cp.seq), + `checkpoint seq ${cp.seq} must be a balanced region START`).toBe(true) + expect(toolPairingBalancedAfter(agent.session, cp.seq), + `checkpoint seq ${cp.seq} must be a balanced region END`).toBe(true) } } finally { await ctx.fiber.dispose() diff --git a/packages/compact/compact-basic/tests/loader-composition.spec.ts b/packages/compact/compact-basic/tests/loader-composition.spec.ts new file mode 100644 index 0000000000..b13e8f8b67 --- /dev/null +++ b/packages/compact/compact-basic/tests/loader-composition.spec.ts @@ -0,0 +1,94 @@ +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 +}) + +async function loadYaml(lines: readonly string[]): Promise { + root = await mkdtemp(join(tmpdir(), 'dsh-token-meter-loader-')) + const configPath = join(root, 'cordis.yml') + await writeFile(configPath, [...lines, ''].join('\n')) + + context = new Context() + context.baseUrl = pathToFileURL(root).href + '/' + await context.plugin(Loader) + context.loader.builtins.include = Include + const modules = new Map([ + ['@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 + await context.loader.create({ + name: 'cordis:include', + config: { path: pathToFileURL(configPath).href }, + }) + await context.loader.await() + return context +} + +describe('real Loader composition', () => { + it('loads the flat token-meter and compact-basic YAML shape', async () => { + const loaded = await loadYaml([ + "- name: '@deepseek-ai/dsh-llm'", + "- name: '@deepseek-ai/dsh-token-meter'", + ' config:', + ' contextWindow: 4096', + "- name: '@deepseek-ai/dsh-compact-basic'", + ' config:', + ' thresholdRatio: 0.5', + ' retainTokens: 512', + ' auto: false', + ]) + + const unloaded = [...loaded.loader.entries()] + .filter(entry => entry.fiber === undefined && !entry.disabled) + .map(entry => entry.options.name) + expect(unloaded).toEqual([]) + expect(loaded.tokenMeter.contextWindow).toBe(4096) + expect(loaded.get('compact')).toBeInstanceOf(BasicCompactService) + expect((loaded.compact as BasicCompactService).config).toMatchObject({ + thresholdRatio: 0.5, + retainTokens: 512, + auto: false, + }) + }) + + it('rejects stale token-meter config after Schemastery normalization', async () => { + context = new Context() + await expect(context.plugin(TokenMeterService, { + models: { legacy: { contextWindow: 4096 } }, + } as never)).rejects.toThrow(/TokenMeterConfig: unknown key "models"/) + }) + + it('rejects stale compact-basic config after Schemastery normalization', async () => { + context = new Context() + await context.plugin(LlmService) + await context.plugin(TokenMeterService) + await expect(context.plugin(BasicCompactService, { + models: { legacy: { thresholdRatio: 0.5 } }, + } as never)).rejects.toThrow(/BasicCompactConfig: unknown key "models"/) + }) +}) diff --git a/packages/compact/compact-basic/tsconfig.json b/packages/compact/compact-basic/tsconfig.json index 075c64cb61..0103ad82a8 100644 --- a/packages/compact/compact-basic/tsconfig.json +++ b/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" } diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index fb26812837..ec14947090 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -7,27 +7,27 @@ 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 | |---|---| | `compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)` | Estimate the surface-derived history size; if over the backend's threshold, compact an older range via `compactRegion`, keeping recent context intact. Returns the `CompactionResult`, or `null` if nothing needed compacting. All parameters required — the loop's `agent/pre-step` checkpoint supplies the agent, assembled `fullSystemPrompt`, composed `sessionPrefix` (request-only messages every request carries but the derived history omits — the pressure estimate must count them), and turn `signal`. A backend's summarization request is a direct `ctx.llm.stream()` call (not a loop step), so per-call interception happens at `llm/stream`. | -| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. | +| `compactRegion(session, start, end, agent, signal?)` | Forcibly summarize surface nodes `[start, end]` (inclusive seqs) into a single replacement node. The agent must own the exact target (`session === agent.session`); a backend rejects mismatch before model resolution, lock acquisition, summarization, or log mutation. **Throws** if a compaction is already in progress, if `start`/`end` aren't surface nodes, or if `start` is positioned after `end` on the surface. The range is a SURFACE-POSITION span, not a numeric seq interval — after a prior replace lands a fresh high-seq summary node at the shadowed range's position, surface order no longer tracks seq order. | -`compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The session being compacted comes from the agent context; the turn that the `compact/*` events belong to is recoverable from the log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value. +`compactIfNeeded` takes a required `signal`; `compactRegion`'s is optional. A backend that summarizes via `ctx.llm.stream()` **must** forward it into the call's `GenerateOptions.signal`, so an abort or fiber dispose tears down the in-flight summarization instead of leaving an orphaned model call running past the cancellation. The turn that the `compact/*` events belong to is recoverable from the owned session's log (the currently-open turn), so the backend stamps it from the log rather than trusting a caller-supplied value. ## Tool-pairing boundaries -The interface exports `toolPairingBalancedBefore(session, node)` and `toolPairingBalancedAfter(session, node)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper identifies the node by seq alone and answers from balances cached per cut in current surface order, so a stale caller-held `node.next` cannot choose the cut. +The interface exports `toolPairingBalancedBefore(session, seq)` and `toolPairingBalancedAfter(session, seq)` for snapping and validating compaction edges. A safe edge has no unanswered assistant tool call crossing it. Each helper validates that the event sequence is in the current surface and answers from balances cached per cut in surface order. -The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-node count. An unchanged generation extends the fold with unseen tail nodes only; a log-only append with no new surface node does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state. +The private per-session cache is keyed by `session.surface.replaceGeneration` and the processed surface-entry count. An unchanged generation extends the fold with unseen tail entries only; a log-only append with no new surface entry does no event reads, while a replacement generation rebuilds current membership and balances. Missing event seqs and a `tool/result` without a preceding open call reject as corrupt surface state. ## Surface contract @@ -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 diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts index 12eb77b362..7361d38ef3 100644 --- a/packages/compact/compact/src/index.ts +++ b/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) { @@ -66,17 +67,19 @@ export abstract class CompactService extends Service { * `start` and `end` name an inclusive span by surface position, not numeric seq * order; replacements can make visible seqs non-monotonic. Both edges must be * balanced so assistant tool calls remain paired with their results. A model- - * backed implementation forwards cancellation and rejects active, missing, - * reversed, or unbalanced ranges. + * backed implementation forwards cancellation. The agent must own the exact + * target session object; implementations reject an ownership mismatch before + * model resolution, lock acquisition, summarization, or log mutation, and + * reject active, missing, reversed, or unbalanced ranges. * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter} * for the edge checks. * - * @param session - session to mutate. + * @param session - session to mutate; must be identical to `agent.session`. * @param start - first surface seq, inclusive. * @param end - last surface seq, inclusive. - * @param agent - summarizer context. + * @param agent - owner of the target session and summarizer context. * @param signal - optional cancellation; model-backed implementations must forward it. - * @throws when compaction is active or the range is missing, reversed, or unbalanced. + * @throws when the agent does not own `session`, compaction is active, or the range is missing, reversed, or unbalanced. * @returns the replaced range and summary. */ abstract compactRegion( diff --git a/packages/compact/compact/src/tool-pairing.ts b/packages/compact/compact/src/tool-pairing.ts index 0fc0f68dc8..56e7a0592d 100644 --- a/packages/compact/compact/src/tool-pairing.ts +++ b/packages/compact/compact/src/tool-pairing.ts @@ -1,24 +1,23 @@ /** * Tool-pairing balance over a session surface. Compaction changes surface * positions, so safe cuts are derived from tool-call/result content in current - * surface order rather than step markers or linked-list fields supplied by a - * caller. + * surface order rather than step markers. * @module @deepseek-ai/dsh-compact/tool-pairing */ -import type { Session, SessionEvent, SurfaceNode } from '@deepseek-ai/dsh-session' +import type { Session, SessionEvent } from '@deepseek-ai/dsh-session' /** Incremental balance state for one session surface generation. */ interface BalanceCache { /** Surface rewrite generation this state describes. */ generation: number /** - * Balance of every surface cut in current order: a surface of N nodes has - * N + 1 cuts, entry `i` being the cut before node `i` and the final entry + * Balance of every surface cut in current order: a surface of N sequences has + * N + 1 cuts, entry `i` being the cut before sequence `i` and the final entry * the cut after the surface tail. */ cutBalanced: readonly boolean[] - /** Current surface position of each node seq, indexing {@link cutBalanced}. */ + /** Current surface position of each event seq, indexing {@link cutBalanced}. */ indexBySeq: Map /** In-progress tool-call count after the processed surface tail. */ inProgressToolCalls: number @@ -27,7 +26,7 @@ interface BalanceCache { const balanceCacheBySession = new WeakMap() /** Return how one surface event changes the in-progress tool-call count. */ -function nodeDelta(event: SessionEvent): number { +function eventDelta(event: SessionEvent): number { switch (event.type) { case 'assistant/message': return event.data.content.filter(block => block.type === 'tool-call').length @@ -38,37 +37,37 @@ function nodeDelta(event: SessionEvent): number { } } -/** Read and validate the event named by a surface node. */ -function eventForNode(events: readonly SessionEvent[], node: SurfaceNode): SessionEvent { - const event = events[node.seq] - if (event === undefined || event.seq !== node.seq) { - throw new Error(`tool-pairing balance: surface seq ${node.seq} has no matching session event (corrupt surface)`) +/** Read and validate the event named by a surface sequence. */ +function eventForSeq(events: readonly SessionEvent[], seq: number): SessionEvent { + const event = events[seq] + if (event === undefined || event.seq !== seq) { + throw new Error(`tool-pairing balance: surface seq ${seq} has no matching session event (corrupt surface)`) } return event } -/** Fold surface nodes not yet in the cache into its balance state. */ +/** Fold surface sequences not yet in the cache into its balance state. */ function extendCache( session: Session, cache: BalanceCache, - nodes: readonly SurfaceNode[], + seqs: readonly number[], ): BalanceCache { const processed = cache.cutBalanced.length - 1 - const tail = nodes.slice(processed) + const tail = seqs.slice(processed) // Validate the unseen tail before mutating the live cache, so a corrupt // append cannot leave a partially advanced state behind. const events = session.events const pendingCuts: boolean[] = [] let inProgressToolCalls = cache.inProgressToolCalls - for (const node of tail) { - inProgressToolCalls += nodeDelta(eventForNode(events, node)) + for (const seq of tail) { + inProgressToolCalls += eventDelta(eventForSeq(events, seq)) if (inProgressToolCalls < 0) { - throw new Error(`tool-pairing balance: tool/result at surface seq ${node.seq} has no matching tool-call (corrupt surface)`) + throw new Error(`tool-pairing balance: tool/result at surface seq ${seq} has no matching tool-call (corrupt surface)`) } pendingCuts.push(inProgressToolCalls === 0) } - tail.forEach((node, offset) => cache.indexBySeq.set(node.seq, processed + offset)) + tail.forEach((seq, offset) => cache.indexBySeq.set(seq, processed + offset)) cache.cutBalanced = cache.cutBalanced.concat(pendingCuts) cache.inProgressToolCalls = inProgressToolCalls return cache @@ -77,11 +76,11 @@ function extendCache( /** Return balance state synchronized with the current session surface. */ function balanceCache(session: Session): BalanceCache { const surface = session.surface - const nodes = surface.nodes + const seqs = surface.nodes const generation = surface.replaceGeneration const cached = balanceCacheBySession.get(session) - if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > nodes.length) { + if (cached === undefined || cached.generation !== generation || cached.cutBalanced.length - 1 > seqs.length) { // A rebuild is the same fold started from the empty-surface state, whose // single leading cut is trivially balanced. const rebuilt = extendCache(session, { @@ -89,15 +88,15 @@ function balanceCache(session: Session): BalanceCache { cutBalanced: [true], indexBySeq: new Map(), inProgressToolCalls: 0, - }, nodes) + }, seqs) balanceCacheBySession.set(session, rebuilt) return rebuilt } - if (cached.cutBalanced.length - 1 < nodes.length) return extendCache(session, cached, nodes) + if (cached.cutBalanced.length - 1 < seqs.length) return extendCache(session, cached, seqs) return cached } -/** Balance of the cut at a node's position plus offset, rejecting seqs outside current membership. */ +/** Balance of the cut at a sequence's position plus offset, rejecting seqs outside current membership. */ function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean { const index = cache.indexBySeq.get(seq) const balanced = index === undefined ? undefined : cache.cutBalanced[index + offset] @@ -108,25 +107,25 @@ function cutBalance(cache: BalanceCache, seq: number, offset: 0 | 1): boolean { } /** - * Whether the cut immediately before a current surface node is tool-pairing balanced. + * Whether the cut immediately before a current surface sequence is tool-pairing balanced. * @param session - session whose surface is checked. - * @param node - surface node whose leading cut is checked; only its seq identifies it. + * @param seq - event sequence whose leading cut is checked. * @returns true when no unanswered tool call crosses the cut. - * @throws when the seq is absent from the current surface, a surface node has no + * @throws when the seq is absent from the current surface, a surface sequence has no * matching log event, or a tool result has no preceding open call. */ -export function toolPairingBalancedBefore(session: Session, node: SurfaceNode): boolean { - return cutBalance(balanceCache(session), node.seq, 0) +export function toolPairingBalancedBefore(session: Session, seq: number): boolean { + return cutBalance(balanceCache(session), seq, 0) } /** - * Whether the cut immediately after a current surface node is tool-pairing balanced. + * Whether the cut immediately after a current surface sequence is tool-pairing balanced. * @param session - session whose surface is checked. - * @param node - surface node whose trailing cut is checked; only its seq identifies it. + * @param seq - event sequence whose trailing cut is checked. * @returns true when no unanswered tool call crosses the cut. - * @throws when the seq is absent from the current surface, a surface node has no + * @throws when the seq is absent from the current surface, a surface sequence has no * matching log event, or a tool result has no preceding open call. */ -export function toolPairingBalancedAfter(session: Session, node: SurfaceNode): boolean { - return cutBalance(balanceCache(session), node.seq, 1) +export function toolPairingBalancedAfter(session: Session, seq: number): boolean { + return cutBalance(balanceCache(session), seq, 1) } diff --git a/packages/compact/compact/tests/tool-pairing.spec.ts b/packages/compact/compact/tests/tool-pairing.spec.ts index d8c6b92bce..5f48e7f99f 100644 --- a/packages/compact/compact/tests/tool-pairing.spec.ts +++ b/packages/compact/compact/tests/tool-pairing.spec.ts @@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest' import { CallId } from '@deepseek-ai/dsh-llm' import { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact' import { Session, SessionId } from '@deepseek-ai/dsh-session' -import type { SessionEvent, SurfaceNode } from '@deepseek-ai/dsh-session' +import type { SessionEvent } from '@deepseek-ai/dsh-session' const SURFACE = { surfaceOp: 'append' as const } @@ -10,18 +10,18 @@ function seqOf(session: Session, type: SessionEvent['type'], nth = 0): number { return session.events.filter(event => event.type === type)[nth]!.seq } -function nodeAt(session: Session, seq: number): SurfaceNode { - const node = session.surface.nodes.find(candidate => candidate.seq === seq) - if (node === undefined) throw new Error(`seq ${seq} is not a surface node`) - return node +function surfaceSeq(session: Session, seq: number): number { + const current = session.surface.nodes.find(candidate => candidate === seq) + if (current === undefined) throw new Error(`seq ${seq} is not on the surface`) + return current } function before(session: Session, type: SessionEvent['type'], nth = 0): boolean { - return toolPairingBalancedBefore(session, nodeAt(session, seqOf(session, type, nth))) + return toolPairingBalancedBefore(session, surfaceSeq(session, seqOf(session, type, nth))) } function after(session: Session, type: SessionEvent['type'], nth = 0): boolean { - return toolPairingBalancedAfter(session, nodeAt(session, seqOf(session, type, nth))) + return toolPairingBalancedAfter(session, surfaceSeq(session, seqOf(session, type, nth))) } function closedToolStep(): Session { @@ -117,9 +117,9 @@ describe('tool-pairing boundaries', () => { }) describe('tool-pairing surface identity', () => { - it('rebuilds after replace and rejects nodes removed from current membership', () => { + it('rebuilds after replace and rejects sequences removed from current membership', () => { const session = closedToolStep() - const staleTail = nodeAt(session, seqOf(session, 'tool/result')) + const staleTail = surfaceSeq(session, seqOf(session, 'tool/result')) expect(toolPairingBalancedAfter(session, staleTail)).toBe(true) const nodes = session.surface.nodes @@ -127,8 +127,8 @@ describe('tool-pairing surface identity', () => { content: [{ type: 'text', text: 'checkpoint' }], source: { kind: 'plugin', plugin: 'compact' }, }, { - surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes.at(-1)!.seq }, - sourceEventSeqs: nodes.map(node => node.seq), + surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes.at(-1)! }, + sourceEventSeqs: [...nodes], }) const checkpoint = session.surface.nodes[0]! @@ -138,16 +138,16 @@ describe('tool-pairing surface identity', () => { expect(() => toolPairingBalancedAfter(session, staleTail)).toThrow(/surface seq .* not found/) }) - it('ignores a caller-held node next field and answers from cached balances', () => { + it('answers repeated queries from cached balances', () => { const session = closedToolStep() - const assistant = nodeAt(session, seqOf(session, 'assistant/message')) - expect(toolPairingBalancedAfter(session, { ...assistant, next: null })).toBe(false) - expect(toolPairingBalancedAfter(session, { ...assistant, next: 999 })).toBe(false) + const assistant = surfaceSeq(session, seqOf(session, 'assistant/message')) + expect(toolPairingBalancedAfter(session, assistant)).toBe(false) + expect(toolPairingBalancedAfter(session, assistant)).toBe(false) }) it('rejects missing seqs before and after, including an empty surface', () => { const session = new Session(SessionId('missing-membership')) - const missing: SurfaceNode = { seq: 999, prev: null, next: null } + const missing = 999 expect(() => toolPairingBalancedBefore(session, missing)).toThrow(/surface seq 999 not found/) expect(() => toolPairingBalancedAfter(session, missing)).toThrow(/surface seq 999 not found/) @@ -183,11 +183,7 @@ describe('tool-pairing cache refresh', () => { surfaceOp: 'append', }, ] - const nodes: SurfaceNode[] = [ - { seq: 0, prev: null, next: 1 }, - { seq: 1, prev: 0, next: 2 }, - { seq: 2, prev: 1, next: null }, - ] + const nodes: number[] = [0, 1, 2] let generation = 0 let eventCollectionReads = 0 let eventIndexReads = 0 @@ -231,7 +227,7 @@ describe('tool-pairing cache refresh', () => { data: { content: [{ type: 'text', text: 'tail' }], source: { kind: 'user' } }, surfaceOp: 'append', }) - nodes.push({ seq: 4, prev: 2, next: null }) + nodes.push(4) expect(toolPairingBalancedAfter(session, nodes[3]!)).toBe(true) expect(eventCollectionReads).toBe(2) expect(eventIndexReads).toBe(4) @@ -253,10 +249,7 @@ describe('tool-pairing cache refresh', () => { surfaceOp: 'append', }, ) - nodes.push( - { seq: 5, prev: 4, next: 6 }, - { seq: 6, prev: 5, next: null }, - ) + nodes.push(5, 6) expect(toolPairingBalancedAfter(session, nodes[5]!)).toBe(true) expect(eventCollectionReads).toBe(3) expect(eventIndexReads).toBe(6) @@ -266,14 +259,14 @@ describe('tool-pairing cache refresh', () => { data: { content: [{ type: 'text', text: 'replacement' }], source: { kind: 'user' } }, surfaceOp: { op: 'replace', start: 0, end: 6 }, }) - nodes.splice(0, nodes.length, { seq: 7, prev: null, next: null }) + nodes.splice(0, nodes.length, 7) generation += 1 expect(toolPairingBalancedAfter(session, nodes[0]!)).toBe(true) expect(eventCollectionReads).toBe(4) expect(eventIndexReads).toBe(7) }) - it('rebuilds defensively when a same-generation surface node count regresses', () => { + it('rebuilds defensively when a same-generation surface entry count regresses', () => { const events: SessionEvent[] = [ { type: 'user/message', seq: 0, time: 0, @@ -284,10 +277,7 @@ describe('tool-pairing cache refresh', () => { data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append', }, ] - const nodes: SurfaceNode[] = [ - { seq: 0, prev: null, next: 1 }, - { seq: 1, prev: 0, next: null }, - ] + const nodes: number[] = [0, 1] const session = { events, surface: { nodes, replaceGeneration: 0 }, @@ -321,24 +311,24 @@ describe('tool-pairing corrupt surfaces', () => { }) it('throws when a current surface seq has no matching event or indexes the wrong event', () => { - const missingNode: SurfaceNode = { seq: 1, prev: null, next: null } + const missingSeq = 1 const missing = { events: [{ type: 'user/message', seq: 0, time: 0, data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append', } satisfies SessionEvent], - surface: { nodes: [missingNode], replaceGeneration: 0 }, + surface: { nodes: [missingSeq], replaceGeneration: 0 }, } as unknown as Session - expect(() => toolPairingBalancedBefore(missing, missingNode)).toThrow(/no matching session event/) + expect(() => toolPairingBalancedBefore(missing, missingSeq)).toThrow(/no matching session event/) - const mismatchedNode: SurfaceNode = { seq: 0, prev: null, next: null } + const mismatchedSeq = 0 const mismatched = { events: [{ type: 'user/message', seq: 99, time: 0, data: { content: [], source: { kind: 'user' } }, surfaceOp: 'append', } satisfies SessionEvent], - surface: { nodes: [mismatchedNode], replaceGeneration: 0 }, + surface: { nodes: [mismatchedSeq], replaceGeneration: 0 }, } as unknown as Session - expect(() => toolPairingBalancedBefore(mismatched, mismatchedNode)).toThrow(/no matching session event/) + expect(() => toolPairingBalancedBefore(mismatched, mismatchedSeq)).toThrow(/no matching session event/) }) }) diff --git a/packages/context/time-context/README.md b/packages/context/time-context/README.md index 6e114ea7e0..fea92e726f 100644 --- a/packages/context/time-context/README.md +++ b/packages/context/time-context/README.md @@ -26,7 +26,7 @@ Step 1 measures from the latest preceding model-visible message, including the p A time reading records a request-preparation attempt, not a committed step or transmitted request. Because the listener runs first, its append may remain when a later pre-step listener cancels or fails the attempt; the log is append-only and the plugin performs no rollback. -The time reading stays in derived conversation history until a later compaction shadows it. Request headers and header deltas contain no time-context state. Request reconstruction uses the complete durable surface prefix at each `step/start`, so transmitted requests need not map one-to-one to readings: a failed preparation can leave an extra reading, while interval suppression can let a request reuse existing history without adding one. +The time reading stays in derived conversation history until a later compaction shadows it. Request headers contain no time-context state. Request reconstruction uses the complete durable surface prefix at each `step/start`, so transmitted requests need not map one-to-one to readings: a failed preparation can leave an extra reading, while interval suppression can let a request reuse existing history without adding one. ## Model Experience diff --git a/packages/context/time-context/package.json b/packages/context/time-context/package.json index 8900eaf900..c0d69a75cb 100644 --- a/packages/context/time-context/package.json +++ b/packages/context/time-context/package.json @@ -33,6 +33,7 @@ "@deepseek-ai/dsh-agent-loop": "workspace:^", "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-loader-smoke": "workspace:^", "@deepseek-ai/dsh-session": "workspace:^", "@deepseek-ai/dsh-system-prompt": "workspace:^", "@deepseek-ai/dsh-tools": "workspace:^", diff --git a/packages/context/time-context/tests/time-context.e2e.ts b/packages/context/time-context/tests/time-context.e2e.ts index 4d5b2ed122..f14981ea36 100644 --- a/packages/context/time-context/tests/time-context.e2e.ts +++ b/packages/context/time-context/tests/time-context.e2e.ts @@ -4,12 +4,17 @@ import { tmpdir } from 'node:os' import { join } from 'node:path' import { fileURLToPath } from 'node:url' import { afterEach, describe, expect, it } from 'vitest' -import type { SessionEvent } from '@deepseek-ai/dsh-session' +import { type SessionEvent } from '@deepseek-ai/dsh-session' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' +// Keep the Loader config under examples so both modes exercise the same deployable +// topology: local fixture source plus bare plugins owned by the examples workspace. const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url)) -const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url)) +const configPath = fileURLToPath(new URL( + '../../../../examples/echo-agent/tests/fixtures/context/time-context/cordis.yml', + import.meta.url, +)) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const PROCESS_TIMEOUT_MS = 30_000 const TEST_TIMEOUT_MS = PROCESS_TIMEOUT_MS + 15_000 const FIRST_REPLY = '[main turn 1] You said: "Time sampled while preparing turn 1, step 1:' @@ -39,21 +44,22 @@ async function runTwoTurns(): Promise<{ stdout: string; stderr: string }> { workdir = await mkdtemp(join(tmpdir(), 'time-context-e2e-')) const cwd = workdir return new Promise((resolve, reject) => { - const proc = spawn( - process.execPath, - ['--expose-internals', '--import', tsxLoader, binScript, configPath], - { - cwd, - env: { - ...process.env, - TZ: 'Asia/Shanghai', - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - }, - stdio: ['pipe', 'pipe', 'pipe'], + const launch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: [configPath], + tsconfigPath: repoTsconfig, + exposeInternals: true, + env: { + TZ: 'Asia/Shanghai', + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), }, - ) + }) + const proc = spawn(launch.command, launch.args, { + cwd, + env: { ...process.env, ...launch.env }, + stdio: ['pipe', 'pipe', 'pipe'], + }) child = proc let stdout = '' let stderr = '' @@ -119,8 +125,7 @@ describe('time-context through a real cordis.yml and stdio process', () => { ) expect(contextText[1]).toMatch(/Time sampled while preparing turn 2, step 1:/) - const headers = events.filter(event => event.type === 'request/header' - || event.type === 'request/header-delta') + const headers = events.filter(event => event.type === 'request/header') expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing') }, TEST_TIMEOUT_MS) }) diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts index 2d6cb49056..2796e8230c 100644 --- a/packages/context/time-context/tests/time-context.spec.ts +++ b/packages/context/time-context/tests/time-context.spec.ts @@ -423,10 +423,8 @@ describe('real agent-loop request history', () => { expect(secondRequestText).toContain('Elapsed since the preceding step context: 1m 1s.') for (const request of adapter.requests) expect(request.system).not.toContain('Time sampled while preparing') - const headers = agent.session.events.filter(event => event.type === 'request/header' - || event.type === 'request/header-delta') + const headers = agent.session.events.filter(event => event.type === 'request/header') expect(JSON.stringify(headers)).not.toContain('Time sampled while preparing') - expect(agent.session.events.filter(event => event.type === 'request/header-delta')).toHaveLength(0) await ctx.fiber.dispose() }) }) diff --git a/packages/context/time-context/tsconfig.json b/packages/context/time-context/tsconfig.json index f8e14d8aa2..7815242b55 100644 --- a/packages/context/time-context/tsconfig.json +++ b/packages/context/time-context/tsconfig.json @@ -10,6 +10,9 @@ { "path": "../../../vendor/cordis" }, { "path": "../../../vendor/schemastery" }, { "path": "../../llm/llm" }, - { "path": "../../core/agent" } + { "path": "../../core/agent" }, + { "path": "../../core/system-prompt" }, + { "path": "../../core/agent" }, + { "path": "../../support/loader-smoke" } ] } diff --git a/packages/context/workspace-context/README.md b/packages/context/workspace-context/README.md index 910c1cfdac..430ffe8a41 100644 --- a/packages/context/workspace-context/README.md +++ b/packages/context/workspace-context/README.md @@ -46,7 +46,7 @@ The core `context/message` envelope is disabled for these messages because the p ## State And Refresh -Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives first because a later tool aborted the step and the loop discarded its context buffer, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. +Model-visible text contains no hidden state markers. Each dynamic context event instead carries JSON metadata with a versioned list of `{ action, scope, path, previousPath?, digest? }` changes. On every relevant tool touch, the plugin reconstructs loaded state from its visible session events and overlays a short in-memory pending window for context present on the immutable top-level `tools/result` but not yet appended by the loop. A matching durable `context/message` confirms the pending transition. If the owning `step/end` arrives before a matching context reaches the log, the plugin clears the pending transition and its version fast path so the next successful touch can load it again. Nested Code Mode results stage pending changes under the outer execution token for same-run duplicate suppression; the outer result rolls that state back and recommits only contexts that survived outer policy. An unchanged path and SHA-1 content digest is not injected again. A per-session, per-scope metadata cache stores only `{ path, version, digest }`: when the provider's opaque `FsVersion` and the effective visible state both match, reconciliation skips the content read; a changed version triggers a bounded read and SHA-1 confirmation before any model-visible update. Resume works because SHA-1 state is persisted in the session log, while an empty in-memory version cache merely causes one confirming read. Compaction re-arms a scope after its context event leaves the visible surface even when the cached version is unchanged. A removal is a tombstone, so a later candidate reappearance is loaded again. Only model-visible changes actually rendered within the byte budget enter metadata, pending state, and the version cache; an omitted change remains eligible for a later touch, while a same-digest version refresh updates metadata only. diff --git a/packages/context/workspace-context/src/state.ts b/packages/context/workspace-context/src/state.ts index ed73c4fa57..4e8ee7de56 100644 --- a/packages/context/workspace-context/src/state.ts +++ b/packages/context/workspace-context/src/state.ts @@ -138,7 +138,7 @@ function visibleInstructionChanges( agent: Agent, pending: Map, ): Map { - const visibleSeqs = new Set(agent.session.surface.nodes.map(node => node.seq)) + const visibleSeqs = new Set(agent.session.surface.nodes) const visible = new Map() for (const [seq, event] of agent.session.events.entries()) { if (event.type !== 'context/message' || !isWorkspaceContextSource(event.data.source)) continue @@ -255,8 +255,8 @@ function invalidateInstructionVersions( /** * Settle provisional tool-result state against durable session events. * A matching context event confirms the transition. If its owning step closes - * first, the loop discarded its context buffer, so both duplicate suppression - * and the metadata fast path must be re-armed for the next successful touch. + * first, both duplicate suppression and the metadata fast path are re-armed for + * the next successful touch. * @param session - session whose append-only log emitted `event`. * @param event - newly committed session event. * @param pendingBySession - provisional transitions awaiting log confirmation. diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts index b3a9947221..2894937c9c 100644 --- a/packages/context/workspace-context/tests/workspace-context.spec.ts +++ b/packages/context/workspace-context/tests/workspace-context.spec.ts @@ -1562,7 +1562,7 @@ describe('workspace context request injection', () => { }) describe('dynamic nested workspace context injection', () => { - it('re-arms a buffered instruction change when a later tool aborts the step before context append', async () => { + it('commits a buffered instruction change before a later tool abort closes the step', async () => { const root = await tempRepo() const home = await tempRepo() const ctx = new Context() @@ -1604,12 +1604,14 @@ describe('dynamic nested workspace context injection', () => { agent.send([{ type: 'text', text: 'read and abort' }]) await agent.whenIdle() - expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(0) + expect(agent.session.events.filter(event => event.type === 'context/message')).toHaveLength(1) agent.send([{ type: 'text', text: 'retry the read' }]) await agent.whenIdle() const contexts = agent.session.events.filter(event => event.type === 'context/message') + // The aborted batch drained its accepted context before step close, so the + // retry sees durable history without producing a duplicate instruction. expect(contexts).toHaveLength(1) expect(adapter.requests).toHaveLength(3) expect(adapter.requests[2]?.messages.map(blocks => blocksText(blocks.content)).join('\n')) diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 7a9ca3c789..07b6228d62 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -243,6 +243,14 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'attachSurface(name: string): () => void', ], }, + { + key: 'tokenMeter', + summary: 'Replay owner for one service-wide estimator and isolated per-session folds.', + methods: [ + 'measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement', + 'estimateMessage(message: Message): number', + ], + }, { key: 'tools', summary: 'Tool registry and execution pipeline.', @@ -715,6 +723,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'DshEnvironmentKey', declaration: 'export type DshEnvironmentKey = `${typeof DSH_ENV_PREFIX}${string}`;', }, + { + 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}', @@ -795,6 +807,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'JsonValue', declaration: 'export type JsonValue = null | boolean | number | string | JsonValue[] | {\n [key: string]: JsonValue;\n};', }, + { + name: 'LlmCallConfig', + declaration: 'export interface LlmCallConfig {\n provider: string;\n model: string;\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n}', + }, { name: 'LlmModelInfo', declaration: 'export interface LlmModelInfo {\n provider: string;\n id: string;\n name: string;\n description?: string;\n}', @@ -1079,6 +1095,18 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'TerminalResultView', declaration: 'export interface TerminalResultView {\n card: \'terminal\';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n}', }, + { + name: 'TokenMeasurement', + declaration: 'export interface TokenMeasurement {\n readonly logRevision: number;\n readonly baseline: TokenMeasurementBaseline;\n readonly surfaceDeltaTokens: number;\n readonly totalTokens: number;\n readonly surfaceTokens: number;\n readonly nodes: readonly TokenSurfaceNode[];\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;\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}', diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index bc4355be3a..cdbf2e49a2 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -46,15 +46,17 @@ Configured agents start automatically. A model call requires both `provider` and - `ReactLoopAgent` — the concrete `Agent` implementation. Its inbox is a JavaScript native-private field, and one prepared session can be claimed by only one concrete driver. Everything observable happens through session events and the `agent/*` event taxonomy. -`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()` and running `steer()` materialize content plus resolved source once as detached, deeply frozen lossless JSON, then share that accepted record between `agent/queued` and the inbox; malformed data throws before either boundary. +`Inbox`, `runLoop`, and the instance-bound publication/start controls are package-internal. The package root does not export them, and the package exports map exposes no `./src/*` escape hatch; lifecycle owners create agents through `ctx.agents` rather than constructing or starting the driver internals. `ReactLoopAgent.send()`, running `steer()`, and open-turn `inject()` materialize content plus resolved source once as detached, deeply frozen lossless JSON; malformed data throws before enqueue or append. An injection that arrives while the current step executes assistant tool calls stays in a FIFO until the batch settles; successful batches place it after the complete result batch, and interrupted batches drain it before the turn closes. ### Loop lifecycle (`loop.ts`) 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 exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history. + 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. -Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and context remain model-ordered. Abort stops new calls, drains started results, discards their context, and follows the normal abort path. +Within a step, exclusive calls form barriers; parallel-safe calls use a bounded rolling pool and are reclassified before start. Only dispatch/body overlaps. Policy, durable results, and result context remain model-ordered. Abort stops new calls, drains started results, then drains accepted batch context before the turn closes through the normal abort path. ### What belongs to plugins diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index faea7d7f08..c8784453b9 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/packages/core/agent-loop/src/agent.ts @@ -8,7 +8,7 @@ import type { Context } from 'cordis' import { agentEvents } from '@deepseek-ai/dsh-agent' -import type { AgentId, AgentOptions, AgentStatus, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent' +import type { AgentId, AgentOptions, AgentStatus, HookContext, InjectOptions, SendOptions } from '@deepseek-ai/dsh-agent' import type { Agent } from '@deepseek-ai/dsh-agent' import { deepFreeze } from '@deepseek-ai/dsh-llm' import type { ContentBlock, MessageSource } from '@deepseek-ai/dsh-llm' @@ -152,6 +152,10 @@ export class ReactLoopAgent implements Agent { * this set before the lifecycle unregisters the agent or detaches its session. */ private pendingIdleFlushes = new Set>() + /** Whether the current step is executing an assistant tool-call batch. */ + private toolBatchActive = false + /** Open-turn injections waiting for the active assistant tool-call batch to close. */ + private deferredInjections: HookContext[] = [] constructor( private loopCtx: Context, @@ -194,12 +198,11 @@ export class ReactLoopAgent implements Agent { } /** - * Accept one public send/steer payload as the exact detached record shared by - * the live notification and inbox. Lossless-JSON materialization reads every - * nested field once; deep freeze prevents an observer from rewriting queued - * work before the loop drains it. + * Accept one public message payload as a detached record. Lossless-JSON + * materialization reads every nested field once; deep freeze prevents later + * caller mutation before an inbox or deferred-injection queue drains it. */ - private acceptInboxMessage(content: ContentBlock[], options?: SendOptions): InboxMessage { + private acceptMessage(content: ContentBlock[], options?: SendOptions): InboxMessage { const source = this.resolveSource(options) const accepted = snapshotJsonValue({ content, source }) if (accepted === undefined) { @@ -208,6 +211,15 @@ export class ReactLoopAgent implements Agent { return deepFreeze(accepted) } + /** Detach one context before it can outlive its caller in the active-batch FIFO. */ + private acceptContext(context: HookContext): HookContext { + const accepted = snapshotJsonValue(context) + if (accepted === undefined) { + throw new TypeError('agent context must be losslessly JSON-serializable') + } + return deepFreeze(accepted) + } + /** Reject a driving operation once teardown has synchronously closed the agent. */ private assertNotDisposed(): void { if (this._status === 'disposed') throw new Error(`agent "${this.id}" is disposed`) @@ -215,7 +227,7 @@ export class ReactLoopAgent implements Agent { send(content: ContentBlock[], options?: SendOptions): void { this.assertNotDisposed() - const accepted = this.acceptInboxMessage(content, options) + const accepted = this.acceptMessage(content, options) this.#inbox.enqueue(accepted) const info = { source: accepted.source, steering: false } as const agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info) @@ -224,7 +236,7 @@ export class ReactLoopAgent implements Agent { steer(content: ContentBlock[], options?: SendOptions): void { this.assertNotDisposed() if (this._status !== 'running') { this.send(content, options); return } - const accepted = this.acceptInboxMessage(content, options) + const accepted = this.acceptMessage(content, options) this.#inbox.steer(accepted) const info = { source: accepted.source, steering: true } as const agentEvents(this.loopCtx, this).emit('agent/queued', accepted.content, info) @@ -240,10 +252,15 @@ export class ReactLoopAgent implements Agent { ...options?.meta !== undefined ? { meta: options.meta } : {}, } if (isTurnOpen(this.session)) { - // A turn is open in the LOG (decided from the log, not agent status — - // status can be `running` with no turn open): the context/message is - // turn-enclosed by that turn, so append it directly. - this.session.append('context/message', context, { surfaceOp: 'append' }) + const accepted = this.acceptContext(context) + // Provider protocols require every assistant tool-call batch to be + // followed only by its tool results. Historical interrupted batches do + // not own new context; only the currently executing batch may defer it. + if (this.toolBatchActive) { + this.deferredInjections.push(accepted) + return + } + this.session.append('context/message', accepted, { surfaceOp: 'append' }) return } // No turn open: wrap the injection in a one-shot turn so every event stays @@ -283,6 +300,34 @@ export class ReactLoopAgent implements Agent { } } + /** Append deferred open-turn injections after the loop closes a tool-result batch. */ + private drainDeferredInjections(): void { + const pending = this.deferredInjections.splice(0) + for (const accepted of pending) { + this.session.append('context/message', accepted, { surfaceOp: 'append' }) + } + } + + /** + * Run one tool-call batch and drain its deferred context before settlement. + * The loop-owned acceptor remains valid after public disposal begins because + * the interrupted turn stays open until this batch settles. + */ + private async withToolBatch( + run: (acceptContext: (context: HookContext) => void) => Promise, + ): Promise { + this.toolBatchActive = true + const acceptContext = (context: HookContext): void => { + this.deferredInjections.push(this.acceptContext(context)) + } + try { + return await run(acceptContext) + } finally { + this.toolBatchActive = false + this.drainDeferredInjections() + } + } + cancel(reason?: string): void { // Arm only for current work; an idle marker would cancel the next prompt. if (this._status === 'running' || this.currentAbort !== undefined || this.#inbox.hasQueued || this.#inbox.hasSteering) { @@ -348,6 +393,7 @@ export class ReactLoopAgent implements Agent { isCancelled: () => this.cancelRequested, cancelReason: () => this.cancelReason, clearCancel: () => { this.cancelRequested = false }, + withToolBatch: run => this.withToolBatch(run), // Pre-step cancellation re-parks without emitting a status transition. settleIdle: () => { this.settleIdleWaiters() }, }) diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts index c93e77e95a..a153eba7e4 100644 --- a/packages/core/agent-loop/src/loop.ts +++ b/packages/core/agent-loop/src/loop.ts @@ -10,7 +10,7 @@ import type { ContentBlock, FinishReason, GenerateOptions, LlmCallConfig, Messag import { isDeepStrictEqual } from 'node:util' import { BlockAssembler, HarnessError, deepFreeze } from '@deepseek-ai/dsh-llm' import { agentEvents, assembleContextFor } from '@deepseek-ai/dsh-agent' -import type { AgentEventDispatch, ContinuationDecision, PromptDecision } from '@deepseek-ai/dsh-agent' +import type { AgentEventDispatch, ContinuationDecision, HookContext, PromptDecision } from '@deepseek-ai/dsh-agent' import { canonicalHeader } from '@deepseek-ai/dsh-session' import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session' import { createTransmissionLog, recordRequestHeader } from './request-log.ts' @@ -89,6 +89,8 @@ export interface LoopHandle { clearCancel(): void /** Settle idle waiters when pre-running cancellation skips a turn, without emitting `agent/status`. */ settleIdle(): void + /** Run an active tool-call batch, accepting post-tool context into the FIFO drained before settlement. */ + readonly withToolBatch: (run: (acceptContext: (context: HookContext) => void) => Promise) => Promise } /** @@ -334,8 +336,7 @@ async function runTurn( let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error } try { stepOutcome = await runStep( - ctx, events, agent, turn, step, assembly, fullSystemPrompt, boundaryMessages, - transmission, abort.signal, handle.maxParallelToolCalls) + ctx, events, agent, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal) } catch (error: unknown) { stepOutcome = { error: toError(error) } } finally { @@ -472,6 +473,7 @@ async function runStep( ctx: Context, events: AgentEventDispatch, agent: ReactLoopAgent, + handle: LoopHandle, turn: number, step: number, assembly: PromptAssembly, @@ -479,7 +481,6 @@ async function runStep( boundaryMessages: Message[], transmission: TransmissionLog, signal: AbortSignal, - maxParallelToolCalls: number, ): Promise<{ hadToolCalls: boolean; finish: FinishReason }> { const { session, options } = agent @@ -541,7 +542,9 @@ async function runStep( const assembled = assembler.message() const assembledContent = structuredClone(assembled.content) let message: Message = withoutToolCalls(assembled) - message = withoutToolCalls(await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message))) + message = withoutToolCalls(await processStepResult( + events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs, + )) // Preserve usage even when max-token truncation produced no content. recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs) return { hadToolCalls: false, finish: assembler.finish } @@ -551,28 +554,55 @@ async function runStep( const assembled = assembler.message() const assembledContent = structuredClone(assembled.content) let message: Message = assembled - message = await events.waterfall('agent/step-result', turn, step, message, () => Promise.resolve(message)) + message = await processStepResult( + events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs, + ) - const toolCalls = message.content.filter(block => block.type === 'tool-call') - - // Empty messages exist only to carry usage; the helper also omits empty chunk provenance. + // Every successful call records its completion anchor, including explicit + // empty chunk provenance for a contentless, usage-less provider response. recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs) - // Dispatch may overlap; policy, results, and context remain model-ordered. - const pendingContext = toolCalls.length > 0 - ? await executeToolCalls(ctx, agent, turn, step, toolCalls, signal, maxParallelToolCalls) - : [] + // Dispatch may overlap; policy, durable results, and result context stay model-ordered. + const toolCalls = message.content.filter(block => block.type === 'tool-call') + if (toolCalls.length === 0) return { hadToolCalls: false, finish: assembler.finish } + return handle.withToolBatch(async (acceptContext) => { + await executeToolCalls( + ctx, agent, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext, + ) + return { hadToolCalls: true, finish: assembler.finish } + }) +} - // Context follows the complete result batch to preserve call/result adjacency. - for (const context of pendingContext) { - agent.inject(context.content, { - source: context.source, - ...context.envelope !== undefined ? { envelope: context.envelope } : {}, - ...context.meta !== undefined ? { meta: context.meta } : {}, - }) +/** Preserve successful-call accounting without retaining output that result processing rejected. */ +async function processStepResult( + events: AgentEventDispatch, + session: Session, + turn: number, + step: number, + config: LlmCallConfig, + assembledContent: ContentBlock[], + message: Message, + assembler: BlockAssembler, + chunkSeqs: number[], +): Promise { + try { + return await events.waterfall( + 'agent/step-result', turn, step, message, () => Promise.resolve(message), + ) + } catch (error: unknown) { + recordAssistantMessage( + session, + turn, + step, + config, + assembledContent, + { ...message, content: [] }, + assembler, + chunkSeqs, + false, + ) + throw error } - - return { hadToolCalls: toolCalls.length > 0, finish: assembler.finish } } /** Record one content-or-usage assistant message with replay-safe provenance. */ @@ -585,8 +615,8 @@ function recordAssistantMessage( message: Message, assembler: BlockAssembler, chunkSeqs: number[], + preserveReplayState = true, ): void { - if (message.content.length === 0 && assembler.usage === undefined) return session.append( 'assistant/message', { @@ -596,11 +626,11 @@ function recordAssistantMessage( provenance: assistantProvenance( config, assembler.replayState, - isDeepStrictEqual(message.content, assembledContent), + preserveReplayState && isDeepStrictEqual(message.content, assembledContent), ), ...assembler.usage === undefined ? {} : { usage: assembler.usage }, }, - { surfaceOp: 'append', ...chunkSeqs.length > 0 ? { sourceEventSeqs: chunkSeqs } : {} }, + { surfaceOp: 'append', sourceEventSeqs: chunkSeqs }, ) } diff --git a/packages/core/agent-loop/src/request-log.ts b/packages/core/agent-loop/src/request-log.ts index c7314c2409..ea6141fea9 100644 --- a/packages/core/agent-loop/src/request-log.ts +++ b/packages/core/agent-loop/src/request-log.ts @@ -1,11 +1,12 @@ /** * Per-loop-instance request-header bookkeeping for reconstructability. The - * comparison baseline is the header folded from the session log, so a fresh - * loop instance needs no special resume or fork state. + * comparison baseline is folded from the session log; a fresh instance anchors + * it with an initial/resume snapshot and later logs full changed snapshots. + * * @module dsh-agent-loop/request-log */ -import { diffHeader, headerEquals, applyHeaderDelta } from '@deepseek-ai/dsh-session' +import { headerEquals } from '@deepseek-ai/dsh-session' import type { EpochHeader, Session } from '@deepseek-ai/dsh-session' import type { Message } from '@deepseek-ai/dsh-llm' @@ -32,10 +33,8 @@ export function createTransmissionLog(): TransmissionLog { } /** - * Append whatever header event makes the log reproduce this request's header. - * The first request from an instance always records a full `initial` or `resume` - * snapshot. Later requests record nothing when unchanged, a round-tripping - * delta when expressible, or a full `fallback` snapshot otherwise. + * Append the full header snapshot owed by this request: initial/resume for the + * instance's first request, nothing when unchanged, or change otherwise. * * @param session - the session whose log explains the request. * @param state - this loop instance's bookkeeping (mutated on first log). @@ -52,12 +51,5 @@ export function recordRequestHeader(session: Session, state: TransmissionLog, he // eslint-disable-next-line @typescript-eslint/no-non-null-assertion const baseline = session.requestHeader()! if (headerEquals(baseline, header)) return - const delta = diffHeader(baseline, header) - /* v8 ignore next -- headerEquals false ⟹ diffHeader defined: both compare the same four parts */ - if (delta === undefined) return - if (headerEquals(applyHeaderDelta(baseline, delta), header)) { - session.append('request/header-delta', delta) - } else { - session.append('request/header', { header, reason: 'fallback' }) - } + session.append('request/header', { header, reason: 'change' }) } diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts index 663321d1ff..a8b7186223 100644 --- a/packages/core/agent-loop/src/tool-calls.ts +++ b/packages/core/agent-loop/src/tool-calls.ts @@ -1,8 +1,8 @@ /** * Schedules one assistant step's tool calls. Exclusive calls form barriers; * parallel calls use a bounded rolling pool and are reclassified before start. - * Dispatch may overlap, while policy, results, and context remain model-ordered. - * Abort stops replenishment and drains started calls. + * Dispatch may overlap, while policy, results, and result context remain + * model-ordered. Abort stops replenishment and drains started calls. * * Each started call records `tool/call`; `tool/result` commits in model order, * preserving derived history when audit events interleave with earlier results. @@ -31,8 +31,8 @@ interface Slot { /** * Schedule one assistant step's tool calls by their live concurrency mode. - * Started calls receive ordered results; abort drains them, discards their - * buffered context, and rethrows so the turn owns final error handling. + * Started calls receive ordered results. Abort drains them and rethrows after + * accepting their context into the batch FIFO owned by the caller. * * @param ctx - loop context that owns the tool registry. * @param agent - agent and session receiving the call lifecycle. @@ -41,7 +41,7 @@ interface Slot { * @param toolCalls - assistant calls in model order. * @param signal - abort signal shared by the step. * @param maxParallel - validated in-flight cap. - * @returns buffered contexts in model call order. + * @param acceptContext - accepts committed result context into the active batch. */ export async function executeToolCalls( ctx: Context, @@ -51,7 +51,8 @@ export async function executeToolCalls( toolCalls: ToolCallBlock[], signal: AbortSignal, maxParallel: number, -): Promise { + acceptContext: (context: HookContext) => void, +): Promise { const { session } = agent // Inputs are distinct because tools/execute wrappers may replace `exec.signal`. @@ -66,7 +67,6 @@ export async function executeToolCalls( }, })) - const pendingContext: HookContext[] = [] let next = 0 while (next < planned.length) { // Commit before classifying again so registry changes affect unstarted calls. @@ -74,9 +74,8 @@ export async function executeToolCalls( const first = planned[next]! const mode = ctx.tools.executionMode(first.exec).kind const group = mode === 'parallel' ? planned.slice(next) : [first] - next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, pendingContext) + next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, acceptContext) } - return pendingContext } /** Parse model arguments, preserving invalid JSON as text and mapping empty input to `{}`. */ @@ -92,8 +91,8 @@ function parseArguments(raw: string): unknown { * Run one exclusive barrier or parallel pool. Later calls are reclassified * before start; an exclusive reclassification waits for the current pool to * drain and remains for the caller's next barrier. Results and contexts commit - * in model order. Abort stops starts, drains and commits started calls, discards - * their contexts, and throws. + * in model order. Abort stops starts, drains and commits started calls, accepts + * their contexts into the owning batch, and throws. */ async function runGroup( ctx: Context, @@ -104,7 +103,7 @@ async function runGroup( mode: ToolExecutionMode['kind'], signal: AbortSignal, maxParallel: number, - pendingContext: HookContext[], + acceptContext: (context: HookContext) => void, ): Promise { /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted')) @@ -127,7 +126,7 @@ async function runGroup( : ctx.tools[TOOL_REGISTRY_SCHEDULER].finish(slot.exec, slot.result) // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!) - pendingContext.push(...result.additionalContexts ?? []) + for (const context of result.additionalContexts ?? []) acceptContext(context) committed++ } } @@ -189,7 +188,7 @@ async function runGroup( } if (aborted) { - // Started calls are committed; their context is discarded with the aborted step. + // Started calls and accepted context settle before the turn records the abort. /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */ throw new Error(String(signal.reason ?? 'aborted')) } diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index 41ec28d0eb..12460039b1 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts @@ -3,12 +3,12 @@ import { Context } from 'cordis' import LlmService, { CallId, ContentBlock, MessageSource, StreamChunk } from '@deepseek-ai/dsh-llm' import SessionStore, { Session, SessionEvent, SessionId, TurnEndReason } from '@deepseek-ai/dsh-session' import SystemPrompt from '@deepseek-ai/dsh-system-prompt' -import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools' +import ToolRegistry, { defineTool, type PostToolDecision } from '@deepseek-ai/dsh-tools' import AgentRegistry, { AgentId, type ContinuationDecision } from '@deepseek-ai/dsh-agent' import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS, ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' import { prepareReactLoopAgent } from '../src/agent.ts' import * as Invariants from '@deepseek-ai/dsh-invariants' -import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts' +import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts' /** Regression tests for agent-loop boundary, identity, and lifecycle contracts. */ @@ -132,6 +132,73 @@ describe('session log records what agent/step-result actually produced', () => { }) }) +describe('successful provider completion survives agent/step-result failure', () => { + async function expectContentlessCompletionAnchor( + response: StreamChunk[], + id: string, + providerText: string, + ): Promise { + const adapter = new MockAdapter([response]) + const ctx = await harness(adapter) + await ctx.plugin(Invariants) + const agent = ctx.agentLoop.create(AgentId(id), { provider: 'mock', model: 'mock' }) + const failure = new Error(`${id} result processing failed`) + const reported: Error[] = [] + + ctx.on('agent/step-result', async () => { + throw failure + }) + ctx.on('agent/error', (subject, _turn, _step, error) => { + if (subject === agent) reported.push(error) + }) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + const events = [...agent.session.events] + const chunks = events.filter(event => event.type === 'assistant/chunk') + const completions = events.filter(event => event.type === 'assistant/message') + expect(completions).toHaveLength(1) + expect(completions[0]?.type === 'assistant/message' && completions[0].data).toEqual({ + turn: 1, + step: 1, + content: [], + provenance: { provider: 'mock', model: 'mock' }, + usage: { inputTokens: 10, outputTokens: providerText.length }, + }) + expect(completions[0]?.sourceEventSeqs).toEqual(chunks.map(event => event.seq)) + expect(agent.session.deriveMessages()).toEqual([ + { role: 'user', content: [{ type: 'text', text: 'go' }] }, + ]) + expect(reported).toHaveLength(1) + expect(reported[0]).toBe(failure) + const turnEnd = events.findLast(event => event.type === 'turn/end') + expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ + kind: 'error', + step: 1, + message: failure.message, + }) + } + + it('records one content-less anchor when ordinary stop result processing rejects', async () => { + const providerText = 'ordinary provider output' + await expectContentlessCompletionAnchor( + textResponse(providerText), + 'a-step-result-stop-failure', + providerText, + ) + }) + + it('records one content-less anchor when max-token result processing rejects', async () => { + const providerText = 'truncated provider output' + await expectContentlessCompletionAnchor( + maxTokensResponse(providerText), + 'a-step-result-max-token-failure', + providerText, + ) + }) +}) + describe('abort during tool execution ends the turn', () => { it('aborting the in-flight step inside a tool prevents both remaining tools and the next model step', async () => { const adapter = new MockAdapter([ @@ -182,6 +249,190 @@ describe('abort during tool execution ends the turn', () => { expect(adapter.requests).toHaveLength(1) // no follow-up model call expect(reasons).toEqual([{ kind: 'aborted', reason: 'user interrupt' }]) }) + + it('records context accepted before a tool-step abort in the same turn', async () => { + const adapter = new MockAdapter([toolCallResponse('c1', 'aborter', {})]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-abort-injection'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + agent.inject([{ type: 'text', text: 'accepted before abort' }], { source: { kind: 'plugin', plugin: 'test' } }) + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.on('tools/post-execute', async (): Promise => ({ + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted result context after abort' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + })) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + const events = [...agent.session.events] + expect(events + .filter(event => event.type === 'tool/result' || event.type === 'context/message' + || event.type === 'step/end' || event.type === 'turn/end') + .map(event => event.type)) + .toEqual(['tool/result', 'context/message', 'context/message', 'step/end', 'turn/end']) + expect(events + .filter(event => event.type === 'context/message') + .map(event => event.data.content)) + .toEqual([ + [{ type: 'text', text: 'accepted before abort' }], + [{ type: 'text', text: 'accepted result context after abort' }], + ]) + }) + + it('records post-tool context when a later call aborts the batch', async () => { + const adapter = new MockAdapter([[ + { type: 'block-start', index: 0, blockType: 'tool-call' }, + { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'first', arguments: '{}' } }, + { type: 'block-start', index: 1, blockType: 'tool-call' }, + { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'aborter', arguments: '{}' } }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ] satisfies StreamChunk[]]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-later-abort-context'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'first', + description: '', + parameters: {}, + async execute() { + return [{ type: 'text', text: 'first done' }] + }, + })) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'aborted' }] + }, + })) + ctx.on('tools/post-execute', async (exec, _result, next): Promise => { + if (exec.callId !== CallId('c1')) return next() + return { + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted after first result' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + } + }) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + const events = [...agent.session.events] + expect(events + .filter(event => event.type === 'tool/result' || event.type === 'context/message' + || event.type === 'step/end' || event.type === 'turn/end') + .map(event => event.type)) + .toEqual(['tool/result', 'tool/result', 'context/message', 'step/end', 'turn/end']) + expect(events.find(event => event.type === 'context/message')?.data.content) + .toEqual([{ type: 'text', text: 'accepted after first result' }]) + }) + + it('drains deferred context before disposal reaches quiescence', async () => { + const adapter = new MockAdapter([toolCallResponse('c1', 'waiter', {})]) + const ctx = await harness(adapter) + const started = Promise.withResolvers() + let agent!: ReactLoopAgent + const fiber = await ctx.plugin(Object.assign((inner: Context) => { + agent = inner.agentLoop.create(AgentId('a-dispose-injection'), { provider: 'mock', model: 'mock' }) + }, { inject: ['agentLoop'] })) + ctx.tools.register(defineTool({ + name: 'waiter', + description: '', + parameters: {}, + async execute(_args, exec) { + agent.inject([{ type: 'text', text: 'accepted before disposal' }], { source: { kind: 'plugin', plugin: 'test' } }) + started.resolve(undefined) + const signal = exec.signal + if (!signal) throw new Error('tool execution signal is missing') + await new Promise((resolve) => { + if (signal.aborted) resolve() + else signal.addEventListener('abort', () => { resolve() }, { once: true }) + }) + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.on('tools/post-execute', async (): Promise => ({ + kind: 'accept', + additionalContexts: [{ + content: [{ type: 'text', text: 'accepted result context during disposal' }], + source: { kind: 'plugin', plugin: 'test' }, + }], + })) + + send(agent, 'go') + await started.promise + await fiber.dispose() + + expect(agent.session.events + .filter(event => event.type === 'context/message') + .map(event => event.data.content)) + .toEqual([ + [{ type: 'text', text: 'accepted before disposal' }], + [{ type: 'text', text: 'accepted result context during disposal' }], + ]) + expect(agent.session.events.find(event => event.type === 'turn/end')?.data.reason) + .toEqual({ kind: 'disposed' }) + }) + + it('limits injection deferral to the current tool batch', async () => { + const adapter = new MockAdapter([ + [ + { type: 'block-start', index: 0, blockType: 'tool-call' }, + { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('c1'), name: 'aborter', arguments: '{}' } }, + { type: 'block-start', index: 1, blockType: 'tool-call' }, + { type: 'block-end', index: 1, block: { type: 'tool-call', id: CallId('c2'), name: 'second', arguments: '{}' } }, + { type: 'finish', reason: { kind: 'tool-calls' } }, + ] satisfies StreamChunk[], + textResponse('later turn'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('a-historical-tool-pair'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'aborter', + description: '', + parameters: {}, + async execute() { + ;(agent as unknown as { currentAbort?: AbortController }).currentAbort?.abort('user interrupt') + return [{ type: 'text', text: 'done' }] + }, + })) + ctx.tools.register(defineTool({ + name: 'second', + description: '', + parameters: {}, + async execute() { + return [{ type: 'text', text: 'must not run' }] + }, + })) + + send(agent, 'leave an unmatched historical call') + await waitForIdle(ctx, agent) + ctx.on('agent/pre-step', (subject, turn) => { + if (subject === agent && turn === 2) { + agent.inject([{ type: 'text', text: 'new turn context' }], { source: { kind: 'plugin', plugin: 'test' } }) + } + }) + send(agent, 'start a text-only turn') + await waitForIdle(ctx, agent) + + expect(agent.session.events.find(event => event.type === 'context/message')?.data.content) + .toEqual([{ type: 'text', text: 'new turn context' }]) + expect(JSON.stringify(adapter.requests[1]?.messages)).toContain('new turn context') + }) }) describe('steering from late extension points is never stranded', () => { @@ -1118,9 +1369,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) @@ -1137,7 +1389,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') }) diff --git a/packages/core/agent-loop/tests/interception.spec.ts b/packages/core/agent-loop/tests/interception.spec.ts index 799de3e517..9932d9ca25 100644 --- a/packages/core/agent-loop/tests/interception.spec.ts +++ b/packages/core/agent-loop/tests/interception.spec.ts @@ -375,8 +375,8 @@ describe('agent/session-prefix', () => { expect(request.messages[0]).toEqual(reminder) } // The anchoring snapshot is the prefix's durable record — and the ONLY - // header event: reuse means no request/header-delta ever. - const headerEvents = events(agent).filter(e => e.type === 'request/header' || e.type === 'request/header-delta') + // header event: reuse means no changed snapshot ever. + const headerEvents = events(agent).filter(e => e.type === 'request/header') expect(headerEvents).toHaveLength(1) expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.header.messagePrefix).toEqual([reminder]) // Never session history: the derivation starts at the real user prompt. @@ -492,7 +492,7 @@ describe('agent/session-prefix', () => { // cached prefix is a deep-frozen clone, so step 2's request is unchanged. held.content = [{ type: 'text', text: 'v2' }] expect(adapter.requests[1]!.messages[0]).toEqual({ role: 'user', content: [{ type: 'text', text: 'v1' }] }) - expect(events(agent).filter(e => e.type === 'request/header-delta')).toHaveLength(0) + expect(events(agent).filter(e => e.type === 'request/header')).toHaveLength(1) }) }) diff --git a/packages/core/agent-loop/tests/loop.spec.ts b/packages/core/agent-loop/tests/loop.spec.ts index b33f9ab1f8..6f4f15ba0c 100644 --- a/packages/core/agent-loop/tests/loop.spec.ts +++ b/packages/core/agent-loop/tests/loop.spec.ts @@ -410,22 +410,30 @@ describe('agent loop', () => { expect(requestText).not.toContain(' { + it('defers inject() during tool execution until after the tool result', async () => { const adapter = new MockAdapter([ toolCallResponse('c1', 'noticer', {}, 'calling'), textResponse('done'), ]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) - // A tool that injects mid-execution: at this point the agent is running, so - // inject must append the context/message into the ALREADY-open turn rather - // than wrap it in its own one-shot turn. + let visibleDuringTool = false + const meta = { kind: 'deferred-test', version: 1 } ctx.tools.register(defineTool({ name: 'noticer', description: 'injects a notice', parameters: {}, async execute() { - agent.inject([{ type: 'text', text: 'mid-turn notice' }], { source: { kind: 'plugin', plugin: 'x' } }) + await Promise.resolve() + const first = { type: 'text' as const, text: 'mid-turn notice' } + agent.inject([first], { + source: { kind: 'plugin', plugin: 'x' }, + envelope: 'raw', + meta, + }) + first.text = 'mutated after inject' + agent.inject([{ type: 'text', text: 'second notice' }], { source: { kind: 'plugin', plugin: 'x' } }) + visibleDuringTool = agent.session.events.some(e => e.type === 'context/message') return [{ type: 'text', text: 'ok' }] }, })) @@ -433,13 +441,67 @@ describe('agent loop', () => { send(agent, 'go') await waitForIdle(ctx, agent) - // Exactly ONE turn ran (no synthetic injection turn), and the mid-turn - // context/message sits inside it. + expect(visibleDuringTool).toBe(false) + + // The injection stays in the open turn, but its user-role context cannot + // split the assistant tool call from the provider's tool-result message. const turnStarts = agent.session.events.filter(e => e.type === 'turn/start') expect(turnStarts).toHaveLength(1) const ts0 = turnStarts[0]! expect(ts0.type === 'turn/start' && ts0.data.trigger.kind).toBe('message') - expect(agent.session.events.some(e => e.type === 'context/message')).toBe(true) + const result = agent.session.events.find(e => e.type === 'tool/result')! + const contexts = agent.session.events.filter(e => e.type === 'context/message') + expect(contexts).toHaveLength(2) + expect(result.seq).toBeLessThan(contexts[0]!.seq) + expect(contexts[0]?.type === 'context/message' && contexts[0].data).toMatchObject({ + envelope: 'raw', + meta, + }) + expect(contexts.flatMap(event => event.type === 'context/message' ? event.data.content : [])) + .toEqual([ + { type: 'text', text: 'mid-turn notice' }, + { type: 'text', text: 'second notice' }, + ]) + + const secondRequest = adapter.requests[1]!.messages + const resultIndex = secondRequest.findIndex(message => + message.content.some(block => block.type === 'tool-result')) + const contextIndexes = secondRequest.flatMap((message, index) => + message.content.some(block => block.type === 'text' + && (block.text.includes('mid-turn notice') || block.text.includes('second notice'))) + ? [index] + : []) + expect(resultIndex).toBeGreaterThanOrEqual(0) + expect(contextIndexes).toHaveLength(2) + expect(contextIndexes.every(index => index > resultIndex)).toBe(true) + }) + + it('rejects non-JSON context before it enters the active tool-batch FIFO', async () => { + const adapter = new MockAdapter([ + toolCallResponse('c1', 'invalid-injector', {}, 'calling'), + textResponse('done'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('invalid-context'), { provider: 'mock', model: 'mock' }) + ctx.tools.register(defineTool({ + name: 'invalid-injector', + description: 'attempts an invalid context injection', + parameters: {}, + async execute() { + expect(() => { + agent.inject([{ type: 'text', text: 'invalid' }], { + source: { kind: 'plugin', plugin: 'test' }, + meta: { bigint: 1n } as never, + }) + }).toThrow('agent context must be losslessly JSON-serializable') + return [{ type: 'text', text: 'rejected invalid context' }] + }, + })) + + send(agent, 'go') + await waitForIdle(ctx, agent) + + expect(agent.session.events.some(event => event.type === 'context/message')).toBe(false) }) it('agent/turn-continuation can force-continue (/loop pattern) and force-stop', async () => { @@ -743,10 +805,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' }, @@ -770,14 +831,20 @@ 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: [], + provenance: { provider: 'mock', model: 'mock' }, + }) + 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'), { provider: 'mock', model: 'mock' }) @@ -789,7 +856,14 @@ 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: [], + provenance: { provider: 'mock', model: 'mock' }, + }) + expect(assistant.sourceEventSeqs?.length).toBe(1) expect(agent.session.deriveMessages()).toEqual([{ role: 'user', content: [{ type: 'text', text: 'go' }] }]) }) diff --git a/packages/core/agent-loop/tests/request-log.spec.ts b/packages/core/agent-loop/tests/request-log.spec.ts index 912a13892c..4a3cfe37a4 100644 --- a/packages/core/agent-loop/tests/request-log.spec.ts +++ b/packages/core/agent-loop/tests/request-log.spec.ts @@ -1,9 +1,8 @@ /** - * recordRequestHeader unit tests: exactly one of four things per request — + * recordRequestHeader unit tests: exactly one of three things per request — * an 'initial' snapshot (log has no header yet), a 'resume' snapshot (fresh - * loop instance over a log that has one), nothing (header unchanged), a - * round-tripping delta, or a 'fallback' snapshot when the delta encoding - * cannot express the change (pure tool reordering). + * loop instance over a log that has one), nothing (header unchanged), or a + * full 'change' snapshot. */ import { describe, expect, it } from 'vitest' @@ -23,7 +22,7 @@ function openSession(id: string): Session { } function headerEvents(session: Session): SessionEvent[] { - return session.events.filter(e => e.type === 'request/header' || e.type === 'request/header-delta') + return session.events.filter(e => e.type === 'request/header') } describe('recordRequestHeader', () => { @@ -53,8 +52,8 @@ describe('recordRequestHeader', () => { expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('resume') }) - it('logs a round-tripping delta for a mid-run change, and the fold reproduces the header', () => { - const session = openSession('rl-delta') + it("logs a full 'change' snapshot for a mid-run change, and the fold reproduces the header", () => { + const session = openSession('rl-change') const state = createTransmissionLog() const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] }) recordRequestHeader(session, state, first) @@ -63,12 +62,12 @@ describe('recordRequestHeader', () => { recordRequestHeader(session, state, second) const events = headerEvents(session) expect(events).toHaveLength(2) - expect(events[1]?.type).toBe('request/header-delta') + expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('change') expect(session.requestHeader()).toEqual(second) }) - it("records a change the delta cannot express (pure reordering) as a 'fallback' snapshot", () => { - const session = openSession('rl-fallback') + it("records a pure tool reordering as a 'change' snapshot", () => { + const session = openSession('rl-reorder') const state = createTransmissionLog() const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, tools: [tool('a'), tool('b')] }) recordRequestHeader(session, state, first) @@ -77,9 +76,7 @@ describe('recordRequestHeader', () => { recordRequestHeader(session, state, reordered) const events = headerEvents(session) expect(events).toHaveLength(2) - expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('fallback') - // The fold still lands on the exact header — deltas are an encoding - // optimization, never a correctness dependency. + expect(events[1]?.type === 'request/header' && events[1].data.reason).toBe('change') expect(session.requestHeader()).toEqual(reordered) }) }) diff --git a/packages/core/agent-loop/tests/request-reconstruction.spec.ts b/packages/core/agent-loop/tests/request-reconstruction.spec.ts index 55e5c2fd1d..ab2c18c99d 100644 --- a/packages/core/agent-loop/tests/request-reconstruction.spec.ts +++ b/packages/core/agent-loop/tests/request-reconstruction.spec.ts @@ -1,9 +1,8 @@ /** * Loop-level reconstructability: every request the loop sends is a pure function of the - * session log — messages are the derivation at the step/start boundary, the header is the fold - * of request/header* events — and every request is an append-extension of its predecessor - * unless a logged event (compaction replace, header change) explains the difference. Mock-adapter - * requests are the observable, and the final offline rebuild states the full contract end to end. + * session log — messages derive at the step/start boundary and the header is the latest + * request/header snapshot. Each request extends its predecessor unless a logged compaction + * replacement or header change explains the difference. */ import { describe, expect, it } from 'vitest' @@ -85,7 +84,7 @@ describe('request stability across the loop', () => { expect(Object.isFrozen(request.messages)).toBe(true) } // One anchoring header snapshot; no further header events (nothing changed). - const headerEvents = agent.session.events.filter(e => e.type === 'request/header' || e.type === 'request/header-delta') + const headerEvents = agent.session.events.filter(e => e.type === 'request/header') expect(headerEvents).toHaveLength(1) expect(headerEvents[0]?.type === 'request/header' && headerEvents[0].data.reason).toBe('initial') }) @@ -122,8 +121,8 @@ describe('request stability across the loop', () => { content: [{ type: 'text', text: '[summary of turn 1]' }], source: { kind: 'plugin', plugin: 'test-compact' }, }, { - surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, - sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq], + surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, + sourceEventSeqs: [nodes[0]!, nodes[1]!], }) }) @@ -137,7 +136,7 @@ describe('request stability across the loop', () => { expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1) }) - it('a real system-prompt change is a logged header delta; a stable prompt logs nothing', async () => { + it('a real system-prompt change is a full changed-header snapshot; a stable prompt logs nothing', async () => { const adapter = new MockAdapter([textResponse('one'), textResponse('two'), textResponse('three')]) const ctx = await harness(adapter) const agent = ctx.agentLoop.create(AgentId('a1'), { provider: 'mock', model: 'mock' }) @@ -147,14 +146,15 @@ describe('request stability across the loop', () => { send(agent, 'second') await waitForIdle(ctx, agent) // Identical assembly re-rendered per step is NOT a change. - expect(agent.session.events.filter(e => e.type === 'request/header-delta')).toHaveLength(0) + expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1) ctx.systemPrompt.section({ name: 'extra', order: 2, text: 'new guidance' }) send(agent, 'third') await waitForIdle(ctx, agent) - const deltas = agent.session.events.filter(e => e.type === 'request/header-delta') - expect(deltas).toHaveLength(1) + const snapshots = agent.session.events.filter(e => e.type === 'request/header') + expect(snapshots).toHaveLength(2) + expect(snapshots[1]?.data.reason).toBe('change') expect(adapter.requests[2]!.system).toContain('new guidance') // History is preserved across the change — only the header moved. expect(adapter.requests[2]!.messages.length).toBeGreaterThan(adapter.requests[1]!.messages.length) @@ -260,9 +260,9 @@ describe('request stability across the loop', () => { send(agent, 'second') await waitForIdle(ctx, agent) - // No delta was logged (nothing really changed), and the session's own + // No changed snapshot was logged (nothing really changed), and the session's own // fold is immutable state. - expect(agent.session.events.filter(e => e.type === 'request/header-delta')).toHaveLength(0) + expect(agent.session.events.filter(e => e.type === 'request/header')).toHaveLength(1) expect(Object.isFrozen(agent.session.requestHeader())).toBe(true) expect(adapter.requests[1]!.temperature).toBeUndefined() }) @@ -296,7 +296,7 @@ describe('request stability across the loop', () => { const rebuilt = new Session(SessionId(`rebuild-${index}`), structuredClone(events.slice(0, stepStart.seq))) expect(structuredClone(request.messages)).toEqual(rebuilt.deriveMessages()) - // Header: the fold of request/header* events up to this step's dispatch + // Header: the latest request/header snapshot up to this step's dispatch // (its header event sits between step/start and the first chunk). const firstChunk = events.find(e => e.type === 'assistant/chunk' && e.seq > stepStart.seq)! const header = foldRequestHeader(events.slice(0, firstChunk.seq))! diff --git a/packages/core/agent-loop/tests/tool-calls.spec.ts b/packages/core/agent-loop/tests/tool-calls.spec.ts index 333975e2a6..8feb20bd96 100644 --- a/packages/core/agent-loop/tests/tool-calls.spec.ts +++ b/packages/core/agent-loop/tests/tool-calls.spec.ts @@ -502,7 +502,7 @@ describe('tool-call scheduler: abort handling', () => { .toEqual([CallId('c1')]) }) - it('stops replenishing after abort, commits started results, and drops buffered additional contexts', async () => { + it('stops replenishing after abort, commits started results, and drains accepted additional contexts', async () => { const adapter = new MockAdapter([ multiCall([1, 2, 3, 4].map(n => ({ id: `c${n}`, name: 'p', args: { id: String(n) } }))), textResponse('should never be requested'), @@ -528,7 +528,12 @@ describe('tool-call scheduler: abort handling', () => { .toEqual([CallId('c1'), CallId('c2')]) expect(events(agent).filter(e => e.type === 'tool/result').map(e => e.data.callId)) .toEqual([CallId('c1'), CallId('c2')]) - expect(events(agent).filter(e => e.type === 'context/message')).toEqual([]) + const settled = events(agent).filter(e => e.type === 'tool/result' || e.type === 'context/message') + expect(settled.map(e => e.type)) + .toEqual(['tool/result', 'tool/result', 'context/message', 'context/message']) + expect(settled.filter(e => e.type === 'context/message') + .map(e => (e.data.content[0] as { text: string }).text)) + .toEqual(['ctx-c1', 'ctx-c2']) }) it('does not run an exclusive barrier after a parallel group aborts', async () => { diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md index ca031995ef..1255731484 100644 --- a/packages/core/agent/README.md +++ b/packages/core/agent/README.md @@ -43,7 +43,7 @@ The handle every plugin programs against: - `agent.send(content, options?)` — queue a message; starts a turn when idle. Content and resolved source become one detached, deeply frozen lossless-JSON record before `agent/queued` and enqueue; invalid data throws synchronously, and caller or notification-listener in-place mutation cannot change the log or model input (`agent/prompt-submit` still rewrites by returning replacement content). - `agent.steer(content, options?)` — steer a running turn (inject between steps); uses the same owned acceptance boundary and behaves like `send` when idle -- `agent.inject(content, options?)` — inject in-session context (`context/message` event); the next request sees it. `options.envelope` defaults to the canonical `` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. Does not run the model. While a turn is open it joins that turn; while idle it is wrapped in a one-shot `injection` turn so every event stays turn-enclosed ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)) +- `agent.inject(content, options?)` — accept detached in-session context without running the model; the next request sees its `context/message`. `options.envelope` defaults to the canonical `` framing and may be `'raw'` when the caller owns a complete familiar frame; `options.meta` persists opaque JSON state without rendering it. While a turn is open it joins that turn, deferring FIFO while the current tool batch executes and draining before turn close if execution is interrupted; while idle it is wrapped in a one-shot `injection` turn and durability checkpoint ([the turn-enclosure invariant](../../../docs/rfc/implemented/architecture/2026-06-15-turn-enclosure-invariant.md)). - `agent.cancel(reason?)` — cancel ALL pending work: clears the queued + steering FIFOs, aborts the in-flight step, and drops a turn about to start (the pre-step window) so a queued-but-not-started prompt never runs. A UI/ACP `session/cancel` maps to this. The single public stop primitive. Idle with nothing pending → a safe no-op. - `agent.whenIdle()` — resolve once the agent reaches quiescence after settling out of `running` (idle → immediately; disposed → awaits the loop exit). A non-owner's quiescence-observation hook: it observes the work settling WITHOUT tearing the agent down. Teardown is separate — a lifecycle owner stops and unregisters via `AgentHandle.dispose()`, which awaits the loop exit directly. - `agent.session`, `agent.status`, `agent.options`, `agent.id` diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index 5f411f4b9a..5c709c828b 100644 --- a/packages/core/agent/src/types.ts +++ b/packages/core/agent/src/types.ts @@ -117,10 +117,11 @@ export interface Agent { steer(content: ContentBlock[], options?: SendOptions): void /** - * Append model-facing context without running the model. Idle injection uses - * a one-shot turn and durability checkpoint, while injection during an open - * turn joins it at the current log position. Disposal awaits idle checkpoints; - * flush failures are reported through `agent/error`, not thrown to the caller. + * Append detached model-facing context without running the model. An open-turn + * injection joins at the current log position unless the current tool batch is + * executing; then it waits FIFO until that batch settles and drains before turn + * close even when interrupted. Idle injection uses a one-shot turn and durability + * checkpoint. Disposal awaits idle checkpoints; flush failures report through `agent/error`. */ inject(content: ContentBlock[], options?: InjectOptions): void diff --git a/packages/core/session/README.md b/packages/core/session/README.md index 219d75df7e..46b6ecb703 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -1,6 +1,6 @@ # dsh-session -Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (a linked list of message-producing events) is maintained on top of the raw log for efficient derivation and compaction. +Event-sourced session log and in-memory store. A `Session` is the append-only source of truth for an agent's whole interaction history — the LLM message history is *derived* from it. A **surface** layer (an ordered projection of message-producing events) is maintained on top of the raw log for efficient derivation and compaction. ## Service: `SessionStore` (ctx key: `sessions`) @@ -33,7 +33,7 @@ The store pairs announced creation with disposal, publishes post-commit append n Plain class (not a Cordis Service). Create via `ctx.sessions.create()`. - `session.append(type, data, opts?)` snapshots and freezes durable data and surface metadata, validates marker shape, provenance, and complete replacement coverage, commits synchronously, then notifies observers with independent failure containment. Reentrant attached-session appends reject, and runtime checks cover widened unions and loaded logs. -- `session.deriveMessages()` incrementally projects each new surface node once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback. +- `session.deriveMessages()` incrementally projects each new surface entry once and returns a fresh array over shared frozen messages. Assistant projections preserve provider/model provenance and adapter-private replay state. A surface rewrite rebuilds the projection; there is no raw-log fallback. - `session.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and invariants. - `session.surface` lazily folds only new `surfaceOp` markers; `replaceGeneration` changes on every rewrite. - `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen. @@ -46,15 +46,14 @@ Durable values need one accepted representation, not a check followed by a secon ### Surface types -- `SurfaceOp` — how a surface node entered the linked list: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace nodes from `start` through `end` inclusive — both must be valid surface node seqs; `start === end` replaces a single node). Used by compaction to shadow old nodes without deleting them. +- `SurfaceOp` — how an event entered the ordered surface: `'append'` (normal tail append) or `{ op: 'replace', start, end }` (replace entries from `start` through `end` inclusive — both must be valid surface seqs; `start === end` replaces one entry). Used by compaction to shadow old events without deleting them. - `SurfaceIntent` — `{ surfaceOp: SurfaceOp; sourceEventSeqs?: number[] }`, the required third parameter to `session.append()` for surface-eligible types. -- `SurfaceNode` — `{ seq: number; prev: number | null; next: number | null }`, one node in the surface linked list. -- `foldSurface(events)` — replay the one canonical surface contract into detached current nodes and actual replacement ranges. The same pass rejects non-contiguous event seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface node; `SurfaceManager` shares the atomic transition while retaining its incremental cache. -- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully-formed surface node (type is surface-eligible AND `surfaceOp` present); the second is the type-only check (is this one of the five `SurfaceEventType` values?), used to detect a surface-eligible event MISSING its marker — e.g. when validating a seed/load log. +- `foldSurface(events)` — replay the canonical surface contract into detached current event sequences and actual replacement ranges. The same pass rejects non-contiguous seqs, misplaced or malformed metadata, empty or duplicate provenance, non-earlier sources, invalid positional ranges, and replacements that fail to cite every shadowed surface entry; `SurfaceManager` shares the atomic transition while retaining only its incremental sequence cache. +- `isSurfaceEvent(event)` / `isSurfaceEligibleType(type)` — the first narrows a `SessionEvent` to a fully formed surface event; the second detects a surface-eligible event missing its marker when validating a seed or loaded log. ### Request-header reconstruction (`request-header.ts`) -`request/header` and `request/header-delta` make the non-history request envelope reconstructable from the log. `foldRequestHeader()` reconstructs the active header, `diffHeader()` encodes changes, and `applyHeaderDelta()` replays them; unsupported deltas fall back to a full snapshot. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md). +`request/header` records a full canonical snapshot of the non-history request envelope with reason `initial`, `resume`, or `change`. `foldRequestHeader()` selects the latest snapshot; legacy delta events and the removed `fallback` reason are rejected. `messagePrefix` remains separate from derived history. See the [reconstructable-requests RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md). `context/message` defaults to the canonical tagged context projection. A producer may set `envelope: 'raw'` when its `content` already contains the complete model-facing frame, and may attach JSON `meta` for replayable plugin state; metadata remains durable but is excluded from `deriveMessages()`. @@ -68,7 +67,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 entries behind a compaction replacement entry). 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`) @@ -79,15 +78,15 @@ Every `SessionEvent` carries two optional top-level fields (structural metadata) - Persistence plugins: subscribe to `session/event` (write-behind) and drain on `session/flush` (awaited) and fiber dispose. A durable backend reads the log and reloads it into a live session; the metadata seam (`SessionHeader`, `session.header`) is what such a backend stores beside the log. - Replay/fork: `create(id, { seed })` validates and freezes a contiguous current-format log and rebuilds its surface; request headers require provider/model and assistant messages require provider/model provenance. `fork(source, boundary?, childSessionId?)` selects a completed-turn prefix and records lineage. -- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface nodes behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns surface membership, positional links, and `replaceGeneration`. +- Compaction: the `dsh-compact-basic` plugin appends a `user/message` with `surfaceOp: { op: 'replace', start, end }` to shadow old surface entries behind a summary checkpoint. Tool-pairing boundary policy and its cache belong to the [`dsh-compact` seam](../../compact/compact/README.md), while this package owns ordered surface membership and `replaceGeneration`. ## Model Experience ### Derived message history -**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface nodes verbatim. A `context/message` is a user-role message containing exactly ``, its content blocks, and ``; `steering/message` uses the identical `` / `` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message. +**What the model sees**: The model receives projections of `user/message`, `assistant/message`, and `tool/result` surface entries verbatim. A `context/message` is a user-role message containing exactly ``, its content blocks, and ``; `steering/message` uses the identical `` / `` wrapper. Tool calls live inside assistant messages. Chunks, boundaries, usage, hook records, todo records, and other log-only events add no message. -**Token effect**: Appended surface nodes are resent on later steps. A `replace` surface operation removes the shadowed nodes from future inputs without deleting their raw log records. +**Token effect**: Appended surface entries are resent on later steps. A `replace` surface operation removes the shadowed entries from future inputs without deleting their raw log records. ### Crash-repair result diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index 9ba4aa60b2..985d475101 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -22,9 +22,9 @@ export * from './types.ts' export { isJsonValue, snapshotJsonValue } from './json.ts' export type { JsonValue } from './json.ts' export { interruptedTurnClosers } from './repair.ts' -export type { SurfaceFoldReplacement, SurfaceFoldResult, SurfaceNode } from './surface.ts' +export type { SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts' export { foldSurface, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts' -export { applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from './request-header.ts' +export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts' declare module 'cordis' { interface Context { @@ -133,6 +133,9 @@ function snapshotSessionHeader(id: SessionId, source?: SessionHeader): SessionHe /** Validate the fixed event envelope after one-pass JSON materialization. */ function assertSessionEventEnvelope(value: Record, index: number): asserts value is SessionEvent { const event = value + if (event['type'] === 'request/header-delta') { + throw new Error(`seed event at index ${index} uses unsupported legacy request/header-delta format`) + } const allowed = new Set(['type', 'seq', 'time', 'data', 'surfaceOp', 'sourceEventSeqs']) if (Object.keys(event).some(key => !allowed.has(key)) || !Object.hasOwn(event, 'type') || typeof event['type'] !== 'string' @@ -156,9 +159,6 @@ function assertCurrentLlmShape(event: Record, index: number): v const config = typeof header === 'object' && header !== null ? (header as Record)['config'] : undefined if (!hasProviderModel(config)) throw new Error(`seed request/header at index ${index} lacks provider/model`) } - if (event['type'] === 'request/header-delta' && record['config'] !== undefined && !hasProviderModel(record['config'])) { - throw new Error(`seed request/header-delta at index ${index} lacks provider/model`) - } if (event['type'] === 'assistant/message' && !hasProviderModel(record['provenance'])) { throw new Error(`seed assistant/message at index ${index} lacks provider/model provenance`) } @@ -172,6 +172,18 @@ function hasProviderModel(value: unknown): boolean { && typeof pair['model'] === 'string' && pair['model'].length > 0 } +/** Reject request-header vocabulary removed with the legacy delta codec. */ +function assertSupportedRequestHeader(type: string, data: unknown, location: string): void { + if (type === 'request/header-delta') { + throw new Error(`${location} uses unsupported legacy request/header-delta format`) + } + if (type === 'request/header' + && data !== null && typeof data === 'object' && !Array.isArray(data) + && (data as Record)['reason'] === 'fallback') { + throw new Error(`${location} uses unsupported legacy request/header reason "fallback"`) + } +} + type SessionCallback = (...args: unknown[]) => unknown /** Resolve one listener snapshot, including Cordis's internal dispatch checks. */ @@ -243,7 +255,7 @@ export class Session { private readonly surfaceValidator = new SurfaceManager(this.log) /** - * Derived surface — a cached linked list of message-producing events. + * Derived surface — a cached order of message-producing event sequences. * Lazily rebuilt from `surfaceOp` markers in the log; processes only new * events (delta) on each access — the log is append-only, so prior events * never change. @@ -251,7 +263,7 @@ export class Session { */ private _surface: SurfaceManager | undefined - /** The surface linked list over this session's event log. */ + /** The ordered surface over this session's event log. */ get surface(): SurfaceManager { if (!this._surface) this._surface = new SurfaceManager(this.log) return this._surface @@ -284,6 +296,7 @@ export class Session { throw new Error(`seed event at index ${index} is not losslessly JSON-serializable`) } assertSessionEventEnvelope(snapshot, index) + assertSupportedRequestHeader(snapshot.type, snapshot.data, `seed event at index ${index}`) if (snapshot.seq !== index) { throw new Error(`seed event at index ${index} has seq ${snapshot.seq} (expected ${index}); seed must be contiguous from 0`) } @@ -331,7 +344,7 @@ export class Session { * @param type - The event type (key of {@link SessionEventMap}). * @param data - The event payload; must be JSON-serializable. * @param opts - Surface metadata: `surfaceOp` controls how the event enters - * the surface linked list; `sourceEventSeqs` records provenance (the seq + * the ordered surface; `sourceEventSeqs` records provenance (the seq * numbers of events this one derives from). REQUIRED for * {@link SurfaceEventType} events (every message-producing event must * declare how it joins the surface, the sole source of derived history) and @@ -368,6 +381,7 @@ export class Session { if (dataSnapshot === undefined) { throw new Error(`session event "${type}" carries non-JSON-serializable data`) } + assertSupportedRequestHeader(type, dataSnapshot, `session event "${type}"`) const surfaceMetadataSnapshot = snapshotJsonValue(surfaceMetadata) if (surfaceMetadataSnapshot === undefined) { throw new Error(`session event "${type}" carries non-JSON-serializable surface metadata`) @@ -439,8 +453,8 @@ export class Session { private derivedGeneration = 0 /** - * Derive the LLM message history by walking the session surface — the linked - * list of message-producing events maintained by `surfaceOp` markers. The + * Derive the LLM message history by walking the ordered sequences of + * message-producing events maintained by `surfaceOp` markers. The * surface is the single source of derived history: every message-producing * append records its `surfaceOp`, so a raw event with no marker (a chunk, a * turn boundary) is correctly absent, and a compaction `replace` deletes the @@ -464,11 +478,11 @@ export class Session { this.derivedNodes = 0 this.derivedGeneration = generation } - for (const node of nodes.slice(this.derivedNodes)) { - // Surface nodes are built from this.log — node.seq is always a valid + for (const seq of nodes.slice(this.derivedNodes)) { + // Surface sequences are built from this.log — seq is always a valid // index by construction. The non-null assertion expresses that invariant. // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - const msg = this.deriveEventMessage(this.log[node.seq]!) + const msg = this.deriveEventMessage(this.log[seq]!) // A surface node is one of the five message-producing types, but an // empty-content assistant/message (a max-tokens step that hosts only // usage) derives to null and must not enter the transcript. diff --git a/packages/core/session/src/request-header.ts b/packages/core/session/src/request-header.ts index dd7b2a758d..8dd61ee884 100644 --- a/packages/core/session/src/request-header.ts +++ b/packages/core/session/src/request-header.ts @@ -1,28 +1,20 @@ /** - * Request-header reconstruction utilities over `request/header` snapshots and - * `request/header-delta` events. Writers round-trip each proposed delta and use - * a full snapshot when the encoding cannot represent the change. + * Request-header reconstruction utilities over full `request/header` session + * events. Anyone holding a session log reconstructs the {@link EpochHeader} + * any request was built under by taking the latest canonical snapshot; the + * loop uses the same equality helper to avoid logging unchanged headers. + * * @module dsh-session/request-header */ import { callConfigEquals } from '@deepseek-ai/dsh-llm' -import type { LlmCallConfig, Message, ToolSchema } from '@deepseek-ai/dsh-llm' -import type { EpochHeader, SessionEvent, SystemDelta, ToolsDelta } from './types.ts' - -/** The `request/header-delta` payload shape: each present field amends the folded header. */ -type HeaderDelta = { - system?: SystemDelta - tools?: ToolsDelta - config?: LlmCallConfig - messagePrefix?: Message[] -} +import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm' +import type { EpochHeader, SessionEvent } from './types.ts' /** - * Normalize a header to canonical form: an empty system prompt, an empty - * tool list, and an empty session prefix become ABSENT fields, matching how - * requests are built (the request-build spreads skip empty values). Diff, - * fold, and comparison all operate on canonical headers, so "no system - * prompt" (and "no session prefix") has exactly one representation. + * Normalize a header to canonical form: an empty system prompt, an empty tool + * list, and an empty session prefix become absent fields, matching how requests + * are built. Logging, folding, and comparison use this one representation. * @param header - the header to normalize (not mutated). * @returns the canonical header. */ @@ -35,85 +27,22 @@ export function canonicalHeader(header: EpochHeader): EpochHeader { } } -/** Split a canonical (possibly absent) system prompt into lines; absence is zero lines. */ -function systemLines(system: string | undefined): string[] { - return system === undefined ? [] : system.split('\n') -} - -/** Join lines back into a canonical system value; zero lines is absence. */ -function joinSystem(lines: string[]): string | undefined { - return lines.length === 0 ? undefined : lines.join('\n') -} - -/** - * Compute the line-level {@link SystemDelta} between two canonical system - * prompts: trim the common prefix and (non-overlapping) common suffix, and - * carry the replacement lines between them. Deterministic and library-free; - * with nothing shared it degenerates to a full replacement. - */ -function diffSystem(prev: string | undefined, next: string | undefined): SystemDelta { - const a = systemLines(prev) - const b = systemLines(next) - let keepStart = 0 - while (keepStart < a.length && keepStart < b.length && a[keepStart] === b[keepStart]) keepStart += 1 - let keepEnd = 0 - while ( - keepEnd < a.length - keepStart && - keepEnd < b.length - keepStart && - a[a.length - 1 - keepEnd] === b[b.length - 1 - keepEnd] - ) keepEnd += 1 - return { keepStart, keepEnd, insert: b.slice(keepStart, b.length - keepEnd) } -} - -/** Apply a {@link SystemDelta} to a canonical system prompt. */ -function applySystem(prev: string | undefined, delta: SystemDelta): string | undefined { - const a = systemLines(prev) - return joinSystem([...a.slice(0, delta.keepStart), ...delta.insert, ...a.slice(a.length - delta.keepEnd)]) -} - -/** Canonical JSON equality for tool schemas — sound because schemas are - * JSON-serializable by construction and both sides come from the same - * assembly path, so key insertion order matches when the values do. */ +/** Canonical JSON equality for tool schemas assembled through the same path. */ function sameSchema(a: ToolSchema, b: ToolSchema): boolean { return JSON.stringify(a) === JSON.stringify(b) } -/** - * Compute the name-keyed {@link ToolsDelta} between two canonical tool lists. - * A pure reordering produces an empty delta — the writer's round-trip guard - * catches that case and records a snapshot instead. - */ -function diffTools(prev: readonly ToolSchema[], next: readonly ToolSchema[]): ToolsDelta { - const prevByName = new Map(prev.map(tool => [tool.name, tool])) - const nextNames = new Set(next.map(tool => tool.name)) - return { - added: next.filter(tool => !prevByName.has(tool.name)), - removed: prev.filter(tool => !nextNames.has(tool.name)).map(tool => tool.name), - changed: next.filter((tool) => { - const before = prevByName.get(tool.name) - return before !== undefined && !sameSchema(before, tool) - }), - } -} - -/** Apply a {@link ToolsDelta} to a canonical tool list: drop removed, replace changed in place, append added. */ -function applyTools(prev: readonly ToolSchema[], delta: ToolsDelta): ToolSchema[] { - const removed = new Set(delta.removed) - const changedByName = new Map(delta.changed.map(tool => [tool.name, tool])) - const kept = prev - .filter(tool => !removed.has(tool.name)) - .map(tool => changedByName.get(tool.name) ?? tool) - return [...kept, ...delta.added] +/** Canonical JSON equality over session-prefix arrays; absence equals empty. */ +function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean { + return JSON.stringify(a ?? []) === JSON.stringify(b ?? []) } /** - * Field-wise equality over canonical headers — the cheap comparison the writer's round-trip - * guard runs (`applyHeaderDelta(prev, delta)` must equal the intended header) and the loop - * runs to skip logging an unchanged header. - * + * Field-wise equality over canonical headers. Tool schemas compare in order; + * the session prefix compares as canonical JSON. * @param a - one canonical header. * @param b - the other. - * @returns whether config, system, tools (in order), and the session prefix all match. + * @returns whether config, system, tools, and session prefix all match. */ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean { if (!callConfigEquals(a.config, b.config) || a.system !== b.system) return false @@ -123,74 +52,19 @@ export function headerEquals(a: EpochHeader, b: EpochHeader): boolean { return at.length === bt.length && at.every((tool, i) => sameSchema(tool, bt[i] as ToolSchema)) } -/** Canonical JSON equality over session-prefix arrays; absence equals the empty array. */ -function sameMessages(a: readonly Message[] | undefined, b: readonly Message[] | undefined): boolean { - return JSON.stringify(a ?? []) === JSON.stringify(b ?? []) -} - /** - * Compute the `request/header-delta` payload between two canonical headers, or - * `undefined` when they are equal. The encoding cannot represent every change, - * including pure tool reordering, so callers must apply and compare the result - * before logging it and fall back to a full snapshot on mismatch. The session - * prefix is replaced whole; an empty array removes it. - * - * @param prev - the folded header the log currently implies. - * @param next - the header the next request will actually use. - * @returns the delta payload, or undefined when nothing changed. - */ -export function diffHeader(prev: EpochHeader, next: EpochHeader): HeaderDelta | undefined { - const delta: HeaderDelta = {} - if (prev.system !== next.system) delta.system = diffSystem(prev.system, next.system) - const prevTools = prev.tools ?? [] - const nextTools = next.tools ?? [] - if (JSON.stringify(prevTools) !== JSON.stringify(nextTools)) delta.tools = diffTools(prevTools, nextTools) - if (!callConfigEquals(prev.config, next.config)) delta.config = next.config - if (!sameMessages(prev.messagePrefix, next.messagePrefix)) delta.messagePrefix = next.messagePrefix ?? [] - return Object.keys(delta).length > 0 ? delta : undefined -} - -/** - * Apply a `request/header-delta` payload to a canonical header, producing the - * canonical header it encodes. Total for well-formed logs (the writer only - * appends round-trip-verified deltas). - * @param prev - the folded header before the delta. - * @param delta - the logged delta payload. - * @returns the canonical header after the delta. - */ -export function applyHeaderDelta(prev: EpochHeader, delta: HeaderDelta): EpochHeader { - const system = delta.system !== undefined ? applySystem(prev.system, delta.system) : prev.system - const tools = delta.tools !== undefined ? applyTools(prev.tools ?? [], delta.tools) : prev.tools - const messagePrefix = delta.messagePrefix ?? prev.messagePrefix - return canonicalHeader({ - config: delta.config ?? prev.config, - ...system !== undefined ? { system } : {}, - ...tools !== undefined ? { tools } : {}, - ...messagePrefix !== undefined ? { messagePrefix } : {}, - }) -} - -/** - * Fold the header events of a log (or any prefix of one) into the {@link EpochHeader} in - * force after the last of them: each `request/header` snapshot replaces the state, each - * `request/header-delta` amends it. - * - * @param events - session events in log order (non-header events are skipped). - * @param from - a previously folded state to continue from (the live session's incremental - * cursor); omit to fold from nothing. - * @returns the folded header, or undefined when no header event exists yet. + * Fold the header events of a log (or any prefix) into the + * {@link EpochHeader} in force after the last snapshot. Non-header events are + * skipped. This is the pure offline reconstruction path; the live session + * tracks the same fold incrementally. + * @param events - session events in log order. + * @param from - a previously folded state to continue from. + * @returns the latest canonical header, or undefined when none exists yet. */ export function foldRequestHeader(events: readonly SessionEvent[], from?: EpochHeader): EpochHeader | undefined { - let state: EpochHeader | undefined = from + let state = from for (const event of events) { - if (event.type === 'request/header') { - state = canonicalHeader(event.data.header) - } else if (event.type === 'request/header-delta') { - if (state === undefined) { - throw new Error(`request/header-delta at seq ${event.seq} before any request/header snapshot: corrupt log`) - } - state = applyHeaderDelta(state, event.data) - } + if (event.type === 'request/header') state = canonicalHeader(event.data.header) } return state } diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts index 1662d2d80d..d4f43bc303 100644 --- a/packages/core/session/src/surface.ts +++ b/packages/core/session/src/surface.ts @@ -1,19 +1,13 @@ /** - * Surface layer on top of the session event log: a derived, cached linked list - * of events that produce LLM messages. Rebuilt deterministically from - * `surfaceOp` markers in the log — the log is the source of truth; the surface - * is a view. + * Surface layer on top of the session event log: an ordered view of events + * that produce LLM messages. The append-only log remains the source of truth. * * @module @deepseek-ai/dsh-session/surface */ import type { SessionEvent, SurfaceEvent, SurfaceEventType, SurfaceOp } from './types.ts' -/** - * The set of event type strings that are eligible for the surface linked list. - * Mirrors the {@link SurfaceEventType} union; kept as a runtime set so the - * type guard can check membership without a chain of string comparisons. - */ +/** Runtime counterpart of the message-producing event union. */ const SURFACE_EVENT_TYPES = new Set([ 'user/message', 'assistant/message', @@ -23,39 +17,22 @@ const SURFACE_EVENT_TYPES = new Set([ ]) /** - * Check only whether a type may enter the message surface; it does not require `surfaceOp`. This - * detects eligible seed/load events missing their mandatory marker. Use {@link isSurfaceEvent} to - * narrow a fully formed event whose marker is present. - * @param type - the event type string to test. - * @returns true when the type is one of the five message-producing types. + * Whether an event type can join the model-visible surface. + * @param type - event type to test. + * @returns true for one of the five message-producing event types. */ export function isSurfaceEligibleType(type: string): boolean { return SURFACE_EVENT_TYPES.has(type) } /** - * Narrow a {@link SessionEvent} to {@link SurfaceEvent}: checks that the - * event's `type` is surface-eligible AND that `surfaceOp` is present. - * The narrowed type has mandatory {@link SurfaceOp}. - * @param event - the event to narrow. - * @returns true when the event is surface-eligible and carries its `surfaceOp` marker. + * Narrow an event to a surface-eligible event carrying its required marker. + * @param event - event to test. + * @returns true when both the type and marker identify a surface event. */ export function isSurfaceEvent(event: SessionEvent): event is SurfaceEvent { if (!SURFACE_EVENT_TYPES.has(event.type)) return false - // surfaceOp is optional on SessionEvent (even for surface-eligible types) - // but mandatory on SurfaceEvent — this check is the narrowing gate. - if ((event as SessionEvent).surfaceOp === undefined) return false - return true -} - -/** One node in the surface linked list. */ -export interface SurfaceNode { - /** The event seq of this surface node. */ - seq: number - /** The previous surface node's seq, or null if this is the head. */ - prev: number | null - /** The next surface node's seq, or null if this is the tail. */ - next: number | null + return (event as SessionEvent).surfaceOp !== undefined } /** One replacement operation observed while folding a session surface. */ @@ -66,22 +43,21 @@ export interface SurfaceFoldReplacement { start: number /** Declared inclusive end seq of the replaced surface range. */ end: number - /** Actual surface nodes removed by the operation, in surface order. */ + /** Actual surface entries removed by the operation, in surface order. */ shadowedSeqs: number[] } /** Complete result of replaying the surface operations in a session log. */ export interface SurfaceFoldResult { - /** Current surface nodes in linked-list order. */ - nodes: SurfaceNode[] + /** Current surface event sequences in model-visible order. */ + nodes: number[] /** Replacement operations in event order. */ replacements: SurfaceFoldReplacement[] } -/** Mutable state shared by the incremental manager and the full-log fold. */ +/** Mutable state shared by complete and incremental folds. */ interface SurfaceFoldState { - nodes: SurfaceNode[] - nodeBySeq: Map + nodes: number[] replaceGeneration: number } @@ -98,12 +74,8 @@ type SurfacePlan = | SurfaceReplacePlan /** Create an empty surface fold state. */ -function createFoldState(replaceGeneration = 0): SurfaceFoldState { - return { - nodes: [], - nodeBySeq: new Map(), - replaceGeneration, - } +function createFoldState(): SurfaceFoldState { + return { nodes: [], replaceGeneration: 0 } } /** Whether a runtime value is a non-negative safe event sequence. */ @@ -160,8 +132,8 @@ function assertProvenance( if (!Array.isArray(raw)) { throw new Error(`sourceEventSeqs on event at seq ${event.seq} must be an array when present`) } - if (raw.length === 0) { - throw new Error('sourceEventSeqs must not be empty when present') + if (raw.length === 0 && event.type !== 'assistant/message') { + throw new Error('sourceEventSeqs must not be empty except on assistant/message') } let nonEarlierSource: number | undefined for (const source of raw) { @@ -189,23 +161,21 @@ function replacementRange( state: SurfaceFoldState, op: Extract, ): Pick { - const startNode = state.nodeBySeq.get(op.start) - if (!startNode) { + const startIdx = state.nodes.indexOf(op.start) + if (startIdx === -1) { throw new Error(`surface replace: start seq ${op.start} not found in surface`) } - const endNode = state.nodeBySeq.get(op.end) - if (!endNode) { + const endIdx = state.nodes.indexOf(op.end) + if (endIdx === -1) { throw new Error(`surface replace: end seq ${op.end} not found in surface`) } - const startIdx = state.nodes.indexOf(startNode) - const endIdx = state.nodes.indexOf(endNode) if (startIdx > endIdx) { throw new Error(`surface replace: start seq ${op.start} (index ${startIdx}) is after end seq ${op.end} (index ${endIdx})`) } return { startIdx, endIdx, - shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1).map(node => node.seq), + shadowedSeqs: state.nodes.slice(startIdx, endIdx + 1), } } @@ -235,27 +205,6 @@ function planSurfaceEvent( } } -/** Apply one already-validated positional replacement. */ -function replaceSurface(state: SurfaceFoldState, plan: SurfaceReplacePlan): void { - const { startIdx, endIdx } = plan - - const removed = state.nodes.splice(startIdx, endIdx - startIdx + 1) - for (const node of removed) state.nodeBySeq.delete(node.seq) - - const prevNode = startIdx > 0 ? state.nodes[startIdx - 1] : undefined - const nextNode = startIdx < state.nodes.length ? state.nodes[startIdx] : undefined - const newNode: SurfaceNode = { - seq: plan.seq, - prev: prevNode?.seq ?? null, - next: nextNode?.seq ?? null, - } - if (prevNode) prevNode.next = plan.seq - if (nextNode) nextNode.prev = plan.seq - state.nodes.splice(startIdx, 0, newNode) - state.nodeBySeq.set(plan.seq, newNode) - state.replaceGeneration += 1 -} - /** Apply one event and return replacement metadata only when one occurred. */ function applySurfaceEvent( state: SurfaceFoldState, @@ -264,13 +213,10 @@ function applySurfaceEvent( ): SurfaceFoldReplacement | undefined { const plan = planSurfaceEvent(state, event, expectedSeq) if (plan?.kind === 'append') { - const tail = state.nodes.at(-1) - const node: SurfaceNode = { seq: plan.seq, prev: tail?.seq ?? null, next: null } - if (tail) tail.next = plan.seq - state.nodes.push(node) - state.nodeBySeq.set(plan.seq, node) + state.nodes.push(plan.seq) } else if (plan?.kind === 'replace') { - replaceSurface(state, plan) + state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq) + state.replaceGeneration += 1 } if (plan?.kind !== 'replace') return return { @@ -283,16 +229,9 @@ function applySurfaceEvent( /** * Replay a complete session log through the canonical surface fold. - * - * The returned arrays and nodes are detached snapshots. The incremental - * {@link SurfaceManager} uses the same transition functions, so query read - * models cannot disagree with `deriveMessages()` about replacement ranges. * @param events - session events in contiguous seq order. - * @returns the current surface and every positional replacement. - * @throws when any event violates the unified surface contract: metadata must - * be well shaped and type-eligible, event seqs must be contiguous, provenance - * must name unique earlier events, and a positional replacement must name and - * cite its complete range. + * @returns detached current sequences and replacement history. + * @throws when an event violates surface metadata, provenance, or range rules. */ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult { const state = createFoldState() @@ -301,68 +240,44 @@ export function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult const replacement = applySurfaceEvent(state, event, index) if (replacement !== undefined) replacements.push(replacement) } - return { - nodes: state.nodes.map(node => ({ ...node })), - replacements, - } + return { nodes: [...state.nodes], replacements } } -/** - * Maintains a cached linked list of surface nodes and validates each candidate - * before it enters the event log. Because the log is append-only, it processes - * only committed deltas and plans the candidate without mutation rather than - * rescanning the whole log. - */ +/** Incremental ordered surface view and append-boundary validator. */ export class SurfaceManager { - /** Incremental state shared with the complete surface fold. */ + /** Shared transition state; replacement history is not retained. */ private _state = createFoldState() - /** The last processed seq. -1 folds the seeded log on first access. */ + /** Last processed seq; -1 folds a seeded log on first access. */ private _lastProcessedSeq = -1 constructor(private log: readonly SessionEvent[]) {} /** - * Validate one candidate as the next log event without applying it. The - * committed log is folded first, then the candidate's complete surface and - * provenance transition is planned atomically; a failure leaves the current - * surface unchanged. - * @param event - candidate event that has not entered `log` yet. + * Validate the next candidate without mutating the committed surface. + * @param event - candidate event that has not entered the log yet. */ validateNext(event: SessionEvent): void { if (this._lastProcessedSeq < this.log.length - 1) this._processDelta() planSurfaceEvent(this._state, event, this.log.length) } - /** - * The surface's rewrite generation, bumped by every folded `replace` op. - * A replace is the ONE operation that rewrites the - * surface non-monotonically, so an incremental consumer of {@link nodes} - * (the session's derived-message cache) compares this between visits — an - * unchanged generation guarantees every node it has not seen is a pure tail - * append; a changed one means its view must rebuild. Monotonic: it never - * moves backwards, so comparisons cannot be fooled by a re-fold. - */ + /** Monotonic count of folded positional replacements. */ get replaceGeneration(): number { if (this._lastProcessedSeq < this.log.length - 1) this._processDelta() return this._state.replaceGeneration } - /** The surface nodes in linked-list order (head to tail). */ - get nodes(): readonly SurfaceNode[] { + /** Surface event sequences in model-visible order. */ + get nodes(): readonly number[] { if (this._lastProcessedSeq < this.log.length - 1) this._processDelta() return this._state.nodes } - /** - * Process events from `_lastProcessedSeq + 1` through the end of the log, - * folding new surface markers into the existing linked list. - */ + /** Fold events appended since the previous access. */ private _processDelta(): void { for (let i = this._lastProcessedSeq + 1; i < this.log.length; i++) { - // Index is bounded by i < this.log.length — never undefined. - // eslint-disable-next-line @typescript-eslint/no-non-null-assertion - const event = this.log[i]! - applySurfaceEvent(this._state, event, i) + // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded by the loop condition + applySurfaceEvent(this._state, this.log[i]!, i) this._lastProcessedSeq = i } } diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts index dca3010a6f..dc34760e9c 100644 --- a/packages/core/session/src/types.ts +++ b/packages/core/session/src/types.ts @@ -143,7 +143,7 @@ export interface TodoItem { /** * Logged request state outside derived history: call config, system prompt, - * tools, and session prefix. Header snapshots and deltas reconstruct it; + * tools, and prefix. The latest full `request/header` snapshot reconstructs it; * canonical empty optional fields are absent. */ export interface EpochHeader { @@ -167,43 +167,9 @@ export interface EpochHeader { * Why a `request/header` snapshot was appended: `'initial'` — the log's first * header (a new conversation); `'resume'` — a loop instance's first request * over a log that already has header events (process restart, fork seed); - * `'fallback'` — a mid-run change the delta encoding could not round-trip - * (e.g. a pure tool reordering), recorded whole instead. + * `'change'` — a later request used a different header. */ -export type RequestHeaderReason = 'initial' | 'resume' | 'fallback' - -/** - * Line-level edit of the system prompt: keep the first `keepStart` and last - * `keepEnd` lines of the previous text, with `insert` replacing everything - * between. Computed as a common-prefix/common-suffix trim — deterministic, - * library-free, degenerating to a full replacement when nothing is shared. - * Absence is encoded as zero lines (the canonical form has no empty-string - * system), so a transition to or from "no system prompt" round-trips. - */ -export interface SystemDelta { - /** Lines kept from the start of the previous system prompt. */ - keepStart: number - /** Lines kept from the end of the previous system prompt. */ - keepEnd: number - /** Lines replacing everything between the kept edges. */ - insert: string[] -} - -/** - * Tool-set edit keyed by tool name (names are unique — the registry rejects - * duplicates): `removed` names drop, `changed` schemas replace their - * predecessor in place, `added` schemas append at the end. A change this - * encoding cannot express (a pure reordering) fails the writer's round-trip - * guard and is recorded as a `'fallback'` snapshot instead. - */ -export interface ToolsDelta { - /** Schemas appended to the end of the tool list. */ - added: ToolSchema[] - /** Names of schemas dropped from the tool list. */ - removed: string[] - /** Schemas replacing the same-named predecessor in place. */ - changed: ToolSchema[] -} +export type RequestHeaderReason = 'initial' | 'resume' | 'change' /** * The merge-extensible, append-only source of truth for an agent interaction. @@ -276,22 +242,13 @@ export interface SessionEventMap { 'tool/result': { turn: number; step: number; callId: CallId; content: ContentBlock[]; isError: boolean; error?: { name: string; code: string }; meta?: unknown } /** Steering content injected between steps of a running turn. */ 'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource } - /** - * Whole-list snapshot; the latest write wins on replay. It is log-only UI - * state and never enters derived model history. - */ + /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */ 'todo/write': { todos: TodoItem[] } /** - * Full {@link EpochHeader} for the next request, appended inside its step - * before dispatch. It is log-only and anchors subsequent deltas. + * Full header for the next request, appended inside its step before dispatch. + * It is log-only; the latest snapshot reconstructs the request header. */ 'request/header': { header: EpochHeader; reason: RequestHeaderReason } - /** - * Log-only amendment to the folded {@link EpochHeader}. System and tools use - * their delta codecs; config and prefix replace whole, with an empty prefix - * encoding removal. Writers verify round-trip equality or log a fallback snapshot. - */ - 'request/header-delta': { system?: SystemDelta; tools?: ToolsDelta; config?: LlmCallConfig; messagePrefix?: Message[] } } /** The appendable event-type keys of {@link SessionEventMap}, plugin-merged extensions included. */ @@ -299,7 +256,7 @@ export type SessionEventType = keyof SessionEventMap /** * The subset of {@link SessionEventType} values whose events produce LLM - * messages and are eligible to appear on the surface linked list. Only these + * messages and are eligible to appear on the ordered surface. Only these * event types may carry {@link SurfaceOp} and {@link SessionEvent.sourceEventSeqs}. */ export type SurfaceEventType = @@ -310,7 +267,7 @@ export type SurfaceEventType = | 'steering/message' /** - * A {@link SessionEvent} that is **on** the surface linked list — its + * A {@link SessionEvent} that is **on** the ordered surface — its * `surfaceOp` is guaranteed present (mandatory), narrowed from a * surface-eligible {@link SessionEvent} by checking both `type` and * `surfaceOp` at runtime. @@ -321,7 +278,7 @@ export type SurfaceEventType = export type SurfaceEvent = SessionEvent & { surfaceOp: SurfaceOp } /** - * How a session event entered the surface linked list. Only valid on + * How a session event entered the ordered surface. Only valid on * {@link SurfaceEventType} events. * * - `'append'`: added to the tail — normal path for user/assistant/tool/context @@ -342,6 +299,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[] } @@ -370,7 +333,9 @@ export type SessionEvent = { /** * 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. */ diff --git a/packages/core/session/tests/derived-cache.spec.ts b/packages/core/session/tests/derived-cache.spec.ts index 8cead0642e..96d1f7048c 100644 --- a/packages/core/session/tests/derived-cache.spec.ts +++ b/packages/core/session/tests/derived-cache.spec.ts @@ -40,7 +40,7 @@ describe('derived-message cache', () => { const nodes = session.surface.nodes session.append('context/message', { content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' }, - }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] }) + }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] }) expect(session.deriveMessages()).toHaveLength(1) expect(session.deriveMessages()).toEqual(scratch(session)) diff --git a/packages/core/session/tests/request-header.spec.ts b/packages/core/session/tests/request-header.spec.ts index 6cd2e2c7fb..b185cf6e56 100644 --- a/packages/core/session/tests/request-header.spec.ts +++ b/packages/core/session/tests/request-header.spec.ts @@ -1,14 +1,7 @@ -/** - * Request-header utility tests: canonical form, the system line-diff - * (prefix/suffix trim), the name-keyed tools delta, config replacement, the - * round-trip contract (including the reorder case the encoding cannot - * express), and the log fold. These pin the reconstruction algebra: for every - * logged delta, apply(prev, delta) === next, and folding a log prefix yields - * the header its next request was built under. - */ +/** Request-header canonicalization, equality, snapshot folding, and format rejection. */ import { describe, expect, it } from 'vitest' -import { Session, SessionId, applyHeaderDelta, canonicalHeader, diffHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session' +import { Session, SessionId, canonicalHeader, foldRequestHeader, headerEquals } from '@deepseek-ai/dsh-session' import type { EpochHeader, SessionEvent } from '@deepseek-ai/dsh-session' import type { Message, ToolSchema } from '@deepseek-ai/dsh-llm' @@ -22,165 +15,77 @@ function msg(text: string): Message { return { role: 'user', content: [{ type: 'text', text }] } } -/** Round-trip helper: diff must reproduce `next` from `prev` exactly. */ -function roundTrip(prev: EpochHeader, next: EpochHeader): ReturnType { - const delta = diffHeader(prev, next) - if (delta !== undefined) { - expect(applyHeaderDelta(prev, delta)).toEqual(canonicalHeader(next)) - } - return delta -} - describe('canonicalHeader', () => { - it('normalizes empty system and empty tools to absent fields', () => { - expect(canonicalHeader({ config: CONFIG, system: '', tools: [] })).toEqual({ config: CONFIG }) - const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')] }) - expect(full.system).toBe('s') - expect(full.tools).toHaveLength(1) + it('normalizes empty optional fields to absence and preserves populated fields', () => { + expect(canonicalHeader({ config: CONFIG, system: '', tools: [], messagePrefix: [] })).toEqual({ config: CONFIG }) + const full = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] }) + expect(full).toEqual({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] }) }) }) -describe('diffHeader / applyHeaderDelta', () => { - it('returns undefined for equal headers', () => { - const header = canonicalHeader({ config: CONFIG, system: 'a\nb', tools: [tool('t')] }) - expect(diffHeader(header, header)).toBeUndefined() +describe('headerEquals', () => { + const base = canonicalHeader({ config: CONFIG, system: 's', tools: [tool('a')], messagePrefix: [msg('p')] }) + + it('compares every canonical field and preserves tool order', () => { + expect(headerEquals(base, structuredClone(base))).toBe(true) + expect(headerEquals(base, { ...base, config: { provider: 'mock', model: 'other' } })).toBe(false) + expect(headerEquals(base, { ...base, system: 'other' })).toBe(false) + expect(headerEquals(base, { ...base, messagePrefix: [msg('other')] })).toBe(false) + expect(headerEquals(base, { ...base, tools: [] })).toBe(false) + expect(headerEquals(base, { ...base, tools: [tool('a', 'changed')] })).toBe(false) + expect(headerEquals({ config: CONFIG, tools: [tool('a'), tool('b')] }, { config: CONFIG, tools: [tool('b'), tool('a')] })).toBe(false) }) - it('encodes a mid-prompt line change as a prefix/suffix trim', () => { - const prev = canonicalHeader({ config: CONFIG, system: 'keep1\nold\nkeep2\nkeep3' }) - const next = canonicalHeader({ config: CONFIG, system: 'keep1\nnew A\nnew B\nkeep2\nkeep3' }) - const delta = roundTrip(prev, next) - expect(delta?.system).toEqual({ keepStart: 1, keepEnd: 2, insert: ['new A', 'new B'] }) - expect(delta?.tools).toBeUndefined() - expect(delta?.config).toBeUndefined() - }) - - it('degenerates to a full replacement when nothing is shared, and round-trips absence transitions', () => { - const none = canonicalHeader({ config: CONFIG }) - const some = canonicalHeader({ config: CONFIG, system: 'x\ny' }) - const gained = roundTrip(none, some) - expect(gained?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: ['x', 'y'] }) - const lost = roundTrip(some, none) - expect(lost?.system).toEqual({ keepStart: 0, keepEnd: 0, insert: [] }) - }) - - it('does not double-count overlapping prefix and suffix (repeated lines)', () => { - const prev = canonicalHeader({ config: CONFIG, system: 'a\na' }) - const next = canonicalHeader({ config: CONFIG, system: 'a\na\na' }) - roundTrip(prev, next) - }) - - it('encodes tool addition, removal, and in-place schema change by name', () => { - const prev = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('drop'), tool('edit', 'before')] }) - const next = canonicalHeader({ config: CONFIG, tools: [tool('keep'), tool('edit', 'after'), tool('new')] }) - const delta = roundTrip(prev, next) - expect(delta?.tools?.added.map(t => t.name)).toEqual(['new']) - expect(delta?.tools?.removed).toEqual(['drop']) - expect(delta?.tools?.changed.map(t => t.name)).toEqual(['edit']) - }) - - it('round-trips a tool set gained from a tool-less header and lost back to one', () => { - const none = canonicalHeader({ config: CONFIG }) - const some = canonicalHeader({ config: CONFIG, tools: [tool('t')] }) - const gained = roundTrip(none, some) - expect(gained?.tools?.added.map(t => t.name)).toEqual(['t']) - const lost = roundTrip(some, none) - expect(lost?.tools?.removed).toEqual(['t']) - }) - - it('cannot express a pure reordering — the writer detects it via the round-trip check', () => { - const prev = canonicalHeader({ config: CONFIG, tools: [tool('a'), tool('b')] }) - const next = canonicalHeader({ config: CONFIG, tools: [tool('b'), tool('a')] }) - const delta = diffHeader(prev, next) - // A delta IS produced (the lists differ)… - expect(delta).toBeDefined() - // …but applying it cannot reproduce the new order — exactly the case the - // writer's guard turns into a 'fallback' snapshot. - expect(applyHeaderDelta(prev, delta!)).not.toEqual(next) - }) - - it('replaces the config whole and leaves untouched parts alone', () => { - const prev = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 's', tools: [tool('t')] }) - const next = canonicalHeader({ config: { provider: 'mock', model: 'm2', temperature: 0.1 }, system: 's', tools: [tool('t')] }) - const delta = roundTrip(prev, next) - expect(delta).toEqual({ config: { provider: 'mock', model: 'm2', temperature: 0.1 } }) - }) -}) - -describe('the session prefix (messagePrefix)', () => { - it('canonicalHeader normalizes an empty prefix to an absent field', () => { - expect(canonicalHeader({ config: CONFIG, messagePrefix: [] })).toEqual({ config: CONFIG }) - const full = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] }) - expect(full.messagePrefix).toEqual([msg('p')]) - }) - - it('headerEquals treats absence and empty as one representation, content differences as unequal', () => { - expect(headerEquals(canonicalHeader({ config: CONFIG }), { config: CONFIG, messagePrefix: [] })).toBe(true) - expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG, messagePrefix: [msg('b')] })).toBe(false) - expect(headerEquals({ config: CONFIG, messagePrefix: [msg('a')] }, { config: CONFIG })).toBe(false) - }) - - it('replaces a changed prefix whole and leaves untouched parts alone', () => { - const prev = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('old')] }) - const next = canonicalHeader({ config: CONFIG, system: 'keep', messagePrefix: [msg('new'), msg('more')] }) - const delta = roundTrip(prev, next) - expect(delta).toEqual({ messagePrefix: [msg('new'), msg('more')] }) - }) - - it('round-trips a prefix gained from a bare header and lost back to one (empty array encodes absence)', () => { - const none = canonicalHeader({ config: CONFIG }) - const some = canonicalHeader({ config: CONFIG, messagePrefix: [msg('p')] }) - const gained = roundTrip(none, some) - expect(gained).toEqual({ messagePrefix: [msg('p')] }) - const lost = roundTrip(some, none) - expect(lost).toEqual({ messagePrefix: [] }) - }) - - it('folds prefix deltas over the log like any other header amendment', () => { - const session = new Session(SessionId('fold-prefix')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - const first = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v1')] }) - session.append('request/header', { header: first, reason: 'initial' }) - const second = canonicalHeader({ config: CONFIG, messagePrefix: [msg('catalog v2')] }) - session.append('request/header-delta', diffHeader(first, second)!) - expect(foldRequestHeader(session.events)).toEqual(second) - session.append('request/header-delta', diffHeader(second, canonicalHeader({ config: CONFIG }))!) - expect(foldRequestHeader(session.events)).toEqual({ config: CONFIG }) + it('treats absent and empty prefix/tool arrays as equivalent canonical absence', () => { + expect(headerEquals({ config: CONFIG }, { config: CONFIG, tools: [], messagePrefix: [] })).toBe(true) }) }) describe('foldRequestHeader', () => { - function headerEvents(session: Session): readonly SessionEvent[] { - return session.events - } - - it('returns undefined on a log with no header events', () => { - const session = new Session(SessionId('fold-none')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - expect(foldRequestHeader(headerEvents(session))).toBeUndefined() + it('returns the supplied baseline when no snapshot follows', () => { + const from: EpochHeader = { config: CONFIG, system: 'baseline' } + const unrelated: SessionEvent[] = [ + { type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }, + ] + expect(foldRequestHeader(unrelated)).toBeUndefined() + expect(foldRequestHeader(unrelated, from)).toBe(from) }) - it('folds snapshot then deltas into the header in force, skipping unrelated events', () => { + it('takes the latest full snapshot and skips unrelated events', () => { const session = new Session(SessionId('fold')) session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - const first = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nb', tools: [tool('t')] }) - session.append('request/header', { header: first, reason: 'initial' }) + session.append('request/header', { header: { config: CONFIG, system: 'first' }, reason: 'initial' }) session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - - const second = canonicalHeader({ config: { provider: 'mock', model: 'm' }, system: 'a\nc', tools: [tool('t')] }) - session.append('request/header-delta', diffHeader(first, second)!) - expect(foldRequestHeader(headerEvents(session))).toEqual(second) - - // A later snapshot replaces the state wholesale (the 'resume'/'fallback' anchor). - const third = canonicalHeader({ config: { provider: 'mock', model: 'other' } }) - session.append('request/header', { header: third, reason: 'resume' }) - expect(foldRequestHeader(headerEvents(session))).toEqual(third) - }) - - it('throws on a delta before any snapshot (corrupt log)', () => { - const session = new Session(SessionId('fold-corrupt')) - session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }) - session.append('request/header-delta', { config: { provider: 'mock', model: 'x' } }) - expect(() => foldRequestHeader(headerEvents(session))).toThrow(/before any request\/header snapshot/) + session.append('request/header', { header: { config: { provider: 'mock', model: 'other' }, tools: [] }, reason: 'change' }) + expect(foldRequestHeader(session.events)).toEqual({ config: { provider: 'mock', model: 'other' } }) + }) +}) + +describe('legacy request-header format', () => { + it('rejects request/header-delta in seeds and untyped appends', () => { + const legacy = [{ + type: 'request/header-delta', seq: 0, time: 1, data: { config: CONFIG }, + }] as unknown as SessionEvent[] + expect(() => new Session(SessionId('legacy'), legacy)).toThrow(/unsupported legacy request\/header-delta/) + + const session = new Session(SessionId('legacy-append-delta')) + const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent + expect(() => appendLegacy('request/header-delta', { config: CONFIG })) + .toThrow(/unsupported legacy request\/header-delta/) + expect(session.events).toHaveLength(0) + }) + + it('rejects the removed fallback reason in seeds and untyped appends', () => { + const legacy = [{ + type: 'request/header', seq: 0, time: 1, data: { header: { config: CONFIG }, reason: 'fallback' }, + }] as unknown as SessionEvent[] + expect(() => new Session(SessionId('legacy-seed-reason'), legacy)) + .toThrow('unsupported legacy request/header reason "fallback"') + + const session = new Session(SessionId('legacy-append-reason')) + const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent + expect(() => appendLegacy('request/header', { header: { config: CONFIG }, reason: 'fallback' })) + .toThrow('unsupported legacy request/header reason "fallback"') + expect(session.events).toHaveLength(0) }) }) diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts index 6b36dfaa77..16a74283be 100644 --- a/packages/core/session/tests/session.spec.ts +++ b/packages/core/session/tests/session.spec.ts @@ -101,13 +101,6 @@ describe('Session', () => { expect(() => new Session(SessionId('old-header'), [requestHeader])) .toThrow('seed request/header at index 0 lacks provider/model') - const requestDelta = { - type: 'request/header-delta', seq: 0, time: 1, - data: { config: { model: 'old-model' } }, - } as unknown as SessionEvent - expect(() => new Session(SessionId('old-delta'), [requestDelta])) - .toThrow('seed request/header-delta at index 0 lacks provider/model') - const assistantMessage = { type: 'assistant/message', seq: 0, time: 1, data: { turn: 1, step: 1, content: [{ type: 'text', text: 'old' }] }, @@ -1244,8 +1237,8 @@ describe('todo/write event', () => { session.append('todo/write', { todos: [{ content: 'a task', status: 'pending' }] }) // The todo event must not add a message to the derived history… expect(session.deriveMessages()).toHaveLength(before) - // …and must not appear on the surface linked list. - expect(session.surface.nodes.some(node => node.seq === session.seq - 1)).toBe(false) + // …and must not appear on the ordered surface. + expect(session.surface.nodes).not.toContain(session.seq - 1) }) it('round-trips through a seeded replay identically (durable, no surfaceOp needed)', () => { diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts index 581388c22f..fe222f8f2f 100644 --- a/packages/core/session/tests/surface.spec.ts +++ b/packages/core/session/tests/surface.spec.ts @@ -54,6 +54,23 @@ describe('foldSurface provenance', () => { expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/) }) + it('accepts explicit empty provenance on an assistant message', () => { + const event = { + type: 'assistant/message', + seq: 0, + time: 0, + data: { + provenance: { provider: 'mock', model: 'mock' }, + turn: 1, + step: 1, + content: [], + }, + surfaceOp: 'append', + sourceEventSeqs: [], + } as SessionEvent + expect(() => foldSurface([event])).not.toThrow() + }) + it.each([ ['a non-array', [{ ...provenanceEvent(0, undefined), sourceEventSeqs: 'invalid' }], /must be an array/], ['an empty array', [provenanceEvent(0, [])], /must not be empty/], @@ -78,7 +95,7 @@ describe('foldSurface provenance', () => { }) describe('SurfaceManager', () => { - it('shares exact nodes and nested replacement ranges with foldSurface', () => { + it('shares ordered entries and nested replacement ranges with foldSurface', () => { const s = new Session(SessionId('shared-fold')) s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) @@ -91,9 +108,10 @@ describe('SurfaceManager', () => { { seq: 2, start: 0, end: 0, shadowedSeqs: [0] }, { seq: 3, start: 2, end: 1, shadowedSeqs: [2, 1] }, ]) - folded.nodes[0]!.next = 99 + folded.nodes[0] = 99 folded.replacements[0]!.shadowedSeqs.push(99) - expect(s.surface.nodes).toEqual([{ seq: 3, prev: null, next: null }]) + expect(s.surface.nodes).toEqual([3]) + expect(foldSurface(s.events).nodes).toEqual([3]) expect(foldSurface(s.events).replacements[0]!.shadowedSeqs).toEqual([0]) }) @@ -102,7 +120,7 @@ describe('SurfaceManager', () => { s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'b' }] }, { surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] }) - expect(s.surface.nodes).toEqual([{ seq: 1, prev: null, next: null }]) + expect(s.surface.nodes).toEqual([1]) const manager = s.surface as unknown as { _state: object } expect(Object.hasOwn(manager._state, 'replacements')).toBe(false) expect(foldSurface(s.events).replacements).toEqual([ @@ -133,7 +151,7 @@ describe('SurfaceManager', () => { expect(s.events).toHaveLength(1) s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) - expect(s.surface.nodes.map(node => node.seq)).toEqual([0, 1]) + expect(s.surface.nodes).toEqual([0, 1]) }) it('foldSurface rejects a surface-eligible event without its mandatory marker', () => { @@ -161,18 +179,12 @@ describe('SurfaceManager', () => { .toThrow(/not surface-eligible and cannot carry surfaceOp/) }) - it('rebuilds a linked list from surfaceOp: append markers', () => { + it('folds an ordered sequence list from surfaceOp: append markers', () => { const s = surfaceSession() const nodes = s.surface.nodes // Only the user/message and assistant/message carry surfaceOp: 'append'. // The turn boundaries do not have surface markers. - expect(nodes.length).toBe(2) - expect(nodes[0]!.seq).toBe(1) // user/message (turn/start is seq 0) - expect(nodes[0]!.prev).toBeNull() - expect(nodes[0]!.next).toBe(2) // assistant/message (seq 2) - expect(nodes[1]!.seq).toBe(2) - expect(nodes[1]!.prev).toBe(1) - expect(nodes[1]!.next).toBeNull() + expect(nodes).toEqual([1, 2]) }) it('empty surface yields empty nodes', () => { @@ -193,9 +205,7 @@ describe('SurfaceManager', () => { // Append another surface node s.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' }) expect(s.surface.nodes.length).toBe(3) - expect(s.surface.nodes[2]!.seq).toBe(4) // seq 4: after turn/end at seq 3 - expect(s.surface.nodes[2]!.prev).toBe(2) - expect(s.surface.nodes[1]!.next).toBe(4) + expect(s.surface.nodes[2]!).toBe(4) // seq 4: after turn/end at seq 3 }) it('replays identically from a seeded log with surface markers', () => { @@ -203,21 +213,17 @@ describe('SurfaceManager', () => { original.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [{ type: 'text', text: 'ok' }], isError: false }, { surfaceOp: 'append' }) const replayed = new Session(SessionId('replay'), [...original.events]) // Surface rebuilds from the seeded log's markers. - expect(replayed.surface.nodes.map(n => n.seq)).toEqual([1, 2, 4]) + expect(replayed.surface.nodes).toEqual([1, 2, 4]) expect(replayed.deriveMessages()).toEqual(original.deriveMessages()) }) it('rebuild with replace operation splices out shadowed nodes', () => { const s = surfaceSession() - // Replace surface seqs 1 (user) and 2 (assistant) with the summary. s.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 2, step: 1, content: [{ type: 'text', text: 'summary' }] }, { surfaceOp: { op: 'replace', start: 1, end: 2 }, sourceEventSeqs: [1, 2] }, ) - expect(s.surface.nodes.length).toBe(1) - expect(s.surface.nodes[0]!.seq).toBe(4) // seq of the compaction marker - expect(s.surface.nodes[0]!.prev).toBeNull() - expect(s.surface.nodes[0]!.next).toBeNull() + expect(s.surface.nodes).toEqual([4]) }) it('replace with both ends at real nodes splices only the range', () => { @@ -230,12 +236,7 @@ describe('SurfaceManager', () => { { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary' }] }, { surfaceOp: { op: 'replace', start: 0, end: 1 }, sourceEventSeqs: [0, 1] }, ) // seq 3 - expect(s.surface.nodes.map(n => n.seq)).toEqual([3, 2]) - // Links: 3 ↔ 2 - expect(s.surface.nodes[0]!.prev).toBeNull() - expect(s.surface.nodes[0]!.next).toBe(2) - expect(s.surface.nodes[1]!.prev).toBe(3) - expect(s.surface.nodes[1]!.next).toBeNull() + expect(s.surface.nodes).toEqual([3, 2]) }) it('single-node replacement (start === end)', () => { @@ -247,9 +248,7 @@ describe('SurfaceManager', () => { { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] }, { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] }, ) // seq 2 - expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 2]) - expect(s.surface.nodes[0]!.next).toBe(2) - expect(s.surface.nodes[1]!.prev).toBe(0) + expect(s.surface.nodes).toEqual([0, 2]) }) it('throws when replace start is not found', () => { @@ -293,7 +292,7 @@ describe('SurfaceManager', () => { expect(logged.sourceEventSeqs).toEqual([0]) }) - it('replace starting at non-head position links to previous node correctly', () => { + it('replace starting at non-head position preserves surrounding order', () => { const s = new Session(SessionId('mid-replace')) s.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 0 s.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 1 @@ -303,14 +302,7 @@ describe('SurfaceManager', () => { { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'x' }] }, { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1] }, ) // seq 3 - expect(s.surface.nodes.map(n => n.seq)).toEqual([0, 3, 2]) - // Links: 0 → 3 → 2 - expect(s.surface.nodes[0]!.prev).toBeNull() - expect(s.surface.nodes[0]!.next).toBe(3) - expect(s.surface.nodes[1]!.prev).toBe(0) - expect(s.surface.nodes[1]!.next).toBe(2) - expect(s.surface.nodes[2]!.prev).toBe(3) - expect(s.surface.nodes[2]!.next).toBeNull() + expect(s.surface.nodes).toEqual([0, 3, 2]) }) it('surfaceOp replace object is snapshot so caller mutation is isolated', () => { @@ -484,7 +476,7 @@ describe('SurfaceManager.replaceGeneration', () => { const nodes = s.surface.nodes s.append('context/message', { content: [{ type: 'text', text: 'summary' }], source: { kind: 'plugin', plugin: 'compact' }, - }, { surfaceOp: { op: 'replace', start: nodes[0]!.seq, end: nodes[1]!.seq }, sourceEventSeqs: [nodes[0]!.seq, nodes[1]!.seq] }) + }, { surfaceOp: { op: 'replace', start: nodes[0]!, end: nodes[1]! }, sourceEventSeqs: [nodes[0]!, nodes[1]!] }) expect(s.surface.replaceGeneration).toBe(1) }) }) diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts index bf0324628a..5fc045ace2 100644 --- a/packages/core/tools/src/index.ts +++ b/packages/core/tools/src/index.ts @@ -312,8 +312,8 @@ export interface ToolExecutionResult { */ error?: ToolErrorInfo /** - * Model-facing context for the next request, separate from this tool result. - * The loop buffers it until all step results are logged, preserving pairing. + * Model-facing context for the next request, separate from this tool result. The loop + * accepts it into the active-batch FIFO, then appends after recorded results even if interrupted. */ additionalContexts?: HookContext[] /** @@ -1013,7 +1013,7 @@ export class ToolRegistry extends Service { * its {@link PostToolDecision}: `accept` keeps the call successful (replacing * `content` when given), `block` turns it into an `isError` whose content is * the corrective `feedback`. Either decision may attach `additionalContexts`, - * which are ferried on the returned result for the loop's per-step buffer. + * which are ferried on the returned result for the loop's active-batch FIFO. * Context deferred by the tool body survives an accepted result but is * discarded when the outer call is blocked; a block exposes only context the * blocking decision explicitly supplied. diff --git a/packages/llm/README.md b/packages/llm/README.md index d971fc830c..4a5e6769e2 100644 --- a/packages/llm/README.md +++ b/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 request and surface token measurement | `ctx.tokenMeter` | | `llm-deepseek/` | DeepSeek API adapter (hand-rolled fetch/SSE) | (registers on `ctx.llm`) | | `llm-pi-ai/` | Multi-provider adapter via `@earendil-works/pi-ai` | (registers on `ctx.llm`) | -The interface lives at `llm/llm/`; adapters are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. A new provider adapter joins here and registers one or more provider routes on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations. +The interface lives at `llm/llm/`; adapters and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. A new provider adapter joins here and registers one or more provider routes on `ctx.llm` without touching the interface. See [twin LLM adapters](../../docs/rfc/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations and the [replay token meter RFC](../../docs/rfc/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership. diff --git a/packages/llm/llm/src/call-config.ts b/packages/llm/llm/src/call-config.ts index e4fd703b24..82eb68615d 100644 --- a/packages/llm/llm/src/call-config.ts +++ b/packages/llm/llm/src/call-config.ts @@ -1,8 +1,8 @@ /** - * Conversation call configuration and freeze utilities. Model and sampling - * values, including provider routing, are request-header state that can affect cache reuse; request - * waterfalls replace them and the loop logs changes instead of allowing - * silent per-call drift. + * Conversation call configuration and freeze utilities. Provider routing, + * model, and sampling values are request-header state that can affect cache + * reuse; request waterfalls replace them and the loop logs changed snapshots + * instead of allowing silent per-call drift. * @module dsh-llm/call-config */ @@ -22,7 +22,7 @@ export interface LlmCallConfig { /** * Field-wise equality over {@link LlmCallConfig} — the comparison a caller * runs to decide whether a proposed configuration is a real change (worth a - * logged header delta) or the held one restated. + * logged header snapshot) or the held one restated. * @param a - one configuration. * @param b - the other. * @returns whether every field (including the `stop` list, element-wise) matches. diff --git a/packages/llm/llm/tests/call-config.spec.ts b/packages/llm/llm/tests/call-config.spec.ts index 4bccd2520a..3e656f7563 100644 --- a/packages/llm/llm/tests/call-config.spec.ts +++ b/packages/llm/llm/tests/call-config.spec.ts @@ -1,6 +1,6 @@ /** * call-config unit tests: field-wise LlmCallConfig equality (the real-change - * detector behind logged header deltas) and the deepFreeze ownership helper + * detector behind logged changed headers) and the deepFreeze ownership helper * the loop applies to every built request. */ diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md new file mode 100644 index 0000000000..262fc8d152 --- /dev/null +++ b/packages/llm/token-meter/README.md @@ -0,0 +1,50 @@ +# @deepseek-ai/dsh-token-meter + +Replay-aware token measurement through the singleton `ctx.tokenMeter` service. It advances one isolated fold per session from the durable log, so compaction and other pressure-sensitive plugins can share accounting without depending on `CompactService`. + +## Configuration + +| Key | Default | Contract | +|---|---:|---| +| `contextWindow` | `128000` | Positive integer service-wide context capacity. | + +The estimator intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. `contextWindow` is the only deployment setting. Direct construction validates it; Loader mounts first apply the package's Schemastery shape validation. Unrecognized top-level keys are rejected. + +## Measurement contract + +`ctx.tokenMeter` directly exposes two operations: + +- `measure(session, requestHeader?)` returns request pressure and the current priced surface at one consumed-log revision. +- `estimateMessage(message)` prices one message with the fixed heuristic. + +`measure()` synchronizes once and returns one detached, deeply immutable snapshot. `totalTokens` is request-and-response pressure, while `surfaceTokens` is the surface-only heuristic total and equals the sum of `nodes[].tokens`. A `requestHeader` override affects pressure fields only; the surface fields still describe the current session. Every call clones the positional nodes, so measurement is O(surface). + +The fold tracks full request-header snapshots, step boundaries, surface appends and replacements, successful assistant messages, provider usage, and assistant-chunk provenance. Provider usage is reused only when the latest successful call's canonical request envelope matches the measured envelope and its total is no lower than that call's full heuristic anchor; a later success replaces the earlier anchor. Otherwise the complete current envelope and surface are estimated. 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. A deployment with a different capacity configures the meter once: + +```yaml +- name: '@deepseek-ai/dsh-token-meter' + config: + 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 + +- **The fixed heuristic is approximate** — content without reusable provider usage is priced by character count plus structural overhead, not an exact provider tokenizer or request serializer. +- **Every measurement clones the current surface** — coherent immutable snapshots make reads O(surface), including below-threshold pressure checks. +- **Provider usage is only reusable for an identical canonical envelope** — prompt, prefix, tools, provider, model, or call-config changes deliberately fall back to full heuristic estimation. +- **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. diff --git a/packages/llm/token-meter/package.json b/packages/llm/token-meter/package.json new file mode 100644 index 0000000000..13fa4e3cdc --- /dev/null +++ b/packages/llm/token-meter/package.json @@ -0,0 +1,37 @@ +{ + "name": "@deepseek-ai/dsh-token-meter", + "description": "Replay-aware 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" + } +} diff --git a/packages/llm/token-meter/src/index.ts b/packages/llm/token-meter/src/index.ts new file mode 100644 index 0000000000..0c18dee74b --- /dev/null +++ b/packages/llm/token-meter/src/index.ts @@ -0,0 +1,419 @@ +/** + * Single replay-aware token-meter service for request and surface pressure. + * + * @module @deepseek-ai/dsh-token-meter + */ + +import { Context, Service } from 'cordis' +import z from 'schemastery' +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 { canonicalHeader, headerEquals, isSurfaceEvent } from '@deepseek-ai/dsh-session' +import type { + TokenMeasurement, + TokenMeasurementBaseline, + TokenMeterConfig, + TokenSurfaceNode, +} from './types.ts' + +export type * from './types.ts' + +/** Default service-wide provider context capacity. */ +const DEFAULT_CONTEXT_WINDOW = 128_000 + +/** Complete public configuration key set. */ +const TOKEN_METER_CONFIG_KEYS: ReadonlySet = new Set(['contextWindow']) + +/** Fixed text-density estimate used until exact tokenization is needed. */ +const CHARS_PER_TOKEN = 4 + +/** 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 MeasurementAnchor { + readonly header: EpochHeader | undefined + readonly surfaceTokens: number + readonly baseline: Exclude +} + +interface ReplayState { + consumedEvents: number + header: EpochHeader | undefined + surface: TokenSurfaceNode[] + surfaceTokens: number + stepStart: { turn: number; step: number; surfaceTokens: number } | undefined + anchor: MeasurementAnchor | 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 +} + +/** Compare optional envelopes so a headerless estimate can track later surface deltas. */ +function optionalHeaderEquals( + left: EpochHeader | undefined, + right: EpochHeader | undefined, +): boolean { + if (left === undefined || right === undefined) return left === right + return headerEquals(left, right) +} + +/** Reject stale or misspelled keys before defaults can hide them. */ +function validateConfigKeys(config: TokenMeterConfig): void { + for (const key of Object.keys(config)) { + if (!TOKEN_METER_CONFIG_KEYS.has(key)) { + throw new Error( + `TokenMeterConfig: unknown key "${key}" (allowed: contextWindow)`, + ) + } + } +} + +/** Resolve and validate the one service-wide context capacity. */ +function resolveContextWindow(config: TokenMeterConfig): number { + validateConfigKeys(config) + const contextWindow = config.contextWindow === undefined + ? DEFAULT_CONTEXT_WINDOW + : config.contextWindow + if (!Number.isInteger(contextWindow) || contextWindow <= 0) { + throw new Error( + `TokenMeterConfig: contextWindow (${contextWindow}) must be a positive integer`, + ) + } + return contextWindow +} + +declare module 'cordis' { + interface Context { + tokenMeter: TokenMeterService + } +} + +/** Replay owner for one service-wide estimator and isolated per-session folds. */ +export class TokenMeterService extends Service { + static Config: z = z.object({ + contextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW), + }) + + /** Provider context-window capacity used by pressure consumers. */ + readonly contextWindow: number + + private readonly states = new WeakMap() + + constructor(ctx: Context, config: TokenMeterConfig = {}) { + super(ctx, 'tokenMeter') + this.contextWindow = resolveContextWindow(config) + + // Readers catch up independently, while eager observation bounds ordinary + // read latency without creating state for sessions no consumer has read. + ctx.on('session/event', (session) => { + if (this.states.has(session)) this._sync(session) + }) + } + + /** + * Measure current request pressure and surface through the durable tail. + * + * Provider usage is reused only when the latest successful call's canonical + * request envelope matches `requestHeader` and its total is no lower than + * that call's full heuristic anchor; otherwise the complete envelope and + * surface are heuristically repriced. + * + * `requestHeader` affects request pressure only; surface fields always + * describe the current session surface. Every call clones those positional + * nodes, so measurement is O(surface). + * + * @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 and surface measurement. + */ + 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 && optionalHeaderEquals(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({ + logRevision: state.consumedEvents, + baseline, + surfaceDeltaTokens, + totalTokens: Math.max(0, baseline.tokens + surfaceDeltaTokens), + surfaceTokens: state.surfaceTokens, + nodes: state.surface, + })) + } + + /** + * Heuristically price one model-visible message. + * @param message - message to price without mutation. + * @returns content and role-framing tokens under the fixed service heuristic. + */ + estimateMessage(message: Message): number { + return this._estimateContent(message.content) + ROLE_OVERHEAD + } + + /** 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 remains unread on every retry instead of partially + * applying the same mutation more than once. + */ + 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 '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') { + 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 && nextHeader !== undefined) { + const providerAssistantTokens = this._estimateProviderAssistant( + session, + event, + eventTokens, + ) + const anchorSurfaceTokens = stepStart.surfaceTokens + providerAssistantTokens + const providerTokens = usageTokens(event.data.usage) + const estimatedAnchorTokens = this._estimateHeader(nextHeader) + anchorSurfaceTokens + nextAnchor = { + header: nextHeader, + surfaceTokens: anchorSurfaceTokens, + // Signed heuristic deltas remain conservative only from an anchor + // that is at least as large as the matching full heuristic price. + baseline: providerTokens >= estimatedAnchorTokens + ? { kind: 'usage', tokens: providerTokens, usage: event.data.usage } + : { kind: 'estimated', tokens: estimatedAnchorTokens }, + } + } 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() + 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 the fixed density heuristic. */ + 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 / CHARS_PER_TOKEN) + BLOCK_OVERHEAD + break + case 'tool-call': + tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN) + + Math.ceil(block.arguments.length / CHARS_PER_TOKEN) + + 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 fixed heuristic. + tokens += BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN) + } + } + 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 / CHARS_PER_TOKEN) + ROLE_OVERHEAD + } + if (header.tools !== undefined && header.tools.length > 0) { + tokens += Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD + } + return tokens + } +} + +export default TokenMeterService diff --git a/packages/llm/token-meter/src/types.ts b/packages/llm/token-meter/src/types.ts new file mode 100644 index 0000000000..7fb35af997 --- /dev/null +++ b/packages/llm/token-meter/src/types.ts @@ -0,0 +1,43 @@ +/** + * Public configuration and measurement vocabulary for replay token metering. + * + * @module @deepseek-ai/dsh-token-meter/types + */ + +import type { TokenUsage } from '@deepseek-ai/dsh-llm' + +/** Token-meter plugin configuration. */ +export interface TokenMeterConfig { + /** Service-wide context-window capacity in tokens. Defaults to `128000`. */ + contextWindow?: number +} + +/** 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 } + +/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */ +export interface TokenMeasurement { + /** 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 + /** Total heuristic tokens across the current surface. */ + readonly surfaceTokens: number + /** Current surface nodes in positional head-to-tail order. */ + readonly nodes: readonly TokenSurfaceNode[] +} + +/** 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 +} diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts new file mode 100644 index 0000000000..e7ddca6696 --- /dev/null +++ b/packages/llm/token-meter/tests/token-meter.spec.ts @@ -0,0 +1,649 @@ +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, SessionEvent } from '@deepseek-ai/dsh-session' +import TokenMeterService from '@deepseek-ai/dsh-token-meter' +import type { TokenMeasurement, TokenMeterConfig } from '@deepseek-ai/dsh-token-meter' + +function header(model: string, extras: Omit = {}): EpochHeader { + return canonicalHeader({ config: { provider: 'mock', 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' }) +} + +/** Inject malformed persisted history after the live append boundary for defensive replay tests. */ +function appendUnchecked(session: Session, event: SessionEvent): void { + const log = (session as unknown as { log: SessionEvent[] }).log + log.push(event) +} + +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', { + provenance: { + provider: value.config.provider, + model: value.config.model, + }, + 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) +} + +function expectSurfaceTotal(measurement: TokenMeasurement): void { + expect(measurement.nodes.reduce((total, node) => total + node.tokens, 0)) + .toBe(measurement.surfaceTokens) +} + +describe('TokenMeterService configuration and registration', () => { + it('provides one zero-config context window', () => { + const service = meter() + expect(service.contextWindow).toBe(128_000) + }) + + it('accepts one service-wide context-window override', () => { + expect(meter({ contextWindow: 32_000 }).contextWindow).toBe(32_000) + }) + + it.each(['models', 'contextWidow'])('rejects unknown top-level config key %s', (key) => { + expect(() => meter({ [key]: {} })) + .toThrow(`TokenMeterConfig: unknown key "${key}"`) + }) + + it.each([ + { contextWindow: 0 }, + { contextWindow: -1 }, + { contextWindow: 1.5 }, + { contextWindow: Number.NaN }, + { contextWindow: null }, + ] as unknown as TokenMeterConfig[])('rejects invalid context capacity %#', (config) => { + expect(() => meter(config)).toThrow(/contextWindow .* positive integer/) + }) + + 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('TokenMeterService pricing', () => { + it('prices every built-in content shape and merge-extended blocks with one fixed heuristic', () => { + const service = meter({ contextWindow: 100 }) + 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 = service.estimateMessage({ role: 'assistant', content: blocks }) + expect(estimated).toBeGreaterThan(30) + expect(service.estimateMessage(textMessage('abcd'))).toBe(9) + }) + + it('returns a detached deeply immutable empty measurement', () => { + const service = meter() + const session = new Session(SessionId('empty')) + const result = service.measure(session) + expect(result).toEqual({ + logRevision: 0, + baseline: { kind: 'none', tokens: 0 }, + surfaceDeltaTokens: 0, + totalTokens: 0, + surfaceTokens: 0, + nodes: [], + }) + expect(Object.isFrozen(result)).toBe(true) + expect(Object.isFrozen(result.baseline)).toBe(true) + expect(Object.isFrozen(result.nodes)).toBe(true) + expectSurfaceTotal(result) + expect(() => { + ;(result as { totalTokens: number }).totalTokens = 1 + }).toThrow(TypeError) + }) + + it('keeps an earlier unified snapshot detached from later replay', () => { + const service = meter() + const session = new Session(SessionId('detached')) + session.append('user/message', { + content: [{ type: 'text', text: 'first' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const snapshot = service.measure(session) + const snapshotCopy = structuredClone(snapshot) + expect(Object.isFrozen(snapshot.nodes)).toBe(true) + expect(Object.isFrozen(snapshot.nodes[0])).toBe(true) + expectSurfaceTotal(snapshot) + expect(() => { + ;(snapshot.nodes as Array<{ seq: number; tokens: number }>).push({ seq: 99, tokens: 1 }) + }).toThrow(TypeError) + expect(() => { + ;(snapshot.nodes[0] as { seq: number; tokens: number }).tokens = 1 + }).toThrow(TypeError) + + session.append('user/message', { + content: [{ type: 'text', text: 'second' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const advanced = service.measure(session) + expect(advanced.logRevision).toBe(2) + expect(advanced.nodes).toHaveLength(2) + expectSurfaceTotal(advanced) + expect(snapshot).toEqual(snapshotCopy) + expect(snapshot.logRevision).toBe(1) + expect(snapshot.nodes).toHaveLength(1) + }) + + it('prices header, prefix, tools, and surface when no reusable usage exists', () => { + const service = meter() + 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 = service.measure(session) + expect(result.baseline.kind).toBe('estimated') + expect(result.totalTokens).toBeGreaterThan(result.surfaceTokens) + expect(result.logRevision).toBe(session.events.length) + expectSurfaceTotal(result) + }) + + it('keeps request-header overrides out of the returned surface', () => { + const service = meter() + const session = new Session(SessionId('override-surface')) + session.append('user/message', { + content: [{ type: 'text', text: 'question' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + + const logged = service.measure(session) + const overridden = service.measure(session, header('another-model', { + system: 'large override '.repeat(100), + })) + expect(overridden.totalTokens).toBeGreaterThan(logged.totalTokens) + expect(overridden.surfaceTokens).toBe(logged.surfaceTokens) + expect(overridden.nodes).toEqual(logged.nodes) + expectSurfaceTotal(overridden) + }) +}) + +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 service = meter() + 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 = service.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('selects a heuristic anchor when provider usage would undercut its scale', () => { + const service = meter() + const session = new Session(SessionId('low-usage-anchor')) + const system = 'system context' + const requestHeader = header('deepseek-v4-flash', { system }) + appendSuccessfulCall(session, requestHeader, { + providerText: 'abcd'.repeat(512), + usage: { inputTokens: 20, outputTokens: 7 }, + }) + + const anchored = service.measure(session) + expect(anchored.baseline.kind).toBe('estimated') + const assistant = anchored.nodes[0]!.seq + session.append('user/message', { + content: [{ type: 'text', text: 'short' }], + source: { kind: 'plugin', plugin: 'test' }, + }, { + surfaceOp: { op: 'replace', start: assistant, end: assistant }, + sourceEventSeqs: [assistant], + }) + + const shrunken = service.measure(session) + expect(27 + shrunken.surfaceDeltaTokens).toBeLessThan(0) + expect(shrunken.totalTokens).toBeGreaterThan(0) + expect(shrunken.totalTokens).toBe(service.measure( + session, + header('different-model', { system }), + ).totalTokens) + }) + + it('uses an estimated anchor when provider usage is absent', () => { + const service = meter() + const session = new Session(SessionId('missing-usage')) + appendSuccessfulCall(session, header('deepseek-v4-flash', { system: 's' }), { + providerText: 'provider', + durableText: 'rewritten', + }) + const anchored = service.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 = service.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 service = meter() + expect(service.measure(explicit).surfaceDeltaTokens).toBeGreaterThan(0) + expect(service.measure(legacy).surfaceDeltaTokens).toBe(0) + }) + + it('keeps only the latest successful request anchor across model switches', () => { + const service = meter({ contextWindow: 1_000 }) + const session = new Session(SessionId('switch')) + const alphaHeader = header('alpha', { system: 'same envelope' }) + appendSuccessfulCall(session, alphaHeader, { usage: USAGE, providerText: 'alpha' }) + expect(service.measure(session).baseline).toMatchObject({ kind: 'usage', tokens: 34 }) + + appendSuccessfulCall(session, header('beta'), { + turn: 1, + step: 2, + usage: { inputTokens: 100, outputTokens: 50 }, + providerText: 'beta response', + }) + expect(service.measure(session).baseline).toMatchObject({ kind: 'usage', tokens: 150 }) + + appendHeader(session, alphaHeader) + const switchedBack = service.measure(session) + expect(switchedBack.baseline.kind).toBe('estimated') + expect(switchedBack.surfaceDeltaTokens).toBe(0) + }) + + it('invalidates usage for any canonical envelope change or explicit override', () => { + const service = meter() + const session = new Session(SessionId('envelope')) + const anchoredHeader = header('deepseek-v4-flash', { system: 'one' }) + appendSuccessfulCall(session, anchoredHeader, { usage: USAGE }) + expect(service.measure(session, { ...anchoredHeader, tools: [] }).baseline.kind).toBe('usage') + expect(service.measure(session, header('deepseek-v4-flash', { system: 'two' })).baseline.kind) + .toBe('estimated') + expect(service.measure(session, header('deepseek-v4-pro', { system: 'one' })).baseline.kind) + .toBe('estimated') + expect(service.measure(session, { + ...anchoredHeader, + config: { ...anchoredHeader.config, temperature: 0.2 }, + }).baseline.kind).toBe('estimated') + expect(service.measure(session, { + ...anchoredHeader, + messagePrefix: [textMessage('prefix')], + }).baseline.kind).toBe('estimated') + expect(service.measure(session, { + ...anchoredHeader, + tools: [{ name: 'read', description: 'read', parameters: { type: 'object' } }], + }).baseline.kind).toBe('estimated') + }) + + it('folds the latest full header snapshot into the effective envelope', () => { + const session = new Session(SessionId('header-snapshot')) + appendHeader(session, header('deepseek-v4-flash')) + session.append('request/header', { + header: header('deepseek-v4-pro'), + reason: 'change', + }) + const result = meter().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 before = service.measure(seeded) + expect(before.nodes).toHaveLength(2) + expect(before.surfaceDeltaTokens).toBeGreaterThan(0) + expectSurfaceTotal(before) + + const first = seeded.surface.nodes[0]! + 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 = service.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(after.surfaceDeltaTokens).toBeLessThan(0) + expectSurfaceTotal(after) + expect(before.nodes).toHaveLength(2) + expect(before.logRevision).toBe(original.events.length) + expect(before.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 measurement = meter().measure(session) + const assistant = session.events.find(event => event.type === 'assistant/message')! + expect(measurement.nodes).toEqual([{ seq: assistant.seq, tokens: 0 }]) + expect(measurement.surfaceTokens).toBe(0) + expectSurfaceTotal(measurement) + }) +}) + +describe('malformed replay and listener lifecycle', () => { + function expectRepeatedFailure(service: TokenMeterService, session: Session, pattern: RegExp): void { + expect(() => service.measure(session)).toThrow(pattern) + expect(() => service.measure(session)).toThrow(pattern) + } + + it('rejects an assistant without its step boundary transactionally', () => { + const session = new Session(SessionId('bad-step')) + appendHeader(session, header('deepseek-v4-flash')) + session.append('assistant/message', { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [{ type: 'text', text: 'bad' }], + }, { surfaceOp: 'append', sourceEventSeqs: [] }) + expectRepeatedFailure(meter(), 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(), + 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', { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [], + }, { surfaceOp: 'append', sourceEventSeqs: [] }) + expectRepeatedFailure( + meter(), + 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(), + 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', { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [{ type: 'text', text: 'bad' }], + usage: { inputTokens: 1, outputTokens: 1 }, + }, { surfaceOp: 'append', sourceEventSeqs }) + expect(() => meter().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 + appendUnchecked(duplicate, { + type: 'assistant/message', + seq: duplicate.seq, + time: 0, + data: { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [], + usage: { inputTokens: 1, outputTokens: 0 }, + }, + surfaceOp: 'append', + sourceEventSeqs: [source, source], + }) + expect(() => meter().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')) + appendUnchecked(future, { + type: 'assistant/message', + seq: future.seq, + time: 0, + data: { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [], + usage: { inputTokens: 1, outputTokens: 0 }, + }, + surfaceOp: 'append', + sourceEventSeqs: [99], + }) + expect(() => meter().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', { + provenance: { provider: 'mock', model: 'deepseek-v4-flash' }, + turn: 1, + step: 1, + content: [{ type: 'text', text: 'replacement' }], + }, { surfaceOp: { op: 'replace', start: head, end: head }, sourceEventSeqs: [head] }) + expectRepeatedFailure( + meter(), + session, + /no matching step\/start/, + ) + }) + + it('rejects corrupt replacement ranges without advancing the replay cursor', () => { + const session = new Session(SessionId('bad-replace')) + const head = session.append('user/message', { + content: [{ type: 'text', text: 'head' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }).seq + appendUnchecked(session, { + type: 'user/message', + seq: session.seq, + time: 0, + data: { + content: [{ type: 'text', text: 'bad' }], + source: { kind: 'user' }, + }, + surfaceOp: { op: 'replace', start: 99, end: 99 }, + sourceEventSeqs: [head], + }) + expectRepeatedFailure(meter(), 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 activeMeter: TokenMeterService | undefined + const revisions: number[] = [] + ctx.on('session/event', (session) => { + if (activeMeter !== undefined) revisions.push(activeMeter.measure(session).logRevision) + }) + const firstFiber = await ctx.plugin(TokenMeterService) + activeMeter = ctx.tokenMeter + const session = ctx.sessions.create(SessionId('listener-order')) + activeMeter.measure(session) + session.append('user/message', { + content: [{ type: 'text', text: 'one' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + expect(revisions).toEqual([1]) + expect(activeMeter.measure(session).logRevision).toBe(1) + + await firstFiber.dispose() + const secondFiber = await ctx.plugin(TokenMeterService) + activeMeter = ctx.tokenMeter + expect(activeMeter.measure(session).logRevision).toBe(1) + await secondFiber.dispose() + }) +}) diff --git a/packages/llm/token-meter/tsconfig.json b/packages/llm/token-meter/tsconfig.json new file mode 100644 index 0000000000..5e1604e02f --- /dev/null +++ b/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" + } + ] +} diff --git a/packages/mcp/mcp-client/tests/fixture-server.ts b/packages/mcp/mcp-client/tests/fixture-server.ts index d127412736..8491b96634 100644 --- a/packages/mcp/mcp-client/tests/fixture-server.ts +++ b/packages/mcp/mcp-client/tests/fixture-server.ts @@ -2,7 +2,7 @@ * Minimal MCP server over stdio for e2e testing of the dsh-mcp-client plugin. * Registers controlled tools with predictable behavior for asserting edge cases. * - * Run: node --import tsx fixture-server.ts + * Run: node fixture-server.ts */ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js' diff --git a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts index 686d51acea..dc783b3edf 100644 --- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts +++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts @@ -26,9 +26,7 @@ import { apply } from '@deepseek-ai/dsh-mcp-client/src/index.ts' import { publicToolName } from '@deepseek-ai/dsh-mcp-client/src/tools.ts' import type { Config } from '@deepseek-ai/dsh-mcp-client' -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const fixtureServerPath = fileURLToPath(new URL('./fixture-server.ts', import.meta.url)) -const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) // Resolve package-local .bin for pnpm-hoisted MCP server binaries. const packageDir = fileURLToPath(new URL('..', import.meta.url)) @@ -86,8 +84,8 @@ describe('fixture server — controlled scenarios', () => { transport: 'stdio', serverName: 'fixture', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, } @@ -170,8 +168,8 @@ describe('fixture server — duplicate serverName', () => { transport: 'stdio', serverName: 'dup', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, } @@ -191,8 +189,8 @@ describe('fixture server — disposal', () => { transport: 'stdio', serverName: 'fixture', command: process.execPath, - args: ['--import', tsxLoader, fixtureServerPath], - env: { TSX_TSCONFIG_PATH: repoTsconfig }, + args: [fixtureServerPath], + env: {}, cwd: packageDir, toolCallTimeoutMs: 15_000, }) diff --git a/packages/sdk/helper/package.json b/packages/sdk/helper/package.json index 1452a1dbee..8d95dafe66 100644 --- a/packages/sdk/helper/package.json +++ b/packages/sdk/helper/package.json @@ -33,7 +33,6 @@ }, "devDependencies": { "@deepseek-ai/dsh-brand": "workspace:^", - "@deepseek-ai/dsh-compact-basic": "workspace:^", "@deepseek-ai/dsh-hooks-claude": "workspace:^", "@deepseek-ai/dsh-hooks-codex": "workspace:^", "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^", diff --git a/packages/sdk/helper/src/features/builtin/index.ts b/packages/sdk/helper/src/features/builtin/index.ts index 85a0d82eac..c4043e7d59 100644 --- a/packages/sdk/helper/src/features/builtin/index.ts +++ b/packages/sdk/helper/src/features/builtin/index.ts @@ -5,7 +5,6 @@ * @module @deepseek-ai/dsh-helper/features/builtin */ -import type { BasicCompactConfig } from '@deepseek-ai/dsh-compact-basic' import type { Config as ClaudeHooksConfig } from '@deepseek-ai/dsh-hooks-claude' import type { Config as CodexHooksConfig } from '@deepseek-ai/dsh-hooks-codex' import type { Config as JsonlConfig } from '@deepseek-ai/dsh-session-persistence-jsonl' @@ -19,16 +18,6 @@ import { AppFeature } from './app.ts' import { ProviderFeature } from './provider.ts' import { SpineFeature } from './spine.ts' -const compactPreset = { - contextWindow: 128_000, - thresholdRatio: 0.8, - retainTokens: 20_480, - summarizationProvider: '', - summarizationModel: '', - maxTokens: 8_192, - compactionRetries: 1, -} satisfies BasicCompactConfig - /** * Build and definition-check the complete builtin set for one project profile. * @param profile - project context used to validate conditional contributions. @@ -275,12 +264,18 @@ config: id: 'basic', label: 'Basic compaction', default: true, - resources: [{ - kind: 'npm-cordis-config-entry', - id: 'compact-basic', - package: '@deepseek-ai/dsh-compact-basic', - config: compactPreset, - }], + resources: [ + { + kind: 'npm-cordis-config-entry', + id: 'token-meter', + package: '@deepseek-ai/dsh-token-meter', + }, + { + kind: 'npm-cordis-config-entry', + id: 'compact-basic', + package: '@deepseek-ai/dsh-compact-basic', + }, + ], }], }, { diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts index 3e4aec1e97..4b279e3c6e 100644 --- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts @@ -6,7 +6,7 @@ import { isAbsolute, join, relative, resolve } from 'node:path' import SessionStore, { SessionId } from '@deepseek-ai/dsh-session' import type { Session, SessionEvent, SessionHeader } from '@deepseek-ai/dsh-session' import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl' -import { encodeSegment, logPath, scanLog, sessionDir } from '../src/format.ts' +import { encodeSegment, logPath, scanLog, sessionDir, toHeaderLine } from '../src/format.ts' import { runPersistenceContract, meta, oneTurnLog, appendLog } from '../../session-persistence/tests/contract.ts' import { runCoordinatorContract, type CoordinatorFixture } from '../../session-persistence/tests/coordinator-contract.ts' @@ -194,6 +194,40 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => { expect(loaded.events).toEqual(log) // chunks preserved, contiguous seqs }) + it('rejects a stored v0 log containing a legacy request/header-delta event', async () => { + const m = meta('legacy-header-delta', '/legacy') + const path = logPath(root, m.cwd, m.id) + await mkdir(sessionDir(root, m.cwd), { recursive: true }) + await writeFile(path, [ + JSON.stringify(toHeaderLine(m)), + JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } } }), + JSON.stringify({ type: 'request/header-delta', seq: 1, time: 2, data: { config: { model: 'legacy' } } }), + JSON.stringify({ type: 'turn/end', seq: 2, time: 3, data: { turn: 1, reason: { kind: 'completed' } } }), + '', + ].join('\n')) + + await expect(ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported legacy request\/header-delta event at seq 1/) + }) + + it('rejects a stored v0 full header carrying the legacy fallback reason', async () => { + const m = meta('legacy-header-fallback', '/legacy') + const path = logPath(root, m.cwd, m.id) + await mkdir(sessionDir(root, m.cwd), { recursive: true }) + await writeFile(path, [ + JSON.stringify(toHeaderLine(m)), + JSON.stringify({ + type: 'request/header', + seq: 0, + time: 1, + data: { header: { config: { model: 'legacy' } }, reason: 'fallback' }, + }), + '', + ].join('\n')) + + await expect(ctx.sessionPersistence.load(m.id)) + .rejects.toThrow(/unsupported legacy request\/header reason "fallback" at seq 0/) + }) + it('persists a forked child seed through the existing session write path', async () => { const source = ctx.sessions.create(SessionId('persist-parent'), { meta: { cwd: '/workspace' } }) appendClosedTurn(source) diff --git a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts index 0e3ffb65f1..a728cc0b71 100644 --- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts +++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts @@ -153,6 +153,42 @@ describe('scanRows', () => { }) describe('SessionPersistenceSqlite: durability and crash semantics', () => { + it('rejects a stored v0 log containing a legacy request/header-delta event', async () => { + const path = await freshDbPath() + const m = meta('legacy-header-delta', '/legacy') + const db = openDatabase(path, 'wal') + db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)') + .run(m.id, m.version, m.createdAt, m.cwd ?? null) + const insert = db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)') + insert.run(m.id, 0, 'turn/start', 1, JSON.stringify({ turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })) + insert.run(m.id, 1, 'request/header-delta', 2, JSON.stringify({ config: { model: 'legacy' } })) + insert.run(m.id, 2, 'turn/end', 3, JSON.stringify({ turn: 1, reason: { kind: 'completed' } })) + db.close() + + const mounted = await backend(path) + await expect(mounted.ctx.sessionPersistence.load(m.id)).rejects.toThrow(/unsupported legacy request\/header-delta event at seq 1/) + await mounted.dispose() + }) + + it('rejects a stored v0 full header carrying the legacy fallback reason', async () => { + const path = await freshDbPath() + const m = meta('legacy-header-fallback', '/legacy') + const db = openDatabase(path, 'wal') + db.prepare('INSERT INTO sessions (id, version, created_at, cwd, parent_session, seed_length) VALUES (?, ?, ?, ?, NULL, NULL)') + .run(m.id, m.version, m.createdAt, m.cwd ?? null) + db.prepare('INSERT INTO events (session_id, seq, type, time, data) VALUES (?, ?, ?, ?, ?)') + .run(m.id, 0, 'request/header', 1, JSON.stringify({ + header: { config: { model: 'legacy' } }, + reason: 'fallback', + })) + db.close() + + const mounted = await backend(path) + await expect(mounted.ctx.sessionPersistence.load(m.id)) + .rejects.toThrow(/unsupported legacy request\/header reason "fallback" at seq 0/) + await mounted.dispose() + }) + it('has no independent per-session log location', async () => { const { ctx, dispose } = await backend() expect(ctx.sessionPersistence.locate(meta('sqlite-location'))).toBeUndefined() diff --git a/packages/session-persistence/session-persistence/src/coordinator.ts b/packages/session-persistence/session-persistence/src/coordinator.ts index 686b9790d4..beb5fca483 100644 --- a/packages/session-persistence/session-persistence/src/coordinator.ts +++ b/packages/session-persistence/session-persistence/src/coordinator.ts @@ -118,6 +118,20 @@ function seedCoversPrefix(seed: readonly SessionEvent[], prefix: readonly Sessio }) } +/** Reject events from an obsolete v0 vocabulary that this build cannot replay. */ +function assertSupportedEvents(events: readonly SessionEvent[], id: SessionId): void { + const legacyType: string = 'request/header-delta' + const legacy = events.find(event => event.type === legacyType) + if (legacy !== undefined) { + throw new Error(`session "${id}" contains unsupported legacy request/header-delta event at seq ${legacy.seq}`) + } + const fallback = events.find(event => event.type === 'request/header' + && (event.data as { reason?: string }).reason === 'fallback') + if (fallback !== undefined) { + throw new Error(`session "${id}" contains unsupported legacy request/header reason "fallback" at seq ${fallback.seq}`) + } +} + /** * Owns the backend-agnostic session write-path orchestration. A backend * constructs one (`new PersistenceCoordinator(ctx, this)`), implements @@ -207,6 +221,11 @@ export class PersistenceCoordinator { } private async appendCore(id: SessionId, events: readonly SessionEvent[]): Promise { + // Every append route converges here: the public service, live write-behind + // drains, and HMR seed/suffix adoption. Keep vocabulary rejection at that + // shared boundary so a stale JavaScript plugin cannot persist an event that + // this same backend will refuse to load. + assertSupportedEvents(events, id) if (events.length === 0) return let state = this.states.get(id) if (state === undefined) state = await this.adopt(id) // calls loadCore, not load @@ -241,6 +260,7 @@ export class PersistenceCoordinator { if (stored === undefined) throw new Error(`session "${id}" not found`) const { meta, events, tornMarker } = stored this.assertVersion(meta) + assertSupportedEvents(events, id) // Preserve complete interrupted events and synthesize only missing closers. const closers = interruptedTurnClosers(events) @@ -509,6 +529,7 @@ export class PersistenceCoordinator { private async adoptLivePrefix(session: Session, seed: readonly SessionEvent[], stored: StoredPrefix): Promise { const { meta, events, tornMarker } = stored this.assertVersion(meta) + assertSupportedEvents(events, session.header.id) if (!seedCoversPrefix(seed, events)) { throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`) } diff --git a/packages/session-persistence/session-persistence/tests/persistence.spec.ts b/packages/session-persistence/session-persistence/tests/persistence.spec.ts index 767e323514..e083ac3543 100644 --- a/packages/session-persistence/session-persistence/tests/persistence.spec.ts +++ b/packages/session-persistence/session-persistence/tests/persistence.spec.ts @@ -12,6 +12,26 @@ import { runCoordinatorContract, type CoordinatorFixture } from './coordinator-c /** The durable store shape: materialized sessions only (no lazy entries). */ type MemoryStore = Map +/** An obsolete event fixture that emulates an untyped pre-change producer. */ +function legacyHeaderDelta(seq = 0): SessionEvent { + return { + type: 'request/header-delta', + seq, + time: 1, + data: { config: { model: 'legacy' } }, + } as unknown as SessionEvent +} + +/** An obsolete full-header reason fixture from the removed delta codec. */ +function legacyFallbackHeader(seq = 0): SessionEvent { + return { + type: 'request/header', + seq, + time: 1, + data: { header: { config: { model: 'legacy' } }, reason: 'fallback' }, + } as unknown as SessionEvent +} + /** Optional plugin config: an EXTERNAL store shared across backend instances. */ interface MemoryConfig { store?: MemoryStore } @@ -432,6 +452,64 @@ describe('SessionPersistence service registration', () => { await fiber.dispose() }) + it('rejects a legacy header delta from a pre-change live producer', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + const fiber = await ctx.plugin(MemoryPersistence) + const session = ctx.sessions.create(SessionId('legacy-live'), { meta: { cwd: '/legacy' } }) + // Model the runtime shape available to JavaScript or a hot-loaded plugin + // compiled against the obsolete event vocabulary. + const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent + expect(() => appendLegacy('request/header-delta', { config: { model: 'legacy' } })) + .toThrow(/unsupported legacy request\/header-delta format/) + expect(session.events).toHaveLength(0) + await fiber.dispose() + }) + + it('rejects a legacy fallback header buffered by a pre-change live producer', async () => { + const ctx = new Context() + await ctx.plugin(SessionStore) + const fiber = await ctx.plugin(MemoryPersistence) + const session = ctx.sessions.create(SessionId('legacy-fallback-live'), { meta: { cwd: '/legacy' } }) + const appendLegacy = session.append.bind(session) as (type: string, data: unknown) => SessionEvent + + expect(() => appendLegacy('request/header', legacyFallbackHeader().data)) + .toThrow('unsupported legacy request/header reason "fallback"') + expect(session.events).toHaveLength(0) + await fiber.dispose() + }) + + it('rejects a legacy stored prefix during live HMR adoption', async () => { + const id = SessionId('legacy-hmr') + const m = meta(id, '/legacy') + const legacy = legacyHeaderDelta() + const store: MemoryStore = new Map([[id, { meta: m, events: [legacy] }]]) + const ctx = new Context() + await ctx.plugin(SessionStore) + // A current live session cannot carry the obsolete event in its seed, but + // HMR still has to identify the persisted prefix as unsupported rather than + // treating it as an ordinary live-prefix collision. + const session = ctx.sessions.create(id, { meta: { cwd: '/legacy' } }) + const fiber = await ctx.plugin(MemoryPersistence, { store }) + + await expect(ctx.sessions.flush(session)) + .rejects.toThrow(/unsupported legacy request\/header-delta event at seq 0/) + await Promise.allSettled([fiber.dispose()]) + }) + + it('rejects a stored legacy fallback header during load', async () => { + const id = SessionId('legacy-fallback-load') + const m = meta(id, '/legacy') + const store: MemoryStore = new Map([[id, { meta: m, events: [legacyFallbackHeader()] }]]) + const ctx = new Context() + await ctx.plugin(SessionStore) + const fiber = await ctx.plugin(MemoryPersistence, { store }) + + await expect(ctx.sessionPersistence.load(id)) + .rejects.toThrow('unsupported legacy request/header reason "fallback" at seq 0') + await fiber.dispose() + }) + it('retires all coordinator bookkeeping for disposed sessions', async () => { const ctx = new Context() await ctx.plugin(SessionStore) diff --git a/packages/session-query/session-query/src/tracing.ts b/packages/session-query/session-query/src/tracing.ts index 2f422d6c26..82d9f12852 100644 --- a/packages/session-query/session-query/src/tracing.ts +++ b/packages/session-query/session-query/src/tracing.ts @@ -162,7 +162,7 @@ function analyzeEventLog( { cause: error }, ) } - const current = new Set(folded.nodes.map(node => node.seq)) + const current = new Set(folded.nodes) const replacedBy = new Map() const replacedEventSeqs = new Map() for (const replacement of folded.replacements) { diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json index 5093e3df40..ec55845f91 100644 --- a/packages/subagent/subagent-acp/package.json +++ b/packages/subagent/subagent-acp/package.json @@ -35,6 +35,7 @@ "devDependencies": { "@deepseek-ai/dsh-agent": "workspace:^", "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-loader-smoke": "workspace:^", "@deepseek-ai/dsh-subagent": "workspace:^", "@deepseek-ai/dsh-subagent-subprocess": "workspace:^", "@cordisjs/plugin-loader": "^1.0.0-rc.5", diff --git a/packages/subagent/subagent-acp/tests/mock-acp-server.ts b/packages/subagent/subagent-acp/tests/mock-acp-server.ts index 000f6d49f0..1496f882aa 100644 --- a/packages/subagent/subagent-acp/tests/mock-acp-server.ts +++ b/packages/subagent/subagent-acp/tests/mock-acp-server.ts @@ -2,8 +2,8 @@ * Minimal no-network ACP child process for keyless backend tests. Environment variables script its * text and stop reason, a cancel-cooperative or cancel-ignoring hang, permission requests, and a * readiness marker. Disposal fixtures can delay an EOF flush, ignore EOF but exit and mark - * SIGTERM, or trap SIGTERM to require SIGKILL. The specs spawn this non-test module under tsx with - * an explicit tsconfig, mirroring real example boot. + * SIGTERM, or trap SIGTERM to require SIGKILL. The specs run this protocol-only fixture directly + * with Node's type stripping; it imports no harness code or workspace paths. * @module @deepseek-ai/dsh-subagent-acp/tests/mock-acp-server */ diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts index 0c20b27fa1..688b1c44aa 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts @@ -6,6 +6,7 @@ import { afterEach, describe, expect, it } from 'vitest' import { Context } from 'cordis' import type { Agent } from '@deepseek-ai/dsh-agent' import SubagentService from '@deepseek-ai/dsh-subagent' +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' import * as acp from '../src/index.ts' /** @@ -17,9 +18,22 @@ import * as acp from '../src/index.ts' // The real acp-agent example: its bin + cordis.yml (the live DeepSeek config). const binScript = fileURLToPath(new URL('../../../examples/acp-demo/src/bin.ts', import.meta.url)) const exampleConfig = fileURLToPath(new URL('../../../../examples/acp-agent/cordis.yml', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) +// How to launch the child acp-agent (src via tsx / lib via plain node, per DSH_EXAMPLE_MODE). +// buildChildEnv scrubs ambient creds but keeps these extras, so the model key is +// forwarded explicitly; TSX_TSCONFIG_PATH is added by the resolver in src mode only. +const childLaunch = resolveExampleLaunch({ + srcBin: binScript, + configArgs: ['--config', exampleConfig], + tsconfigPath: repoTsconfig, + env: { + ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, + ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, + DSH_PERMISSION_MODE: 'danger-full-access', + }, +}) + /** The ACP backend ignores the parent, but the seam requires one. */ const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent @@ -40,18 +54,11 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive await ctx.plugin(SubagentService) await ctx.plugin(acp, { providerName: 'acp', - command: process.execPath, - args: ['--import', tsxLoader, binScript, '--config', exampleConfig], + command: childLaunch.command, + args: childLaunch.args, cwd: workdir, permission: 'reject', - // The child harness needs the key to reach the model; forward it - // explicitly (buildChildEnv scrubs ambient creds but keeps these extras). - env: { - ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, - ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - }, + env: childLaunch.env as Record, }) const run = await ctx.subagents.start('acp', { @@ -76,17 +83,12 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('ACP backend with-key e2e (drive await ctx.plugin(SubagentService) await ctx.plugin(acp, { providerName: 'acp', - command: process.execPath, - args: ['--import', tsxLoader, binScript, '--config', exampleConfig], + command: childLaunch.command, + args: childLaunch.args, cwd: workdir, // The child needs to act (run bash), so approve its permission prompts. permission: 'allow', - env: { - ...process.env.DEEPSEEK_API_KEY !== undefined ? { DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY } : {}, - ...process.env.DEEPSEEK_BASE_URL !== undefined ? { DEEPSEEK_BASE_URL: process.env.DEEPSEEK_BASE_URL } : {}, - TSX_TSCONFIG_PATH: repoTsconfig, - DSH_PERMISSION_MODE: 'danger-full-access', - }, + env: childLaunch.env as Record, }) const run = await ctx.subagents.start('acp', { diff --git a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts index eed3cfe1ed..bfc8476bae 100644 --- a/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts +++ b/packages/subagent/subagent-acp/tests/subagent-acp.spec.ts @@ -21,8 +21,6 @@ import { acpStopReason, acpContentText, DEFAULT_DISPOSE_EOF_GRACE_MS, DEFAULT_DI */ const mockServer = fileURLToPath(new URL('./mock-acp-server.ts', import.meta.url)) -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) -const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)) /** A throwaway parent Agent — the ACP backend ignores it, but the seam requires one. */ const fakeParent = { id: 'parent', session: { header: {} } } as unknown as Agent @@ -46,11 +44,9 @@ async function setup(mockEnv: SetupEnv = {}, permission: 'allow' | 'reject' = 'r await ctx.plugin(acp, { providerName: 'acp', command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], permission, - // The mock-server scripting vars must reach the child; TSX_TSCONFIG_PATH lets - // tsx resolve @deepseek-ai/* from a child cwd outside the repo. - env: { ...mockEnv, TSX_TSCONFIG_PATH: repoTsconfig }, + env: mockEnv, }) return ctx } @@ -197,10 +193,10 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready }, // Short on BOTH tiers: the trap ignores EOF and SIGTERM, so dispose must // burn the EOF window, then the SIGTERM window, then SIGKILL — keep each // small so the whole ladder finishes well within the 4000ms bound. @@ -240,7 +236,7 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', // MOCK_HANG so the prompt never resolves on its own — we tear down a live @@ -249,7 +245,7 @@ describe('dsh-subagent-acp', () => { // wider grace. env: { MOCK_HANG: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, - MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400', TSX_TSCONFIG_PATH: repoTsconfig, + MOCK_FLUSH_ON_EOF: flushed, MOCK_FLUSH_DELAY_MS: '400', }, disposeEofGraceMs: 2000, disposeGraceMs: 50, @@ -280,12 +276,12 @@ describe('dsh-subagent-acp', () => { try { const spec: AcpRunSpec = { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', env: { MOCK_HANG: '1', MOCK_IGNORE_EOF: '1', MOCK_TEXT: 'x', - MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, TSX_TSCONFIG_PATH: repoTsconfig, + MOCK_READY_FILE: ready, MOCK_SIGTERM_FILE: sigterm, }, // Tiny EOF grace so the ignored-EOF window elapses fast, then SIGTERM. disposeEofGraceMs: 150, @@ -404,9 +400,9 @@ describe('dsh-subagent-acp', () => { await ctx.plugin(acp, { providerName: 'acp', command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], permission: 'reject', - env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready, TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_TRAP_SIGTERM: '1', MOCK_TEXT: 'x', MOCK_READY_FILE: ready }, disposeEofGraceMs: 150, disposeGraceMs: 150, }) @@ -455,10 +451,10 @@ describe('dsh-subagent-acp', () => { request(), { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_CRASH_ON_PROMPT: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, onError: (error, stopReason) => { errors.push({ message: error.message, stopReason }) }, @@ -493,10 +489,10 @@ describe('dsh-subagent-acp', () => { request(), { command: process.execPath, - args: ['--import', tsxLoader, mockServer], + args: [mockServer], cwd: process.cwd(), permission: 'reject', - env: { MOCK_CRASH_ON_PROMPT: '1', TSX_TSCONFIG_PATH: repoTsconfig }, + env: { MOCK_CRASH_ON_PROMPT: '1' }, disposeEofGraceMs: DEFAULT_DISPOSE_EOF_GRACE_MS, disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS, onError: () => { throw new Error('sink boom') }, diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json index e415ace1de..5aa28528ac 100644 --- a/packages/subagent/subagent-acp/tsconfig.json +++ b/packages/subagent/subagent-acp/tsconfig.json @@ -28,6 +28,9 @@ }, { "path": "../subagent-subprocess" + }, + { + "path": "../../support/loader-smoke" } ] } diff --git a/packages/support/acp-snapshot/README.md b/packages/support/acp-snapshot/README.md index 55e9aadf4d..222d572043 100644 --- a/packages/support/acp-snapshot/README.md +++ b/packages/support/acp-snapshot/README.md @@ -35,7 +35,7 @@ defineAcpSnapshotSuite({ }) ``` -A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized composed prompt in generated `system-prompt.golden.md` and the initial schemas plus schema deltas in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. +A scenario booting a differently-composed tree sets its own `configPath` (an overlay whose basename still ends in `cordis.yml`, so the bin's replay swap finds the sibling `*cordis.snapshot.yml`) and, when that composition changes the request header, its own `headerClass` with its own pinning scenario — the acp-agent example's Code Mode and filesystem scenarios are templates. Each pinning directory stores the normalized full prompt sequence in generated `system-prompt.golden.md` and the corresponding full tool-schema sequence in generated `tool-schemas.golden.json`; `session.jsonl` stores `"system":"{{system}}","tools":"{{tools}}"` while retaining config, reason, and any model-visible prefix. A pin with legitimate mid-run header changes declares `expectedHeaderChanges`, which fixes the length of both sidecar sequences. Examples use a `cordis.snapshot.yml` overlay with [`dsh-llm-replay`](../llm-replay/README.md). Recording calls the live model and updates model fixtures; keyless refresh replays those fixtures and updates derived stdout, session-log, prompt, and tool-schema snapshots. See the [snapshot RFC](../../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md). diff --git a/packages/support/acp-snapshot/package.json b/packages/support/acp-snapshot/package.json index d206b08161..eb6b46deaf 100644 --- a/packages/support/acp-snapshot/package.json +++ b/packages/support/acp-snapshot/package.json @@ -23,7 +23,7 @@ "license": "BSD-3-Clause", "dependencies": { "@agentclientprotocol/sdk": "0.25.1", - "tsx": "^4.22.4", + "@deepseek-ai/dsh-loader-smoke": "workspace:*", "vitest": "^4.1.8" }, "peerDependencies": { diff --git a/packages/support/acp-snapshot/src/harness.ts b/packages/support/acp-snapshot/src/harness.ts index c26cb84299..e2072b6b17 100644 --- a/packages/support/acp-snapshot/src/harness.ts +++ b/packages/support/acp-snapshot/src/harness.ts @@ -11,7 +11,6 @@ import { cp, mkdtemp, readFile, readdir, rm } from 'node:fs/promises' import { existsSync } from 'node:fs' import { tmpdir } from 'node:os' import { join, delimiter } from 'node:path' -import { fileURLToPath } from 'node:url' import { Readable, Writable } from 'node:stream' import { ClientSideConnection, @@ -23,12 +22,7 @@ import { type RequestPermissionResponse, type SessionNotification, } from '@agentclientprotocol/sdk' - -// Resolve tsx's ESM loader to an ABSOLUTE path once: the child runs with its -// cwd in a temp dir OUTSIDE the repo, where a bare `--import tsx` would not -// resolve from node_modules. import.meta.resolve gives this package's tsx -// regardless of the child cwd. -const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke' /** * The agent composition a scenario runs against: which bin to boot and which @@ -37,8 +31,10 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) * them from its own `import.meta.url`. */ export interface AgentUnderTest { - /** The agent bin entry (e.g. `packages/examples/acp-demo/src/bin.ts`), run unbuilt via tsx. */ + /** The agent bin's SOURCE entry (e.g. `packages/examples/acp-demo/src/bin.ts`); the `lib` bin is derived from it. */ binScript: string + /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */ + libBinScript?: string | undefined /** * The example's live `cordis.yml`. Under `DSH_SNAPSHOT=replay` the bin swaps * it for the sibling `cordis.snapshot.yml` (the keyless replay overlay), so @@ -47,10 +43,8 @@ export interface AgentUnderTest { configPath: string /** * The repo-root tsconfig whose `paths` map resolves the unbuilt workspace - * imports. Passed to the child as `TSX_TSCONFIG_PATH`: tsx finds a tsconfig - * by searching UP from the child's cwd — a temp dir outside the repo — so - * without the explicit pin the dsh-* imports fail before the bin writes a - * byte. + * imports in `src` mode (passed to the child as `TSX_TSCONFIG_PATH`). Ignored + * in `lib` mode, where the example resolves plugins through real `exports`. */ tsconfigPath: string } @@ -184,25 +178,32 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise if (opts.workspaceDir !== undefined && existsSync(opts.workspaceDir)) { await cp(opts.workspaceDir, cwd, { recursive: true }) } - const env: NodeJS.ProcessEnv = { - ...process.env, - TSX_TSCONFIG_PATH: opts.agent.tsconfigPath, - DSH_SNAPSHOT: opts.mode, - DSH_SNAPSHOT_FILE: opts.fixtureFile, - DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot, - DSH_SNAPSHOT_SPILL_ROOT: spillRoot, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {}, - ...opts.childFiles !== undefined && opts.childFiles.length > 0 - ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) } - : {}, - } + // Boot the agent in the environment's mode (DSH_EXAMPLE_MODE): `src` runs the + // source bin under tsx with the paths map; `lib` runs the built bin under plain + // Node, resolving plugins through the example's workspace node_modules → lib. + const launch = resolveExampleLaunch({ + srcBin: opts.agent.binScript, + libBin: opts.agent.libBinScript, + configArgs: ['--config', opts.configPath ?? opts.agent.configPath], + tsconfigPath: opts.agent.tsconfigPath, + env: { + DSH_SNAPSHOT: opts.mode, + DSH_SNAPSHOT_FILE: opts.fixtureFile, + DSH_SNAPSHOT_SESSIONS_ROOT: sessionsRoot, + DSH_SNAPSHOT_SPILL_ROOT: spillRoot, + DSH_HOME: join(cwd, '.dsh'), + DSH_AGENTS_HOME: join(cwd, '.agents'), + ...opts.overrideFile !== undefined ? { DSH_SNAPSHOT_OVERRIDE: opts.overrideFile } : {}, + ...opts.childFiles !== undefined && opts.childFiles.length > 0 + ? { DSH_SNAPSHOT_CHILD_FILES: opts.childFiles.join(delimiter) } + : {}, + }, + }) child = spawn( - process.execPath, - ['--import', tsxLoader, opts.agent.binScript, '--config', opts.configPath ?? opts.agent.configPath], - { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }, + launch.command, + launch.args, + { cwd, env: { ...process.env, ...launch.env }, stdio: ['pipe', 'pipe', 'pipe'] }, ) child.stderr.setEncoding('utf8') diff --git a/packages/support/acp-snapshot/src/normalize.ts b/packages/support/acp-snapshot/src/normalize.ts index 591053798e..48761864f0 100644 --- a/packages/support/acp-snapshot/src/normalize.ts +++ b/packages/support/acp-snapshot/src/normalize.ts @@ -125,8 +125,8 @@ export function normalizeSessionLog(rawLog: string, ctx: NormalizeContext): stri } /** - * Replace system-prompt content in request headers and header deltas with - * `{{system}}` tokens while retaining field presence and delta structure. + * Replace system-prompt content in request headers with `{{system}}` tokens + * while retaining field presence. * Other header content stays verbatim, so a header-pinning fixture can keep * its complete tool schemas while every JSONL fixture omits the prompt text. * Lines without a system payload pass through byte-for-byte; the transform is @@ -140,11 +140,11 @@ export function scrubSystemPrompts(rawLog: string): string { } /** - * Replace tool schemas in request headers and header deltas with `{{tools}}` - * tokens while retaining field presence, tool names, and delta structure. - * System prompts and session-prefix messages stay verbatim so pinning fixtures - * can move only schema bulk into their dedicated JSON sidecar. Lines without a - * tool payload pass through byte-for-byte; the transform is idempotent. + * Replace tool schemas in full request-header snapshots with `{{tools}}` + * tokens while retaining field presence. System prompts and session-prefix + * messages stay verbatim so pinning fixtures can move only schema bulk into + * their dedicated JSON sidecar. Lines without a tool payload pass through + * byte-for-byte; the transform is idempotent. * * @param rawLog The raw session `.jsonl` content. * @returns The JSONL with tool-schema content tokenized. @@ -157,9 +157,9 @@ export function scrubToolSchemas(rawLog: string): string { * Replace all bulky request-header content in a session JSONL with stable * tokens. This includes the system-prompt fields handled by * {@link scrubSystemPrompts}, tool schemas, and session-prefix messages. It - * keeps system-delta line positions and arity, tool-delta names, prefix - * message counts, field presence, config, and reason. Lines without content - * to scrub pass through byte-for-byte, and the transform is idempotent. + * keeps prefix message counts, field presence, config, and reason. Lines + * without content to scrub pass through byte-for-byte, and the transform is + * idempotent. * * @param rawLog The raw session `.jsonl` content. * @returns The JSONL with all header bulk tokenized, other lines byte-identical. @@ -195,33 +195,7 @@ function scrubHeaderContent(rawLog: string, options: HeaderScrubOptions): string } return touched ? JSON.stringify(record) : line } - if (record.type === 'request/header-delta') { - let touched = false - const system = data.system as Record | null | undefined - if (options.system === true && system !== null && typeof system === 'object' && Array.isArray(system.insert)) { - system.insert = system.insert.map(() => SYSTEM) - touched = true - } - const tools = data.tools as Record | null | undefined - if (options.tools === true && tools !== null && typeof tools === 'object') { - if (Array.isArray(tools.added)) { tools.added = tools.added.map(scrubToolSchema); touched = true } - if (Array.isArray(tools.changed)) { tools.changed = tools.changed.map(scrubToolSchema); touched = true } - } - if (options.prefix === true && Array.isArray(data.messagePrefix)) { - data.messagePrefix = data.messagePrefix.map(() => MESSAGE_PREFIX) - touched = true - } - return touched ? JSON.stringify(record) : line - } return line }) return out.join('\n') } - -/** Tokenize one tool schema's bulk (description, parameters, anything else), keeping its identifying `name`. */ -function scrubToolSchema(tool: unknown): unknown { - if (tool === null || typeof tool !== 'object' || Array.isArray(tool)) return tool - const out: Record = {} - for (const [k, v] of Object.entries(tool)) out[k] = k === 'name' ? v : TOOLS - return out -} diff --git a/packages/support/acp-snapshot/src/suite.ts b/packages/support/acp-snapshot/src/suite.ts index 7bd457b7b4..322439bb01 100644 --- a/packages/support/acp-snapshot/src/suite.ts +++ b/packages/support/acp-snapshot/src/suite.ts @@ -1,14 +1,17 @@ /** - * Keyless-by-default ACP snapshot suite factory. Each scenario drives the real subprocess and - * compares normalized stdout; comparable session fixtures are both replay input and expected - * output. Record mode refreshes reproducible model scenarios from the live API, while refresh - * mode replays committed scripts and rewrites derived artifacts without a key. - * Replay scenarios run concurrently because each subprocess owns unique temp cwd and persistence - * roots and only reads committed fixtures. Record and refresh scenarios stay serial while writing. + * Keyless-by-default ACP snapshot suite factory. Each scenario drives the real + * subprocess and compares normalized stdout; comparable session fixtures are + * both replay input and expected output. Record mode refreshes reproducible + * model scenarios from the live API, while refresh mode replays committed + * scripts and rewrites derived artifacts without a key. + * Replay scenarios run concurrently because each subprocess owns unique temp + * cwd and persistence roots and reads only committed fixtures. Record and + * refresh stay serial while writing. * - * Exactly one scenario per header-composition class pins the system prompt and tool schemas in - * dedicated sidecars. Every live header is checked against that pin, so session-dependent - * composition must declare a separate class instead of escaping coverage. + * Exactly one scenario per header-composition class pins the full prompt and + * tool-schema sequences in dedicated sidecars. Every live header is checked + * against that pin, so session-dependent composition must declare a separate + * class instead of escaping coverage. * @module @deepseek-ai/dsh-acp-snapshot/suite */ @@ -82,14 +85,11 @@ export interface Scenario { */ pinsHeader?: boolean /** - * How many `request/header-delta` events this PINNING scenario's fixture - * legitimately carries (default 0). A recorded mid-run header change — a - * config-option switch rewriting a prompt section — is part of the pinned - * surface, with readable prompt text in Markdown; any OTHER count - * still fails, so fixture rot stays caught. Meaningless off the pin (the - * live uniformity guard keeps non-pinning scenarios delta-free). + * How many changed `request/header` snapshots this PINNING scenario's primary + * fixture legitimately carries (default 0). Their full prompt text is kept in + * the readable Markdown pin; any other count fails. Meaningless off the pin. */ - expectedHeaderDeltas?: number + expectedHeaderChanges?: number /** * Which header-composition class this scenario belongs to. Scenarios that * boot the same config compose the same header; each class has exactly one @@ -210,114 +210,58 @@ export function normalizedToolSchemas(rawLog: string, ctx: NormalizeContext): un }) } -/** - * Extract normalized tool-schema edits from request-header deltas in log order. - * Deltas without an object-valued tools edit are omitted; their remaining - * structure stays pinned in the session JSONL. - * - * @param rawLog The session `.jsonl` content to inspect. - * @param ctx The volatile values of the run that produced it. - * @returns The normalized tool-schema edits, in event order. - */ -export function normalizedToolSchemaDeltas(rawLog: string, ctx: NormalizeContext): unknown[] { - return normalizeSessionLog(rawLog, ctx) - .split('\n') - .filter(line => line.trim().length > 0) - .map(line => JSON.parse(line) as { type?: unknown; data?: { tools?: unknown } }) - .filter(record => record.type === 'request/header-delta') - .flatMap((record) => { - const tools = record.data?.tools - return tools !== null && typeof tools === 'object' && !Array.isArray(tools) ? [tools] : [] - }) -} - /** The structured contents of a tool-schema sidecar. */ export interface ToolSchemasSnapshot { /** The complete tool schemas from the pinned request header. */ initial: unknown[] - /** Complete tool-schema edits from subsequent request-header deltas. */ - deltas: unknown[] + /** Complete tool schemas from subsequent changed-header snapshots. */ + changes: unknown[][] } /** - * Render tool schemas and later schema edits as canonical, readable JSON. + * Render the full tool-schema sequence as canonical, readable JSON. * * @param initial The pinned request header's complete tool schemas. - * @param deltas Complete tool-schema edits from request-header deltas. + * @param changes Complete tool schemas from later changed headers. * @returns A pretty-printed JSON snapshot ending in one newline. */ -export function formatToolSchemasSnapshot(initial: readonly unknown[], deltas: readonly unknown[] = []): string { - return `${JSON.stringify({ initial, deltas }, null, 2)}\n` +export function formatToolSchemasSnapshot(initial: readonly unknown[], changes: readonly unknown[][] = []): string { + return `${JSON.stringify({ initial, changes }, null, 2)}\n` } /** * Parse and validate the stable top-level shape of a tool-schema sidecar. * * @param snapshot The JSON sidecar text. - * @returns Its initial schemas and schema deltas. + * @returns Its initial and changed-header schema sets. */ export function parseToolSchemasSnapshot(snapshot: string): ToolSchemasSnapshot { const parsed = JSON.parse(snapshot) as unknown if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { throw new Error('acp-snapshot: tool-schema snapshot must be an object') } - const { initial, deltas } = parsed as { initial?: unknown; deltas?: unknown } - if (!Array.isArray(initial) || !Array.isArray(deltas)) { - throw new Error('acp-snapshot: tool-schema snapshot must carry array-valued initial and deltas fields') + const { initial, changes } = parsed as { initial?: unknown; changes?: unknown } + if (!Array.isArray(initial) || !Array.isArray(changes) || !changes.every(Array.isArray)) { + throw new Error('acp-snapshot: tool-schema snapshot must carry array-valued initial and changes fields') } - return { initial, deltas } + return { initial, changes } } /** - * Restore a sidecar's initial schemas into a tokenized pinned header. + * Restore one sidecar schema set into a tokenized pinned header. * * @param header The parsed request header carrying `tools: "{{tools}}"`. - * @param snapshot The parsed tool-schema sidecar. - * @returns A copy of the header with its complete initial schemas restored. + * @param schemas The complete schemas for this full header snapshot. + * @returns A copy of the header with its complete schemas restored. */ -export function restorePinnedToolSchemas(header: unknown, snapshot: ToolSchemasSnapshot): unknown { +export function restorePinnedToolSchemas(header: unknown, schemas: readonly unknown[]): unknown { if (header === null || typeof header !== 'object' || Array.isArray(header)) { throw new Error('acp-snapshot: pinned request header must be an object') } if ((header as { tools?: unknown }).tools !== TOOLS_TOKEN) { throw new Error(`acp-snapshot: pinned request header tools must equal ${TOOLS_TOKEN}`) } - return { ...header, tools: snapshot.initial } -} - -/** One normalized system-prompt edit carried by a `request/header-delta`. */ -export interface SystemPromptDeltaSnapshot { - /** How many leading lines remain from the prior prompt. */ - keepStart: number - /** How many trailing lines remain from the prior prompt. */ - keepEnd: number - /** The normalized replacement lines inserted between the retained ranges. */ - insert: string[] -} - -/** - * Extract normalized system-prompt edits from request-header deltas in log - * order. Deltas without a well-formed system edit are omitted; their non-prompt - * structure remains pinned in JSONL. - * - * @param rawLog The session `.jsonl` content to inspect. - * @param ctx The volatile values of the run that produced it. - * @returns The normalized system-prompt edits, in event order. - */ -export function normalizedSystemPromptDeltas(rawLog: string, ctx: NormalizeContext): SystemPromptDeltaSnapshot[] { - return normalizeSessionLog(rawLog, ctx) - .split('\n') - .filter(line => line.trim().length > 0) - .map(line => JSON.parse(line) as { type?: unknown; data?: { system?: unknown } }) - .filter(record => record.type === 'request/header-delta') - .flatMap((record) => { - const system = record.data?.system - if (system === null || typeof system !== 'object') return [] - const { keepStart, keepEnd, insert } = system as { keepStart?: unknown; keepEnd?: unknown; insert?: unknown } - if (typeof keepStart !== 'number' || typeof keepEnd !== 'number' || !Array.isArray(insert)) return [] - if (!insert.every(line => typeof line === 'string')) return [] - return [{ keepStart, keepEnd, insert: insert }] - }) + return { ...header, tools: schemas } } /** @@ -326,38 +270,40 @@ export function normalizedSystemPromptDeltas(rawLog: string, ctx: NormalizeConte * the committed file follows the repository newline contract. * * @param prompt The normalized system prompt. - * @param deltas Normalized prompt edits to append as readable sections. + * @param changes Full normalized prompts from later changed-header snapshots. * @returns Markdown snapshot text ending in a newline. */ export function formatSystemPromptSnapshot( prompt: string, - deltas: readonly SystemPromptDeltaSnapshot[] = [], + changes: readonly string[] = [], ): string { let snapshot = prompt.endsWith('\n') ? prompt : `${prompt}\n` - for (const [index, delta] of deltas.entries()) { - snapshot += `\n\n\n` - const insert = delta.insert.join('\n') - snapshot += insert.endsWith('\n') ? insert : `${insert}\n` + for (const [index, change] of changes.entries()) { + snapshot += `\n\n\n` + snapshot += change.endsWith('\n') ? change : `${change}\n` } return snapshot } -/** Return the initial-prompt portion of a possibly delta-bearing snapshot. */ +/** Return the initial-prompt portion of a possibly multi-header snapshot. */ function initialSystemPromptSnapshot(snapshot: string): string { - const marker = snapshot.indexOf('\n + + +SYS PROMPT NEW PROMPT LINE diff --git a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json index f96325d18b..38bc716d49 100644 --- a/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json +++ b/packages/support/acp-snapshot/tests/fixtures/suite/pin-turn/tool-schemas.golden.json @@ -8,5 +8,15 @@ } } ], - "deltas": [] + "changes": [ + [ + { + "name": "t1", + "description": "D1", + "parameters": { + "type": "object" + } + } + ] + ] } diff --git a/packages/support/acp-snapshot/tests/harness.spec.ts b/packages/support/acp-snapshot/tests/harness.spec.ts index 42ccbd7de4..1d953f5e95 100644 --- a/packages/support/acp-snapshot/tests/harness.spec.ts +++ b/packages/support/acp-snapshot/tests/harness.spec.ts @@ -14,10 +14,12 @@ import { runScenario, type AgentUnderTest, type InputStep } from '../src/harness * assertions read plain `rawStdout`. */ +const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)) const AGENT: AgentUnderTest = { - binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + binScript: fakeAgent, + libBinScript: fakeAgent, // The fake bin ignores its config argv; any real path documents the shape. - configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + configPath: fakeAgent, tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)), } diff --git a/packages/support/acp-snapshot/tests/normalize.spec.ts b/packages/support/acp-snapshot/tests/normalize.spec.ts index f9992e82dd..2beaba5114 100644 --- a/packages/support/acp-snapshot/tests/normalize.spec.ts +++ b/packages/support/acp-snapshot/tests/normalize.spec.ts @@ -227,89 +227,19 @@ describe('scrubRequestHeaders', () => { expect(scrubRequestHeaders(`${headerLine}\n${odd}\n`)).toContain('"messagePrefix":"weird"') }) - it('scrubs a header-delta prefix replacement to one token per message', () => { - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'leaked opener' }] }] }, - }) - const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`) - expect(out).toContain('"messagePrefix":["{{messagePrefix}}"]') - expect(out).not.toContain('leaked opener') - // The empty-array transition-to-absence stays a structural fact. - const toNone = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { messagePrefix: [] } }) - expect(scrubRequestHeaders(`${headerLine}\n${toNone}\n`)).toContain('"messagePrefix":[]') - }) - - it('leaves a delta with no scrubbable payload byte-identical (config-only, or non-array shapes)', () => { - const configOnly = JSON.stringify({ type: 'request/header-delta', seq: 8, time: 9, data: { config: { model: 'm2' } } }) - const oddShapes = JSON.stringify({ type: 'request/header-delta', seq: 9, time: 9, data: { system: { insert: 'not-an-array' }, tools: null } }) + it('leaves malformed headers with no scrubbable payload byte-identical', () => { const headerless = JSON.stringify({ type: 'request/header', seq: 10, time: 9, data: { reason: 'initial' } }) const nullData = JSON.stringify({ type: 'request/header', seq: 11, time: 9, data: null }) - const raw = `${headerLine}\n${configOnly}\n${oddShapes}\n${headerless}\n${nullData}\n` + const raw = `${headerLine}\n${headerless}\n${nullData}\n` expect(scrubRequestHeaders(raw)).toBe(raw) }) - it('scrubs a one-sided tools delta and passes non-object schema entries through', () => { - const addedOnly = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { tools: { added: [null, 'weird', { name: 'x', description: 'D' }] } }, - }) - const out = scrubRequestHeaders(`${headerLine}\n${addedOnly}\n`) - // Non-object entries survive untouched; the object entry keeps only name. - expect(out).toContain('"added":[null,"weird",{"name":"x","description":"{{tools}}"}]') - const changedOnly = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { tools: { changed: [{ name: 'y', parameters: {} }] } }, - }) - expect(scrubRequestHeaders(`${headerLine}\n${changedOnly}\n`)) - .toContain('"changed":[{"name":"y","parameters":"{{tools}}"}]') - }) - - it('scrubs a header-delta system payload but keeps its line positions and arity', () => { - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { system: { keepStart: 1, keepEnd: 4, insert: ['leaked prompt line', 'second line'] }, config: { model: 'm2' } }, - }) - const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`) - // One token PER inserted line: the edit's position AND extent survive. - expect(out).toContain('"insert":["{{system}}","{{system}}"]') - expect(out).toContain('"keepStart":1') - expect(out).toContain('"keepEnd":4') - expect(out).toContain('"config":{"model":"m2"}') - expect(out).not.toContain('leaked prompt line') - expect(out).not.toContain('{{tools}}') // no tools delta → none invented - }) - - it('scrubs a header-delta tools payload but keeps the added/removed/changed names', () => { - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { - tools: { - added: [{ name: 'grep', description: 'Search files.', parameters: { type: 'object' } }], - removed: ['bash_kill'], - changed: [{ name: 'read', description: 'Read v2.', parameters: { type: 'object' } }], - }, - }, - }) - const out = scrubRequestHeaders(`${headerLine}\n${delta}\n`) - // WHICH tools changed is behavior and survives; their bulk does not. - expect(out).toContain('"added":[{"name":"grep","description":"{{tools}}","parameters":"{{tools}}"}]') - expect(out).toContain('"removed":["bash_kill"]') - expect(out).toContain('"changed":[{"name":"read","description":"{{tools}}","parameters":"{{tools}}"}]') - expect(out).not.toContain('Search files') - expect(out).not.toContain('Read v2') - }) - it('passes every other line through byte-for-byte and is idempotent', () => { const other = JSON.stringify({ type: 'assistant/chunk', seq: 4, time: 9, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } } }) - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 8, time: 9, - data: { system: { keepStart: 0, keepEnd: 0, insert: ['x'] }, tools: { added: [{ name: 't', description: 'd', parameters: {} }], removed: [], changed: [] } }, - }) - const raw = `${headerLine}\n${headerEvent({ config: { model: 'm' }, system: 's', tools: [] })}\n${delta}\n${other}\n` + const raw = `${headerLine}\n${headerEvent({ config: { model: 'm' }, system: 's', tools: [] })}\n${other}\n` const once = scrubRequestHeaders(raw) expect(once.split('\n')[0]).toBe(headerLine) - expect(once.split('\n')[3]).toBe(other) + expect(once.split('\n')[2]).toBe(other) expect(scrubRequestHeaders(once)).toBe(once) }) }) @@ -327,12 +257,15 @@ describe('scrubSystemPrompts', () => { reason: 'initial', }, }) - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 2, time: 3, + const changed = JSON.stringify({ + type: 'request/header', seq: 2, time: 3, data: { - system: { keepStart: 1, keepEnd: 2, insert: ['new prompt line'] }, - tools: { changed: [{ name: 'read', description: 'changed schema' }] }, - messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }], + header: { + system: 'new prompt', + tools: [{ name: 'read', description: 'changed schema' }], + messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }], + }, + reason: 'change', }, }) const toolsOnly = JSON.stringify({ @@ -340,11 +273,10 @@ describe('scrubSystemPrompts', () => { data: { header: { tools: [{ name: 'read', description: 'schema only' }] }, reason: 'resume' }, }) - const out = scrubSystemPrompts(`${header}\n${delta}\n${toolsOnly}\n`) + const out = scrubSystemPrompts(`${header}\n${changed}\n${toolsOnly}\n`) expect(out).toContain('"system":"{{system}}"') - expect(out).toContain('"insert":["{{system}}"]') expect(out).not.toContain('full prompt') - expect(out).not.toContain('new prompt line') + expect(out).not.toContain('new prompt') expect(out).toContain('full schema') expect(out).toContain('full prefix') expect(out).toContain('changed schema') @@ -367,12 +299,15 @@ describe('scrubToolSchemas', () => { reason: 'initial', }, }) - const delta = JSON.stringify({ - type: 'request/header-delta', seq: 2, time: 3, + const changed = JSON.stringify({ + type: 'request/header', seq: 2, time: 3, data: { - system: { keepStart: 1, keepEnd: 2, insert: ['new prompt line'] }, - tools: { added: [{ name: 'grep', description: 'new schema' }], changed: [{ name: 'read', description: 'changed schema' }] }, - messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }], + header: { + system: 'new prompt', + tools: [{ name: 'grep', description: 'new schema' }], + messagePrefix: [{ role: 'user', content: [{ type: 'text', text: 'changed prefix' }] }], + }, + reason: 'change', }, }) const systemOnly = JSON.stringify({ @@ -380,15 +315,12 @@ describe('scrubToolSchemas', () => { data: { header: { system: 'prompt only' }, reason: 'resume' }, }) - const out = scrubToolSchemas(`${header}\n${delta}\n${systemOnly}\n`) - expect(out).toContain('"tools":"{{tools}}"') - expect(out).toContain('"added":[{"name":"grep","description":"{{tools}}"}]') - expect(out).toContain('"changed":[{"name":"read","description":"{{tools}}"}]') + const out = scrubToolSchemas(`${header}\n${changed}\n${systemOnly}\n`) + expect(out.match(/"tools":"{{tools}}"/g)).toHaveLength(2) expect(out).not.toContain('full schema') expect(out).not.toContain('new schema') - expect(out).not.toContain('changed schema') expect(out).toContain('full prompt') - expect(out).toContain('new prompt line') + expect(out).toContain('new prompt') expect(out).toContain('full prefix') expect(out).toContain('changed prefix') expect(out.split('\n')[2]).toBe(systemOnly) diff --git a/packages/support/acp-snapshot/tests/suite.spec.ts b/packages/support/acp-snapshot/tests/suite.spec.ts index 204647d8c9..4cedc1cdfb 100644 --- a/packages/support/acp-snapshot/tests/suite.spec.ts +++ b/packages/support/acp-snapshot/tests/suite.spec.ts @@ -9,12 +9,10 @@ import { childFixturePaths, fixtureContext, formatSystemPromptSnapshot, + headerChangeCount, formatToolSchemasSnapshot, - headerDeltaCount, normalizedHeaders, - normalizedSystemPromptDeltas, normalizedSystemPrompts, - normalizedToolSchemaDeltas, normalizedToolSchemas, parseToolSchemasSnapshot, refreshFixtureReplacements, @@ -34,9 +32,11 @@ import { * spec once with `ACP_SNAPSHOT_SPEC_BOOTSTRAP=1`, then review and commit the resulting tree. */ +const fakeAgent = fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)) const AGENT = { - binScript: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), - configPath: fileURLToPath(new URL('./fixtures/fake-acp-agent.ts', import.meta.url)), + binScript: fakeAgent, + libBinScript: fakeAgent, + configPath: fakeAgent, tsconfigPath: fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url)), } @@ -45,7 +45,7 @@ const RECORD_SRC = fileURLToPath(new URL('./fixtures/record-suite', import.meta. // Replay pins explicit header classes; recording covers the default fallback. const REPLAY_SCENARIOS: Scenario[] = [ - { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderDeltas: 1, headerClass: 'main' }, + { name: 'pin-turn', hasModelTurn: true, recorded: true, pinsHeader: true, expectedHeaderChanges: 1, headerClass: 'main' }, { name: 'plain-turn', hasModelTurn: true, recorded: true, childSessions: 1, headerClass: 'main', configPath: AGENT.configPath }, { name: 'no-model', hasModelTurn: false, recorded: false, headerClass: 'main' }, { name: 'blocked-log', hasModelTurn: false, comparesLog: true, recorded: false, headerClass: 'main' }, @@ -76,7 +76,7 @@ afterAll(async () => { function staleRefreshFixtures(dir: string): void { writeFileSync(join(dir, 'plain-turn', 'stdout.golden.jsonl'), 'stale stdout\n') writeFileSync(join(dir, 'pin-turn', 'system-prompt.golden.md'), 'STALE PROMPT\n') - writeFileSync(join(dir, 'pin-turn', 'tool-schemas.golden.json'), '{"initial":[{"name":"stale"}],"deltas":[]}\n') + writeFileSync(join(dir, 'pin-turn', 'tool-schemas.golden.json'), '{"initial":[{"name":"stale"}],"changes":[]}\n') const plainBehaviorFile = join(dir, 'plain-turn', 'behavior.json') const plainBehavior = JSON.parse(readFileSync(plainBehaviorFile, 'utf8')) as Record @@ -127,7 +127,9 @@ describe('defineAcpSnapshotSuite: refresh write-back', () => { expect(readFileSync(join(refreshDir, 'pin-turn', 'system-prompt.golden.md'), 'utf8')).toBe([ 'SYS PROMPT', '', - '', + '', + '', + 'SYS PROMPT', '', 'NEW PROMPT LINE', '', @@ -262,65 +264,41 @@ describe('normalizedToolSchemas', () => { }) }) -describe('normalizedToolSchemaDeltas', () => { - it('extracts and normalizes object-valued schema edits', () => { - const log = [ - '{"type":"request/header-delta","data":{"tools":{"added":[{"name":"read","description":"work in /w"}]}}}', - '{"type":"request/header-delta","data":{"tools":null}}', - '{"type":"request/header-delta","data":{"tools":"invalid"}}', - '{"type":"request/header-delta","data":{"tools":[]}}', - '{"type":"request/header-delta","data":{"system":{"insert":[]}}}', - '{"type":"request/header","data":{"tools":{"added":[]}}}', - '', - ].join('\n') - expect(normalizedToolSchemaDeltas(log, { sessionIds: [], cwd: '/w' })).toEqual([ - { added: [{ name: 'read', description: 'work in {{cwd}}' }] }, - ]) - }) -}) - -describe('normalizedSystemPromptDeltas', () => { - it('extracts and normalizes well-formed system edits', () => { - const log = [ - '{"type":"request/header-delta","data":{"system":{"keepStart":1,"keepEnd":0,"insert":["work in /w"]}}}', - '{"type":"request/header-delta","data":{"tools":{"replace":[]}}}', - '{"type":"request/header-delta","data":{"system":{"keepStart":"1","keepEnd":0,"insert":[]}}}', - '{"type":"request/header-delta","data":{"system":{"keepStart":1,"keepEnd":0,"insert":[null]}}}', - '', - ].join('\n') - expect(normalizedSystemPromptDeltas(log, { sessionIds: [], cwd: '/w' })).toEqual([ - { keepStart: 1, keepEnd: 0, insert: ['work in {{cwd}}'] }, - ]) - }) -}) - describe('formatSystemPromptSnapshot', () => { it('adds a missing terminal newline without changing an existing one', () => { expect(formatSystemPromptSnapshot('prompt')).toBe('prompt\n') expect(formatSystemPromptSnapshot('prompt\n')).toBe('prompt\n') }) - it('renders readable system-prompt delta sections', () => { - expect(formatSystemPromptSnapshot('prompt', [ - { keepStart: 1, keepEnd: 0, insert: ['new', 'lines'] }, - ])).toBe('prompt\n\n\n\nnew\nlines\n') + it('renders readable changed-prompt sections', () => { + expect(formatSystemPromptSnapshot('prompt', ['new\nlines'])) + .toBe('prompt\n\n\n\nnew\nlines\n') }) - it('does not double the newline of a delta insert with a trailing blank line', () => { - expect(formatSystemPromptSnapshot('prompt\n', [ - { keepStart: 2, keepEnd: 1, insert: ['tail', ''] }, - ])).toBe('prompt\n\n\n\ntail\n') + it('does not double the newline of a changed prompt', () => { + expect(formatSystemPromptSnapshot('prompt\n', ['changed\n'])) + .toBe('prompt\n\n\n\nchanged\n') + }) +}) + +describe('headerChangeCount', () => { + it('counts changed request headers, ignoring anchors, blanks, and other lines', () => { + const change = JSON.stringify({ type: 'request/header', seq: 2, time: 9, data: { reason: 'change' } }) + const anchor = JSON.stringify({ type: 'request/header', seq: 0, time: 9, data: { reason: 'initial' } }) + const other = JSON.stringify({ type: 'turn/start', seq: 1, time: 9, data: {} }) + expect(headerChangeCount(`${anchor}\n${other}\n\n${change}\n${change}\n`)).toBe(2) + expect(headerChangeCount(`${anchor}\n`)).toBe(0) }) }) describe('tool-schema snapshots', () => { const snapshot = { initial: [{ name: 'read', description: 'Read a file.' }], - deltas: [{ added: [{ name: 'grep', description: 'Search files.' }] }], + changes: [[{ name: 'grep', description: 'Search files.' }]], } it('formats and parses canonical structured JSON', () => { - const formatted = formatToolSchemasSnapshot(snapshot.initial, snapshot.deltas) + const formatted = formatToolSchemasSnapshot(snapshot.initial, snapshot.changes) expect(formatted).toBe(`${JSON.stringify(snapshot, null, 2)}\n`) expect(parseToolSchemasSnapshot(formatted)).toEqual(snapshot) }) @@ -329,29 +307,21 @@ describe('tool-schema snapshots', () => { expect(() => parseToolSchemasSnapshot('null')).toThrow(/must be an object/) expect(() => parseToolSchemasSnapshot('"invalid"')).toThrow(/must be an object/) expect(() => parseToolSchemasSnapshot('[]')).toThrow(/must be an object/) - expect(() => parseToolSchemasSnapshot('{"initial":{},"deltas":[]}')).toThrow(/array-valued/) - expect(() => parseToolSchemasSnapshot('{"initial":[],"deltas":{}}')).toThrow(/array-valued/) + expect(() => parseToolSchemasSnapshot('{"initial":{},"changes":[]}')).toThrow(/array-valued/) + expect(() => parseToolSchemasSnapshot('{"initial":[],"changes":{}}')).toThrow(/array-valued/) + expect(() => parseToolSchemasSnapshot('{"initial":[],"changes":[{}]}')).toThrow(/array-valued/) }) it('restores initial schemas into the pinned header token', () => { - expect(restorePinnedToolSchemas({ system: '{{system}}', tools: '{{tools}}' }, snapshot)) + expect(restorePinnedToolSchemas({ system: '{{system}}', tools: '{{tools}}' }, snapshot.initial)) .toEqual({ system: '{{system}}', tools: snapshot.initial }) }) it('rejects invalid headers and a missing tool token', () => { - expect(() => restorePinnedToolSchemas(null, snapshot)).toThrow(/must be an object/) - expect(() => restorePinnedToolSchemas('invalid', snapshot)).toThrow(/must be an object/) - expect(() => restorePinnedToolSchemas([], snapshot)).toThrow(/must be an object/) - expect(() => restorePinnedToolSchemas({ tools: [] }, snapshot)).toThrow(/must equal/) - }) -}) - -describe('headerDeltaCount', () => { - it('counts request/header-delta events, ignoring blanks and other lines', () => { - const delta = JSON.stringify({ type: 'request/header-delta', seq: 2, time: 9, data: {} }) - const other = JSON.stringify({ type: 'request/header', seq: 0, time: 9, data: {} }) - expect(headerDeltaCount(`${other}\n\n${delta}\n${delta}\n`)).toBe(2) - expect(headerDeltaCount(`${other}\n`)).toBe(0) + expect(() => restorePinnedToolSchemas(null, snapshot.initial)).toThrow(/must be an object/) + expect(() => restorePinnedToolSchemas('invalid', snapshot.initial)).toThrow(/must be an object/) + expect(() => restorePinnedToolSchemas([], snapshot.initial)).toThrow(/must be an object/) + expect(() => restorePinnedToolSchemas({ tools: [] }, snapshot.initial)).toThrow(/must equal/) }) }) diff --git a/packages/support/acp-snapshot/tsconfig.json b/packages/support/acp-snapshot/tsconfig.json index 749cb0208e..9120df0ad1 100644 --- a/packages/support/acp-snapshot/tsconfig.json +++ b/packages/support/acp-snapshot/tsconfig.json @@ -7,5 +7,7 @@ "include": [ "src" ], - "references": [] + "references": [ + { "path": "../loader-smoke" } + ] } diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md index 4624f72937..661e073d13 100644 --- a/packages/support/invariants/README.md +++ b/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): @@ -39,7 +40,7 @@ Agent status (per agent): Model requests (on `llm/stream`): -- **a loop-built request is exactly what the log reconstructs** — a frozen request with a live `sessionId` is rebuilt through a fresh `Session` from the prefix before its in-flight `step/start`; later content belongs to the next request, and hand-built unfrozen one-shots are excluded. Frozen messages must match that derivation, while every other field matches folded `request/header*` events. The prepended check runs before ordinary short-circuiting stream listeners, but correctness comes from the sequence boundary rather than listener timing. See the [reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md). +- **a loop-built request is exactly what the log reconstructs** — a frozen request with a live `sessionId` (the loop-built marker; hand-built one-shots like compaction's summarize are unfrozen and skipped) must carry frozen `messages` deep-equal to the derivation over the log prefix strictly before the in-flight step's `step/start` (rebuilt through a FRESH `Session`, so the live cache cannot vouch for itself — and boundary-correct: content logged after `step/start` legitimately belongs to the next request), and every non-content field must equal the latest logged `request/header` (see [the reconstructability RFC](../../../docs/rfc/implemented/architecture/2026-07-05-reconstructable-requests.md)). Registered with `prepend: true` so a short-circuiting `llm/stream` listener (the replay adapter) cannot silence it; prepend orders it against append-registered listeners only — correctness rests on the seq-bounded rebuild, never listener timing. On any violation it throws `InvariantError` (`code: 'INVARIANT'`). diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts index ae7337b216..cdb06edbac 100644 --- a/packages/support/invariants/src/index.ts +++ b/packages/support/invariants/src/index.ts @@ -346,7 +346,7 @@ export function apply(ctx: Context): void { // the boundary (an `agent/request`-window inject) is legitimately absent // from this request, and a current-surface comparison would false-fire. // - header: every non-content field must equal the fold of the log's - // `request/header*` events — the loop logs the header event BEFORE + // `request/header` events — the loop logs the header event BEFORE // dispatch, so the fold already covers this request. // // Registered with `prepend: true` so a short-circuiting llm/stream listener diff --git a/packages/support/invariants/tests/invariants.spec.ts b/packages/support/invariants/tests/invariants.spec.ts index d1294a65fd..d5bd2707ab 100644 --- a/packages/support/invariants/tests/invariants.spec.ts +++ b/packages/support/invariants/tests/invariants.spec.ts @@ -487,13 +487,17 @@ describe('surface contract under the invariants composition', () => { // 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', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [] }) - }).toThrow(/must not be empty/) + }).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 () => { @@ -609,7 +613,7 @@ describe('surface contract under the invariants composition', () => { session.append('user/message', { content: [{ type: 'text', text: 'a' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 2 session.append('user/message', { content: [{ type: 'text', text: 'b' }], source: { kind: 'user' } }, { surfaceOp: 'append' }) // seq 3 // Replace node 2 (position 0) with seq 4 — surface is now [4, 3], so seq 4 - // precedes seq 3 in linked-list order even though 4 > 3 numerically. + // precedes seq 3 in surface order even though 4 > 3 numerically. session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 's' }] }, { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [2] }) // seq 4 // A replace with start=3, end=4 passes the seq check (3 <= 4) but is // reversed positionally (3 is at pos 1, 4 is at pos 0). @@ -700,7 +704,7 @@ describe('request-reconstruction cross-check (llm/stream)', () => { it('expects the folded header\'s session prefix ahead of the derivation (prefix + derived)', async () => { const { ctx, session, boundary } = await requestSetup() const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'catalog' }] } - session.append('request/header-delta', { messagePrefix: [prefix] }) + session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' }) // The prefixed request matches the fold… const prefixed = Object.freeze({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id }) expect(() => { dispatch(ctx, prefixed) }).not.toThrow() diff --git a/packages/support/loader-smoke/README.md b/packages/support/loader-smoke/README.md index ea197b25d0..04f519b4c1 100644 --- a/packages/support/loader-smoke/README.md +++ b/packages/support/loader-smoke/README.md @@ -1,10 +1,10 @@ # `@deepseek-ai/dsh-loader-smoke` -Shared subprocess harness for keyless example smokes that boot the real stdio-agent bin and a real `cordis.yml` through the Cordis Loader. A test supplies absolute bin/config/tsconfig paths, optional environment overrides, and stdin lines; `runLoaderSmoke` owns the isolated cwd, DSH homes, tsx path resolution, 30-second process deadline, captured diagnostics, forced kill, EOF, and cleanup. +Shared subprocess harness for tests that boot an app and `cordis.yml` through the Cordis Loader. `resolveExampleLaunch` selects local `src` mode (tsx and root tsconfig paths) or CI `lib` mode (plain Node and package exports) from an explicit mode or `DSH_EXAMPLE_MODE`. -Successful runs return stdout and stderr only after a zero exit. Non-zero exits and deadlines reject with both captured streams. `LOADER_SMOKE_TEST_TIMEOUT_MS` leaves Vitest enough room for the process-owned diagnostic timeout to fire first. +`runLoaderSmoke` owns the isolated cwd, DSH homes, stdin, diagnostics, deadline, termination, and cleanup. It returns both streams after a zero exit and rejects with both streams on failure. -This is support-tier test infrastructure, not product API. The consumers are the Loader-path smokes under `examples/{echo-agent,coding-agent,cordis-agent}`. +This is support-tier test infrastructure, not product API. ## Model Experience @@ -12,6 +12,6 @@ None, as this test-only harness boots example processes and inspects their strea ## Known Limitations and Deferred Work -- **Only the unbuilt tsx/Loader path is exercised** — built-bin artifacts remain the responsibility of their separate e2e smokes. +- **Built mode requires a prior build** — the config must also resolve every named package upward through `examples/node_modules`. - **Captured stdout and stderr are unbounded** — a runaway child can consume memory until the deadline kills it. - **Timeout kills only the direct child** — a process tree spawned by a faulty fixture can outlive the smoke and needs external cleanup. diff --git a/packages/support/loader-smoke/src/index.ts b/packages/support/loader-smoke/src/index.ts index 72839c6a05..edbe39d8ca 100644 --- a/packages/support/loader-smoke/src/index.ts +++ b/packages/support/loader-smoke/src/index.ts @@ -2,6 +2,14 @@ * Shared subprocess harness for keyless example smokes that boot a real * `cordis.yml` through the stdio-agent bin and Cordis Loader. * + * It also owns the mode-aware launch resolver every example subprocess harness shares + * ({@link resolveExampleLaunch}): booting an example bin from TypeScript source under `tsx` (the + * zero-build dev path, resolving `@deepseek-ai/dsh-*` / `@cordisjs/*` through the tsconfig `paths` + * map) or from built `lib/` under plain Node (resolving bare packages through real `exports`, as an + * installed consumer does, while Node type-strips relative example-local TypeScript plugins). + * Consolidating that spawn glue here retires the copies in the ACP snapshot harness and the example + * e2e drivers (the `TODO(acp-test-harness)`). + * * @module @deepseek-ai/dsh-loader-smoke */ @@ -9,26 +17,125 @@ import { spawn } from 'node:child_process' import { mkdtemp, rm } from 'node:fs/promises' import { tmpdir } from 'node:os' import { join } from 'node:path' -import { fileURLToPath } from 'node:url' const DEFAULT_PROCESS_TIMEOUT_MS = 30_000 -const TSX_LOADER = fileURLToPath(import.meta.resolve('tsx')) /** Vitest deadline that leaves room for the subprocess-owned 30-second diagnostic timeout. */ export const LOADER_SMOKE_TEST_TIMEOUT_MS = DEFAULT_PROCESS_TIMEOUT_MS + 15_000 +/** Which artifact an example bin is booted from: unbuilt `src` via tsx, or built `lib` via plain Node. */ +export type ExampleMode = 'src' | 'lib' + +/** Environment variable selecting the mode; CI and pre-push set it to `lib`, dev leaves it unset (`src`). */ +export const EXAMPLE_MODE_ENV = 'DSH_EXAMPLE_MODE' + +/** + * Parse an {@link ExampleMode} from a raw string, defaulting to `src` when absent so an unset + * environment reproduces the dev/tsx behavior. Throws on any other value rather than silently + * falling back, so a typo in a gate's env fails loud. + * @param raw - the raw value; defaults to `process.env.DSH_EXAMPLE_MODE`. + * @returns the validated mode. + */ +export function resolveExampleMode(raw: string | undefined = process.env[EXAMPLE_MODE_ENV]): ExampleMode { + switch (raw) { + case undefined: + case '': + case 'src': + return 'src' + case 'lib': + return 'lib' + default: + throw new Error(`${EXAMPLE_MODE_ENV} must be 'src' or 'lib', got ${JSON.stringify(raw)}.`) + } +} + +/** Inputs to {@link resolveExampleLaunch}. */ +export interface ExampleLaunchOptions { + /** Absolute path to the example bin's TypeScript source entry (`/src/bin.ts`); the `lib` bin is derived from it. */ + readonly srcBin: string + /** Explicit plain-Node entry for `lib` mode; test fixtures may point this at Node-type-strippable TypeScript. */ + readonly libBin?: string | undefined + /** Arguments passed after the bin — the config, positional (`[configPath]`) or flagged (`['--config', configPath]`). */ + readonly configArgs?: readonly string[] + /** The mode to launch in; defaults to {@link resolveExampleMode} of the environment. */ + readonly mode?: ExampleMode + /** Absolute repo tsconfig whose `paths` map resolves unbuilt workspace imports. Required in `src` mode, ignored in `lib`. */ + readonly tsconfigPath?: string + /** Prepend `--expose-internals` (the Cordis Loader's bare-plugin resolver needs it for some bins); defaults to `false`. */ + readonly exposeInternals?: boolean + /** Extra environment entries the mode-specific ones layer over; the caller then merges the result over `process.env`. */ + readonly env?: NodeJS.ProcessEnv +} + +/** The resolved spawn: `spawn(command, args, { env: { ...process.env, ...env } })`. */ +export interface ExampleLaunch { + /** The executable to spawn — always the current Node binary. */ + readonly command: string + /** Node flags, the resolved bin, then the caller's `configArgs`. */ + readonly args: string[] + /** Mode-specific environment (`TSX_TSCONFIG_PATH` in `src`, nothing added in `lib`) layered over the caller's `env`. */ + readonly env: NodeJS.ProcessEnv +} + +/** Derive the built-lib bin (`/lib/.js`) from a source bin (`/src/.ts`). */ +function toLibBin(srcBin: string): string { + const markerLength = '/src/'.length + const cut = Math.max(srcBin.lastIndexOf('/src/'), srcBin.lastIndexOf('\\src\\')) + if (cut === -1) { + throw new Error(`resolveExampleLaunch: expected a "/src/" segment or Windows equivalent in bin path ${JSON.stringify(srcBin)}.`) + } + const separator = srcBin.slice(cut, cut + 1) + const tail = srcBin.slice(cut + markerLength).replace(/\.ts$/, '.js') + return `${srcBin.slice(0, cut)}${separator}lib${separator}${tail}` +} + +/** + * Resolve how to spawn an example bin in the selected mode. + * + * `src` yields `node [--expose-internals] --import ` with `TSX_TSCONFIG_PATH` + * set so the tsconfig `paths` map resolves workspace imports to source. `lib` yields + * `node [--expose-internals] ` under plain Node with no tsx and no paths map, so + * bare package plugins resolve through real package `exports` into built `lib/`; relative example-local + * TypeScript plugins remain source files loaded through Node's built-in type stripping. Bare resolution + * requires the config to live below a workspace that declares its `cordis.yml` package dependencies. + * + * @param options - the source bin, config arguments, mode, and environment. + * @returns the command, argument vector, and mode-specific environment to spawn with. + */ +export function resolveExampleLaunch(options: ExampleLaunchOptions): ExampleLaunch { + const mode = options.mode ?? resolveExampleMode() + const configArgs = options.configArgs ?? [] + const flags = options.exposeInternals === true ? ['--expose-internals'] : [] + const env: NodeJS.ProcessEnv = { ...options.env } + + if (mode === 'src') { + if (options.tsconfigPath === undefined) { + throw new Error("resolveExampleLaunch: 'src' mode needs tsconfigPath for the workspace paths map.") + } + const tsxLoader = import.meta.resolve('tsx') + env.TSX_TSCONFIG_PATH = options.tsconfigPath + return { command: process.execPath, args: [...flags, '--import', tsxLoader, options.srcBin, ...configArgs], env } + } + + return { command: process.execPath, args: [...flags, options.libBin ?? toLibBin(options.srcBin), ...configArgs], env } +} + /** Inputs that vary between real-Loader example smokes. */ export interface LoaderSmokeOptions { /** Human-readable example name used in failure diagnostics. */ readonly label: string /** Prefix for the isolated temporary process cwd. */ readonly tempDirPrefix: string - /** Absolute stdio-agent bin path. */ + /** Absolute stdio-agent bin SOURCE path (`/src/bin.ts`); the `lib` bin is derived from it. */ readonly binScript: string + /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */ + readonly libBinScript?: string | undefined /** Absolute real Loader config path. */ readonly configPath: string - /** Absolute repo tsconfig path used for unbuilt workspace-package resolution. */ + /** Absolute repo tsconfig path used for unbuilt workspace-package resolution (required in `src` mode). */ readonly tsconfigPath: string + /** Boot from source via tsx (`src`) or built lib via plain Node (`lib`); defaults to the environment's mode. */ + readonly mode?: ExampleMode /** Environment overrides layered over the parent and isolated DSH homes. */ readonly env?: Readonly /** Lines written to stdin before EOF; omitted means immediate EOF. */ @@ -48,30 +155,29 @@ export interface LoaderSmokeResult { /** * Boot one real Loader tree from an isolated cwd, write the requested stdin * script, close stdin, and await a clean exit. The helper owns process kill and - * temp-directory cleanup on every outcome. - * @param options - example paths, environment, stdin, and diagnostic identity. + * temp-directory cleanup on every outcome, and picks src/lib via {@link resolveExampleLaunch}. + * @param options - example paths, mode, environment, stdin, and diagnostic identity. * @returns captured stdout and stderr after a zero exit. */ export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise { const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix)) const processTimeoutMs = options.processTimeoutMs ?? DEFAULT_PROCESS_TIMEOUT_MS + const launch = resolveExampleLaunch({ + srcBin: options.binScript, + libBin: options.libBinScript, + configArgs: [options.configPath], + ...options.mode !== undefined ? { mode: options.mode } : {}, + tsconfigPath: options.tsconfigPath, + exposeInternals: true, + env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env }, + }) try { return await new Promise((resolve, reject) => { - const child = spawn( - process.execPath, - ['--expose-internals', '--import', TSX_LOADER, options.binScript, options.configPath], - { - cwd, - env: { - ...process.env, - DSH_HOME: join(cwd, '.dsh'), - DSH_AGENTS_HOME: join(cwd, '.agents'), - ...options.env, - TSX_TSCONFIG_PATH: options.tsconfigPath, - }, - stdio: ['pipe', 'pipe', 'pipe'], - }, - ) + const child = spawn(launch.command, launch.args, { + cwd, + env: { ...process.env, ...launch.env }, + stdio: ['pipe', 'pipe', 'pipe'], + }) let stdout = '' let stderr = '' let deferredFailure: Error | undefined diff --git a/packages/support/loader-smoke/tests/example-launch.spec.ts b/packages/support/loader-smoke/tests/example-launch.spec.ts new file mode 100644 index 0000000000..20520e6fb6 --- /dev/null +++ b/packages/support/loader-smoke/tests/example-launch.spec.ts @@ -0,0 +1,111 @@ +import { afterEach, describe, expect, it } from 'vitest' +import { + EXAMPLE_MODE_ENV, + resolveExampleLaunch, + resolveExampleMode, +} from '@deepseek-ai/dsh-loader-smoke' + +const SRC_BIN = '/repo/packages/examples/stdio-demo/src/bin.ts' +const TSCONFIG = '/repo/tsconfig.json' + +const originalMode = process.env[EXAMPLE_MODE_ENV] +afterEach(() => { + if (originalMode === undefined) Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + else process.env[EXAMPLE_MODE_ENV] = originalMode +}) + +describe('resolveExampleMode', () => { + it('defaults absent/empty/src to src', () => { + Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + expect(resolveExampleMode()).toBe('src') + expect(resolveExampleMode('')).toBe('src') + expect(resolveExampleMode('src')).toBe('src') + }) + + it('accepts lib', () => { + expect(resolveExampleMode('lib')).toBe('lib') + }) + + it('throws on any other value', () => { + expect(() => resolveExampleMode('prod')).toThrow(/must be 'src' or 'lib'/) + }) + + it('reads the environment when no argument is given', () => { + process.env[EXAMPLE_MODE_ENV] = 'lib' + expect(resolveExampleMode()).toBe('lib') + Reflect.deleteProperty(process.env, EXAMPLE_MODE_ENV) + expect(resolveExampleMode()).toBe('src') + }) +}) + +describe('resolveExampleLaunch', () => { + it('src mode: --import tsx on the source bin with the tsconfig paths env', () => { + const { command, args, env } = resolveExampleLaunch({ + srcBin: SRC_BIN, + configArgs: ['./cordis.yml'], + mode: 'src', + tsconfigPath: TSCONFIG, + }) + expect(command).toBe(process.execPath) + expect(args).toContain('--import') + expect(args).toContain(SRC_BIN) + expect(args[args.length - 1]).toBe('./cordis.yml') + expect(args).not.toContain('--expose-internals') + expect(env.TSX_TSCONFIG_PATH).toBe(TSCONFIG) + }) + + it('src mode: throws without a tsconfig path', () => { + expect(() => resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'src' })).toThrow(/needs tsconfigPath/) + }) + + it('lib mode: plain node on the derived lib bin, no tsx and no paths env', () => { + const { args, env } = resolveExampleLaunch({ + srcBin: SRC_BIN, + configArgs: ['--config', './cordis.yml'], + mode: 'lib', + env: { DSH_HOME: '/tmp/home' }, + }) + expect(args).not.toContain('--import') + expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + expect(args.slice(-2)).toEqual(['--config', './cordis.yml']) + expect(env.TSX_TSCONFIG_PATH).toBeUndefined() + expect(env.DSH_HOME).toBe('/tmp/home') + }) + + it('lib mode: uses an explicit plain-Node bin when provided', () => { + const fixture = '/repo/fixture.ts' + const { args } = resolveExampleLaunch({ srcBin: fixture, libBin: fixture, mode: 'lib' }) + expect(args).toContain(fixture) + }) + + it('prepends --expose-internals when requested', () => { + const { args } = resolveExampleLaunch({ srcBin: SRC_BIN, mode: 'lib', exposeInternals: true }) + expect(args[0]).toBe('--expose-internals') + }) + + it('lib mode: rewrites only the last /src/ segment', () => { + const { args } = resolveExampleLaunch({ + srcBin: '/repo/src/packages/examples/acp-demo/src/bin.ts', + mode: 'lib', + }) + expect(args).toContain('/repo/src/packages/examples/acp-demo/lib/bin.js') + }) + + it('lib mode: derives the built bin from a Windows source path', () => { + const { args } = resolveExampleLaunch({ + srcBin: String.raw`D:\repo\src\packages\examples\acp-demo\src\bin.ts`, + mode: 'lib', + }) + expect(args).toContain(String.raw`D:\repo\src\packages\examples\acp-demo\lib\bin.js`) + }) + + it('lib mode: throws when the bin has no /src/ segment', () => { + expect(() => resolveExampleLaunch({ srcBin: '/repo/lib/bin.js', mode: 'lib' })).toThrow(/"\/src\/" segment/) + }) + + it('defaults the mode from the environment', () => { + process.env[EXAMPLE_MODE_ENV] = 'lib' + const { args } = resolveExampleLaunch({ srcBin: SRC_BIN }) + expect(args).toContain('/repo/packages/examples/stdio-demo/lib/bin.js') + }) +}) diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts index 4cc9f878f9..b99d810188 100644 --- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts +++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts @@ -16,6 +16,7 @@ describe('runLoaderSmoke', () => { binScript: fixture('success'), configPath, tsconfigPath, + mode: 'src', env: { LOADER_SMOKE_MARKER: 'present' }, stdinLines: ['one', 'two'], }) @@ -43,6 +44,7 @@ describe('runLoaderSmoke', () => { label: 'failure fixture', tempDirPrefix: 'loader-smoke-fail-', binScript: fixture('fail'), + libBinScript: fixture('fail'), configPath, tsconfigPath, })).rejects.toThrow('failure fixture exited 7. stdout:\n\nstderr:\nfixture failed') @@ -53,6 +55,7 @@ describe('runLoaderSmoke', () => { label: 'hanging fixture', tempDirPrefix: 'loader-smoke-hang-', binScript: fixture('hang'), + libBinScript: fixture('hang'), configPath, tsconfigPath, processTimeoutMs: 100, diff --git a/packages/ui/user-approval/README.md b/packages/ui/user-approval/README.md index 571dc0e7b8..cebd25275e 100644 --- a/packages/ui/user-approval/README.md +++ b/packages/ui/user-approval/README.md @@ -6,7 +6,7 @@ Each request must belong to an open agent turn. The service appends a paired `ap Answerers are `approval/request` waterfall listeners. Return an outcome to answer for an owned agent or call `next()` to delegate. Agent-scoped listeners receive only that agent's requests; compose one terminal answerer per deployment because sibling listener order is not a policy priority mechanism. The ACP bridge is the shipped human answerer. -`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice whose header marker distinguishes user changes from operator/config changes. +`ApprovalPolicy` is `'ask'` or `'never'`. The effective value is the last `approval/policy` event, falling back to config; `setApprovalPolicy()` is the write path. `'never'` rejects before interactive dispatch and is the only policy stated in the prompt. Switches produce at most one coalesced notice, attributed to the user when the override follows the last `request/header` and to operator/config otherwise. The tools pipeline routes `ask` decisions through this seam and fails closed when it is absent; the sandboxed bash tool also uses it for escalated retries. The ACP bridge is the shipped human answerer for calls it owns. Audit events remain log-only, so the model sees only the asking consumer's result. See the [approval-seam RFC](../../../docs/rfc/implemented/feature/2026-07-06-approval-seam.md) and [sandbox RFC](../../../docs/rfc/implemented/feature/2026-07-06-sandbox.md). diff --git a/packages/ui/user-approval/src/index.ts b/packages/ui/user-approval/src/index.ts index b9d757964d..69a243a854 100644 --- a/packages/ui/user-approval/src/index.ts +++ b/packages/ui/user-approval/src/index.ts @@ -63,7 +63,7 @@ declare module '@deepseek-ai/dsh-session' { * from the prompt section and the narrator's notices). The LAST such * event is the session's override ({@link effectiveApprovalPolicy}); * who asked for it is derivable from position (an event after the log's - * last `request/header*` was a runtime switch by the user). + * last `request/header` was a runtime switch by the user). */ 'approval/policy': { policy: ApprovalPolicy } } @@ -258,7 +258,7 @@ export class ApprovalService extends Service { // narrated no later than the next step. What each session was last told // is in-memory with a log-derived fallback (the folded header's system // text), so restarts lose nothing. Attribution is positional: an - // override event after the log's last `request/header*` was a runtime + // override event after the log's last `request/header` was a runtime // switch by the user; otherwise the configured default moved under the // session (operator/config). const narrated = new WeakMap() @@ -271,7 +271,7 @@ export class ApprovalService extends Service { const event = events[index] as (typeof events)[number] if (overrideIndex < 0 && event.type === 'approval/policy') { overrideIndex = index - } else if (headerIndex < 0 && (event.type === 'request/header' || event.type === 'request/header-delta')) { + } else if (headerIndex < 0 && event.type === 'request/header') { headerIndex = index } } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 75ebab5ef6..9810a9a61e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -90,6 +90,120 @@ importers: specifier: ^4.1.8 version: 4.1.8(@types/node@22.20.0)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@22.20.0)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)) + examples: + dependencies: + '@cordisjs/plugin-hmr': + specifier: workspace:* + version: link:../vendor/hmr + '@cordisjs/plugin-include': + specifier: workspace:* + version: link:../vendor/include + '@deepseek-ai/dsh-acp-demo': + specifier: workspace:* + version: link:../packages/examples/acp-demo + '@deepseek-ai/dsh-bash-local': + specifier: workspace:* + version: link:../packages/bash/bash-local + '@deepseek-ai/dsh-bash-sandbox': + specifier: workspace:* + version: link:../packages/bash/bash-sandbox + '@deepseek-ai/dsh-code-runtime-worker': + specifier: workspace:* + version: link:../packages/code-runtime/code-runtime-worker + '@deepseek-ai/dsh-compact-basic': + specifier: workspace:* + version: link:../packages/compact/compact-basic + '@deepseek-ai/dsh-fs-local': + specifier: workspace:* + version: link:../packages/fs/fs-local + '@deepseek-ai/dsh-fs-policy': + specifier: workspace:* + version: link:../packages/fs/fs-policy + '@deepseek-ai/dsh-hooks-claude': + specifier: workspace:* + version: link:../packages/hooks/hooks-claude + '@deepseek-ai/dsh-hooks-codex': + specifier: workspace:* + version: link:../packages/hooks/hooks-codex + '@deepseek-ai/dsh-llm': + specifier: workspace:* + version: link:../packages/llm/llm + '@deepseek-ai/dsh-llm-deepseek': + specifier: workspace:* + version: link:../packages/llm/llm-deepseek + '@deepseek-ai/dsh-llm-replay': + specifier: workspace:* + version: link:../packages/support/llm-replay + '@deepseek-ai/dsh-permission': + specifier: workspace:* + version: link:../packages/ui/permission + '@deepseek-ai/dsh-repeat-tool-guard': + specifier: workspace:* + version: link:../packages/guard/repeat-tool-guard + '@deepseek-ai/dsh-sandbox-local': + specifier: workspace:* + version: link:../packages/sandbox/sandbox-local + '@deepseek-ai/dsh-spill-local': + specifier: workspace:* + version: link:../packages/spill/spill-local + '@deepseek-ai/dsh-spill-policy': + specifier: workspace:* + version: link:../packages/spill/spill-policy + '@deepseek-ai/dsh-stdio-demo': + specifier: workspace:* + version: link:../packages/examples/stdio-demo + '@deepseek-ai/dsh-subagent': + specifier: workspace:* + version: link:../packages/subagent/subagent + '@deepseek-ai/dsh-subagent-fork': + specifier: workspace:* + version: link:../packages/subagent/subagent-fork + '@deepseek-ai/dsh-subagent-spawn': + specifier: workspace:* + version: link:../packages/subagent/subagent-spawn + '@deepseek-ai/dsh-time-context': + specifier: workspace:* + version: link:../packages/context/time-context + '@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-cordis': + specifier: workspace:* + version: link:../packages/cordis/tool-cordis + '@deepseek-ai/dsh-tool-fs': + specifier: workspace:* + version: link:../packages/fs/tool-fs + '@deepseek-ai/dsh-tool-fs-search': + specifier: workspace:* + version: link:../packages/fs/tool-fs-search + '@deepseek-ai/dsh-tool-subagent': + specifier: workspace:* + version: link:../packages/subagent/tool-subagent + '@deepseek-ai/dsh-tool-todo': + specifier: workspace:* + version: link:../packages/todo/tool-todo + '@deepseek-ai/dsh-tool-workflow': + specifier: workspace:* + version: link:../packages/workflow/tool-workflow + '@deepseek-ai/dsh-tools': + specifier: workspace:* + version: link:../packages/core/tools + '@deepseek-ai/dsh-user-approval': + specifier: workspace:* + version: link:../packages/ui/user-approval + '@deepseek-ai/dsh-web': + specifier: workspace:* + version: link:../packages/web/web + '@deepseek-ai/dsh-web-fetch-local': + specifier: workspace:* + version: link:../packages/web/web-fetch-local + '@deepseek-ai/dsh-workflow-workerthread': + specifier: workspace:* + version: link:../packages/workflow/workflow-workerthread + packages/bash/bash: devDependencies: '@deepseek-ai/dsh-sandbox': @@ -233,7 +347,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 @@ -255,12 +379,15 @@ importers: '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session + '@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: @@ -280,6 +407,9 @@ importers: '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:^ + version: link:../../support/loader-smoke '@deepseek-ai/dsh-session': specifier: workspace:^ version: link:../../core/session @@ -965,6 +1095,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/mcp/mcp-client: dependencies: '@modelcontextprotocol/sdk': @@ -1055,9 +1201,6 @@ importers: '@deepseek-ai/dsh-brand': specifier: workspace:^ version: link:../../util/brand - '@deepseek-ai/dsh-compact-basic': - specifier: workspace:^ - version: link:../../compact/compact-basic '@deepseek-ai/dsh-hooks-claude': specifier: workspace:^ version: link:../../hooks/hooks-claude @@ -1326,6 +1469,9 @@ importers: '@deepseek-ai/dsh-llm': specifier: workspace:^ version: link:../../llm/llm + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:^ + version: link:../../support/loader-smoke '@deepseek-ai/dsh-subagent': specifier: workspace:^ version: link:../subagent @@ -1506,9 +1652,9 @@ importers: '@agentclientprotocol/sdk': specifier: 0.25.1 version: 0.25.1(zod@4.4.3) - tsx: - specifier: ^4.22.4 - version: 4.22.4 + '@deepseek-ai/dsh-loader-smoke': + specifier: workspace:* + version: link:../loader-smoke vitest: specifier: ^4.1.8 version: 4.1.8(@types/node@25.9.3)(@vitest/coverage-v8@4.1.8)(jsdom@29.1.1)(vite@8.0.16(@types/node@25.9.3)(esbuild@0.28.1)(jiti@2.7.0)(tsx@4.22.4)(yaml@2.9.0)) @@ -2330,6 +2476,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 diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 07182c9959..8f93814899 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -2,6 +2,13 @@ packages: - vendor/* - packages/*/* - website + # The runnable demo leaves join as ONE workspace member: examples/package.json + # declares the union of every leaf's cordis.yml plugins as workspace:*, so a + # plain-node (`:lib`) boot of any leaf (examples//cordis.yml) resolves its + # plugins through real package `exports`→lib by walking up to examples/node_modules. + # Members for DEPENDENCY RESOLUTION only — NOT build targets: tsdown's explicit + # globs (vendor/*, packages/*/*) exclude them. See the example-execute-over-tsx RFC. + - examples # Deploy root of the single-exe build: a pure dependency manifest whose # closure is what the exe bundles and what the Python runtime distributes. - python/sdk-runtime diff --git a/python/sdk-runtime/package.json b/python/sdk-runtime/package.json index c456fae848..2d3560ec5c 100644 --- a/python/sdk-runtime/package.json +++ b/python/sdk-runtime/package.json @@ -31,6 +31,7 @@ "@deepseek-ai/dsh-jsonrpc": "workspace:^", "@deepseek-ai/dsh-jsonrpc-demo": "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:^", diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index f8a39137aa..3b99ad454a 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -4,8 +4,8 @@ "docs/architecture.md": 1790, "docs/cordis-primer.md": 600, "docs/defensive-patterns.md": 550, - "docs/testing.md": 800, - "examples/AGENTS.md": 200, + "docs/testing.md": 960, + "examples/AGENTS.md": 310, "packages/AGENTS.md": 290, "packages/README.md": 760 } diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 56205abb54..f6aaa6c2d9 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -87,6 +87,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-session replay folds; pressure consumers share immutable revisioned measurements.', + }, { key: 'sessions', pkg: 'session', @@ -859,6 +867,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), @@ -886,9 +896,9 @@ function renderToolPipeline(): string { ` owned["Tool-owned session events
${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/code-dispatch')}"]`, ` post["${mermaidCode('tools/post-execute')} waterfall
accept, block, replace, add context"]`, ` final["${mermaidCode('tools/result')} synchronous notification
frozen authoritative outcome"]`, - ' context["Buffered additionalContexts
context/message after all tool results"]', + ' context["Active-batch additionalContexts FIFO
context/message after recorded tool results"]', ` toolResult["Session event: ${mermaidCode('tool/result')}
single model-facing outcome"]`, - ' allResults["All calls in the step settled
and tool/result events recorded"]', + ' allResults["Tool batch settled
recorded tool/result events complete"]', ' presentResult["UI completed card
presentResult(args, result)"]', ' model --> toolCall', ' toolCall --> presentCall', diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 4d0d03427e..f178f70e9f 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -133,7 +133,7 @@ const TOOL_PACKAGES: ToolPackage[] = [ await ctx.plugin(ToolCordis) }, note: - 'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes.', + 'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; a full changed request header logs those tool-set changes.', }, { pkg: '@deepseek-ai/dsh-tool-fs', diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index fde83ff5ea..ed575858a6 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -163,11 +163,13 @@ function gatesForMode(selected: Mode): Gate[] { ] case 'ci-coverage': return [ + pnpmScript('build', 'build'), coverageGate(), ] case 'ci-snapshot': return [ - pnpmScript('snapshot', 'test:snapshot'), + pnpmScript('build', 'build'), + snapshotGate(), ] case 'ci-artifacts': return ciArtifactGates() @@ -186,7 +188,7 @@ function gatesForMode(selected: Mode): Gate[] { pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }), pnpmScript('test', 'test'), pnpmScript('duplication', 'duplication'), - pnpmScript('snapshot', 'test:snapshot'), + snapshotGate(), pnpmScript('build', 'build'), ...hygieneLeafGates({ artifactNeeds: ['build'] }), ...docSyncLeafGates({ @@ -207,7 +209,7 @@ function ciPrimaryGates(): Gate[] { lintGate(), pnpmScript('duplication', 'duplication'), coverageGate(), - pnpmScript('snapshot', 'test:snapshot'), + snapshotGate(), demoSmokeGate({ needs: ['lint'] }), ...docSyncLeafGates(), pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }), @@ -281,6 +283,18 @@ function coverageGate(): Gate { ...positiveIntArg('DSH_COVERAGE_MAX_WORKERS', '--maxWorkers'), ], { label: 'test:coverage', + env: { DSH_EXAMPLE_MODE: 'lib' }, + needs: ['build'], + }) +} + +// The snapshot suite boots the example bins in `lib` mode (built artifact under plain Node, +// plugins via real exports) — CI and pre-push already build, so they exercise what ships rather +// than the tsx/source path dev uses. It therefore waits on `build`. +function snapshotGate(): Gate { + return pnpmScript('snapshot', 'test:snapshot', { + env: { DSH_EXAMPLE_MODE: 'lib' }, + needs: ['build'], }) } diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 7fc7c47b6a..643716515f 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -707,7 +707,7 @@ def normalize_snapshot_value( def scrub_snapshot_header(value: dict[object, object]) -> None: - """Tokenize request-header bulk while retaining delta tool names.""" + """Tokenize full request-header bulk while retaining tool names.""" data = value.get("data") if not isinstance(data, dict): return @@ -725,29 +725,6 @@ def scrub_snapshot_header(value: dict[object, object]) -> None: ] if isinstance(header.get("messagePrefix"), list): header["messagePrefix"] = ["{{messagePrefix}}" for _ in header["messagePrefix"]] - return - if value.get("type") != "request/header-delta": - return - system = data.get("system") - if isinstance(system, dict) and isinstance(system.get("insert"), list): - system["insert"] = ["{{system}}" for _ in system["insert"]] - tools = data.get("tools") - if isinstance(tools, dict): - for key in ("added", "changed"): - if isinstance(tools.get(key), list): - tools[key] = [scrub_snapshot_tool_schema(tool) for tool in tools[key]] - if isinstance(data.get("messagePrefix"), list): - data["messagePrefix"] = ["{{messagePrefix}}" for _ in data["messagePrefix"]] - - -def scrub_snapshot_tool_schema(value: object) -> object: - """Keep a changed tool's name while tokenizing its schema bulk.""" - if not isinstance(value, dict): - return value - return { - key: item if key == "name" else "{{tools}}" - for key, item in value.items() - } def render_jsonl(records: list[object]) -> str: diff --git a/scripts/snapshots/python-sdk-single-exe/advanced/result.json b/scripts/snapshots/python-sdk-single-exe/advanced/result.json index ca89b2d9a9..499ddafdf8 100644 --- a/scripts/snapshots/python-sdk-single-exe/advanced/result.json +++ b/scripts/snapshots/python-sdk-single-exe/advanced/result.json @@ -253,7 +253,7 @@ "workflow" ] }, - "reason": "fallback" + "reason": "change" } }, { @@ -915,22 +915,29 @@ } }, { - "type": "request/header-delta", + "type": "request/header", "seq": 56, "time": 0, "data": { - "system": { - "keepStart": 62, - "keepEnd": 34, - "insert": [] + "header": { + "config": { + "model": "smoke-model" + }, + "system": "{{system}}", + "tools": [ + "bash", + "bash_kill", + "bash_output", + "cordis_inspect", + "cordis_mount", + "cordis_unmount", + "run_code", + "skill", + "subagent", + "workflow" + ] }, - "tools": { - "added": [], - "removed": [ - "snapshot_double" - ], - "changed": [] - } + "reason": "change" } }, { @@ -1396,7 +1403,7 @@ "workflow" ] }, - "reason": "fallback" + "reason": "change" } } } @@ -2358,22 +2365,29 @@ "payload": { "sessionId": "{{parent}}", "event": { - "type": "request/header-delta", + "type": "request/header", "seq": 56, "time": 0, "data": { - "system": { - "keepStart": 62, - "keepEnd": 34, - "insert": [] + "header": { + "config": { + "model": "smoke-model" + }, + "system": "{{system}}", + "tools": [ + "bash", + "bash_kill", + "bash_output", + "cordis_inspect", + "cordis_mount", + "cordis_unmount", + "run_code", + "skill", + "subagent", + "workflow" + ] }, - "tools": { - "added": [], - "removed": [ - "snapshot_double" - ], - "changed": [] - } + "reason": "change" } } } diff --git a/scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl b/scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl index 82fb190727..3d09295028 100644 --- a/scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl +++ b/scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl @@ -13,7 +13,7 @@ {"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","content":[{"type":"text","text":"mounted dyn-1 (plugin \"\", state: active)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"} {"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}} {"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}} -{"type":"request/header","seq":14,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","snapshot_double","subagent","workflow"]},"reason":"fallback"}} +{"type":"request/header","seq":14,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","snapshot_double","subagent","workflow"]},"reason":"change"}} {"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}} {"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\"}"}}} {"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\"}"}}}} @@ -55,7 +55,7 @@ {"type":"tool/result","seq":53,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","content":[{"type":"text","text":"unmounted dyn-1 (plugin \"\")"}],"isError":false},"sourceEventSeqs":[52],"surfaceOp":"append"} {"type":"step/end","seq":54,"time":0,"data":{"turn":1,"step":5}} {"type":"step/start","seq":55,"time":0,"data":{"turn":1,"step":6}} -{"type":"request/header-delta","seq":56,"time":0,"data":{"system":{"keepStart":62,"keepEnd":34,"insert":[]},"tools":{"added":[],"removed":["snapshot_double"],"changed":[]}}} +{"type":"request/header","seq":56,"time":0,"data":{"header":{"config":{"model":"smoke-model"},"system":"{{system}}","tools":["bash","bash_kill","bash_output","cordis_inspect","cordis_mount","cordis_unmount","run_code","skill","subagent","workflow"]},"reason":"change"}} {"type":"assistant/chunk","seq":57,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}} {"type":"assistant/chunk","seq":58,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_EXECUTABLE_OK"}}} {"type":"assistant/chunk","seq":59,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}}} diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 507e9275c0..c16245f7cf 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -34,6 +34,9 @@ { "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/session.md", "symbol": "ContextEnvelope", "source": "packages/core/session/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" }, @@ -44,7 +47,6 @@ { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" }, { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" }, { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" }, - { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceNode", "source": "packages/core/session/src/surface.ts" }, { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" }, { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" }, diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts index 131bcf0e58..88615ee57a 100644 --- a/scripts/verify-cordis-config.ts +++ b/scripts/verify-cordis-config.ts @@ -1,18 +1,32 @@ /** - * Reject JavaScript expressions in Cordis Loader entry metadata. + * Validate Cordis Loader entry metadata and example package resolution. * * The Loader interpolates only a plugin entry's `config`; expression objects in * fields such as `disabled` remain truthy data and silently change composition. + * Example configs run from built packages, so every named package must resolve + * from the examples workspace and every local package must be in the root + * TypeScript project graph. */ import { globSync, readFileSync } from 'node:fs' -import { resolve } from 'node:path' +import { dirname, relative, resolve } from 'node:path' import * as yaml from 'js-yaml' +import ts from 'typescript' interface JsExpr { __jsExpr: string } +interface PackageManifest { + name?: string + dependencies?: Record +} + +interface PluginReference { + file: string + name: string +} + const root = resolve(import.meta.dirname, '..') const metadataFields = ['id', 'name', 'group', 'disabled', 'inject', 'intercept', 'isolate'] as const const jsExprType = new yaml.Type('tag:yaml.org,2002:js', { @@ -30,6 +44,7 @@ const files = globSync(['**/*cordis*.yml', '**/*cordis*.yaml'], { exclude: ['.claude/**', 'node_modules/**', 'vendor/**'], }).sort() const errors: string[] = [] +const examplePluginReferences: PluginReference[] = [] for (const file of files) { const document: unknown = yaml.load(readFileSync(resolve(root, file), 'utf8'), { schema }) @@ -42,8 +57,10 @@ for (const file of files) { } } +errors.push(...validateExampleResolution()) + if (errors.length > 0) { - console.error('verify-cordis-config: Loader entry metadata is static; move !!js under plugin config or select an explicit overlay.') + console.error('verify-cordis-config: invalid Loader metadata or example package resolution:') for (const error of errors) console.error(`- ${error}`) process.exitCode = 1 } else { @@ -55,6 +72,7 @@ function validateEntry(value: unknown, file: string, path: string): void { errors.push(`${file}${path}: entry must be an object`) return } + recordExamplePlugin(value, file) validateMetadata(value, file, path) if ((value.group === true || value.name === '@cordisjs/plugin-group') && isUnknownArray(value.config)) { for (let index = 0; index < value.config.length; index++) { @@ -68,6 +86,7 @@ function validateEntry(value: unknown, file: string, path: string): void { const patch = config.patches[index] const patchPath = `${path}.config.patches[${index}]` if (!isRecord(patch)) continue + recordExamplePlugin(patch, file) validateMetadata(patch, file, patchPath) if (!isUnknownArray(patch.insert)) continue for (let insertIndex = 0; insertIndex < patch.insert.length; insertIndex++) { @@ -76,6 +95,83 @@ function validateEntry(value: unknown, file: string, path: string): void { } } +function recordExamplePlugin(entry: Record, file: string): void { + if (file.startsWith('examples/') && typeof entry.name === 'string') { + examplePluginReferences.push({ file, name: entry.name }) + } +} + +function validateExampleResolution(): string[] { + const violations: string[] = [] + const exampleManifest = readManifest('examples/package.json') + const dependencies = exampleManifest.dependencies ?? {} + const localPackages = localPackageDirectories() + const rootReferences = rootProjectReferences() + const requiredPackages = new Map>() + + for (const reference of examplePluginReferences) { + const packageName = packageNameFromSpecifier(reference.name) + if (packageName === undefined) continue + const locations = requiredPackages.get(packageName) ?? new Set() + locations.add(reference.file) + requiredPackages.set(packageName, locations) + } + + for (const [packageName, locations] of requiredPackages) { + if (!(packageName in dependencies)) { + violations.push(`${[...locations].join(', ')}: ${packageName} must be declared in examples/package.json dependencies`) + } + } + + const localExamplePackages = new Set([ + ...Object.keys(dependencies), + ...requiredPackages.keys(), + ]) + for (const packageName of localExamplePackages) { + const packageDirectory = localPackages.get(packageName) + if (packageDirectory === undefined || rootReferences.has(packageDirectory)) continue + const repoPath = relative(root, packageDirectory).replaceAll('\\', '/') + violations.push(`tsconfig.json: missing project reference for ${packageName} (${repoPath})`) + } + + return violations +} + +function readManifest(path: string): PackageManifest { + return JSON.parse(readFileSync(resolve(root, path), 'utf8')) as PackageManifest +} + +function localPackageDirectories(): Map { + const manifests = globSync(['packages/*/*/package.json', 'vendor/*/package.json'], { cwd: root }) + const packages = new Map() + for (const manifestPath of manifests) { + const manifest = readManifest(manifestPath) + if (manifest.name !== undefined) packages.set(manifest.name, resolve(root, dirname(manifestPath))) + } + return packages +} + +function rootProjectReferences(): Set { + const config = ts.readConfigFile(resolve(root, 'tsconfig.json'), path => ts.sys.readFile(path)) + if (config.error !== undefined) { + throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n')) + } + const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? [] + return new Set(references.flatMap((reference) => { + if (typeof reference.path !== 'string') return [] + return [resolve(root, reference.path)] + })) +} + +function packageNameFromSpecifier(specifier: string): string | undefined { + if (specifier.startsWith('.') || specifier.startsWith('/') || specifier.startsWith('file:')) return undefined + const segments = specifier.split('/') + if (specifier.startsWith('@')) { + return segments.length >= 2 ? `${segments[0]}/${segments[1]}` : undefined + } + return segments[0] || undefined +} + function validateMetadata(entry: Record, file: string, path: string): void { for (const field of metadataFields) { if (!(field in entry)) continue diff --git a/scripts/verify-package-readme-model-experience.ts b/scripts/verify-package-readme-model-experience.ts index ba3b2b2cc0..75fb2b75ad 100644 --- a/scripts/verify-package-readme-model-experience.ts +++ b/scripts/verify-package-readme-model-experience.ts @@ -48,6 +48,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly> = { '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/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' }, 'packages/sdk/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' }, diff --git a/tsconfig.build.json b/tsconfig.build.json index 678c8cd818..dd13e018c3 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -16,6 +16,7 @@ { "path": "./packages/util/timeout" }, { "path": "./packages/util/retention" }, { "path": "./packages/llm/llm" }, + { "path": "./packages/llm/token-meter" }, { "path": "./packages/core/session" }, { "path": "./packages/core/scope" }, { "path": "./packages/session-persistence/session-persistence" }, diff --git a/tsconfig.json b/tsconfig.json index 2f433786bb..22451dc10f 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -27,6 +27,7 @@ { "path": "./packages/util/timeout" }, { "path": "./packages/util/retention" }, { "path": "./packages/llm/llm" }, + { "path": "./packages/llm/token-meter" }, { "path": "./packages/core/session" }, { "path": "./packages/core/scope" }, { "path": "./packages/session-persistence/session-persistence" }, diff --git a/website/.vitepress/config/api-sidebar.json b/website/.vitepress/config/api-sidebar.json index cdb6e2bfac..3a2b11db3c 100644 --- a/website/.vitepress/config/api-sidebar.json +++ b/website/.vitepress/config/api-sidebar.json @@ -98,6 +98,10 @@ "text": "ctx.tasks", "link": "/zh-CN/api/harness/tasks" }, + { + "text": "ctx.tokenMeter", + "link": "/zh-CN/api/harness/token-meter" + }, { "text": "ctx.tools", "link": "/zh-CN/api/harness/tools" diff --git a/website/zh-CN/api/harness/compact.md b/website/zh-CN/api/harness/compact.md index c565039550..8be3b4287a 100644 --- a/website/zh-CN/api/harness/compact.md +++ b/website/zh-CN/api/harness/compact.md @@ -4,9 +4,9 @@ `CompactService` (abstract seam) — provided by `@deepseek-ai/dsh-compact`. -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`. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L37) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L38) ### ctx.compact.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal) @@ -23,7 +23,7 @@ Check token pressure and compact if the conversation is too large. Estimate the **Returns** the compaction result, or `null` if no compaction was needed. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L57) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L58) ### ctx.compact.compactRegion(session, start, end, agent, signal?) @@ -31,14 +31,14 @@ Check token pressure and compact if the conversation is too large. Estimate the abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise ``` -Forcibly compact a range of surface nodes into a single summary node. `start` and `end` name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation and rejects active, missing, reversed, or unbalanced ranges. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks. +Forcibly compact a range of surface nodes into a single summary node. `start` and `end` name an inclusive span by surface position, not numeric seq order; replacements can make visible seqs non-monotonic. Both edges must be balanced so assistant tool calls remain paired with their results. A model- backed implementation forwards cancellation. The agent must own the exact target session object; implementations reject an ownership mismatch before model resolution, lock acquisition, summarization, or log mutation, and reject active, missing, reversed, or unbalanced ranges. Use toolPairingBalancedBefore and toolPairingBalancedAfter for the edge checks. -- `session` — session to mutate. +- `session` — session to mutate; must be identical to `agent.session`. - `start` — first surface seq, inclusive. - `end` — last surface seq, inclusive. -- `agent` — summarizer context. +- `agent` — owner of the target session and summarizer context. - `signal` — optional cancellation; model-backed implementations must forward it. **Returns** the replaced range and summary. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L82) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/compact/compact/src/index.ts#L85) diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md index cee0b34c72..5f99cb4f32 100644 --- a/website/zh-CN/api/harness/events.md +++ b/website/zh-CN/api/harness/events.md @@ -18,7 +18,7 @@ A fully configured agent and live session were published. Setup is composition-o - `agent` — the newly registered agent with its live session and completed setup. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L153) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L154) ### agent/disposed @@ -32,7 +32,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef - `agent` — the exact agent removed from the registry. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L162) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L163) ### agent/error @@ -49,7 +49,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w - `step` — the step at which the failure surfaced. - `error` — the failure, verbatim. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L297) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L298) ### agent/pre-step @@ -68,7 +68,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and - `sessionPrefix` — the frozen request prefix. - `signal` — the turn abort signal. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L216) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L217) ### agent/prompt-submit @@ -84,7 +84,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca - `content` — the drained message's blocks, as queued. - `source` — the message's resolved source. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L226) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L227) ### agent/queued @@ -100,7 +100,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already - `content` — the accepted content blocks retained by the inbox. - `info` — the accepted source plus whether it entered as steering. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L181) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L182) ### agent/request @@ -117,7 +117,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha - `step` — the step whose request this is. - `config` — the config the loop would use (frozen); return a replacement to switch. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L238) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L239) ### agent/session-prefix @@ -133,7 +133,7 @@ Compose request-only messages placed before derived history. The frozen result i - `prefix` — the frozen seed; return an extended replacement. - `signal` — aborts composition when the step is torn down. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L253) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L254) ### agent/session-start @@ -148,7 +148,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to - `agent` — the agent whose session lifecycle began. - `source` — why the session started (fresh startup, resume, …). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L194) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L195) ### agent/status @@ -163,7 +163,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no - `agent` — the agent whose status flipped. - `status` — the status just entered (the transition's destination). Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L171) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L172) ### agent/step-result @@ -180,7 +180,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va - `step` — the step that produced the message. - `message` — the assistant message as assembled from the stream. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L264) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L265) ### agent/turn-continuation @@ -196,7 +196,7 @@ Override whether the turn continues. The default continues after tool calls or s - `turn` — the turn being continued or stopped. - `defaultDecision` — what the loop would do absent an override. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L274) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L275) ### agent/turn-stop @@ -211,7 +211,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a - `agent` — the agent whose composed continuation outcome may be stopped. - `turn` — the turn at its terminal-stop checkpoint. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L284) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/types.ts#L285) ## approval/* diff --git a/website/zh-CN/api/harness/sessions.md b/website/zh-CN/api/harness/sessions.md index b778d4e44c..e5c8997c49 100644 --- a/website/zh-CN/api/harness/sessions.md +++ b/website/zh-CN/api/harness/sessions.md @@ -7,7 +7,7 @@ In-memory session store (`ctx.sessions`). Persistence is intentionally not implemented here — persistence plugins subscribe to `session/event` and flush on `session/flush` / dispose. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L566) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L580) ### ctx.sessions.create(id?, options?) @@ -23,7 +23,7 @@ For an agent whose session must be torn down IN ORDER with its loop (so the loop **Returns** the live session, already entered and announced. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L595) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L609) ### ctx.sessions.prepare(id?, options?) @@ -38,7 +38,7 @@ Build a session WITHOUT entering it into the store — validate the id/cwd and c **Returns** the constructed session, NOT yet in the store. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L624) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L638) ### ctx.sessions.enter(session) @@ -53,7 +53,7 @@ Re-checks the id for a duplicate: `prepare` and `enter` are public cross-package **Returns** the detach disposer (publication hooks + store removal). When called from a synchronous `session/created` listener, removal and disposal wait until that creation dispatch unwinds. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L668) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L682) ### ctx.sessions.announce(session) @@ -65,7 +65,7 @@ Emit `session/created` exactly once for an entered session (with the carrier ent - `session` — the entered session to announce to listeners. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L723) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L737) ### ctx.sessions.flush(session) @@ -79,7 +79,7 @@ Dispatch the awaited `session/flush` durability checkpoint for `session`, with t **Returns** resolves when every flush listener has settled; after all settle, rejects with the first registered listener failure if any listener failed. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L775) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L789) ### ctx.sessions.get(id) @@ -93,7 +93,7 @@ Look up a live session. **Returns** the session, or undefined when no live session has that id. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L807) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L821) ### ctx.sessions.list() @@ -105,7 +105,7 @@ All live sessions, in creation order. **Returns** a fresh array; mutating it does not affect the store. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L815) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L829) ### ctx.sessions.fork(source, boundary?, childSessionId?) @@ -121,4 +121,4 @@ Create a live child session from a turn-enclosed prefix of a live source. `bound **Returns** The created live child session. -[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L832) +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/session/src/index.ts#L846) diff --git a/website/zh-CN/api/harness/token-meter.md b/website/zh-CN/api/harness/token-meter.md new file mode 100644 index 0000000000..ab4dd8f684 --- /dev/null +++ b/website/zh-CN/api/harness/token-meter.md @@ -0,0 +1,50 @@ + + +# ctx.tokenMeter + +`TokenMeterService` — provided by `@deepseek-ai/dsh-token-meter`. + +Replay owner for one service-wide estimator and isolated per-session folds. + +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/token-meter/src/index.ts#L106) + +### ctx.tokenMeter.contextWindow + +```ts website-api +readonly contextWindow: number +``` + +Provider context-window capacity used by pressure consumers. + +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/token-meter/src/index.ts#L112) + +### ctx.tokenMeter.measure(session, requestHeader?) + +```ts website-api +measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement +``` + +Measure current request pressure and surface through the durable tail. +Provider usage is reused only when the latest successful call's canonical request envelope matches `requestHeader` and its total is no lower than that call's full heuristic anchor; otherwise the complete envelope and surface are heuristically repriced. +`requestHeader` affects request pressure only; surface fields always describe the current session surface. Every call clones those positional nodes, so measurement is O(surface). + +- `session` — session to replay through its current durable tail. +- `requestHeader` — optional effective request envelope replacing the latest logged header. + +**Returns** a detached deeply immutable pressure and surface measurement. + +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/token-meter/src/index.ts#L143) + +### ctx.tokenMeter.estimateMessage(message) + +```ts website-api +estimateMessage(message: Message): number +``` + +Heuristically price one model-visible message. + +- `message` — message to price without mutation. + +**Returns** content and role-framing tokens under the fixed service heuristic. + +[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/token-meter/src/index.ts#L181) diff --git a/website/zh-CN/guide/config.md b/website/zh-CN/guide/config.md index 3b98c1f286..07943288b8 100644 --- a/website/zh-CN/guide/config.md +++ b/website/zh-CN/guide/config.md @@ -84,14 +84,18 @@ Harness 使用 `cordis.yml` 描述一个 Agent 加载哪些插件、以什么参 You are coding-agent, a coding assistant powered by the {{model}} model. Verify your work by running the code or tests. Keep answers brief and factual. +# Token 计量：统一定义模型能看到的 token 上限 +- id: token-meter + name: '@deepseek-ai/dsh-token-meter' + config: + contextWindow: 128000 + # 自动压缩：对话太长时自动总结旧内容，腾出上下文空间 -# contextWindow 是模型能看到的 token 上限 # thresholdRatio 超过这个比例就触发压缩 # compactionRetries 是压缩后仍超标时的额外重试次数 - id: compact-basic name: '@deepseek-ai/dsh-compact-basic' config: - contextWindow: 128000 thresholdRatio: 0.8 retainTokens: 20480 maxTokens: 8192 @@ -214,8 +218,6 @@ config: - id: compact-basic name: '@deepseek-ai/dsh-compact-basic' disabled: true - config: - contextWindow: 128000 ``` ## 各插件配置参考