diff --git a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
index 90e215019b..fb1dc93159 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md
@@ -28,11 +28,11 @@ This guarantee belongs in `Session`, not in an optional listener, because every
`deriveMessages()` projects logged surface events into detached, deep-frozen `Message` objects and returns a fresh array snapshot. Request assembly can therefore combine derived history with other inputs without exposing a path back into the log. The cache reuses safe immutable projections rather than recloning the complete history for each model call.
-### The invariants plugin checks relationships
+### Package-owned invariant companions check relationships
-`dsh-invariants` is a pure-listener development plugin. It does not freeze records and has no configuration; disposal removes only its assertions. It checks rules that require trace state or observation of another seam, including monotonic sequence numbers, turn and step nesting, tool-call/result pairing, legal agent-status transitions, subject-correct scoped dispatch, and equality between a loop-built request and the request reconstructed from its session-log prefix.
+`dsh-invariants` registers the configurable `ctx.invariants` service and contains no product checks. Every package publishes a `./invariant` ownership companion; `dsh-session`, `dsh-agent`, `dsh-scope`, and `dsh-agent-loop` currently add the rules that require trace state or observation of another seam: monotonic sequence numbers, turn and step nesting, tool-call/result pairing, legal agent-status transitions, subject-correct scoped dispatch, and equality between a loop-built request and the request reconstructed from its session-log prefix. Global enablement and package-name regex filters belong to the service ([package-owned invariant service](2026-07-19-package-owned-invariant-service.md)).
-When the plugin attaches to an existing or seeded session, it replays the immutable log to rebuild trace state. This makes hot reload safe in the middle of a turn without giving the plugin ownership of session storage.
+When the session companion attaches to an existing or seeded session, it replays the immutable log to rebuild trace state. The service gives each contribution a disposable child fiber, so hot reload is safe in the middle of a turn without giving diagnostics ownership of session storage.
## Alternatives considered
@@ -53,6 +53,6 @@ Detaching `deriveMessages()` would protect the most common request path but leav
- Every accepted live or seeded session event is detached from caller-owned inputs and deeply immutable before any observer can receive it.
- `session.events` exposes stable immutable snapshots instead of the private growing array.
- Request-side mutation cannot reach stored history through derived messages.
-- Development builds can enable relational assertions without changing storage behavior, and disposing or omitting the plugin does not weaken log immutability.
-- `dsh-invariants` has no `Config` surface because it has no behavior to tune.
+- Development builds can enable relational assertions without changing storage behavior, and disposing or filtering a companion does not weaken log immutability.
+- `dsh-invariants` configures global enablement plus package allow/block regex lists; each check remains owned and tested by its product package.
- The runtime boundary carries a recursive snapshot-and-freeze cost once per accepted event; later readers and cached projections reuse the owned immutable records.
diff --git a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
index eacd409a57..b2f4ea66b4 100644
--- a/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
+++ b/.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md
@@ -10,7 +10,7 @@ Failures crossed seams as bare strings. A tool error flattened to a text block
A single `HarnessError extends Error` base in `dsh-llm` (the leaf package every other imports — no new dependency edge): a stable `code` distinct from `message`, `cause` chaining via `ErrorOptions`, and `name` defaulting to the subclass. `isHarnessError` narrows at seams.
-- `LlmError`, `ToolArgsError` (dsh-tools), and `InvariantError` (dsh-invariants) now extend it, keeping their existing codes.
+- `LlmError` and `ToolArgsError` (dsh-tools) extend it, keeping their existing codes.
- `ToolExecutionResult` gains optional `error: { name, code }`, populated in the registry's catch when the thrown value is a `HarnessError`. The agent loop forwards it onto the `tool/result` session event (which gained the same optional field), so the structured failure survives into the log for retry/sandbox plugins and replay. The model-facing text block is unchanged.
- The loop's `toError` wraps a non-Error throw in a `HarnessError` (`code: 'UNKNOWN'`, original chained as `cause`) instead of a bare `Error`, so even a bad throw carries a routable code into the session `error` event (which already surfaced `code`).
@@ -19,6 +19,6 @@ A single `HarnessError extends Error` base in `dsh-llm` (the leaf package every
- Errors are machine-routable end-to-end: a plugin can branch on `error.code` rather than substring-matching a message.
- One base class is imported widely, but it lives in the package everyone already depends on, so the cost is a single import, not a new edge.
- `deriveMessages` does not surface `error` into model history — the model still sees the text block; the structured field is for code and replay.
-- Argument validation and dev invariants retain their existing codes and behavior; the shared base adds cross-seam routing metadata without changing model-facing text.
+- Argument validation retains its existing code and behavior; package-owned diagnostic invariants carry their stable code independently so the invariant registry does not import a product package. The shared base adds cross-seam routing metadata without changing model-facing text.
diff --git a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
index 74ab8b6bf3..00352b01c4 100644
--- a/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
+++ b/.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md
@@ -21,7 +21,7 @@ In case 2, if the injected `context/message` is the last event before a flush/di
- 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`.
+- The `dsh-session/invariant` companion registers the check with `ctx.invariants`: when selected, a `user/message` / `context/message` / `steering/message` appended while no turn is open throws an `InvariantError` attributed to `@deepseek-ai/dsh-session`.
The serializability invariant is enforced at the same source boundary (`Session.append` throws on non-JSON-serializable data), so "what may enter the log" is now governed in one place rather than discovered downstream by whichever backend happens to be watching.
diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
index 1916dc1974..f1297b1f05 100644
--- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
+++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md
@@ -47,7 +47,7 @@ The `repair.ts` module synthesizes `tool/result` closers for orphaned tool calls
### Invariants
-The dev-mode invariants plugin validates: `sourceEventSeqs` references (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).
+`Session` validates `sourceEventSeqs` and `surfaceOp` at the always-on seed/append boundary: only `assistant/message` may use an empty provenance list; references are unique, earlier, and known; replacement endpoints exist in surface order; and provenance covers every shadowed node. These are single-record acceptance and storage-projection rules, not optional invariant-service contributions.
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.
@@ -63,7 +63,6 @@ Every surface-eligible event must carry `surfaceOp` or it would disappear from d
- **`packages/core/session`**: `surface.ts` (`SurfaceManager`) maintains one ordered seq array for candidate acceptance and live projection; `SessionSurface` is its readonly public view. `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.
diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
index 162a83ad0c..40cd4180e9 100644
--- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
+++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md
@@ -12,7 +12,7 @@ The reference shape for the happy path is MiniCode's `LLMClient`: a stateful con
### The principle
-**Model-visible ⟺ logged.** Anything that reaches a model request must be recorded in the session log. The checkable consequence: **every conversation request the loop sends is a pure function of the session log** — anyone holding the log reconstructs it byte-for-byte. Scope, stated precisely: the guarantee covers the loop-built `GenerateOptions`; provider wire bytes follow from it because both adapters' serialization is a pure per-message function at a pinned code version; direct one-shots (compaction's summarize call) log their envelope scalars (`compact/summary.{provider, model, maxTokens}`) and their input is deterministic code over the logged region — reconstructable from log + code, outside the invariant by the unfrozen-request marker.
+**Model-visible ⟺ logged.** Anything that reaches a model request must be recorded in the session log. The checkable consequence: **every conversation request the loop sends is a pure function of the session log** — anyone holding the log reconstructs it byte-for-byte. Scope, stated precisely: the guarantee covers the loop-built `GenerateOptions`; provider wire bytes follow from it because both adapters' serialization is a pure per-message function at a pinned code version; direct one-shots (compaction's summarize call) log their envelope scalars (`compact/summary.{provider, model, maxTokens}`) and their input is deterministic code over the logged region — reconstructable from log + code, outside the invariant because only the loop marks request ownership.
Prefix-cache stability is corollary #1, not the headline: an append-only log projected by a per-node pure function yields requests that are append-extensions of their predecessors whenever the header is unchanged — stability is emergent, not managed. Byte-exact audit/replay is corollary #2; resume and fork with *attributable* drift is corollary #3.
@@ -26,7 +26,7 @@ Each step rebuilds prompt assembly. On the instance's first step, `agent/session
**`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(agent, turn, step, signal)` remains the generic 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.
+**Enforcement.** The `dsh-agent-loop/invariant` companion registers with `ctx.invariants` and, when selected, 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`. The loop applies an internal non-enumerable identity before freezing each request; the independently built companion recognizes that identity, while direct one-shots remain excluded regardless of their frozen shape or session id. 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.
### The MiniCode shape: adopted, with the provenance arrow inverted
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
index 68b9d2d55b..b25f335819 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.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-10-after-call-compaction-pressure-and-overflow-recovery.md: d470cceaff68229b3872d0ade93d5fabc2e10c3f
-2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: b7753fb226638b16b0f244b681cd2b9bcc9f25c2
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md: b934f7fd7087006be4f7eb3659e44e78b8ede367
+2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md: 3b5b60a95bef0695a446cdd3d45d299550f449f6
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
index d470cceaff..b934f7fd70 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md
@@ -32,9 +32,9 @@ If cancellation lands after assistant tool calls are durable but before all call
`CompactService.compactIfNeeded(agent, trigger, signal)` accepts `trigger: 'pressure' | 'context-overflow'`. The interface gains no estimation methods or token types; `ctx.tokenMeter` remains the reusable accounting owner.
-For `pressure`, compact-basic applies the service-wide threshold and retained-tail policy to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, provenance, shadowed token counts, and non-shrinking-summary rejection. The common defaults remain threshold ratio `0.8`, retained history `floor(contextWindow × 0.16)`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`.
+For `pressure`, compact-basic resolves the durable provider/model target's adapter-owned capacity and exact-target policy, then applies the resulting threshold and retained-tail budgets to one unified `ctx.tokenMeter.measure()` result. Below pressure it returns without pruning. Once pressure qualifies, optional `ctx.toolResultPrune` rewrites oversized current results and compact-basic remeasures through the same meter; safe pressure skips the model call, while remaining pressure selects and summarizes from the pruned surface. The same singleton meter owns range pricing, provenance, shadowed token counts, and non-shrinking-summary rejection. Common defaults remain threshold ratio `0.8`, retained-history ratio `0.16`, summarization provider/model `''`, `maxTokens: 8192`, `compactionRetries: 1`, and `auto: true`; optional `modelPolicies` entries override them for an exact provider/model pair.
-For canonical overflow, compact-basic bypasses scalar pressure and the normal retained-token budget. It prunes first, then chooses the maximal tool-balanced head range while leaving the newest indivisible unit and attempts one shrinking summary compaction under the same signal when a range exists. The automatic listener snapshots `session.surface.replaceGeneration` and returns `{ action: 'retry' }` whenever pruning or summarization increases it. This remains true when pruning lands before later summary work throws; cancellation still wins. A backend returning a result without replacement cannot authorize retry, while pruning-only progress can authorize a retry without a `CompactionResult`.
+For canonical overflow, compact-basic requires no capacity metadata and bypasses scalar pressure and the normal retained-token budget. It prunes first, then chooses the maximal tool-balanced head range while leaving the newest indivisible unit and attempts one shrinking summary compaction under the same signal when a range exists. The automatic listener snapshots `session.surface.replaceGeneration` and returns `{ action: 'retry' }` whenever pruning or summarization increases it. This remains true when pruning lands before later summary work throws; cancellation still wins. A backend returning a result without replacement cannot authorize retry, while pruning-only progress can authorize a retry without a `CompactionResult`.
`maxOverflowRetries` is optional and defaults to `1`; `0` disables overflow recovery without disabling pressure. `auto: false` registers neither automatic listener. Noncanonical errors, exhausted attempts, an already-aborted signal, a missing routed model, no safe range, no generation change, and recovery throws before any replacement all delegate to the next listener. With no later recovery, the loop reports the original provider error object and code. A recovery throw after generation advances authorizes retry from durable progress; cancellation or disposal remains authoritative even if recovery work completes concurrently.
diff --git a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
index b7753fb226..3b5b60a95b 100644
--- a/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.zh.md
@@ -32,9 +32,9 @@ Status: implemented
`CompactService.compactIfNeeded(agent, trigger, signal)` 接收 `trigger: 'pressure' | 'context-overflow'`。接口不增加估算方法或 token 类型；`ctx.tokenMeter` 继续作为可复用的核算所有者。
-对于 `pressure`，compact-basic 把服务级阈值与保留尾部策略应用到一次统一的 `ctx.tokenMeter.measure()` 结果。低于压力时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力恢复安全则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、来源、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史 `floor(contextWindow × 0.16)`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`。
+对于 `pressure`，compact-basic 先解析持久提供方/模型目标的适配器所属容量与精确目标策略，再把得到的阈值与保留尾部预算应用到一次统一的 `ctx.tokenMeter.measure()` 结果。低于压力时直接返回，不执行剪枝。压力达到条件后，可选的 `ctx.toolResultPrune` 会改写当前表层中过大的工具结果，compact-basic 再通过同一个 meter 重新计量；若压力恢复安全则跳过模型调用，否则从已剪枝表层选择范围并生成摘要。范围定价、来源、被遮蔽 token 数与非缩小摘要拒绝也由同一个单例 meter 完成。通用默认值保持为阈值比例 `0.8`、保留历史比例 `0.16`、摘要提供方/模型 `''`、`maxTokens: 8192`、`compactionRetries: 1` 与 `auto: true`；可选 `modelPolicies` 项可以按精确提供方/模型组合覆盖这些值。
-对于规范化溢出，compact-basic 绕过标量压力与普通保留 token 预算。它先执行剪枝，再在保留最新不可分割单元的同时选择最大的工具配对平衡头部范围；存在范围时，才在同一 signal 下尝试一次缩小摘要压缩。自动监听器先记录 `session.surface.replaceGeneration`，剪枝或摘要让 generation 增加时就返回 `{ action: 'retry' }`。即使剪枝先落盘而后续摘要工作抛错，这条规则仍然成立；取消依然优先。后端若只返回结果但没有替换表层，不能授权重试；只有剪枝取得进展时，即使没有 `CompactionResult` 也可以授权重试。
+对于规范化溢出，compact-basic 不要求容量元数据，并绕过标量压力与普通保留 token 预算。它先执行剪枝，再在保留最新不可分割单元的同时选择最大的工具配对平衡头部范围；存在范围时，才在同一 signal 下尝试一次缩小摘要压缩。自动监听器先记录 `session.surface.replaceGeneration`，剪枝或摘要让 generation 增加时就返回 `{ action: 'retry' }`。即使剪枝先落盘而后续摘要工作抛错，这条规则仍然成立；取消依然优先。后端若只返回结果但没有替换表层，不能授权重试；只有剪枝取得进展时，即使没有 `CompactionResult` 也可以授权重试。
`maxOverflowRetries` 可选且默认为 `1`；`0` 只禁用溢出恢复，不会禁用压力检查。`auto: false` 不注册任何自动监听器。非规范化错误、尝试耗尽、已经中止的 signal、缺失路由模型、没有安全范围、generation 未变化，以及在任何替换之前恢复抛错，都会委托给下一个监听器。若没有后续恢复，循环报告原始提供方错误对象与代码。generation 增加后的恢复抛错会基于持久进展授权重试；即使恢复工作并发完成，取消或销毁仍具有最终优先级。
diff --git a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index 2ddbe0a351..eb7b1d873d 100644
--- a/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/.agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -322,7 +322,7 @@ TypeScript cannot govern JavaScript casts, direct Cordis dispatch, process messa
### Runtime invariants cover cross-service facts
-The invariants plugin verifies that every declared scoped event uses a marked carrier and that event families exposing a subject use the matching key. Session trace validation stages before append commit and advances after the same event commits.
+The `dsh-scope/invariant` companion verifies, when selected, that every declared scoped event uses a marked carrier and that event families exposing a subject use the matching key. The separate `dsh-session/invariant` contribution stages trace validation before append commit and advances after the same event commits; both register through `ctx.invariants`.
The plugin does not police trusted setup by scanning registries or reject prompt assembly objects fabricated through casts. Those checks would turn composition contracts into speculative runtime machinery without protecting a real external boundary.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
index d49aedb545..c560903ca7 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.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-replay-token-meter-service.md: 9bbc177f456e006179c466f8c245e4599db3dd5a
-2026-07-15-replay-token-meter-service.zh.md: 4437626c8651a80537d45197a93733271a592173
+2026-07-15-replay-token-meter-service.md: 4bedbb0cb9fa383108a688dbbb32546c7f39bd20
+2026-07-15-replay-token-meter-service.zh.md: ccf1b014cd86d16ef498b4209818e78be562e66f
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
index 9bbc177f45..4bedbb0cb9 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md
@@ -6,7 +6,7 @@ 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.
+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 many tokens 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.
@@ -14,9 +14,9 @@ Provider usage is not a complete answer. It describes one successful call under
### 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.
+`@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 `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.
+The service has no configuration. Estimation uses a fixed four-characters-per-token heuristic plus structural overhead. There are no model profiles, capacity settings, density settings, tokenizer backends, or language-specific strategies. Exact provider/model capacity is a separate adapter-owned query, as specified by the [routed model context and compaction policy Agent Note](2026-07-20-routed-model-context-and-compaction-policy.md).
### Per-session replay folds
@@ -34,7 +34,7 @@ Usage sums the disjoint input, cache-read, cache-write, and output buckets. Reas
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)`, `summarizationProvider: ''`, `summarizationModel: ''`, `maxTokens: 8192`, `compactionRetries: 1`, `maxOverflowRetries: 1`, and `auto: true`. Top-level `thresholdRatio` and `retainTokens` override the pressure policy; retention must remain below the resulting threshold. The summarization provider and model must both be set or both be empty; an empty pair resolves the latest logged request target, then the `AgentOptions` pair.
+Compact policy has service-wide defaults: threshold ratio `0.8`, retained-tail ratio `0.16`, `summarizationProvider: ''`, `summarizationModel: ''`, `maxTokens: 8192`, `compactionRetries: 1`, `maxOverflowRetries: 1`, and `auto: true`. Top-level fields apply to every routed target; exact provider/model entries in `modelPolicies` partially override them. Pressure scales ratios against capacity resolved from the owning adapter, and `retainTokens` may replace `retainRatio`; retention must remain below the resulting threshold. The summarization provider and model must both be set or both be empty; an empty pair resolves the latest logged request target, then the `AgentOptions` pair.
Automatic pressure runs at `agent/post-step` and measures the canonical durable envelope produced under the provider/model actually selected by `agent/request`. A headerless session has no completed routed request to assess and produces no work; any routed target can use the singleton estimator. Canonical overflow recovery uses the same measurement for forced range selection and retries only after a proven surface replacement.
@@ -46,14 +46,14 @@ Unit tests cover fixed estimation, envelope invalidation and anchor replacement,
- **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.
+- **Put model-keyed windows and density profiles in the meter** — rejected because replay estimation does not own model routing or capacity facts. The route-owning adapter exposes capacity, while compact-basic owns the consumer-specific threshold and retention policy.
- **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.
+- The default makes the meter a zero-config composition entry; deployments configure capacity on each route-owning adapter and optional policy overrides on compact-basic.
- 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.
diff --git a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
index 4437626c86..ccf1b014cd 100644
--- a/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.zh.md
@@ -6,7 +6,7 @@ Status: implemented
## 问题
-上下文压力并不只对压缩有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求占用了已配置上下文窗口的多少容量？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现回放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方复用陈旧的核算结果。
+上下文压力并不只对压缩有用。压缩后端、溢出保护或未来的请求策略插件都可能需要回答同一个问题：持久请求消耗了多少 token？如果把该折叠逻辑留在 `dsh-compact-basic` 内部，就会重复实现回放逻辑，使未加载压缩的调用方无法使用计量，并诱使调用方复用陈旧的核算结果。
提供方 usage 也不是完整答案。它只描述某个精确请求信封下的一次成功调用，而当前表层之后还可能增长、缩小或被替换。会话也可能切换提供方与模型，旧日志可能缺少分片来源，usage 字段还会分别报告输入、缓存读取、缓存写入、输出与推理计数。因此，可用的服务必须把最新精确锚点与保守的启发式重新定价结合起来，并公开每个结果已经消费的日志修订号。
@@ -14,9 +14,9 @@ Status: implemented
### 一个具体的 LLM 家族服务
-`@deepseek-ai/dsh-token-meter` 是 `packages/llm/` 下的单个具体包，并注册 `ctx.tokenMeter`。在第二种实现出现之前，它不会被拆成接口与后端。`TokenMeterService` 本身公开 `contextWindow`、`measure(session, requestHeader?)` 与 `estimateMessage(message)`；消费方直接调用这个单例服务。
+`@deepseek-ai/dsh-token-meter` 是 `packages/llm/` 下的单个具体包，并注册 `ctx.tokenMeter`。在第二种实现出现之前，它不会被拆成接口与后端。`TokenMeterService` 本身公开 `measure(session, requestHeader?)` 与 `estimateMessage(message)`；消费方直接调用这个单例服务。
-服务只有一个 `contextWindow`，默认值为 128,000 token，并允许配置为正整数。估算采用固定的每 token 四个字符启发式规则，并加上结构开销。服务不提供模型 profile、密度设置、分词器后端或语言专用策略。
+服务没有配置。估算采用固定的每 token 四个字符启发式规则，并加上结构开销。服务不提供模型 profile、容量设置、密度设置、分词器后端或语言专用策略。精确提供方/模型容量由独立的适配器查询拥有，具体见[路由模型上下文与压缩策略 Agent Note](2026-07-20-routed-model-context-and-compaction-policy.md)。
### 逐会话回放折叠
@@ -34,7 +34,7 @@ Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket
自动压缩的每次阈值与保留联合决策只使用一次统一计量。区域事务先追加持久 `compact/start` 锁，再执行一次计量，并在异步摘要完成后再次计量；期间任何持久追加都会改变 `logRevision`，从而阻止替换。
-压缩策略采用服务级默认值：阈值比例 `0.8`、保留尾部 `floor(contextWindow × 0.16)`、`summarizationProvider: ''`、`summarizationModel: ''`、`maxTokens: 8192`、`compactionRetries: 1`、`maxOverflowRetries: 1` 与 `auto: true`。顶层 `thresholdRatio` 与 `retainTokens` 覆盖压力策略；保留值必须小于最终阈值。摘要提供方与模型必须同时设置或同时为空；空组合先解析最近记录的请求目标，再使用 `AgentOptions` 中的组合。
+压缩策略采用服务级默认值：阈值比例 `0.8`、保留尾部比例 `0.16`、`summarizationProvider: ''`、`summarizationModel: ''`、`maxTokens: 8192`、`compactionRetries: 1`、`maxOverflowRetries: 1` 与 `auto: true`。顶层字段适用于每个路由目标；`modelPolicies` 中的精确提供方/模型项可以部分覆盖这些字段。压力检查根据所属适配器解析的容量缩放比例，`retainTokens` 可以替代 `retainRatio`；保留值必须小于最终阈值。摘要提供方与模型必须同时设置或同时为空；空组合先解析最近记录的请求目标，再使用 `AgentOptions` 中的组合。
自动压力检查运行在 `agent/post-step`，并计量 `agent/request` 实际所选提供方/模型产生的规范持久信封。没有请求头的会话尚无已完成的路由请求可供判断，因此不执行工作；任意路由目标都可使用这个单例估算器。规范化溢出恢复使用同一计量结果强制选择范围，并且只有在表层替换得到证明后才重试。
@@ -46,14 +46,14 @@ Usage 会对互不重叠的输入、缓存读取、缓存写入与输出 bucket
- **把估算保留在 `CompactService` 内**——不予采纳，因为计量拥有独立于压缩的消费方与回放语义；它还会强迫每个压缩器暴露同一套无关 API。
- **立即把 token meter 拆成接口与启发式后端**——不予采纳，因为目前只有一种实现。单个具体服务保留未来接缝，同时避免推测性的包与配置。
-- **保留模型键控的窗口与密度 profile**——不予采纳，因为当前部署只有一种上下文策略与一个估算器。模型注册表、未知模型错误和可配置密度只增加分支，却没有第二种行为可供选择。
+- **把模型键控窗口与密度 profile 放进 meter**——不予采纳，因为回放估算不拥有模型路由或容量事实。路由所属适配器公开容量，compact-basic 则拥有消费方专用的阈值与保留策略。
- **保留独立的标量与表层计量**——不予采纳，因为消费方必须为一次决策执行两次读取并匹配修订号。仅读取标量可以避免在低于阈值时复制节点，但拆分 API 会在消费方引入竞态窗口；统一快照接受 O(surface) 复制成本，以换取结果一致性。
- **在不同信封之间移用提供方 usage**——不予采纳，因为模型、工具、前缀与调用配置都是请求事实。不匹配时会重新定价完整当前请求。
## 后果
- Token 压力拥有一个可供压缩与未来插件共享的回放感知所有者。
-- 默认值让内置组合只需两个零配置插件条目即可使用；部署需要时只覆盖一个上下文容量。
+- 默认值让 meter 成为零配置组合项；部署在各个路由所属适配器上配置容量，并在 compact-basic 上配置可选策略覆盖。
- 固定启发式定价仍然只是提供方行为的估计，并不是精确分词器或请求序列化器。
- 每次计量都会复制当前的位置表层，因此成本为 O(surface)，低于阈值即可结束的压力检查也不例外。
- 遇到畸形持久边界时，计量会明确失败。这会把损坏的回放转化为具名集成错误，而不是让压力静默漂移。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.i18n.yaml
new file mode 100644
index 0000000000..60f33a0e1e
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.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-19-package-invariant-runtime-contracts.md: 7d1fb1ad5a2e7563bdddffde1f49368b9f0c13f7
+2026-07-19-package-invariant-runtime-contracts.zh.md: 669eb02221aea4b0654497bb81327d725648dabe
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
new file mode 100644
index 0000000000..7d1fb1ad5a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md
@@ -0,0 +1,78 @@
+# Agent Note: Meaningful package invariant contracts
+
+Status: implemented
+
+English | [中文](2026-07-19-package-invariant-runtime-contracts.zh.md)
+
+## Problem
+
+The package-owned invariant seam made publication and registration exhaustive, but its first generated baseline accepted empty installers. A follow-up then replaced those empties with generic assertions about plugin names, injections, effects, service methods, and fixed pure-library examples. Those assertions made every companion executable without making the system safer: TypeScript, Cordis startup, package tests, and module-load tests already enforce those shapes, while the invariant service should detect impossible runtime state.
+
+A useful runtime invariant relates observations over time or across a mutable data structure. Examples include a terminal event without its start, an LLM delta for a block that is not open, or a durable result whose identity differs from its request. Merely confirming that a declared method exists, that a plugin has its expected name, or that a constant example still returns a known value is not such a relation.
+
+Some packages genuinely own no continuously observable relation. Pure utilities, composition-only packages, thin adapters, binaries, and test-support packages may have important contracts, but those contracts are better enforced by types, load checks, focused unit tests, or integration tests. Requiring a synthetic runtime assertion for those packages would optimize for satisfying a gate instead of detecting corruption.
+
+## Decision
+
+### Registration is exhaustive; assertions must be meaningful
+
+Every workspace package publishes a separately built `./invariant` companion and registers its exact npm package name. A companion does one of two things:
+
+- installs a package-owned check over an event stream or relevant mutable data structure and reports violations through its bound `fail(message)` reporter; or
+- uses an empty installer whose declaration has an owner-specific `No runtime invariant:` comment explaining why the package has no plausible runtime relation to observe.
+
+The empty form is an explicit architectural conclusion, not a generated placeholder. A future package change that introduces mutable state or an event protocol must replace the explanation with the corresponding check.
+
+The central `dsh-invariants` service owns only configuration, registration uniqueness, child-fiber lifecycle, rollback, disposal, and package-attributed failure. It exposes no generic plugin-shape, service-shape, or startup-assertion helpers and imports no product package.
+
+### Implemented checks
+
+The current 103-package workspace has 21 executable companions and 82 justified empty companions.
+
+| Owner | Runtime relationship |
+|---|---|
+| `dsh-session` | Strict sequence growth, turn/step enclosure, and same-step tool call/result pairing. |
+| `dsh-agent` | Non-repeating agent status and terminal disposal transitions. |
+| `dsh-scope` | Scoped-event carrier presence and routed-subject consistency. |
+| `dsh-agent-loop` | Explicitly marked, frozen loop request reconstruction from the session event log. |
+| `dsh-llm` | Stream block grammar, delta type/index matching, single usage, closed blocks, and terminal finish. |
+| `dsh-llm-retry` | Durable retry records identify the open turn's latest closed step, remain unique per step, increase monotonically, and stay within retry and non-negative timer bounds. |
+| `dsh-tools` | Monotonic pre/execute/post stages and immutable final execution/result snapshots. |
+| `dsh-system-prompt` | Authoritative assembly section, tool, and variable data constraints. |
+| `dsh-compact` | Compaction start/summary/end pairing, range endpoints, token counts, and successful-summary presence. |
+| `dsh-hook-protocol` | Hook invocation/result correlation, dialect, identity, and duration constraints. |
+| `dsh-sandbox-policy` | Durable `sandbox/mode` events use the closed sandbox-mode vocabulary. |
+| `dsh-fs` | Filesystem decision/observation events carry usable target and version identities. |
+| `dsh-goal` | Durable goal snapshots preserve source attribution, rendered content, revisions, lifecycle and timestamp relationships, and sequential admitted rounds. |
+| `dsh-goal-session` | Goal-sourced continuation messages match the prompt reconstructed from the preceding durable goal state. |
+| `dsh-subagent` | Provider add/remove and child start/end events preserve identity and pairing. |
+| `dsh-permission` | Durable permission decisions name a preset in the active permission table. |
+| `dsh-user-approval` | Approval asked/decided records pair by call and use valid outcomes and policies. |
+| `dsh-workflow` | Workflow and child-agent start/end events preserve run metadata, identity, outcome, count, and error relations. |
+| `dsh-tasks` | Current and terminal task snapshots preserve id/kind, owner, status, and timestamp relationships. |
+| `dsh-tool-todo` | Durable whole-list snapshots use unique trimmed items, closed statuses, and at most one active item. |
+| `dsh-time-context` | Plugin-attributed clock readings agree with the session's open turn, next pre-step position, and elapsed baseline; rendered time parses and does not postdate its event. |
+
+Session-backed companions validate existing durable events when they load, using the prefix preceding each candidate where the relationship depends on event order. Other checks observe the authoritative live event boundary or mutable service result. Validation runs before publication where accepting an invalid event would otherwise commit bad state.
+
+### Repository gate and tests
+
+`verify-package-invariants` discovers every workspace package and enforces companion source, exact-name registration, named-only Loader shape, `./invariant` exports, publication files, dependencies, TypeScript references, and bundle entries. Its AST rule rejects generated markers, default exports, and unexplained empty installers. A non-empty installer must accept and use the failure reporter, and registration must pass that checked local `install` function. The gate deliberately does not infer semantic quality from method names or helper calls.
+
+Vitest mounts `InvariantService` with `{ enabled: true }` for every package test topology and loads the owning companion. The invariant subpath path mapping resolves source companions instead of stale built output. Focused suites cover every executable companion's valid and invalid observations, and the exhaustive topology runs every source companion through the real Loader namespace normalization. An artifact gate stages each package's exact `npm pack` file inventory, imports its compiled `./invariant` self-reference under plain Node, and repeats that Loader-shape check, so an unpublished shared runtime chunk fails before release. Tests that synthesize event streams must produce a valid surrounding lifecycle unless the test is intentionally asserting a violation.
+
+## Alternatives considered
+
+- **Keep generated empty companions.** Rejected because an unexplained placeholder can survive after a package gains a meaningful runtime relation.
+- **Require an assertion from every package.** Rejected because method-presence, plugin-shape, and fixed-example assertions duplicate stronger type, load, and unit-test contracts without checking runtime consistency.
+- **Keep generic shape helpers in the service.** Rejected because they blur compile-time API validation with runtime invariants and encourage centrally defined product assumptions.
+- **Move the product checks into the service.** Rejected because product vocabulary, dependencies, tests, and change ownership belong with the package that emits the data.
+- **Register companions implicitly from root entrypoints.** Rejected because composition order and optional service presence would create hidden effects.
+
+## Consequences
+
+- Every package has visible ownership and publication wiring, but only packages with a plausible runtime relation add listeners or trace state.
+- Empty companions remain reviewable decisions with package-specific explanations and fail the gate if the explanation is removed.
+- Type declarations, Cordis loadability, plugin metadata, service method surfaces, and pure algebra remain covered by their owning compile, load, unit, or integration gates.
+- Runtime failures identify the owning npm package and point to an inconsistent observation rather than restating a required API shape.
+- The original selection, blocklist precedence, duplicate ownership, rollback, disposal, and HMR service contracts remain unchanged.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
new file mode 100644
index 0000000000..669eb02221
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.zh.md
@@ -0,0 +1,78 @@
+# Agent Note: 有意义的包不变量契约
+
+Status: implemented
+
+[English](2026-07-19-package-invariant-runtime-contracts.md) | 中文
+
+## 问题
+
+包自有不变量接缝让发布和注册实现了全覆盖，但最初的生成基线允许空安装器。后续方案又用针对插件名称、注入、effect、服务方法和固定纯函数示例的通用断言替代这些空实现。这些断言虽然让每个 companion 都能执行，却没有提高系统安全性：TypeScript、Cordis 启动、包测试和模块加载测试已经约束这些形状，而不变量服务应当发现不可能出现的运行时状态。
+
+有用的运行时不变量会关联时间上的多个观测，或关联可变数据结构中的多个部分。例如：终止事件没有对应的开始事件、LLM delta 指向未打开的 block，或持久化结果的身份与请求不同。仅确认声明的方法存在、插件名称符合预期，或常量示例仍返回已知值，都不属于这种关系。
+
+有些包确实没有可持续观测的关系。纯工具、仅负责组合的包、薄适配器、可执行入口和测试支持包可能仍有重要契约，但类型检查、加载检查、聚焦单元测试或集成测试更适合执行这些契约。强迫这些包添加合成运行时断言，只会让实现围绕通过门禁优化，而不是检测损坏。
+
+## 决策
+
+### 注册必须全覆盖；断言必须有意义
+
+每个 workspace 包都发布单独构建的 `./invariant` companion，并用完整 npm 包名注册。companion 只能采用以下两种形式之一：
+
+- 安装包自有的事件流或相关可变数据结构检查，并通过绑定的 `fail(message)` 报告器报告违规；或
+- 使用空安装器，并在其声明前写一条该包专属的 `No runtime invariant:` 注释，说明为什么该包没有合理的运行时关系可供观测。
+
+空形式是明确的架构结论，不是生成占位符。如果后续包变更引入可变状态或事件协议，就必须用相应检查替换该说明。
+
+中央 `dsh-invariants` 服务只负责配置、注册唯一性、子 fiber 生命周期、回滚、释放和归属到包的失败。它不暴露通用插件形状、服务形状或启动断言 helper，也不导入产品包。
+
+### 已实施的检查
+
+当前 103 个包的 workspace 包含 21 个可执行 companion 和 82 个有理由的空 companion。
+
+| 所有者 | 运行时关系 |
+|---|---|
+| `dsh-session` | 序号严格递增、turn/step 包围关系，以及同一 step 内的工具调用/结果配对。 |
+| `dsh-agent` | agent 状态不得重复，并且不能离开终态 disposed。 |
+| `dsh-scope` | scoped event 必须携带 carrier，且路由 subject 保持一致。 |
+| `dsh-agent-loop` | 从 session 事件日志重建带显式标记的冻结 loop 请求。 |
+| `dsh-llm` | stream block 文法、delta 类型/索引匹配、单次 usage、block 闭合和终止 finish。 |
+| `dsh-llm-retry` | 持久化重试记录指向当前打开 turn 中最近关闭的 step；每个 step 的记录保持唯一，重试次数单调递增，并且重试次数和非负的定时器延迟均保持在边界内。 |
+| `dsh-tools` | pre/execute/post 阶段单调推进，以及最终 execution/result 快照不可变。 |
+| `dsh-system-prompt` | 权威 assembly 中 section、tool 和 variable 的数据约束。 |
+| `dsh-compact` | compaction start/summary/end 配对、范围端点、token 数量和成功时必须存在 summary。 |
+| `dsh-hook-protocol` | hook invocation/result 的关联、dialect、身份和 duration 约束。 |
+| `dsh-sandbox-policy` | 持久化 `sandbox/mode` 事件必须使用封闭的 sandbox-mode 词表。 |
+| `dsh-fs` | 文件系统决策/观测事件必须携带可用的 target 和 version 身份。 |
+| `dsh-goal` | 持久化目标快照保持来源归属、渲染内容、修订号、生命周期和时间戳关系，并保证已准入的目标回合连续编号。 |
+| `dsh-goal-session` | 目标来源的继续执行消息必须匹配根据此前持久化目标状态重建的提示词。 |
+| `dsh-subagent` | provider add/remove 和 child start/end 事件必须保持身份与配对。 |
+| `dsh-permission` | 持久化 permission 决策必须引用当前 permission 表中的 preset。 |
+| `dsh-user-approval` | approval asked/decided 记录按 call 配对，并使用有效 outcome 和 policy。 |
+| `dsh-workflow` | workflow 和 child-agent start/end 事件保持 run metadata、身份、outcome、数量和 error 关系。 |
+| `dsh-tasks` | 当前与终态 task snapshot 保持 id/kind、owner、status 和 timestamp 关系。 |
+| `dsh-tool-todo` | 持久化全量 snapshot 使用唯一且已 trim 的条目、封闭 status，并且最多有一个活动条目。 |
+| `dsh-time-context` | 标注插件来源的时钟 reading 必须匹配 session 当前打开的 turn、下一个 step 开始前的位置和 elapsed baseline；渲染时间必须可解析，且不得晚于对应事件。 |
+
+基于 session 的 companion 在加载时验证已有持久化事件；关系依赖事件顺序时，会使用每个候选事件之前的事件前缀。其他检查观测权威 live event 边界或可变服务结果。如果接受无效事件会提交错误状态，验证就在发布前执行。
+
+### 仓库门禁与测试
+
+`verify-package-invariants` 发现每个 workspace 包，并强制 companion 源文件、完整名称注册、仅含具名 export 的 Loader 形状、`./invariant` export、发布文件、依赖、TypeScript reference 和 bundle entry 完整。其 AST 规则拒绝生成标记、默认导出和没有解释的空安装器。非空安装器必须接收并使用失败报告器，注册时还必须传入该经检查的本地 `install` 函数。门禁不会通过方法名或 helper 调用推断语义质量。
+
+Vitest 为每个包测试拓扑使用 `{ enabled: true }` 挂载 `InvariantService`，并加载所有者 companion。不变量 subpath 的 path mapping 会解析源 companion，而不是陈旧的构建输出。聚焦 suite 覆盖每个可执行 companion 的有效和无效观测；穷举拓扑通过真实 Loader 命名空间归一化运行每个源 companion。产物门禁会按每个包的精确 `npm pack` 文件清单暂存文件，在 plain Node 下导入该包已编译的 `./invariant` 自引用，并重复执行该 Loader 形状检查；这样，未发布的共享运行时分片会在正式发布前导致门禁失败。合成事件流的测试必须构造有效的外围生命周期，除非测试本身就是在断言违规。
+
+## 考虑过的替代方案
+
+- **保留生成的空 companion。** 拒绝，因为包获得有意义的运行时关系后，没有解释的占位符仍可能继续存在。
+- **要求每个包都执行断言。** 拒绝，因为方法存在性、插件形状和固定示例断言会重复更强的类型、加载和单元测试契约，却没有检查运行时一致性。
+- **在服务中保留通用形状 helper。** 拒绝，因为这会混淆编译期 API 验证和运行时不变量，并鼓励在中央定义产品假设。
+- **把产品检查移入服务。** 拒绝，因为产品词汇、依赖、测试和变更所有权应归属于产生这些数据的包。
+- **从根入口隐式注册 companion。** 拒绝，因为组合顺序和可选服务存在性会产生隐藏 effect。
+
+## 后果
+
+- 每个包都有可见的所有权与发布 wiring，但只有具备合理运行时关系的包才会增加 listener 或 trace 状态。
+- 空 companion 是带包专属说明、可评审的决策；删除说明后门禁会失败。
+- 类型声明、Cordis 可加载性、插件 metadata、服务方法形状和纯代数继续由所属的编译、加载、单元或集成门禁覆盖。
+- 运行时失败会标明所属 npm 包，并指出不一致的观测，而不是复述必要的 API 形状。
+- 原有 selection、blocklist 优先级、重复所有权、回滚、释放和 HMR 服务契约保持不变。
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.i18n.yaml
new file mode 100644
index 0000000000..a3e8c3ad8a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-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-19-package-owned-invariant-service.md: 2443a8f7d04b96f51bb798130078a7457f78b2a1
+2026-07-19-package-owned-invariant-service.zh.md: 3c71d3b7f99a507d4c0236b7ef6dc0794814cdc8
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
new file mode 100644
index 0000000000..2443a8f7d0
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.md
@@ -0,0 +1,105 @@
+# Agent Note: Package-owned invariant service seam
+
+Status: implemented
+
+English | [中文](2026-07-19-package-owned-invariant-service.zh.md)
+
+## Problem
+
+Runtime invariant checks span session traces, agent state, scoped dispatch, and request reconstruction. Putting all checks in one diagnostics package makes that package import product vocabularies from unrelated domains, centralizes tests away from their owners, and requires the central package to change whenever a product package adds or removes a check.
+
+Deployments also need more than presence or absence of one plugin. A standard composition should carry the known invariant contributions while permitting a global off switch and package-selective diagnostics. Selection must remain stable when a package loads later or reloads under HMR, and disabled contributions must not allow two plugins to claim the same package name silently.
+
+Package ownership must also be exhaustive. Without a mechanical repository rule, a new package can omit the companion, dependency, or publication wiring and remain invisible to diagnostics until a maintainer notices the gap.
+
+## Decision
+
+### One registry service, package-owned contributions
+
+`@deepseek-ai/dsh-invariants` is a product-independent Cordis service plugin that registers `ctx.invariants`. It owns configuration, registration uniqueness, child-fiber lifecycle, and package-attributed failures. It imports no session, agent, scope, or agent-loop package and contains none of their checks.
+
+Every workspace package publishes a `./invariant` companion plugin that registers its exact full npm name. A companion checks a meaningful event or mutable-data relationship when its owner has one; otherwise it carries an owner-specific explanation for its empty installer. Generated ownership placeholders and synthetic API-shape assertions are forbidden by the follow-up [runtime-contract Agent Note](2026-07-19-package-invariant-runtime-contracts.md). Package root entrypoints do not import or register diagnostics implicitly, so loading a root package does not change runtime checking or require the invariant service.
+
+### Configuration and selection
+
+```ts
+interface Config {
+ enabled?: boolean
+ package_allowlist?: string[]
+ package_blocklist?: string[]
+}
+```
+
+Defaults are `enabled: true`, `package_allowlist: []`, and `package_blocklist: []`. For a full registration name, selection is:
+
+```ts
+export function selected(enabled: boolean, package_allowlist: RegExp[], package_blocklist: RegExp[], packageName: string): boolean {
+ return enabled
+ && (
+ package_allowlist.length === 0
+ || package_allowlist.some(pattern => pattern.test(packageName))
+ )
+ && !package_blocklist.some(pattern => pattern.test(packageName))
+}
+```
+
+Blocklist matches override allowlist matches. Each list entry is a case-sensitive JavaScript regex source compiled by `new RegExp(pattern)`. Matching is unanchored unless callers supply `^` and `$`; slash-delimited syntax and flags are not interpreted. Startup rejects blank, whitespace-padded, invalid, or duplicate sources within either list. A source that matches no loaded package remains valid because registration order, later loading, and HMR must not change config validity.
+
+### Registration and failure ownership
+
+The public registration boundary is `ctx.invariants.register(packageName, installer)`. It reserves one active registration per full npm package name even when filters disable installation, and returns the effect disposer. Disposing the companion or service releases the reservation and all contribution state.
+
+An enabled installer runs in a dedicated child Cordis fiber owned by the service. `InvariantInstaller.inject` declares the child fiber's service surface explicitly; the registry carries no product-specific dependency metadata. The service joins a returned installer promise before registration succeeds, so asynchronous startup checks remain transactional. The installer receives a bound `fail(message)` reporter. Calling it throws an `Error` subclass named `InvariantError` with stable code `INVARIANT` and the registering `packageName`; it does not extend a product-package error base.
+
+Registration setup is transactional. If an installer fails after registering listeners, the child fiber is disposed completely and the name reservation is released before the failure escapes. Filtered registrations create no child but retain their reservation until disposal. Reloading a companion therefore begins with one clean installer state; stateful contributions rebuild baselines from their owning services.
+
+The former functional-plugin entrypoint and one-argument `InvariantError` constructor are not retained as compatibility surfaces. The repository is pre-release and all call sites move to the service and package-attributed error together.
+
+### Initial stateful companions and exhaustive ownership
+
+| Companion entry | Registration name | Owned checks |
+|---|---|---|
+| `@deepseek-ai/dsh-session/invariant` | `@deepseek-ai/dsh-session` | session sequence, turn/step enclosure, and same-step call/result trace |
+| `@deepseek-ai/dsh-agent/invariant` | `@deepseek-ai/dsh-agent` | agent-status transitions |
+| `@deepseek-ai/dsh-scope/invariant` | `@deepseek-ai/dsh-scope` | scoped-event carrier presence and subject consistency |
+| `@deepseek-ai/dsh-agent-loop/invariant` | `@deepseek-ai/dsh-agent-loop` | model-request reconstruction |
+
+These four owners supplied the initial stateful checks. The follow-up runtime-contract decision adds checks for seventeen more owners with real event or mutable-data relationships and records justified empty companions for the rest. Every companion is a separately bundled `./invariant` export with its own declarations and Loader-safe namespace plugin shape; the service package's own companion imports its local service type to avoid a self-dependency.
+
+`verify-package-invariants` discovers every workspace package and rejects missing companion source, generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, foreign or unresolved registration names, missing `./invariant` exports or published files, missing invariant peer/development dependencies and project references, and bundle overrides that omit the companion entry.
+
+### Scoped-event semantic map
+
+The generated scoped-event subject resolver lives in `dsh-scope`, beside the contract and invariant that consume it. `gen-scoped-events` uses the root TypeScript Program to enumerate `this: Scoped` declarations, infer routing-key types from real `scopeTarget(base, key)` calls, and require one unambiguous payload subject or an explicit unsupported marker. The committed runtime map imports no event-owner package, so semantic completeness does not expand either the service or scope package's runtime closure.
+
+### Standard composition and SDK output
+
+The standard agent spine mounts the service and all four stateful companion subpaths, forwarding `enabled`, `package_allowlist`, and `package_blocklist` to the service. Generated SDK Cordis composition emits the same entries. A subpath entry adds its installable root npm package rather than treating the subpath as a package name.
+
+Workspace constraints recognize the separate invariant bundle, and package exports, project references, build configuration, dependency declarations, and the lockfile describe the same publication surface. Generated config catalogs, module graphs, and API documentation derive from those sources.
+
+## Testing
+
+Service tests cover defaults, global disablement, allow/block selection, blocklist precedence, anchoring, unanchored matching, case sensitivity, invalid configuration, zero-match patterns, late registration, duplicate ownership, disposal, rollback, and HMR re-registration. Owners with executable checks keep positive and negative behavior beside the companion source.
+
+Composition tests cover standard-spine forwarding and generated SDK entries. Loader tests preserve each companion namespace, while built plain-Node smokes exercise the compiled subpath exports. The scoped-event freshness gate reruns its semantic Program analysis.
+
+Every Vitest configuration loads a test host that mounts an explicitly enabled service before an ordinary Cordis root's first plugin and adds the current test package's companion. One exhaustive topology mounts all package companions once; focused service and owner tests construct their own invariant topology so they can exercise disablement, filtering, rollback, and reload without duplicate ownership. Gate tests also execute every companion's `apply` function and verify that it calls `register` with its manifest name, rather than accepting source text alone.
+
+## Alternatives considered
+
+- **Keep all checks in `dsh-invariants`.** Rejected because the registry would continue importing every checked product domain, owner changes would require central edits, and package tests would remain detached from the contracts they protect.
+- **Let root package entrypoints register checks implicitly when `ctx.invariants` happens to exist.** Rejected because root behavior would depend on composition order and optional service presence, diagnostics could not be selected independently, and package loading would hide a registration effect outside an explicit companion.
+- **Discover every `invariant.ts` file automatically at runtime.** Rejected because filesystem/package discovery is not a runtime ownership contract, makes bundled publication ambiguous, and cannot express explicit Cordis load order or dependency installation. Build-time generation, verification, and the test host may enumerate the source tree because they validate repository completeness rather than composing a shipped deployment.
+- **Validate allow/block entries against the currently loaded package set.** Rejected because a zero-match pattern can intentionally target a later or HMR-loaded contribution; current load order must not determine config validity.
+
+## Consequences
+
+- Product packages own and test their relational assertions while the service stays product-independent.
+- Every package pays the publication and dependency cost of a companion; only owners with a meaningful runtime relationship add listener or trace-state cost.
+- Standard compositions can disable all checks or select package names without changing their plugin tree.
+- Explicit companion entries make diagnostic cost and ownership visible in Cordis config and package exports.
+- One selected executable contribution adds one child fiber and its listener/state cost; a selected empty contribution has no listener or trace-state cost, while filtered registrations retain only name ownership.
+- Regex sources are deployment configuration and remain fixed until the service reloads.
+- Ordinary Vitest roots install the owning test package's selected companion; one exhaustive topology pays the full child-fiber cost once for repository-wide registration coverage.
+- Session storage validation, snapshotting, freezing, provenance, and surface acceptance remain always on and are not affected by invariant selection.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
new file mode 100644
index 0000000000..3c71d3b7f9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-19-package-owned-invariant-service.zh.md
@@ -0,0 +1,105 @@
+# Agent Note: 包拥有的不变式服务接缝
+
+Status: implemented
+
+[English](2026-07-19-package-owned-invariant-service.md) | 中文
+
+## 问题
+
+运行时不变式检查跨越会话轨迹、agent 状态、作用域 dispatch 和请求重建。如果所有检查都放在一个诊断包中，该包就必须导入彼此无关的产品领域词汇，测试也会离开真正的所有者；任何产品包新增或移除检查时，都要修改中央包。
+
+部署还需要比“是否加载一个插件”更细的控制。标准组合应携带已知的不变式贡献，同时允许全局关闭或按包选择诊断。包稍后加载或在 HMR 下重载时，选择结果必须保持稳定；被过滤的贡献也不能让两个插件静默占用同一个包名。
+
+包所有权还必须覆盖完整。若没有机械化的仓库规则，新包可能遗漏伴随插件、依赖或发布配置，并一直不会进入诊断范围，直到维护者发现这一缺口。
+
+## 决策
+
+### 一个注册服务，贡献归包所有
+
+`@deepseek-ai/dsh-invariants` 是与产品无关的 Cordis 服务插件，注册 `ctx.invariants`。它只负责配置、注册唯一性、子 fiber 生命周期和带包归属的失败；不导入 session、agent、scope 或 agent-loop 包，也不包含这些包的检查。
+
+工作区内的每个包都发布 `./invariant` 伴随插件，注册自己完整且准确的 npm 包名。如果所有者具备有意义的事件或可变数据关系，companion 就检查该关系；否则空 installer 必须携带该所有者专属的说明。后续的[运行时契约 Agent Note](2026-07-19-package-invariant-runtime-contracts.md) 禁止生成的所有权占位符和合成 API 形状断言。包的根入口不会隐式导入或注册诊断，因此加载根包不会改变运行时检查，也不要求不变式服务存在。
+
+### 配置与选择
+
+```ts
+interface Config {
+ enabled?: boolean
+ package_allowlist?: string[]
+ package_blocklist?: string[]
+}
+```
+
+默认值为 `enabled: true`、`package_allowlist: []` 和 `package_blocklist: []`。对完整注册名的选择规则为：
+
+```ts
+export function selected(enabled: boolean, package_allowlist: RegExp[], package_blocklist: RegExp[], packageName: string): boolean {
+ return enabled
+ && (
+ package_allowlist.length === 0
+ || package_allowlist.some(pattern => pattern.test(packageName))
+ )
+ && !package_blocklist.some(pattern => pattern.test(packageName))
+}
+```
+
+blocklist 匹配优先于 allowlist 匹配。每个条目都是区分大小写的 JavaScript 正则表达式源，通过 `new RegExp(pattern)` 编译。除非调用方提供 `^` 与 `$`，否则匹配不锚定；系统不会解析斜杠包围语法或 flags。服务启动会拒绝空白、首尾带空白、无效或同一列表内重复的源。没有匹配当前已加载包的有效源仍然合法，因为注册顺序、稍后加载和 HMR 不应改变配置有效性。
+
+### 注册与失败归属
+
+公开注册边界是 `ctx.invariants.register(packageName, installer)`。即使过滤器禁止安装，它也会为每个完整 npm 包名保留唯一的活跃注册，并返回 effect disposer。卸载伴随插件或服务都会释放注册名及全部贡献状态。
+
+启用的 installer 在服务拥有的独立 Cordis 子 fiber 中运行。`InvariantInstaller.inject` 显式声明该子 fiber 的服务表面；注册服务不携带产品专用依赖元数据。服务会在注册成功前等待 installer 返回的 promise，因此异步启动检查仍具有事务性。installer 接收绑定后的 `fail(message)` 报告器。调用它会抛出名为 `InvariantError` 的 `Error` 子类，保留稳定代码 `INVARIANT` 并记录注册方 `packageName`；该错误不继承产品包中的错误基类。
+
+注册启动是事务性的。如果 installer 在注册监听器后失败，子 fiber 会完整释放，并在失败向外传播前解除包名占用。被过滤的注册不创建子 fiber，但会保留占用直到 dispose。伴随插件重载时总会从干净的 installer 状态开始；有状态贡献从其所属服务重建基线。
+
+原有函数式插件入口与单参数 `InvariantError` 构造函数不作为兼容表面保留。仓库尚未发布，所有调用方会一起迁移到服务和带包归属的错误。
+
+### 首批有状态伴随插件与完整所有权
+
+| 伴随入口 | 注册名 | 所属检查 |
+|---|---|---|
+| `@deepseek-ai/dsh-session/invariant` | `@deepseek-ai/dsh-session` | 会话序号、turn/step 包围关系和同 step 的 call/result 轨迹 |
+| `@deepseek-ai/dsh-agent/invariant` | `@deepseek-ai/dsh-agent` | agent 状态转换 |
+| `@deepseek-ai/dsh-scope/invariant` | `@deepseek-ai/dsh-scope` | scoped event carrier 存在性与主体一致性 |
+| `@deepseek-ai/dsh-agent-loop/invariant` | `@deepseek-ai/dsh-agent-loop` | 模型请求重建 |
+
+这四个所有者提供了首批有状态检查。后续运行时契约决策为另外十七个确有事件或可变数据关系的所有者增加检查，并为其余包记录有理由的空 companion。每个伴随入口都是单独打包的 `./invariant` export，具有独立声明和对 Loader 安全的命名空间插件形态；服务包自身的伴随插件导入本地服务类型，避免形成自依赖。
+
+`verify-package-invariants` 会发现每个工作区包，并拒绝缺失的伴随插件源码、生成标记、没有解释的空 installer、缺少或不使用失败报告器的非空 installer、外部或无法解析的注册名、缺失的 `./invariant` export 或发布文件、缺失的不变式对等依赖（peer dependency）、开发依赖及项目引用，以及遗漏伴随入口的自定义构建配置。
+
+### Scoped event 语义映射
+
+生成的 scoped event 主体解析表位于 `dsh-scope`，与消费它的契约和不变式相邻。`gen-scoped-events` 使用根 TypeScript Program 枚举 `this: Scoped` 声明，从真实 `scopeTarget(base, key)` 调用推断路由键类型，并要求唯一、无歧义的 payload 主体或显式 unsupported 标记。提交的运行时映射不导入事件所有者包，因此语义完整性不会扩大服务包或 scope 包的运行时依赖闭包。
+
+### 标准组合与 SDK 输出
+
+标准 agent spine 会挂载服务和四个有状态伴随子路径，并把 `enabled`、`package_allowlist` 与 `package_blocklist` 转发给服务。生成的 SDK Cordis 组合输出相同条目。子路径条目添加可安装的根 npm 包，而不会把子路径误当成包名。
+
+Workspace 约束识别独立的不变式 bundle；包 exports、项目引用、构建配置、依赖声明和 lockfile 描述同一发布表面。生成的配置目录、模块图和 API 文档都从这些源派生。
+
+## 测试
+
+服务测试覆盖默认值、全局关闭、allow/block 选择、blocklist 优先级、锚定与非锚定匹配、大小写敏感、无效配置、零匹配模式、延迟注册、重复所有权、dispose、回滚和 HMR 重新注册。具备可执行检查的所有者会把正向与负向行为保留在 companion 源码旁边。
+
+组合测试覆盖标准 spine 转发和生成的 SDK 条目。Loader 测试固定每个伴随命名空间，构建后的纯 Node smoke 覆盖编译子路径 export。scoped event 新鲜度门禁会重新执行语义 Program 分析。
+
+每个 Vitest 配置都会加载测试宿主；在普通 Cordis 根上下文启动第一个插件之前，宿主会挂载显式启用的服务，并添加当前测试包的伴随插件。一个完整拓扑会一次挂载所有包的伴随插件；服务与所有者的聚焦测试自行构建不变式拓扑，从而在不发生重复所有权冲突的前提下覆盖关闭、过滤、回滚与重载。门禁测试还会执行每个伴随插件的 `apply` 函数，并验证它调用 `register` 时使用包清单中的包名，而不是只检查源码文本。
+
+## 考虑过的替代方案
+
+- **把所有检查保留在 `dsh-invariants`。** 不予采纳，因为注册包仍要导入所有被检查的产品领域，所有者变更仍需中央编辑，测试也继续远离被保护的契约。
+- **当 `ctx.invariants` 恰好存在时，让根包入口隐式注册检查。** 不予采纳，因为根入口行为会依赖组合顺序与可选服务是否存在，诊断无法独立选择，而且包加载会隐藏一个不在显式伴随插件中的注册 effect。
+- **在运行时自动发现所有 `invariant.ts` 文件。** 不予采纳，因为文件系统或包发现不是运行时所有权契约，会让 bundle 发布含义不清，也无法表达显式 Cordis 加载顺序或依赖安装。构建期生成与校验以及测试 host 可以枚举源码树，因为它们验证的是仓库完整性，而不是组合已发布的部署。
+- **根据当前已加载包集合验证 allow/block 条目。** 不予采纳，因为零匹配模式可能有意指向稍后加载或 HMR 加载的贡献；当前加载顺序不能决定配置有效性。
+
+## 后果
+
+- 产品包拥有并测试自己的关系断言，服务保持与产品无关。
+- 每个包都承担 companion 的发布与依赖成本；只有具备有意义运行时关系的所有者才增加 listener 或 trace 状态成本。
+- 标准组合无需改变插件树即可关闭全部检查或按包名选择。
+- 显式伴随条目让诊断成本和所有权在 Cordis 配置与包 export 中可见。
+- 每个选中的可执行贡献增加一个子 fiber 及其 listener/状态成本；选中的空贡献不增加 listener 或 trace 状态成本，被过滤注册则只保留包名占用。
+- 正则表达式源属于部署配置，在服务重载前保持固定。
+- 普通 Vitest 根上下文会安装当前测试包中被选中的伴随插件；一个完整拓扑只支付一次全部子 fiber 成本，用于覆盖整个仓库的注册。
+- 会话存储验证、快照、冻结、provenance 与 surface 接受规则始终启用，不受不变式选择影响。
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.i18n.yaml
new file mode 100644
index 0000000000..c9290db5ea
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.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-20-routed-model-context-and-compaction-policy.md: f0b9288d3d864bfcc2964862b1ff294406daa345
+2026-07-20-routed-model-context-and-compaction-policy.zh.md: cda740a5671a3ef8a5bb415e5cc45ca8397c1c59
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
new file mode 100644
index 0000000000..f0b9288d3d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md
@@ -0,0 +1,57 @@
+# Agent Note: Routed model context and compaction policy
+
+Status: implemented
+
+English | [中文](2026-07-20-routed-model-context-and-compaction-policy.zh.md)
+
+## Problem
+
+Compaction cannot safely apply one global context window when a process routes requests to models with different capacities. The same model id can also exist under multiple providers, and an adapter may accept dynamic ids absent from its advisory catalog. A wrong capacity either compacts too late and triggers avoidable overflow or compacts too early and discards useful context.
+
+Neither obvious configuration owner is sufficient. Compact-basic is optional and does not know which models an adapter accepts. LLM adapters own model routing but must not depend on an optional compaction plugin or absorb consumer-specific threshold, retention, summarizer, and retry policy. The design needs an authoritative capacity fact and optional per-target compaction policy without creating a second model registry.
+
+## Decision
+
+### Adapters own exact-route capacity
+
+`LlmAdapter.resolveModelContext(provider, model)` optionally returns `LlmModelContext` for one exact route. `LlmService.resolveModelContext()` selects the registered route owner, validates a positive integer `contextWindow`, and returns a detached value. The query is independent of `listModels()`: an unlisted dynamic model may have capacity metadata, and `undefined` means only that the adapter cannot describe capacity.
+
+The hand-rolled DeepSeek adapter accepts optional `contextWindow` on each configured model. Its two default model entries publish 128,000 tokens; an explicit entry without capacity and an unlisted pass-through id return `undefined`. The pi-ai adapter resolves capacity from the same catalog descriptor that authoritatively resolves the request model.
+
+### Token measurement remains model-agnostic
+
+`dsh-token-meter` has no configuration and no model profiles. It owns one fixed replay fold and returns absolute estimated token pressure plus positional surface prices. Removing global capacity keeps measurement reusable when compact-basic is absent and prevents replay accounting from becoming another model registry.
+
+### Compact-basic resolves a target spec
+
+Compact-basic owns consumer policy. Top-level fields define defaults; `modelPolicies` contains partial overrides keyed by the exact `{ provider, model }` pair. Duplicate targets and unknown or invalid fields fail plugin load. `thresholdRatio` defaults to `0.8`, and retention defaults to `retainRatio: 0.16`; callers may use an absolute `retainTokens` instead, but the two retention forms are mutually exclusive. After inheritance, a ratio retention that is not below its threshold ratio also fails plugin load because no model capacity can make that policy valid.
+
+For proactive pressure, compact-basic reads the latest durable request route, resolves its adapter capacity and exact-target policy, and scales ratios into a `ResolvedCompactSpec`. It performs this resolution on every check, so a provider or model switch in one session changes capacity and policy immediately. An absolute retained budget that is not below the scaled threshold fails when the target capacity first makes that comparison possible.
+
+The same exact-target override can select summarization provider/model, summarization output cap, convergence retries, and overflow retry cap. These are compaction concerns and never enter the adapter seam.
+
+### Target-specific pressure failures preserve optional composition
+
+An adapter that lacks capacity metadata remains a valid LLM route. Manual proactive pressure fails with a target-specific configuration error; the automatic listener warns once per exact route and continues with full history. The same per-route suppression applies when resolved capacity exposes an invalid absolute retention budget, while unrelated operational failures remain independently visible. Canonical provider-confirmed overflow does not need capacity metadata: it bypasses the proactive threshold and normal retention budget, attempts one maximal balanced reduction, and preserves the original provider error unless replacement proves progress.
+
+## Testing
+
+Service tests cover detached context metadata, invalid adapter output, catalog independence, and default absence. Adapter tests cover DeepSeek configured/default/unlisted behavior and pi-ai exact descriptor resolution. Compact tests cover ratio scaling, exact provider/model overrides, load-time rejection of invalid merged ratios, runtime absolute-budget validation, same-model-id provider switches, target-specific warning suppression, and capacity-independent overflow recovery. Loader fixtures reject the removed token-meter capacity setting, and examples configure capacity on adapters.
+
+## Alternatives considered
+
+- **Put capacity and all policies in compact-basic** — rejected because compact-basic would duplicate adapter model knowledge, dynamic unlisted models would require parallel registration, and capacity would disappear when compaction is not installed.
+- **Put compaction policy in each LLM adapter** — rejected because adapters must remain independent of optional consumers, while summarization and retry policy are not provider facts.
+- **Make `listModels()` authoritative** — rejected because discovery is advisory and some adapters intentionally accept dynamic ids. Correctness metadata must not turn selector membership into a routing whitelist.
+- **Add per-model folds to token-meter** — rejected because the replay algorithm is shared; only the capacity and consumer policy change. Multiple folds would duplicate state without improving estimation.
+- **Create a standalone model-context registry** — rejected because the adapter already owns authoritative route resolution. A second registry would introduce lifecycle ordering, duplicate-key, and drift problems without an independent backend.
+
+## Consequences
+
+- Capacity has one authoritative owner at the provider seam, while compaction policy stays in the optional consuming plugin.
+- The same compact-basic instance safely handles different windows, provider switches, and identical model ids under different providers without consulting discovery metadata.
+- LLM-only and meter-only compositions remain valid; loading compact-basic adds no reverse dependency from adapters.
+- Deployments using explicit DeepSeek model lists must provide `contextWindow` for proactive pressure on those entries. Missing metadata is visible instead of silently applying a wrong global fallback.
+- Ratio defaults scale naturally across models, while exact-target absolute retention remains available for deployment-specific behavior.
+
+This note supersedes the global-capacity and no-model-policy parts of the [replay token meter service Agent Note](2026-07-15-replay-token-meter-service.md). Its single-fold measurement decision remains unchanged.
diff --git a/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
new file mode 100644
index 0000000000..cda740a567
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.zh.md
@@ -0,0 +1,57 @@
+# Agent Note: 路由模型上下文与压缩策略
+
+Status: implemented
+
+[English](2026-07-20-routed-model-context-and-compaction-policy.md) | 中文
+
+## 问题
+
+当一个进程把请求路由到不同容量的模型时，压缩不能安全地应用同一个全局上下文窗口。相同模型 id 也可能存在于多个提供方下，适配器还可能接受不在建议目录中的动态 id。错误容量要么让压缩触发过晚并造成原本可避免的溢出，要么让压缩触发过早并丢弃有用上下文。
+
+两个直观的配置归属方都无法独立解决问题。Compact-basic 是可选插件，不知道适配器接受哪些模型。LLM 适配器拥有模型路由，但不能依赖可选压缩插件，也不应吸收消费方专用的阈值、保留、摘要器与重试策略。该设计既需要权威容量事实和可选的逐目标压缩策略，又不能建立第二套模型注册表。
+
+## 决策
+
+### 适配器拥有精确路由容量
+
+`LlmAdapter.resolveModelContext(provider, model)` 可以为一条精确路由返回 `LlmModelContext`。`LlmService.resolveModelContext()` 选择已注册的路由所属方，验证 `contextWindow` 为正整数，并返回分离值。该查询独立于 `listModels()`：不在目录中的动态模型也可以拥有容量元数据，而 `undefined` 只表示适配器无法描述容量。
+
+手写 DeepSeek 适配器允许每个已配置模型提供可选 `contextWindow`。两个默认模型项都公开 128,000 token；未提供容量的显式模型项与未列出的透传 id 返回 `undefined`。pi-ai 适配器从同一个目录描述符解析容量，该描述符也用于权威解析请求模型。
+
+### Token 计量保持模型无关
+
+`dsh-token-meter` 没有配置，也没有模型 profile。它拥有一个固定回放折叠，并返回绝对估算 token 压力与逐位置表层价格。移除全局容量后，未加载 compact-basic 时仍可复用计量，同时避免让回放核算变成另一套模型注册表。
+
+### Compact-basic 解析目标规格
+
+Compact-basic 拥有消费方策略。顶层字段定义默认值；`modelPolicies` 包含以精确 `{ provider, model }` 组合为键的部分覆盖。重复目标、未知字段或无效字段都会让插件加载失败。`thresholdRatio` 默认为 `0.8`，保留策略默认为 `retainRatio: 0.16`；调用方也可以改用绝对 `retainTokens`，但两种保留形式互斥。完成继承后，如果保留比例不小于阈值比例，插件也会加载失败，因为任何模型容量都无法让该策略有效。
+
+对于主动压力检查，compact-basic 读取最新持久请求路由，解析其适配器容量与精确目标策略，再把比例缩放为 `ResolvedCompactSpec`。每次检查都会重新解析，因此同一会话切换提供方或模型后，容量与策略会立即变化。若绝对保留预算不小于缩放后的阈值，系统会在目标容量首次允许比较两者时失败。
+
+同一精确目标覆盖还可以选择摘要提供方/模型、摘要输出上限、收敛重试次数与溢出重试上限。这些都属于压缩问题，不会进入适配器 seam。
+
+### 目标专用压力错误仍保留可选组合
+
+缺少容量元数据的适配器仍是有效 LLM 路由。手动主动压力检查会返回目标专用配置错误；自动监听器按精确路由只警告一次，并继续保留完整历史。当已解析容量暴露出无效的绝对保留预算时，系统也按路由抑制重复警告；其他运行故障仍会各自对外可见。提供方已经确认的规范化溢出不需要容量元数据：它绕过主动阈值与普通保留预算，尝试一次最大的平衡缩减，并在替换无法证明进展时保留原始提供方错误。
+
+## 测试
+
+服务测试覆盖分离上下文元数据、无效适配器输出、目录独立性与默认缺失行为。适配器测试覆盖 DeepSeek 的配置值、默认值与未列出行为，以及 pi-ai 的精确描述符解析。压缩测试覆盖比例缩放、精确提供方/模型覆盖、加载期拒绝无效合并比例、运行时校验绝对预算、相同模型 id 的提供方切换、目标专用警告抑制与不依赖容量的溢出恢复。Loader fixture 会拒绝已经移除的 token-meter 容量设置，示例则在适配器上配置容量。
+
+## 考虑过的替代方案
+
+- **把容量与所有策略都放进 compact-basic**——不予采纳，因为 compact-basic 会复制适配器的模型知识，未列出的动态模型需要并行注册，而且未安装压缩时容量也会消失。
+- **把压缩策略放进各个 LLM 适配器**——不予采纳，因为适配器必须独立于可选消费方，而摘要与重试策略也不是提供方事实。
+- **让 `listModels()` 成为权威来源**——不予采纳，因为发现能力只是建议信息，一些适配器有意接受动态 id。正确性元数据不能把选择器成员关系变成路由白名单。
+- **给 token-meter 增加逐模型折叠**——不予采纳，因为回放算法可以共享，变化的只有容量与消费方策略。多个折叠会重复状态，却不会改善估算。
+- **建立独立模型上下文注册表**——不予采纳，因为适配器已经拥有权威路由解析。第二套注册表会引入生命周期顺序、重复键与漂移问题，却没有独立后端。
+
+## 后果
+
+- 容量在提供方 seam 上拥有唯一权威归属方，而压缩策略留在可选消费插件中。
+- 同一个 compact-basic 实例无需查询发现元数据，就能安全处理不同窗口、提供方切换，以及不同提供方下的相同模型 id。
+- 仅 LLM 与仅 meter 的组合仍然有效；加载 compact-basic 不会让适配器产生反向依赖。
+- 使用显式 DeepSeek 模型列表的部署必须为需要主动压力检查的条目提供 `contextWindow`。系统会暴露缺失元数据，而不是静默应用错误的全局回退值。
+- 比例默认值会随模型自然缩放，同时仍可按精确目标使用绝对保留值，以满足部署专用行为。
+
+本记录取代[回放式 token 计量服务 Agent Note](2026-07-15-replay-token-meter-service.md) 中的全局容量与无模型策略部分，单折叠计量决策保持不变。
diff --git a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
index 99313866ed..93a14c9f93 100644
--- a/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
+++ b/.agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md
@@ -8,7 +8,7 @@ A long-running agent conversation grows without bound. As the event log accumula
The [session surface](../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 policy and reusable token measurement vary independently: measurement belongs to the LLM-family [`ctx.tokenMeter` service](../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.
+Two forces shape the design. First, compaction policy and reusable token measurement vary independently: measurement belongs to the LLM-family [`ctx.tokenMeter` service](../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 and Session's always-on append/seed boundary reject `surfaceOp` on it.
## Decision
@@ -53,7 +53,7 @@ retry → next numbered step/start ⟵ derives from the replacement surface
Auto-compaction checks after **every successful** step, not once per turn. This is load-bearing for runaway-turn survival: a tool-heavy ReAct turn appends an `assistant/message` + a `tool/result` per step, so the surface grows within a turn. The post-step check can compact early closed tool pairs before continuation opens the next step, and provider-confirmed overflow remains the backstop when a request crosses the limit first.
-`compactIfNeeded` retains the smallest tail of whole surface units whose estimated size reaches `retainTokens` and compacts older nodes. A unit is a complete closed step or one no-step message. If the token cutoff lands inside a step, retention expands until the cut is tool-pairing balanced. Balance is checked on surface order, not log sequence, because replacement summaries have new sequence numbers at old surface positions. `dsh-compact` exports the before/after edge helpers; their per-session cache folds only appended surface-tail nodes while `replaceGeneration` is unchanged, does no event reads for log-only growth, and rebuilds current membership and balances after replacement. `compactRegion` rejects boundaries that split a tool call from its result. The in-flight turn receives no special retention.
+`compactIfNeeded` retains the smallest tail of whole surface units whose estimated size reaches the resolved retained-token budget and compacts older nodes. A unit is a complete closed step or one no-step message. If the token cutoff lands inside a step, retention expands until the cut is tool-pairing balanced. Balance is checked on surface order, not log sequence, because replacement summaries have new sequence numbers at old surface positions. `dsh-compact` exports the before/after edge helpers; their per-session cache folds only appended surface-tail nodes while `replaceGeneration` is unchanged, does no event reads for log-only growth, and rebuilds current membership and balances after replacement. `compactRegion` rejects boundaries that split a tool call from its result. The in-flight turn receives no special retention.
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.
@@ -65,7 +65,7 @@ Auto-compaction always starts at the surface head, merging the prior checkpoint
### Approximate convergence invariant
-`resolveConfig` supplies usable defaults: threshold ratio `0.8`, retained tail `floor(contextWindow × 0.16)`, empty summarization provider/model overrides, `maxTokens: 8192`, `compactionRetries: 1`, `maxOverflowRetries: 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 pressure 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. Overflow bypasses threshold and retained-tail policy for one maximal balanced head reduction, leaving the newest indivisible unit.
+`resolveConfig` supplies usable defaults: threshold ratio `0.8`, retained-tail ratio `0.16`, empty summarization provider/model overrides, `maxTokens: 8192`, `compactionRetries: 1`, `maxOverflowRetries: 1`, and `auto: true`. Optional exact provider/model policies partially override the top-level defaults; pressure scales ratios against capacity from the route-owning LLM adapter, while `retainTokens` can replace ratio retention. 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 pressure 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. Overflow needs no capacity metadata and bypasses threshold and retained-tail policy for one maximal balanced head reduction, leaving the newest indivisible unit. The ownership split is specified by the [routed model context and compaction policy Agent Note](../architecture/2026-07-20-routed-model-context-and-compaction-policy.md).
### Surface replacement: `compact/*` events are log-only; one `user/message` carries the summary
@@ -115,7 +115,7 @@ Two failure paths, both documented:
- **Automatic seams**: `agent/post-step` (`@mode serial`) handles successful-call pressure and `agent/request-error` (`@mode waterfall`) handles final request failures after the failed step closes. Generic `agent/pre-step` remains a four-argument checkpoint with no compaction-only prompt/prefix payload.
- **`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, 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`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. `dsh-invariants` treats fresh appended tool results as executions that require an open step and pending call; validated replacements remain turn-enclosed rewrites.
+- **`dsh-session`** validates positional replacement, complete provenance, and content-only single-node `tool/result` rewrites through its one surface manager. Its invariant companion treats fresh appended tool results as executions that require an open step and pending call; validated replacements remain turn-enclosed rewrites.
- **Wiring**: `examples/tui-agent/cordis.yml` loads zero-config `dsh-token-meter`, `dsh-compact-tool-result-prune`, then `dsh-compact-basic`; service-wide defaults make the composition usable without repeated numeric policy.
## Testing
diff --git a/.agents/notes/implemented/feature/2026-07-07-session-prefix.md b/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
index c2f58dac0c..7faf80cf80 100644
--- a/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
+++ b/.agents/notes/implemented/feature/2026-07-07-session-prefix.md
@@ -14,7 +14,7 @@ The obvious third option — let a plugin edit the request's `messages` on the w
Three properties carry the design:
-- **Request-only, header-logged.** `deriveMessages()` never returns the prefix; its one durable record is `EpochHeader.messagePrefix` on the instance's anchoring `request/header` snapshot — the channel the reconstructable-requests Agent Note already owns for the request's non-history half, so no new session event exists. The dev invariant ([dsh-invariants](../../../../packages/support/invariants/src/index.ts)) recomputes `messagePrefix + boundary derivation` against every loop-built request; an unlogged prefix cannot reach the wire.
+- **Request-only, header-logged.** `deriveMessages()` never returns the prefix; its one durable record is `EpochHeader.messagePrefix` on the instance's anchoring `request/header` snapshot — the channel the reconstructable-requests Agent Note already owns for the request's non-history half, so no new session event exists. The [`dsh-agent-loop/invariant`](../../../../packages/core/agent-loop/src/invariant.ts) companion recomputes `messagePrefix + boundary derivation` against every loop-built request; an unlogged prefix cannot reach the wire when that contribution is enabled.
- **Frozen per instance.** Reuse is structural, not disciplined: the cached product cannot change mid-session, so the provider's prompt cache holds by construction and the prefix extends the cacheable region at zero marginal cost per step. A process restart or `ctx.agents.resume()` is a new instance: it recomposes, and any drift lands attributably on the `'resume'` header snapshot. This is the routing rule the seam creates: session-frozen openers ride the prefix; content that changes mid-session rides the append-only history channels (`agent.inject()` or tool/prompt-submit `additionalContexts` — [the interception-seams Agent Note](2026-06-30-interception-seams.md)), each a durable `context/message` paid once and prefix-cached thereafter.
- **Exact in the durable request envelope.** Composition precedes the instance's first `agent/pre-step` and request boundary. The first routed request logs the current prefix on its header, so post-step token pressure reads the exact prefix together with the actual prompt, tools, and routed model; no compaction-only parameter is carried through the generic pre-step seam. A composition interrupted by cancel/dispose is discarded, never cached: an abort-aware listener's degraded fallback cannot leak into later requests, and the next turn recomposes under a live signal.
diff --git a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
index b3bdbb0c1b..44d1b17a5b 100644
--- a/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
+++ b/.agents/notes/implemented/process/2026-07-13-documentation-site-projection.md
@@ -20,7 +20,7 @@ The projector parses Markdown links without reserializing the document. A link t
Mermaid renders the canonical diagrams. The website workspace explicitly declares the five packages that `vitepress-plugin-mermaid` asks Vite to prebundle because pnpm's strict dependency isolation otherwise makes those transitive packages unavailable to the local development server; Knip records this runtime-only use as an intentional dependency exception.
-Site publication is separate from site construction. The repository contains local development and build commands, but no hosting or deployment workflow until a public destination is chosen.
+Site publication remains separate from site construction. A dedicated GitHub Actions workflow runs the existing documentation gates, uploads `website/.dist` as a Pages artifact, and deploys only after the build succeeds. `actions/configure-pages` supplies the destination's base path to VitePress at build time, so the private Pages origin, a later public project path, and a custom domain do not require distinct checked-in configurations. Pages visibility remains a repository hosting setting rather than a workflow permission.
## Alternatives considered
@@ -34,8 +34,10 @@ Site publication is separate from site construction. The repository contains loc
**Build only in a deployment workflow.** A deployment job can reveal rendering failures after merge. Keeping the production build in `doc-sync` makes the same failure visible locally and in ordinary CI even when no public deployment exists.
+**Hard-code the public project path.** A fixed `/deepseek-harness/` base works for the public project URL but not for the unique origin assigned to a private Pages site or for a future custom domain. Consuming Pages metadata keeps one build contract across those destinations.
+
## Consequences
-Documentation facts have one editable home, public routes remain stable across source moves, and the site can include generated references without committing another generated copy. Local development watches canonical inputs and regenerates the disposable projection.
+Documentation facts have one editable home, public routes remain stable across source moves, and the site can include generated references without committing another generated copy. Local development watches canonical inputs and regenerates the disposable projection. Merges that affect the documentation site deploy the checked result to Pages, while manual dispatch provides a recovery and validation entry point.
The publication manifest is a maintained allowlist, and link projection adds a small repository-specific build adapter. A new kind of Markdown link behavior needs a projector test. Mermaid support also increases the client bundle size, but preserves diagrams already used by the canonical documentation.
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
index 366faaf6a3..b56814b9a3 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.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-typescript-program-backed-semantic-gates.md: f9c00a4b6a5e9f08c11902e9267e4c1a954cebf8
-2026-07-14-typescript-program-backed-semantic-gates.zh.md: ce1f1edc765f621ca9f650720aa2db43f636e330
+2026-07-14-typescript-program-backed-semantic-gates.md: 43a7b9b5369feb199721f5f1348c03cde66ee411
+2026-07-14-typescript-program-backed-semantic-gates.zh.md: 1ab027d723e30007e6675ae1f3589fb594d10afc
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
index f9c00a4b6a..43a7b9b536 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
@@ -38,9 +38,9 @@ Every declared harness event must have a discovered producer. A missing producer
Exactly one match generates a resolver. Multiple matches are ambiguous and fail. Zero matches require `@dshScopeScan unsupported`, which is reserved for events whose routing key intentionally stays outside the payload, such as owner-keyed session events and parent-keyed subagent lifecycle events. The annotation records an unsupported scan; it does not encode an event name, parameter index, property path, or replacement type.
-The committed [`scoped-events.generated.ts`](../../../../packages/support/invariants/src/scoped-events.generated.ts) imports every scoped-event owner for its type-side `Events` contributions. Each generated lambda accepts `Parameters`, and the complete object satisfies a `Record` over the derived `ScopedEventName` union. Ordinary TypeScript compilation therefore checks event existence, parameter position, property access, and scoped-event completeness. The only cast adapts Cordis's runtime `unknown[]` dispatch boundary to the already type-checked resolver.
+The committed [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) is a runtime-only map in the package that owns scoped dispatch and imports no event-owner package. Semantic completeness lives in the generator: its root Program enumerates every scoped `Events` declaration and real `scopeTarget` contract, resolves the unique payload path with the checker, and refuses missing, stale, or ambiguous entries before rendering the `unknown[]` runtime boundary.
-The invariants plugin consumes this generated runtime map instead of maintaining its own table. Additional event-owner packages are dev dependencies and project references of `dsh-invariants`, not peer dependencies, so the compile-time aggregation does not expand the plugin's runtime closure.
+The `dsh-scope/invariant` companion consumes this map instead of maintaining a handwritten table. Because Program analysis happens in the repository gate rather than through generated type imports, neither `dsh-scope` nor `dsh-invariants` acquires dependencies on every event owner.
### Semantic gaps fail explicitly
@@ -48,7 +48,7 @@ The generators reject missing declarations, config diagnostics, widened or gener
## Verification
-`verify-doc-graphs` freshness-checks semantic producer/listener discovery, and `verify-scoped-events` freshness-checks the generated resolver map. The root TypeScript build compiles the resolver against merged `Events`; workspace constraints and runtime-closure checks ensure its type-only aggregation does not become a deployment dependency.
+`verify-doc-graphs` freshness-checks semantic producer/listener discovery, and `verify-scoped-events` reruns the Program analysis while freshness-checking the generated resolver map. The root TypeScript build compiles its runtime adapter; workspace constraints and runtime-closure checks keep event-owner aggregation out of deployment dependencies.
## Alternatives considered
@@ -58,6 +58,6 @@ The generators reject missing declarations, config diagnostics, widened or gener
- Event relation generation follows semantic receiver identity and closed event values instead of local naming conventions.
- Scoped-event membership, subject extraction, and runtime invariant coverage come from event declarations and real dispatch contracts rather than handwritten tables.
-- Refactors that change event names, parameter positions, subject properties, or routing-key types fail generation or compilation at the owning contract.
+- Refactors that change event names, parameter positions, subject properties, or routing-key types fail generation at the owning contract.
- Building a flattened Program costs more startup time and memory than parsing isolated files, and semantic gates depend on a valid root project graph.
- Generated TypeScript remains committed source: changes to event owners or dispatch shapes must regenerate it and the affected documentation.
diff --git a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
index ce1f1edc76..1ab027d723 100644
--- a/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
+++ b/.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md
@@ -38,9 +38,9 @@ Context 与 AgentEventDispatch 调用只贡献有限的字符串字面量事件
恰好一个匹配项会生成解析函数。存在多个匹配项时，含义不明确，生成器会失败。没有匹配项时，事件必须标记 `@dshScopeScan unsupported`；该标记只用于路由键有意留在事件参数之外的情况，例如按所属 agent（智能体）路由的会话事件和按父 agent 路由的 subagent 生命周期事件。此标记只表示扫描不受支持，不编码事件名、参数下标、属性路径或替代类型。
-仓库提交的 [`scoped-events.generated.ts`](../../../../packages/support/invariants/src/scoped-events.generated.ts) 会导入每个带作用域的事件声明方，使它们从类型侧合并进 `Events`。每个生成函数都接收 `Parameters`，完整对象则满足基于 `ScopedEventName` 联合类型派生出的 `Record`。因此，常规 TypeScript 编译会检查事件是否存在、参数位置、属性访问和带作用域的事件集合完整性。唯一的类型断言只负责将 Cordis 运行时的 `unknown[]` dispatch 边界适配到已经通过类型检查的解析函数。
+仓库提交的 [`scoped-events.generated.ts`](../../../../packages/core/scope/src/scoped-events.generated.ts) 是位于 scoped dispatch 所属包中的纯运行时映射，不导入任何事件声明方包。语义完整性由生成器自身保证：根 Program 枚举所有 scoped `Events` 声明与真实 `scopeTarget` 契约，通过 checker 解析唯一的 payload 路径，并在渲染 `unknown[]` 运行时边界前拒绝缺失、陈旧或含义不明确的条目。
-不变式插件消费这份生成的运行时表，不再维护自己的事件表。新增的事件声明方包只作为 `dsh-invariants` 的开发依赖和项目引用存在，不进入对等依赖，因此编译期聚合不会扩大插件的运行时依赖闭包。
+`dsh-scope/invariant` companion 消费这份映射，不再维护手写事件表。Program 分析发生在仓库门禁内，而不是依赖生成的类型导入，因此 `dsh-scope` 和 `dsh-invariants` 都不需要依赖所有事件声明方。
### 语义缺口必须显式失败
@@ -48,7 +48,7 @@ Context 与 AgentEventDispatch 调用只贡献有限的字符串字面量事件
## 验证
-`verify-doc-graphs` 对语义生产方/监听方扫描执行新鲜度检查，`verify-scoped-events` 对生成的解析函数表执行新鲜度检查。根 TypeScript 构建会将解析函数与合并后的 `Events` 一起编译；workspace 约束和运行时依赖闭包检查则确保仅参与类型聚合的依赖不会变成部署依赖。
+`verify-doc-graphs` 对语义生产方/监听方扫描执行新鲜度检查；`verify-scoped-events` 会重新运行 Program 分析，并检查生成映射的新鲜度。根 TypeScript 构建编译其运行时适配器；workspace 约束与运行时依赖闭包检查确保事件声明方聚合不会进入部署依赖。
## 考虑过的替代方案
@@ -58,6 +58,6 @@ Context 与 AgentEventDispatch 调用只贡献有限的字符串字面量事件
- 事件关系生成依据语义接收者身份和封闭事件值，不再依赖局部命名约定；
- 带作用域的事件成员关系、主体提取和运行时不变式覆盖来自事件声明与真实 dispatch 契约，不再来自手写表；
-- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属契约处触发生成或编译失败；
+- 修改事件名、参数位置、主体属性或路由键类型时，会在其所属契约处触发生成失败；
- 构建扁平化 Program 比解析孤立文件消耗更多启动时间和内存，语义门禁也依赖有效的根项目图；
- 生成的 TypeScript 仍属于提交到仓库的源码：事件声明方或 dispatch 形态发生变化后，必须重新生成该文件和受影响的文档。
diff --git a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
index 91679a0a6c..500be241c6 100644
--- a/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
+++ b/.agents/notes/proposed/architecture/2026-06-16-typed-event-schemas.md
@@ -28,7 +28,7 @@ A migration of the event/vocabulary surface to runtime schemas touches, at minim
- **Six merge-extensible maps** (~370 LOC of core types): `ContentBlockMap`, `MessageSourceMap`, `FinishReasonMap` (in `dsh-llm`); `TurnTriggerMap`, `TurnEndReasonMap`, `SessionEventMap` (in `dsh-session`).
- **~10 `declare module` augmentation sites** across `dsh-agent`, `dsh-agent-loop`, `dsh-bash`, `dsh-llm`, `dsh-session`, `dsh-session-persistence`, `dsh-system-prompt`, `dsh-tools` — each would move from declaration merging to a runtime `register()` call.
- **The event producers** — 16 `session.append(...)` call sites in the loop — unchanged in shape but now validated at the boundary.
-- **~7 switch-consumers** that branch on these unions: `deriveMessages` (`dsh-session`), `BlockAssembler` (`dsh-llm`), the `dsh-invariants` plugin, both LLM adapters (`dsh-llm-deepseek`, `dsh-llm-pi-ai`), and the tool schema layer (`dsh-tools`). The `assertNever`-on-closed-unions vs fall-through-on-extensible-unions convention (a documented lint rule) would need rethinking — runtime variants are not statically exhaustive.
+- **~7 switch-consumers** that branch on these unions: `deriveMessages` and the package-owned invariant companion (`dsh-session`), `BlockAssembler` (`dsh-llm`), both LLM adapters (`dsh-llm-deepseek`, `dsh-llm-pi-ai`), and the tool schema layer (`dsh-tools`). The `assertNever`-on-closed-unions vs fall-through-on-extensible-unions convention (a documented lint rule) would need rethinking — runtime variants are not statically exhaustive.
- **The `defineTool` `InferArgs` DSL** (`dsh-tools`), which derives zero-cast `execute` arg types from a compile-time schema spec — the showcase of the current approach.
- **Docs**: architecture.md (the pattern is described as foundational), [dev-mode invariants](../../implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md), and any Agent Note that references the pattern.
@@ -37,7 +37,7 @@ This is a repository-wide vocabulary redesign, not a persistence implementation
## Alternatives considered
### A. Status quo — merge-extensible types + `isJsonValue` at the durable boundary
-Keep the compile-time pattern. Persistence stays opaque-JSON + serializability guard. Plugins extend via declaration merging; correctness of event *shape* is the producer's responsibility, enforced by TypeScript at compile time and by the `dsh-invariants` plugin's structural checks in dev.
+Keep the compile-time pattern. Persistence stays opaque-JSON + serializability guard. Plugins extend via declaration merging; correctness of event *shape* is the producer's responsibility and is enforced by TypeScript at compile time. Package-owned invariant companions check selected cross-record relationships when enabled but do not provide general runtime shape schemas.
- **Pros**: zero churn; plugin extension is a one-line `interface` augmentation with full type inference and no runtime registration ceremony; no new runtime dependency; the `defineTool` DSL and `assertNever` exhaustiveness keep working.
- **Cons**: no runtime structural validation at the persistence boundary or at plugin seams; a malformed-but-JSON datum is caught late.
@@ -72,4 +72,4 @@ Defer. If runtime validation is wanted at the durable boundary, **Option B** (sc
- If a registry is adopted, is the library **schemastery** (already in the tree, already the config schema lib) or **Zod** (richer ecosystem, currently only transitive)? Adopting two schema libraries is a cost in itself.
- Can a hybrid keep compile-time inference (so `defineTool` and plugin DX survive) while adding an *optional* runtime schema per variant, validated only at the persistence/wire boundary rather than on every in-process append?
-- Does the `dsh-invariants` plugin already cover enough of the runtime-shape gap in dev that boundary validation is only needed for genuinely untrusted input (reload of an externally-modified log)?
+- Does the `ctx.invariants` service already cover enough of the runtime-shape gap when enabled that boundary validation is only needed for genuinely untrusted input (reload of an externally-modified log)?
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 814132d481..925dc5b6ac 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -23,7 +23,8 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
2. **Docs match the code.** Config, defaults, errors, wire fields, events, and public behavior update the package README and JSDoc in the same diff. Comments state non-obvious contracts; flag implementation narration, test walkthroughs, review history, and duplicated rationale for deletion or a link to their one home.
3. **Core type docs match.** Changes to spine or seam vocabulary update the appropriate [core-data-structures](../../../docs/core-data-structures/core.md) page and any `type-equiv` entry. Internal types need no catalog entry.
4. **Registrations clean up.** Verify each new registry contribution satisfies the disposal-test contract in [packages/AGENTS.md](../../../packages/AGENTS.md).
-5. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
+5. **Invariant companions are semantic.** For every touched `./invariant`, require an owner event-stream or mutable-data relationship at its authoritative boundary; service or method presence, plugin metadata or effects, and fixed pure examples belong in type, load, or unit tests. Accept an empty installer when its package-specific reason establishes that no plausible runtime relationship exists; do not demand an invented check merely to eliminate emptiness ([repository rule](../../../AGENTS.md#conventions); [package contract](../../../packages/AGENTS.md)).
+6. **Required gates pass.** Trust the [current readiness sequence](../../../AGENTS.md#run-the-ci-gates-locally-before-marking-a-pr-ready) and `pnpm run check:pre-push` for their enforced inventory; review the semantic gaps they cannot detect.
## Manual checks
@@ -38,7 +39,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
- **Bounds cover the final operation:** locate the owner of the complete emitted or retained result, including wrappers and metadata. Probe tiny and exact limits, oversized single chunks, and multibyte text for byte limits.
- **Real entry path:** tests exercise the shipped Loader, bin, worker, ACP bridge, or subprocess where relevant. A hand-mounted plugin does not catch Loader export-shape failures; a function plugin must named-export its namespace and have no default export.
- **Test strength:** assertions fail on the intended regression and verify external state, logs, events, or disposal rather than restating the implementation or trusting an agent's report. Coverage is necessary but not evidence that the scenario is correct.
-- **Mechanized invariants and negative controls:** trace each new or changed check through the executed top-level gate and its deliberately invalid case; confirm the real runner fails for the intended rule.
+- **Invariant lifecycle and negative controls:** verify candidate observations are rejected before publication where possible, session-backed checks reconstruct durable history after late loading or HMR, and a deliberately invalid case fails through the real runner for the intended rule.
- **Implemented Agent Notes match shipped reality:** when a PR implements a proposed Agent Note, move and rewrite it as present-tense shipped state in the same diff, then verify paths, names, and mechanisms against the implementation.
- **Transcript changes:** editor-visible or model-visible changes update snapshots or explain why no snapshot applies. Review expected-output diffs as behavior changes, not formatting noise.
- **Bilingual changes:** compare meaning and terminology on both sides; a green pairing hash does not prove translation quality.
diff --git a/.github/workflows/docs-pages.yml b/.github/workflows/docs-pages.yml
new file mode 100644
index 0000000000..e1ad20997d
--- /dev/null
+++ b/.github/workflows/docs-pages.yml
@@ -0,0 +1,83 @@
+name: Deploy documentation
+
+on:
+ push:
+ branches: [master]
+ paths:
+ - '.github/workflows/docs-pages.yml'
+ - 'docs/**'
+ - 'package.json'
+ - 'pnpm-lock.yaml'
+ - 'pnpm-workspace.yaml'
+ - 'scripts/project-doc-site.ts'
+ - 'scripts/project-doc-site.spec.ts'
+ - 'website/**'
+ workflow_dispatch:
+
+concurrency:
+ group: github-pages
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+
+env:
+ PRIMARY_NODE_VERSION: '24'
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pages: read
+ steps:
+ - uses: actions/checkout@v6
+
+ - uses: actions/setup-node@v6
+ with:
+ node-version: ${{ env.PRIMARY_NODE_VERSION }}
+
+ - name: Enable corepack (pnpm)
+ run: corepack enable
+
+ - name: Resolve pnpm store path
+ id: pnpm-store
+ run: echo "path=$(pnpm store path --silent)" >> "$GITHUB_OUTPUT"
+
+ - uses: actions/cache@v4
+ with:
+ path: ${{ steps.pnpm-store.outputs.path }}
+ key: ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}
+ restore-keys: |
+ ${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-
+
+ - name: Install (immutable)
+ run: pnpm install --frozen-lockfile
+
+ - name: Configure Pages
+ id: pages
+ uses: actions/configure-pages@v5
+
+ - name: Verify and build documentation
+ env:
+ DOCS_BASE: ${{ steps.pages.outputs.base_path }}/
+ run: pnpm run doc-sync
+
+ - name: Upload Pages artifact
+ uses: actions/upload-pages-artifact@v4
+ with:
+ path: website/.dist
+
+ deploy:
+ needs: build
+ runs-on: ubuntu-latest
+ permissions:
+ pages: write
+ id-token: write
+ environment:
+ name: github-pages
+ url: ${{ steps.deployment.outputs.page_url }}
+ steps:
+ - name: Deploy to GitHub Pages
+ id: deployment
+ uses: actions/deploy-pages@v4
diff --git a/AGENTS.md b/AGENTS.md
index 5835149048..e2fc77211a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -99,6 +99,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
- 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; 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.
+- **Runtime invariants assert owned relationships.** Check authoritative event streams or mutable data, not service or method presence, plugin metadata or effects, or fixed pure examples. If a package has no plausible relationship, an explained empty companion is correct ([package contract](packages/AGENTS.md)).
- **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.
- **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
diff --git a/docs/architecture.md b/docs/architecture.md
index 5106fcc706..384ebc5dcd 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -4,9 +4,9 @@ The **DeepSeek Harness SDK** builds on Cordis: **everything is a plugin**, inclu
## Overview
-Harnesses are [Cordis](cordis-primer.md) contexts. Packages contribute services (`ctx.llm`, `ctx.tools`, `ctx.sessions`), typed events (`agent/request`, `tools/pre-execute`, `session/event`), and disposable prompts, tools, providers, adapters, and listeners.
+Harnesses are [Cordis](cordis-primer.md) contexts whose packages contribute disposable services, events, and registrations.
-`packages/core/` groups the default agent flow; surrounding capabilities are equally first-class Cordis plugins.
+`packages/core/` groups the default agent flow.
### Default Services
@@ -40,6 +40,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts. Packages contribute services
| `ctx.goals` | [`goal/`](../packages/goal/README.md) | persisted same-session goals |
| `ctx.sessionPersistence` | [`session-persistence/`](../packages/session-persistence/README.md) | durable storage for session logs |
| `ctx.sessionQuery` | [`session-query/`](../packages/session-query/README.md) | live-preferred logical-corpus exact reads and relationship traces |
+| `ctx.invariants` | [`support/invariants`](../packages/support/invariants/README.md) | registry and package-name selection for package-owned runtime checks |
## Event
@@ -112,7 +113,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](../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)).
-Canonical tool JSON stays execution-local; post-policy replaces value or presentation, or blocks; the loop persists projections ([contract](../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md)). Tool-time context—including async `agent.inject()` notices and post-tool `additionalContexts`—settles after results. Steering drains; before signal closure, `agent/post-step` observes durable output, results, context, and steering. Leftovers queue. Terminal `agent/turn-stop` runs after continuation and steering folding, remains authoritative through close/flush, and discards later steering while preserving queued prompts.
+Canonical JSON stays execution-local; post-policy replaces value or presentation, or blocks; the loop persists projections ([contract](../.agents/notes/implemented/architecture/2026-07-20-canonical-tool-output-contract.md)). Tool-time context—including async `agent.inject()` notices and post-tool `additionalContexts`—settles after results. Steering drains; before signal closure, `agent/post-step` observes durable output, results, context, and steering. Leftovers queue. Terminal `agent/turn-stop` runs after continuation and steering folding, remains authoritative through close/flush, and discards later steering while preserving queued prompts.
Pruning precedes summaries; overflow retries require durable progress. Bounded transient retries compose on `agent/request-error`; cancellation wins ([compaction](../.agents/notes/implemented/architecture/2026-07-10-after-call-compaction-pressure-and-overflow-recovery.md), [retry](../.agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.md)).
@@ -138,7 +139,7 @@ Every live agent owns a scoped `agent.ctx`. Its registrations shadow globals, re
The session log is the source of truth. `deriveMessages()` projects session events into the `Message[]` sent to the model; raw `assistant/chunk` events stay in the log for replay and UI fidelity. Replay, fork, resume, transcript rendering, telemetry, and persistence all derive from the same event stream.
-**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` fronted by the header's session prefix, headers by folding `request/header` — and dev invariants assert this ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
+**Model-visible ⟺ logged**: the log reconstructs every request — messages at `step/start` fronted by the header's session prefix, and headers by folding `request/header` — and the package-owned `dsh-agent-loop/invariant` can assert it through `ctx.invariants` ([reconstructability](../.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md)).
Durability is a plugin concern. Backends buffer synchronous `session/event` notifications; the loop awaits a turn-end checkpoint. `SessionPersistence` stores `SessionEvent` directly and metadata in `SessionHeader`; JSONL defaults to checksummed Zstandard, with SQLite under one contract.
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 4b60089577..0cb39f9041 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -26,6 +26,8 @@ flowchart LR
pkg_session_query["session-query"]
pkg_subagent_inprocess["subagent-inprocess"]
pkg_invariants["invariants"]
+ svc_invariants["ctx.invariants
Package-owned invariant registry"]
+ pkg_scope["scope"]
svc_sessionPersistence["ctx.sessionPersistence
Durable session persistence seam"]
pkg_session_persistence_jsonl["session-persistence-jsonl"]
pkg_session_persistence_sqlite["session-persistence-sqlite"]
@@ -124,6 +126,7 @@ flowchart LR
pkg_fs_local --> svc_fs
pkg_fs_sandbox --> svc_fs
pkg_goal --> svc_goals
+ pkg_invariants --> svc_invariants
pkg_llm --> svc_llm
pkg_llm_deepseek --> svc_llm
pkg_llm_pi_ai --> svc_llm
@@ -163,7 +166,6 @@ flowchart LR
svc_agents --> pkg_acp
svc_agents --> pkg_agent_loop
svc_agents --> pkg_cli_demo
- svc_agents --> pkg_invariants
svc_agents --> pkg_subagent_inprocess
svc_agents --> pkg_tui_demo
svc_approval --> pkg_tool_bash
@@ -176,6 +178,10 @@ flowchart LR
svc_commands --> pkg_tui
svc_compact --> pkg_compact_basic
svc_fs --> pkg_tool_fs
+ svc_invariants --> pkg_agent
+ svc_invariants --> pkg_agent_loop
+ svc_invariants --> pkg_scope
+ svc_invariants --> pkg_session
svc_llm --> pkg_agent_loop
svc_llm --> pkg_compact_basic
svc_permission --> pkg_acp
@@ -191,7 +197,6 @@ flowchart LR
svc_sessions --> pkg_agent
svc_sessions --> pkg_agent_loop
svc_sessions --> pkg_cli_demo
- svc_sessions --> pkg_invariants
svc_sessions --> pkg_session_persistence
svc_sessions --> pkg_session_query
svc_sessions --> pkg_subagent_inprocess
@@ -232,7 +237,8 @@ flowchart LR
| `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.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`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.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
| `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. |
| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
@@ -240,7 +246,7 @@ flowchart LR
| `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
| `ctx.commands` | `core` | [`commands`](../packages/ui/commands) | - | [`tui`](../packages/ui/tui), [`acp`](../packages/ui/acp) | - | Plugins register direct human commands; TUI and ACP consume the same effective per-agent catalog without sending invocations to the model. |
| `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tui-demo`](../packages/examples/tui-demo) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
| `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
| `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
| `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index d517dc60ed..e079ee3fe2 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -122,8 +122,9 @@ Source: [`packages/core/agent-loop/src/index.ts:360`](../packages/core/agent-loo
* skill registry/local provider/tool consumer, `workspaceContext` to the
* workspace-context loader, `llmRetry` to the bounded request-recovery policy,
* and `toolBash`/`toolTasks` to the model-facing tool plugins this bundle owns.
- * `goals` opts into and configures the persisted goal
- * domain plus its model tool and same-session driver. Owner schemas supply defaults for optional input;
+ * `goals` opts into and configures the persisted goal domain plus its model tool
+ * and same-session driver; `invariants` configures global and package-filtered
+ * relational checks. Owner schemas supply defaults for optional input;
* workspace context instead requires an explicit byte budget or `false` because
* it changes model-visible input. Producer opt-in stays producer-local:
* `toolBash` configures bash only; independently composed producers keep their
@@ -150,6 +151,8 @@ export interface Config {
toolBash?: toolBash.Config
/** Generic background-task controls; set false to keep the task service without model-facing task tools. */
toolTasks?: toolTasks.Config | false
+ /** Global enablement and package-name filters for invariant companions. */
+ invariants?: InvariantConfig
/** Opt-in persisted same-session goal stack; set false or omit to leave it unmounted. */
goals?: GoalConfig | false
/** Bounded transient model-request retry policy. */
@@ -177,9 +180,9 @@ export interface GoalConfig {
}
```
-Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`llmRetry`](../packages/llm/llm-retry/src/index.ts) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts) · [`workspaceContext`](../packages/context/workspace-context/src/index.ts)
+Depends on: [`AgentLoopConfig`](#deepseek-aidsh-agent-loop) · [`GoalDomainConfig`](#deepseek-aidsh-goal) · [`InvariantConfig`](#deepseek-aidsh-invariants) · [`llmRetry`](../packages/llm/llm-retry/src/index.ts) · [`SkillLocal`](../packages/skill/skill-local/src/index.ts) · [`SkillRegistryConfig`](#deepseek-aidsh-skill) · [`SystemPromptConfig`](#deepseek-aidsh-system-prompt) · [`toolBash`](../packages/bash/tool-bash/src/index.ts) · [`toolGoal`](../packages/goal/tool-goal/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools) · [`toolSkill`](../packages/skill/tool-skill/src/index.ts) · [`toolTasks`](../packages/tasks/tool-tasks/src/index.ts) · [`workspaceContext`](../packages/context/workspace-context/src/index.ts)
-Source: [`packages/examples/agent-spine-demo/src/index.ts:73`](../packages/examples/agent-spine-demo/src/index.ts)
+Source: [`packages/examples/agent-spine-demo/src/index.ts:78`](../packages/examples/agent-spine-demo/src/index.ts)
## `@deepseek-ai/dsh-bash-local`
@@ -298,15 +301,25 @@ Source: [`packages/code-runtime/code-runtime-worker/src/index.ts:21`](../package
Requires: `llm` · `tokenMeter`
```ts config-catalog
-/** Basic compaction configuration; every common field has a deployment default. */
-export interface BasicCompactConfig {
- /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */
+/** Basic compaction configuration with an optional exact-target policy table. */
+export interface BasicCompactConfig extends CompactPolicyConfig {
+ /** Exact provider/model overrides; duplicate targets fail plugin load. */
+ modelPolicies?: ModelCompactPolicyConfig[]
+ /** Enable automatic post-step pressure and overflow-recovery listeners. Defaults to `true`. */
+ auto?: boolean
+}
+
+/** Policy fields shared by the default policy and exact model overrides. */
+export interface CompactPolicyConfig {
+ /** Compact at this fraction of the model's context window. Defaults to `0.8`. */
thresholdRatio?: number
- /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
+ /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */
+ retainRatio?: number
+ /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */
retainTokens?: number
- /** Summary provider; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+ /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */
summarizationProvider?: string
- /** Summary model; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+ /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */
summarizationModel?: string
/** Provider generation cap for summarization. Defaults to `8192`. */
maxTokens?: number
@@ -314,12 +327,18 @@ export interface BasicCompactConfig {
compactionRetries?: number
/** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
maxOverflowRetries?: number
- /** Enable automatic post-step pressure and overflow-recovery listeners. Defaults to `true`. */
- auto?: boolean
+}
+
+/** Exact provider/model override merged over the default compaction policy. */
+export interface ModelCompactPolicyConfig extends CompactPolicyConfig {
+ /** Registered provider route to match. */
+ provider: string
+ /** Exact routed model id to match within `provider`. */
+ model: string
}
```
-Source: [`packages/compact/compact-basic/src/types.ts:8`](../packages/compact/compact-basic/src/types.ts)
+Source: [`packages/compact/compact-basic/src/types.ts:38`](../packages/compact/compact-basic/src/types.ts)
## `@deepseek-ai/dsh-compact-tool-result-prune`
@@ -442,6 +461,22 @@ export interface Config {
Source: [`packages/hooks/hooks-codex/src/index.ts:42`](../packages/hooks/hooks-codex/src/index.ts)
+## `@deepseek-ai/dsh-invariants`
+
+```ts config-catalog
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+ /** Global switch; defaults to `true`. */
+ readonly enabled?: boolean
+ /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+ readonly package_allowlist?: string[]
+ /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+ readonly package_blocklist?: string[]
+}
+```
+
+Source: [`packages/support/invariants/src/index.ts:15`](../packages/support/invariants/src/index.ts)
+
## `@deepseek-ai/dsh-jsonrpc`
Requires: `agents`
@@ -498,6 +533,8 @@ export interface DeepSeekCatalogModel {
name?: string
/** Optional selector detail for deployments with similar model variants. */
description?: string
+ /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+ contextWindow?: number
}
```
@@ -584,10 +621,12 @@ export interface ReplayModelConfig {
name?: string
/** Optional selector description. */
description?: string
+ /** Optional positive integer context capacity published by the replay adapter. */
+ contextWindow?: number
}
```
-Source: [`packages/support/llm-replay/src/index.ts:375`](../packages/support/llm-replay/src/index.ts)
+Source: [`packages/support/llm-replay/src/index.ts:385`](../packages/support/llm-replay/src/index.ts)
## `@deepseek-ai/dsh-llm-retry`
@@ -1077,11 +1116,8 @@ Source: [`packages/context/time-context/src/index.ts:19`](../packages/context/ti
## `@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
-}
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record
```
Source: [`packages/llm/token-meter/src/types.ts:10`](../packages/llm/token-meter/src/types.ts)
@@ -1647,7 +1683,6 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
- `@deepseek-ai/dsh-commands` ([`packages/ui/commands/src/index.ts`](../packages/ui/commands/src/index.ts))
- `@deepseek-ai/dsh-fs-policy` ([`packages/fs/fs-policy/src/index.ts`](../packages/fs/fs-policy/src/index.ts))
- `@deepseek-ai/dsh-goal-session` — requires `agents` · `goals` · `sessions` ([`packages/goal/goal-session/src/index.ts`](../packages/goal/goal-session/src/index.ts))
-- `@deepseek-ai/dsh-invariants` — requires `sessions` ([`packages/support/invariants/src/index.ts`](../packages/support/invariants/src/index.ts))
- `@deepseek-ai/dsh-llm` ([`packages/llm/llm/src/index.ts`](../packages/llm/llm/src/index.ts))
- `@deepseek-ai/dsh-lsp` ([`packages/lsp/lsp/src/index.ts`](../packages/lsp/lsp/src/index.ts))
- `@deepseek-ai/dsh-session` ([`packages/core/session/src/index.ts`](../packages/core/session/src/index.ts))
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 1cc60675cb..8dd783ebe4 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -536,7 +536,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
-Source: [`packages/llm/llm/src/index.ts:44`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:52`](../../packages/llm/llm/src/index.ts)
## `session/*`
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index df163a95e7..ba881f641e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -613,6 +613,24 @@ Types: [Agent](../core-data-structures/core.md) · [CreateGoalRequest](../core-d
Source: [`packages/goal/goal/src/index.ts:135`](../../packages/goal/goal/src/index.ts)
+## `ctx.invariants` — `InvariantService`
+
+Package-owned invariant registry with global and regex-based selection.
+
+```ts cordis-catalog
+/**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+register(packageName: string, installer: InvariantInstaller): () => void
+```
+
+Source: [`packages/support/invariants/src/index.ts:94`](../../packages/support/invariants/src/index.ts)
+
## `ctx.llm` — `LlmService`
The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
@@ -642,6 +660,16 @@ listProviders(): LlmProviderInfo[]
*/
async listModels(provider: string): Promise
+/**
+ * Resolve context capacity from the adapter that owns one exact route.
+ * This query is independent of the advisory model catalog: an unlisted model
+ * may return metadata, while `undefined` never rejects later routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @returns detached context metadata, or `undefined` when the adapter has none.
+ */
+async resolveModelContext( provider: string, model: string, ): Promise
+
/**
* Stream one model call as raw chunks (token-level deltas). Throws
* `LlmError` with code `NO_ADAPTER` if no adapter is registered for
@@ -657,9 +685,9 @@ async listModels(provider: string): Promise
stream(options: GenerateOptions): AsyncIterable
```
-Types: [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmModelContext](../core-data-structures/core.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
-Source: [`packages/llm/llm/src/index.ts:137`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:159`](../../packages/llm/llm/src/index.ts)
## `ctx.permission` — `PermissionService`
@@ -1246,7 +1274,7 @@ estimateMessage(message: Message): number
Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md)
-Source: [`packages/llm/token-meter/src/index.ts:106`](../../packages/llm/token-meter/src/index.ts)
+Source: [`packages/llm/token-meter/src/index.ts:82`](../../packages/llm/token-meter/src/index.ts)
## `ctx.toolResultPrune` — `ToolResultPruneService`
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 214306126b..5428ac2023 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -193,6 +193,16 @@ interface LlmModelInfo {
}
```
+Correctness-sensitive model capacity is queried separately from the advisory catalog and is owned by the adapter serving the exact route.
+
+```ts type-equiv
+/** Provider-owned context capacity for one exact provider/model route. */
+interface LlmModelContext {
+ /** Maximum combined request and response context in tokens. */
+ contextWindow: number
+}
+```
+
```ts type-equiv
/** A single model request, fully assembled. */
interface GenerateOptions {
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md
index 674bff9dc8..257ce90cda 100644
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -154,7 +154,7 @@ declare class BlockAssembler {
## The seam
-`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerInfo()` and asynchronous `listModels()` methods feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
+`LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerInfo()` and asynchronous `listModels()` methods feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. The separate `resolveModelContext()` query exposes correctness-sensitive capacity for an exact route without making catalog membership authoritative; absence means unknown metadata, not invalid routing. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
```ts public-api
/**
@@ -178,6 +178,17 @@ declare abstract class LlmAdapter {
* @returns discoverable models in adapter-preferred order.
*/
listModels(_provider: string): Promise;
+ /**
+ * Resolve context capacity for one model accepted by this adapter. Absence
+ * means the adapter does not know the capacity, not that routing is invalid.
+ * @param _provider - one provider route owned by this adapter.
+ * @param _model - exact model id passed to {@link GenerateOptions.model}.
+ * @returns provider-owned context metadata, or `undefined` when unavailable.
+ */
+ resolveModelContext(
+ _provider: string,
+ _model: string,
+ ): Promise;
/**
* Stream one model call as raw chunks. The only required method.
* @param options - the fully-assembled request; implementations must honor `options.signal`.
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index b8f2d64136..c926e2ff44 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -511,7 +511,7 @@ interface TurnEndReasonMap {
## The turn-enclosure invariant
-Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, and an idle `agent.inject()` wraps its `context/message` in a one-shot `injection` turn. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The `dsh-invariants` plugin enforces it in dev (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).
+Every session event lives **inside** a turn (between a `turn/start` and its `turn/end`). The loop appends queued `user/message` events *after* `turn/start`, and an idle `agent.inject()` wraps its `context/message` in a one-shot `injection` turn. This makes the turn the single durability/replay boundary: a backend can treat anything after the last `turn/end` as an interrupted-crash tail without risking the loss of legitimately-recorded between-turn context. The optional `dsh-session/invariant` companion enforces it in dev through `ctx.invariants` (a message event outside an open turn throws). See [the turn-enclosure invariant Agent Note](../../.agents/notes/implemented/architecture/2026-06-15-turn-enclosure-invariant.md).
## Plugin-contributed log-only events
@@ -521,6 +521,6 @@ The hook bridges' `hook/invoked` / `hook/result` provenance pairs (from `@deepse
## Durability contract
-What a persistence backend relies on: the durable log persists every event verbatim, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.events` always equals what a backend can persist. Adding an event type that carries non-serializable data, or that breaks the turn/step nesting the invariants plugin checks, is a breaking change to the on-disk format.
+What a persistence backend relies on: the durable log persists every event verbatim, **including** `assistant/chunk` — `seq` must stay contiguous, so chunks cannot be filtered out of the canonical log. All `event.data` must be JSON-serializable; `Session.append` enforces this at the source (throwing on non-serializable data), so a bad event never enters the log and `session.events` always equals what a backend can persist. Adding an event type that carries non-serializable data, or that breaks the turn/step nesting checked by the session invariant companion, is a breaking change to the on-disk format.
The backends that consume this contract are on [persistence.md](persistence.md).
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 42f0f9280f..c9698a394a 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -20,7 +20,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:295`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
| `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:257`](../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:204`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`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`) | [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`tui`](../packages/ui/tui) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:171`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
| `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:268`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
| `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:305`](../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:315`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`tool-goal`](../packages/goal/tool-goal) |
@@ -30,34 +30,34 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
| `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
| `goal/changed` | `emit` | [`packages/goal/goal/src/types.ts:167`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:44`](../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:47`](../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) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:52`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`agent-loop`](../packages/core/agent-loop), [`llm`](../packages/llm/llm), [`llm-replay`](../packages/support/llm-replay) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`user-approval`](../packages/ui/user-approval) |
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:79`](../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:139`](../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:113`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:119`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:130`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
-| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:27`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:139`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:113`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:119`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:130`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:27`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:33`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:136`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:109`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`timeout-policy`](../packages/timeout/timeout-policy) |
| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:118`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search), [`workspace-context`](../packages/context/workspace-context) |
| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:100`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:126`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`workspace-context`](../packages/context/workspace-context) |
-| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
-| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
-| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:81`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/agent-start` | `emit` | [`packages/workflow/workflow/src/index.ts:70`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
+| `workflow/end` | `emit` | [`packages/workflow/workflow/src/index.ts:91`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
| `workflow/log` | `emit` | [`packages/workflow/workflow/src/index.ts:60`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
| `workflow/phase` | `emit` | [`packages/workflow/workflow/src/index.ts:53`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
-| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | - |
+| `workflow/start` | `emit` | [`packages/workflow/workflow/src/index.ts:45`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`workflow`](../packages/workflow/workflow) |
## Non-harness or undeclared event strings seen in package source
| Event string | Dispatchers | Listeners |
| --- | --- | --- |
-| `internal/dispatch` | - | [`invariants`](../packages/support/invariants) |
+| `internal/dispatch` | - | [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
| `internal/status` | - | [`agent`](../packages/core/agent) |
Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 88f04c747b..7126e7c252 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -167,116 +167,173 @@ flowchart TD
pkg_workflow["workflow"]
pkg_workflow_workerthread["workflow-workerthread"]
end
+ pkg_brand --> pkg_invariants
+ pkg_home --> pkg_invariants
+ pkg_paths --> pkg_invariants
+ pkg_retention --> pkg_invariants
+ pkg_timeout --> pkg_invariants
+ pkg_scope --> pkg_invariants
+ pkg_skill --> pkg_invariants
+ pkg_subagent_subprocess --> pkg_invariants
+ pkg_acp_snapshot --> pkg_invariants
+ pkg_loader_smoke --> pkg_invariants
+ pkg_app_boot --> pkg_invariants
+ pkg_code_runtime --> pkg_invariants
+ pkg_jsonrpc_demo --> pkg_invariants
pkg_llm --> pkg_brand
+ pkg_llm --> pkg_invariants
pkg_helper --> pkg_brand
+ pkg_helper --> pkg_invariants
pkg_scripts --> pkg_app_boot
+ pkg_scripts --> pkg_invariants
pkg_telemetry --> pkg_brand
+ pkg_telemetry --> pkg_invariants
+ pkg_llm_deepseek --> pkg_invariants
pkg_llm_deepseek --> pkg_llm
pkg_llm_deepseek --> pkg_timeout
+ pkg_llm_pi_ai --> pkg_invariants
pkg_llm_pi_ai --> pkg_llm
pkg_llm_pi_ai --> pkg_timeout
pkg_session --> pkg_brand
+ pkg_session --> pkg_invariants
pkg_session --> pkg_llm
pkg_session --> pkg_scope
+ pkg_system_prompt --> pkg_invariants
pkg_system_prompt --> pkg_llm
pkg_system_prompt --> pkg_scope
+ pkg_web --> pkg_invariants
pkg_web --> pkg_llm
pkg_lsp --> pkg_brand
+ pkg_lsp --> pkg_invariants
pkg_lsp --> pkg_llm
+ pkg_sandbox --> pkg_invariants
pkg_sandbox --> pkg_llm
+ pkg_token_meter --> pkg_invariants
pkg_token_meter --> pkg_llm
pkg_token_meter --> pkg_session
pkg_agent --> pkg_brand
+ pkg_agent --> pkg_invariants
pkg_agent --> pkg_llm
pkg_agent --> pkg_scope
pkg_agent --> pkg_session
pkg_agent --> pkg_system_prompt
+ pkg_bash --> pkg_invariants
pkg_bash --> pkg_sandbox
pkg_fs --> pkg_brand
+ pkg_fs --> pkg_invariants
pkg_fs --> pkg_llm
pkg_fs --> pkg_sandbox
+ pkg_compact --> pkg_invariants
pkg_compact --> pkg_llm
pkg_compact --> pkg_session
+ pkg_compact_tool_result_prune --> pkg_invariants
pkg_compact_tool_result_prune --> pkg_llm
pkg_compact_tool_result_prune --> pkg_session
+ pkg_web_fetch_local --> pkg_invariants
pkg_web_fetch_local --> pkg_timeout
pkg_web_fetch_local --> pkg_web
+ pkg_web_search_deepseek --> pkg_invariants
pkg_web_search_deepseek --> pkg_web
+ pkg_web_search_exa --> pkg_invariants
pkg_web_search_exa --> pkg_web
+ pkg_web_search_perplexity --> pkg_invariants
pkg_web_search_perplexity --> pkg_web
pkg_spill --> pkg_brand
+ pkg_spill --> pkg_invariants
pkg_spill --> pkg_llm
pkg_spill --> pkg_session
+ pkg_session_persistence --> pkg_invariants
pkg_session_persistence --> pkg_session
+ pkg_llm_replay --> pkg_invariants
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
pkg_code_runtime_worker --> pkg_code_runtime
+ pkg_code_runtime_worker --> pkg_invariants
pkg_code_runtime_worker --> pkg_session
pkg_lsp_local --> pkg_brand
+ pkg_lsp_local --> pkg_invariants
pkg_lsp_local --> pkg_llm
pkg_lsp_local --> pkg_lsp
pkg_lsp_local --> pkg_timeout
+ pkg_sandbox_local --> pkg_invariants
pkg_sandbox_local --> pkg_llm
pkg_sandbox_local --> pkg_sandbox
+ pkg_sandbox_policy --> pkg_invariants
pkg_sandbox_policy --> pkg_sandbox
pkg_sandbox_policy --> pkg_session
pkg_llm_retry --> pkg_agent
+ pkg_llm_retry --> pkg_invariants
pkg_llm_retry --> pkg_llm
pkg_llm_retry --> pkg_session
pkg_llm_retry --> pkg_timeout
pkg_goal --> pkg_agent
pkg_goal --> pkg_brand
+ pkg_goal --> pkg_invariants
pkg_goal --> pkg_llm
pkg_goal --> pkg_scope
pkg_goal --> pkg_session
pkg_bash_local --> pkg_bash
+ pkg_bash_local --> pkg_invariants
pkg_bash_local --> pkg_timeout
pkg_fs_local --> pkg_fs
+ pkg_fs_local --> pkg_invariants
pkg_fs_policy --> pkg_fs
+ pkg_fs_policy --> pkg_invariants
pkg_skill_local --> pkg_fs
pkg_skill_local --> pkg_home
+ pkg_skill_local --> pkg_invariants
pkg_skill_local --> pkg_skill
pkg_compact_basic --> pkg_agent
pkg_compact_basic --> pkg_compact
pkg_compact_basic --> pkg_compact_tool_result_prune
+ pkg_compact_basic --> pkg_invariants
pkg_compact_basic --> pkg_llm
pkg_compact_basic --> pkg_session
pkg_compact_basic --> pkg_token_meter
+ pkg_spill_local --> pkg_invariants
pkg_spill_local --> pkg_spill
pkg_hook_protocol --> pkg_bash
+ pkg_hook_protocol --> pkg_invariants
pkg_hook_protocol --> pkg_session
+ pkg_session_persistence_jsonl --> pkg_invariants
pkg_session_persistence_jsonl --> pkg_session
pkg_session_persistence_jsonl --> pkg_session_persistence
+ pkg_session_persistence_sqlite --> pkg_invariants
pkg_session_persistence_sqlite --> pkg_session
pkg_session_persistence_sqlite --> pkg_session_persistence
+ pkg_session_query --> pkg_invariants
pkg_session_query --> pkg_llm
pkg_session_query --> pkg_session
pkg_session_query --> pkg_session_persistence
- pkg_invariants --> pkg_agent
- pkg_invariants --> pkg_llm
- pkg_invariants --> pkg_scope
- pkg_invariants --> pkg_session
pkg_commands --> pkg_agent
+ pkg_commands --> pkg_invariants
pkg_commands --> pkg_scope
pkg_user_approval --> pkg_agent
pkg_user_approval --> pkg_brand
+ pkg_user_approval --> pkg_invariants
pkg_user_approval --> pkg_llm
pkg_user_approval --> pkg_scope
pkg_user_approval --> pkg_session
pkg_user_approval --> pkg_system_prompt
pkg_user_interaction --> pkg_agent
+ pkg_user_interaction --> pkg_invariants
pkg_user_interaction --> pkg_llm
pkg_time_context --> pkg_agent
+ pkg_time_context --> pkg_invariants
+ pkg_time_context --> pkg_session
pkg_tasks --> pkg_agent
pkg_tasks --> pkg_brand
+ pkg_tasks --> pkg_invariants
pkg_tasks --> pkg_session
pkg_tasks --> pkg_timeout
pkg_workflow --> pkg_agent
pkg_workflow --> pkg_brand
+ pkg_workflow --> pkg_invariants
pkg_workflow --> pkg_llm
pkg_workflow --> pkg_session
pkg_tools --> pkg_agent
pkg_tools --> pkg_code_runtime
+ pkg_tools --> pkg_invariants
pkg_tools --> pkg_llm
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
@@ -284,24 +341,30 @@ flowchart TD
pkg_tools --> pkg_user_approval
pkg_command_goal --> pkg_commands
pkg_command_goal --> pkg_goal
+ pkg_command_goal --> pkg_invariants
pkg_goal_session --> pkg_agent
pkg_goal_session --> pkg_goal
+ pkg_goal_session --> pkg_invariants
pkg_goal_session --> pkg_llm
pkg_goal_session --> pkg_session
pkg_bash_sandbox --> pkg_bash
pkg_bash_sandbox --> pkg_bash_local
+ pkg_bash_sandbox --> pkg_invariants
pkg_bash_sandbox --> pkg_sandbox
pkg_bash_sandbox --> pkg_sandbox_policy
pkg_fs_sandbox --> pkg_fs
pkg_fs_sandbox --> pkg_fs_local
+ pkg_fs_sandbox --> pkg_invariants
pkg_fs_sandbox --> pkg_sandbox
pkg_fs_sandbox --> pkg_sandbox_policy
pkg_permission --> pkg_bash
+ pkg_permission --> pkg_invariants
pkg_permission --> pkg_sandbox
pkg_permission --> pkg_sandbox_policy
pkg_permission --> pkg_session
pkg_permission --> pkg_user_approval
pkg_agent_loop --> pkg_agent
+ pkg_agent_loop --> pkg_invariants
pkg_agent_loop --> pkg_llm
pkg_agent_loop --> pkg_scope
pkg_agent_loop --> pkg_session
@@ -310,6 +373,7 @@ flowchart TD
pkg_agent_loop --> pkg_tools
pkg_tool_goal --> pkg_agent
pkg_tool_goal --> pkg_goal
+ pkg_tool_goal --> pkg_invariants
pkg_tool_goal --> pkg_llm
pkg_tool_goal --> pkg_session
pkg_tool_goal --> pkg_system_prompt
@@ -317,6 +381,7 @@ flowchart TD
pkg_tool_bash --> pkg_agent
pkg_tool_bash --> pkg_bash
pkg_tool_bash --> pkg_home
+ pkg_tool_bash --> pkg_invariants
pkg_tool_bash --> pkg_llm
pkg_tool_bash --> pkg_sandbox
pkg_tool_bash --> pkg_sandbox_policy
@@ -326,6 +391,7 @@ flowchart TD
pkg_tool_bash --> pkg_tools
pkg_tool_bash --> pkg_user_approval
pkg_tool_fs --> pkg_fs
+ pkg_tool_fs --> pkg_invariants
pkg_tool_fs --> pkg_llm
pkg_tool_fs --> pkg_sandbox
pkg_tool_fs --> pkg_sandbox_policy
@@ -334,6 +400,7 @@ flowchart TD
pkg_tool_fs --> pkg_tools
pkg_tool_fs --> pkg_user_approval
pkg_tool_fs_search --> pkg_bash
+ pkg_tool_fs_search --> pkg_invariants
pkg_tool_fs_search --> pkg_llm
pkg_tool_fs_search --> pkg_retention
pkg_tool_fs_search --> pkg_session
@@ -341,39 +408,48 @@ flowchart TD
pkg_tool_fs_search --> pkg_system_prompt
pkg_tool_fs_search --> pkg_tools
pkg_tool_skill --> pkg_agent
+ pkg_tool_skill --> pkg_invariants
pkg_tool_skill --> pkg_llm
pkg_tool_skill --> pkg_skill
pkg_tool_skill --> pkg_tools
pkg_subagent --> pkg_agent
pkg_subagent --> pkg_brand
+ pkg_subagent --> pkg_invariants
pkg_subagent --> pkg_llm
pkg_subagent --> pkg_scope
pkg_subagent --> pkg_session
pkg_subagent --> pkg_tools
+ pkg_tool_web --> pkg_invariants
pkg_tool_web --> pkg_llm
pkg_tool_web --> pkg_system_prompt
pkg_tool_web --> pkg_tools
pkg_tool_web --> pkg_web
+ pkg_spill_policy --> pkg_invariants
pkg_spill_policy --> pkg_llm
pkg_spill_policy --> pkg_retention
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_tools
+ pkg_timeout_policy --> pkg_invariants
pkg_timeout_policy --> pkg_llm
pkg_timeout_policy --> pkg_timeout
pkg_timeout_policy --> pkg_tools
pkg_tool_todo --> pkg_agent
+ pkg_tool_todo --> pkg_invariants
pkg_tool_todo --> pkg_session
pkg_tool_todo --> pkg_tools
+ pkg_tool_cordis --> pkg_invariants
pkg_tool_cordis --> pkg_scope
pkg_tool_cordis --> pkg_tools
pkg_hooks_codex --> pkg_agent
pkg_hooks_codex --> pkg_hook_protocol
+ pkg_hooks_codex --> pkg_invariants
pkg_hooks_codex --> pkg_llm
pkg_hooks_codex --> pkg_session
pkg_hooks_codex --> pkg_session_persistence
pkg_hooks_codex --> pkg_tools
pkg_agent_loop_testkit --> pkg_agent
+ pkg_agent_loop_testkit --> pkg_invariants
pkg_agent_loop_testkit --> pkg_llm
pkg_agent_loop_testkit --> pkg_session
pkg_agent_loop_testkit --> pkg_system_prompt
@@ -381,6 +457,7 @@ flowchart TD
pkg_acp --> pkg_agent
pkg_acp --> pkg_bash
pkg_acp --> pkg_commands
+ pkg_acp --> pkg_invariants
pkg_acp --> pkg_llm
pkg_acp --> pkg_llm_retry
pkg_acp --> pkg_permission
@@ -392,56 +469,68 @@ flowchart TD
pkg_acp --> pkg_user_approval
pkg_acp --> pkg_user_interaction
pkg_tool_ask_user --> pkg_agent
+ pkg_tool_ask_user --> pkg_invariants
pkg_tool_ask_user --> pkg_tools
pkg_tool_ask_user --> pkg_user_interaction
pkg_workspace_context --> pkg_agent
pkg_workspace_context --> pkg_fs
+ pkg_workspace_context --> pkg_invariants
pkg_workspace_context --> pkg_llm
pkg_workspace_context --> pkg_paths
pkg_workspace_context --> pkg_session
pkg_workspace_context --> pkg_tools
pkg_repeat_tool_guard --> pkg_agent
+ pkg_repeat_tool_guard --> pkg_invariants
pkg_repeat_tool_guard --> pkg_tools
+ pkg_tool_lsp --> pkg_invariants
pkg_tool_lsp --> pkg_llm
pkg_tool_lsp --> pkg_lsp
pkg_tool_lsp --> pkg_system_prompt
pkg_tool_lsp --> pkg_timeout
pkg_tool_lsp --> pkg_tools
+ pkg_mcp_client --> pkg_invariants
pkg_mcp_client --> pkg_llm
pkg_mcp_client --> pkg_tools
pkg_tool_tasks --> pkg_agent
+ pkg_tool_tasks --> pkg_invariants
pkg_tool_tasks --> pkg_system_prompt
pkg_tool_tasks --> pkg_tasks
pkg_tool_tasks --> pkg_tools
pkg_tool_workflow --> pkg_agent
+ pkg_tool_workflow --> pkg_invariants
pkg_tool_workflow --> pkg_llm
pkg_tool_workflow --> pkg_system_prompt
pkg_tool_workflow --> pkg_tools
pkg_tool_workflow --> pkg_workflow
pkg_subagent_acp --> pkg_agent
+ pkg_subagent_acp --> pkg_invariants
pkg_subagent_acp --> pkg_llm
pkg_subagent_acp --> pkg_session
pkg_subagent_acp --> pkg_subagent
pkg_subagent_acp --> pkg_subagent_subprocess
pkg_subagent_inprocess --> pkg_agent
+ pkg_subagent_inprocess --> pkg_invariants
pkg_subagent_inprocess --> pkg_llm
pkg_subagent_inprocess --> pkg_session
pkg_subagent_inprocess --> pkg_subagent
pkg_subagent_inprocess --> pkg_system_prompt
pkg_subagent_inprocess --> pkg_tools
pkg_tool_subagent --> pkg_agent
+ pkg_tool_subagent --> pkg_invariants
pkg_tool_subagent --> pkg_llm
pkg_tool_subagent --> pkg_subagent
pkg_tool_subagent --> pkg_tasks
pkg_tool_subagent --> pkg_tools
pkg_hooks_claude --> pkg_agent
pkg_hooks_claude --> pkg_hook_protocol
+ pkg_hooks_claude --> pkg_invariants
pkg_hooks_claude --> pkg_llm
pkg_hooks_claude --> pkg_session
pkg_hooks_claude --> pkg_session_persistence
pkg_hooks_claude --> pkg_subagent
pkg_hooks_claude --> pkg_tools
pkg_jsonrpc --> pkg_agent
+ pkg_jsonrpc --> pkg_invariants
pkg_jsonrpc --> pkg_llm
pkg_jsonrpc --> pkg_llm_deepseek
pkg_jsonrpc --> pkg_scope
@@ -450,6 +539,7 @@ flowchart TD
pkg_tui --> pkg_agent
pkg_tui --> pkg_agent_loop
pkg_tui --> pkg_commands
+ pkg_tui --> pkg_invariants
pkg_tui --> pkg_llm
pkg_tui --> pkg_llm_retry
pkg_tui --> pkg_session
@@ -465,6 +555,7 @@ flowchart TD
pkg_agent_spine_demo --> pkg_invariants
pkg_agent_spine_demo --> pkg_llm
pkg_agent_spine_demo --> pkg_llm_retry
+ pkg_agent_spine_demo --> pkg_scope
pkg_agent_spine_demo --> pkg_session
pkg_agent_spine_demo --> pkg_skill
pkg_agent_spine_demo --> pkg_skill_local
@@ -477,6 +568,7 @@ flowchart TD
pkg_agent_spine_demo --> pkg_tools
pkg_agent_spine_demo --> pkg_workspace_context
pkg_tool_ralph --> pkg_agent
+ pkg_tool_ralph --> pkg_invariants
pkg_tool_ralph --> pkg_llm
pkg_tool_ralph --> pkg_subagent
pkg_tool_ralph --> pkg_system_prompt
@@ -484,15 +576,18 @@ flowchart TD
pkg_tool_ralph --> pkg_workflow
pkg_workflow_workerthread --> pkg_agent
pkg_workflow_workerthread --> pkg_brand
+ pkg_workflow_workerthread --> pkg_invariants
pkg_workflow_workerthread --> pkg_llm
pkg_workflow_workerthread --> pkg_session
pkg_workflow_workerthread --> pkg_subagent
pkg_workflow_workerthread --> pkg_tools
pkg_workflow_workerthread --> pkg_workflow
pkg_subagent_fork --> pkg_agent
+ pkg_subagent_fork --> pkg_invariants
pkg_subagent_fork --> pkg_session
pkg_subagent_fork --> pkg_subagent
pkg_subagent_fork --> pkg_subagent_inprocess
+ pkg_subagent_spawn --> pkg_invariants
pkg_subagent_spawn --> pkg_subagent
pkg_subagent_spawn --> pkg_subagent_inprocess
pkg_acp_demo --> pkg_acp
@@ -500,6 +595,7 @@ flowchart TD
pkg_acp_demo --> pkg_app_boot
pkg_acp_demo --> pkg_command_goal
pkg_acp_demo --> pkg_commands
+ pkg_acp_demo --> pkg_invariants
pkg_acp_demo --> pkg_session_persistence_jsonl
pkg_acp_demo --> pkg_tools
pkg_acp_demo --> pkg_user_interaction
@@ -507,6 +603,7 @@ flowchart TD
pkg_cli_demo --> pkg_agent
pkg_cli_demo --> pkg_agent_spine_demo
pkg_cli_demo --> pkg_app_boot
+ pkg_cli_demo --> pkg_invariants
pkg_cli_demo --> pkg_llm
pkg_cli_demo --> pkg_session
pkg_cli_demo --> pkg_session_persistence_jsonl
@@ -518,6 +615,7 @@ flowchart TD
pkg_tui_demo --> pkg_app_boot
pkg_tui_demo --> pkg_command_goal
pkg_tui_demo --> pkg_commands
+ pkg_tui_demo --> pkg_invariants
pkg_tui_demo --> pkg_llm
pkg_tui_demo --> pkg_session
pkg_tui_demo --> pkg_session_persistence_jsonl
@@ -530,105 +628,105 @@ flowchart TD
| Package | Group | Depends on |
| --- | --- | --- |
-| [`brand`](../packages/util/brand) | `util` | — |
-| [`home`](../packages/util/home) | `util` | — |
-| [`paths`](../packages/util/paths) | `util` | — |
-| [`retention`](../packages/util/retention) | `util` | — |
-| [`timeout`](../packages/util/timeout) | `util` | — |
-| [`scope`](../packages/core/scope) | `core` | — |
-| [`skill`](../packages/skill/skill) | `skill` | — |
-| [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | — |
-| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | — |
-| [`loader-smoke`](../packages/support/loader-smoke) | `support` | — |
-| [`app-boot`](../packages/ui/app-boot) | `ui` | — |
-| [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | — |
-| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | — |
-| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand) |
-| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand) |
-| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot) |
-| [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand) |
-| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
-| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
-| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
-| [`system-prompt`](../packages/core/system-prompt) | `core` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
-| [`web`](../packages/web/web) | `web` | [`llm`](../packages/llm/llm) |
-| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`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) |
-| [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
-| [`compact`](../packages/compact/compact) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
-| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`web`](../packages/web/web) |
-| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`web`](../packages/web/web) |
-| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`web`](../packages/web/web) |
-| [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`session`](../packages/core/session) |
-| [`llm-replay`](../packages/support/llm-replay) | `support` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`session`](../packages/core/session) |
-| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`timeout`](../packages/util/timeout) |
-| [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
-| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
-| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
-| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`timeout`](../packages/util/timeout) |
-| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs) |
-| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs) |
-| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`home`](../packages/util/home), [`skill`](../packages/skill/skill) |
-| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`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) |
-| [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`session-query`](../packages/session-query/session-query) | `session-query` | [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| [`invariants`](../packages/support/invariants) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
-| [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`scope`](../packages/core/scope) |
-| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
-| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm) |
-| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent) |
-| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
-| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
-| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal) |
-| [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
-| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
-| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`home`](../packages/util/home), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
-| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`bash`](../packages/bash/bash), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
-| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
-| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
-| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
-| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
-| [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
-| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
-| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) |
-| [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
-| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
-| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
-| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
-| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
-| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
-| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
-| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
-| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
-| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
-| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
-| [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
-| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`invariants`](../packages/support/invariants) | `support` | — |
+| [`brand`](../packages/util/brand) | `util` | [`invariants`](../packages/support/invariants) |
+| [`home`](../packages/util/home) | `util` | [`invariants`](../packages/support/invariants) |
+| [`paths`](../packages/util/paths) | `util` | [`invariants`](../packages/support/invariants) |
+| [`retention`](../packages/util/retention) | `util` | [`invariants`](../packages/support/invariants) |
+| [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
+| [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
+| [`skill`](../packages/skill/skill) | `skill` | [`invariants`](../packages/support/invariants) |
+| [`subagent-subprocess`](../packages/subagent/subagent-subprocess) | `subagent` | [`invariants`](../packages/support/invariants) |
+| [`acp-snapshot`](../packages/support/acp-snapshot) | `support` | [`invariants`](../packages/support/invariants) |
+| [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`invariants`](../packages/support/invariants) |
+| [`app-boot`](../packages/ui/app-boot) | `ui` | [`invariants`](../packages/support/invariants) |
+| [`code-runtime`](../packages/code-runtime/code-runtime) | `code-runtime` | [`invariants`](../packages/support/invariants) |
+| [`jsonrpc-demo`](../packages/examples/jsonrpc-demo) | `examples` | [`invariants`](../packages/support/invariants) |
+| [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`helper`](../packages/sdk/helper) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`scripts`](../packages/sdk/scripts) | `sdk` | [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants) |
+| [`telemetry`](../packages/sdk/telemetry) | `sdk` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants) |
+| [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
+| [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
+| [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`system-prompt`](../packages/core/system-prompt) | `core` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |
+| [`web`](../packages/web/web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`lsp`](../packages/lsp/lsp) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`sandbox`](../packages/sandbox/sandbox) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`token-meter`](../packages/llm/token-meter) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`agent`](../packages/core/agent) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`bash`](../packages/bash/bash) | `bash` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox) |
+| [`fs`](../packages/fs/fs) | `fs` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`compact`](../packages/compact/compact) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | `compact` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`web-fetch-local`](../packages/web/web-fetch-local) | `web` | [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout), [`web`](../packages/web/web) |
+| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-exa`](../packages/web/web-search-exa) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`web-search-perplexity`](../packages/web/web-search-perplexity) | `web` | [`invariants`](../packages/support/invariants), [`web`](../packages/web/web) |
+| [`spill`](../packages/spill/spill) | `spill` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`session-persistence`](../packages/session-persistence/session-persistence) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`llm-replay`](../packages/support/llm-replay) | `support` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | `code-runtime` | [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`lsp-local`](../packages/lsp/lsp-local) | `lsp` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`timeout`](../packages/util/timeout) |
+| [`sandbox-local`](../packages/sandbox/sandbox-local) | `sandbox` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox) |
+| [`sandbox-policy`](../packages/sandbox/sandbox-policy) | `sandbox` | [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session) |
+| [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session) |
+| [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
+| [`fs-local`](../packages/fs/fs-local) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`fs-policy`](../packages/fs/fs-policy) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants) |
+| [`skill-local`](../packages/skill/skill-local) | `skill` | [`fs`](../packages/fs/fs), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`skill`](../packages/skill/skill) |
+| [`compact-basic`](../packages/compact/compact-basic) | `compact` | [`agent`](../packages/core/agent), [`compact`](../packages/compact/compact), [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`token-meter`](../packages/llm/token-meter) |
+| [`spill-local`](../packages/spill/spill-local) | `spill` | [`invariants`](../packages/support/invariants), [`spill`](../packages/spill/spill) |
+| [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | `session-persistence` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`session-query`](../packages/session-query/session-query) | `session-query` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| [`commands`](../packages/ui/commands) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope) |
+| [`user-approval`](../packages/ui/user-approval) | `ui` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt) |
+| [`user-interaction`](../packages/ui/user-interaction) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm) |
+| [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
+| [`tasks`](../packages/tasks/tasks) | `tasks` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
+| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`code-runtime`](../packages/code-runtime/code-runtime), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/ui/user-approval) |
+| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/ui/commands), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants) |
+| [`goal-session`](../packages/goal/goal-session) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`bash-sandbox`](../packages/bash/bash-sandbox) | `bash` | [`bash`](../packages/bash/bash), [`bash-local`](../packages/bash/bash-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
+| [`permission`](../packages/ui/permission) | `ui` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`user-approval`](../packages/ui/user-approval) |
+| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-bash`](../packages/bash/tool-bash) | `bash` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval) |
+| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-skill`](../packages/skill/tool-skill) | `skill` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`skill`](../packages/skill/skill), [`tools`](../packages/core/tools) |
+| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`tool-web`](../packages/web/tool-web) | `web` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) |
+| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`retention`](../packages/util/retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`tools`](../packages/core/tools) |
+| [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`invariants`](../packages/support/invariants), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) |
+| [`agent-loop-testkit`](../packages/support/agent-loop-testkit) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`sandbox`](../packages/sandbox/sandbox), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`user-interaction`](../packages/ui/user-interaction) |
+| [`tool-ask-user`](../packages/ui/tool-ask-user) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`workspace-context`](../packages/context/workspace-context) | `context` | [`agent`](../packages/core/agent), [`fs`](../packages/fs/fs), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`paths`](../packages/util/paths), [`session`](../packages/core/session), [`tools`](../packages/core/tools) |
+| [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`tools`](../packages/core/tools) |
+| [`tool-lsp`](../packages/lsp/tool-lsp) | `lsp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`lsp`](../packages/lsp/lsp), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) |
+| [`mcp-client`](../packages/mcp/mcp-client) | `mcp` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
+| [`tool-tasks`](../packages/tasks/tool-tasks) | `tasks` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`subagent-acp`](../packages/subagent/subagent-acp) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-subprocess`](../packages/subagent/subagent-subprocess) |
+| [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
+| [`tool-subagent`](../packages/subagent/tool-subagent) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`tasks`](../packages/tasks/tasks), [`tools`](../packages/core/tools) |
+| [`hooks-claude`](../packages/hooks/hooks-claude) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools) |
+| [`jsonrpc`](../packages/ui/jsonrpc) | `ui` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent) |
+| [`tui`](../packages/ui/tui) | `ui` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction) |
+| [`agent-spine-demo`](../packages/examples/agent-spine-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`home`](../packages/util/home), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`skill`](../packages/skill/skill), [`skill-local`](../packages/skill/skill-local), [`system-prompt`](../packages/core/system-prompt), [`tasks`](../packages/tasks/tasks), [`tool-bash`](../packages/bash/tool-bash), [`tool-goal`](../packages/goal/tool-goal), [`tool-skill`](../packages/skill/tool-skill), [`tool-tasks`](../packages/tasks/tool-tasks), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`tool-ralph`](../packages/workflow/tool-ralph) | `workflow` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`subagent`](../packages/subagent/subagent), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`workflow-workerthread`](../packages/workflow/workflow-workerthread) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
+| [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`invariants`](../packages/support/invariants), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
+| [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
+| [`tui-demo`](../packages/examples/tui-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`command-goal`](../packages/goal/command-goal), [`commands`](../packages/ui/commands), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
diff --git a/examples/acp-agent/cordis.yml b/examples/acp-agent/cordis.yml
index c70b41f9c7..b0a6c7b8e1 100644
--- a/examples/acp-agent/cordis.yml
+++ b/examples/acp-agent/cordis.yml
@@ -9,6 +9,11 @@
config:
apiKey: !!js process.env.DEEPSEEK_API_KEY
baseURL: !!js process.env.DEEPSEEK_BASE_URL
+ models:
+ - id: deepseek-v4-flash
+ contextWindow: 256000
+ - id: deepseek-v4-pro
+ contextWindow: 256000
# The default composition confines bash AND the filesystem tools to the
# workspace and asks before a wider retry. Snapshot runs select
@@ -58,20 +63,17 @@
Verify your work by running the code or tests. Keep answers brief and factual.
-# Replay-aware request pressure with one service-wide context window.
+# Replay-aware request pressure; the routed adapter supplies model capacity.
- id: token-meter
name: '@deepseek-ai/dsh-token-meter'
- config:
- # FIXME: Resolve compaction config per model; this capacity assumes a 256k context window.
- contextWindow: 256000
# Summarize an older range after measured pressure or a canonical provider overflow.
-# Service-wide policy provides pressure, retention, and one overflow-retry default.
+# Ratios scale against the routed model's context window.
- id: compact-basic
name: '@deepseek-ai/dsh-compact-basic'
config:
thresholdRatio: 0.8
- retainTokens: 20480
+ retainRatio: 0.08
maxTokens: 8192
compactionRetries: 1
diff --git a/examples/headless-agent/composition.md b/examples/headless-agent/composition.md
index 3e5876c2b6..e467d32833 100644
--- a/examples/headless-agent/composition.md
+++ b/examples/headless-agent/composition.md
@@ -21,6 +21,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_headless_token_meter["token-meter
@deepseek-ai/dsh-token-meter"]
+ cfg --> plugin_headless_token_meter
plugin_headless_compact_basic["compact-basic
@deepseek-ai/dsh-compact-basic"]
cfg --> plugin_headless_compact_basic
plugin_headless_subagent["subagent
@deepseek-ai/dsh-subagent"]
@@ -54,6 +56,7 @@ flowchart LR
| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
| `bash` | `@deepseek-ai/dsh-bash-local` |
| `cli-agent` | `@deepseek-ai/dsh-cli-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/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml
index aa2d9fd7ca..05c4facea9 100644
--- a/examples/headless-agent/cordis.yml
+++ b/examples/headless-agent/cordis.yml
@@ -11,7 +11,9 @@
baseURL: !!js process.env.DEEPSEEK_BASE_URL
models:
- id: deepseek-v4-pro
+ contextWindow: 128000
- id: deepseek-v4-flash
+ contextWindow: 128000
- id: bash
name: '@deepseek-ai/dsh-bash-local'
@@ -35,13 +37,14 @@
factual.
# Summarize an older range when derived history approaches the context window.
+- id: token-meter
+ name: '@deepseek-ai/dsh-token-meter'
+
- id: compact-basic
name: '@deepseek-ai/dsh-compact-basic'
config:
- contextWindow: 128000
thresholdRatio: 0.8
- retainTokens: 20480
- summarizationModel: ''
+ retainRatio: 0.16
maxTokens: 8192
compactionRetries: 1
diff --git a/examples/headless-agent/tests/compaction.e2e.ts b/examples/headless-agent/tests/compaction.e2e.ts
index d992fc9efa..fcebddb863 100644
--- a/examples/headless-agent/tests/compaction.e2e.ts
+++ b/examples/headless-agent/tests/compaction.e2e.ts
@@ -33,9 +33,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('compaction: a long session compa
// Reasoning tokens require a larger generation cap than the retained checkpoint.
ctx = await codingHarness(workdir, {
persona: SYSTEM_PROMPT,
- tokenMeter: {
- contextWindow: 2000,
- },
+ modelContextWindow: 2000,
compact: {
thresholdRatio: 0.5,
retainTokens: 400,
diff --git a/examples/headless-agent/tests/harness.ts b/examples/headless-agent/tests/harness.ts
index ca1c59871e..6cfa31a750 100644
--- a/examples/headless-agent/tests/harness.ts
+++ b/examples/headless-agent/tests/harness.ts
@@ -8,7 +8,6 @@ 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 ToolResultPruneService from '@deepseek-ai/dsh-compact-tool-result-prune'
import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
@@ -46,8 +45,8 @@ export interface CodingHarnessOptions {
* compaction plugin (the default suites run without it).
*/
compact?: BasicCompactConfig
- /** Optional token-meter capacity loaded before compact-basic. */
- tokenMeter?: TokenMeterConfig
+ /** Test-only context capacity advertised for `deepseek-v4-flash`. */
+ modelContextWindow?: number
}
export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise {
@@ -56,14 +55,15 @@ export async function codingHarness(workdir: string, options: CodingHarnessOptio
systemPrompt: { persona: options.persona ?? '' },
})
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(LlmDeepSeek)
+ await ctx.plugin(LlmDeepSeek, options.modelContextWindow === undefined ? {} : {
+ models: [{ id: 'deepseek-v4-flash', contextWindow: options.modelContextWindow }],
+ })
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 the reusable meter and
- // backend, with a lower context window so a short real session crosses the threshold.
+ // Compaction is opt-in: only the compaction e2e loads the reusable meter and backend.
if (options.compact !== undefined) {
- await ctx.plugin(TokenMeterService, options.tokenMeter)
+ await ctx.plugin(TokenMeterService)
await ctx.plugin(ToolResultPruneService)
await ctx.plugin(BasicCompactService, options.compact)
}
diff --git a/examples/jsonrpc-agent/cordis.yml b/examples/jsonrpc-agent/cordis.yml
index 00ef48f4ed..5c8029db6b 100644
--- a/examples/jsonrpc-agent/cordis.yml
+++ b/examples/jsonrpc-agent/cordis.yml
@@ -63,12 +63,13 @@
- id: tool-fs
name: '@deepseek-ai/dsh-tool-fs'
+- id: token-meter
+ name: '@deepseek-ai/dsh-token-meter'
+
- id: compact-basic
name: '@deepseek-ai/dsh-compact-basic'
config:
- contextWindow: 128000
thresholdRatio: 0.8
- retainTokens: 20480
- summarizationModel: ''
+ retainRatio: 0.16
maxTokens: 8192
compactionRetries: 1
diff --git a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
index 020394ebe3..2806e205a4 100644
--- a/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
+++ b/examples/tui-agent/tests/fixtures/tui-scripted-llm.ts
@@ -1,5 +1,5 @@
import type { Context } from 'cordis'
-import type { GenerateOptions, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelContext, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
const CONTROL_PROBE = '\u001b]2;MODEL_CONTROLLED\u0007\u001b[999CMODEL_CURSOR\u009b31mMODEL_C1'
@@ -25,6 +25,10 @@ class ScriptedTuiAdapter extends LlmAdapter {
])
}
+ override resolveModelContext(_provider: string, _model: string): Promise {
+ return Promise.resolve({ contextWindow: 128_000 })
+ }
+
override async * stream(options: GenerateOptions): AsyncIterable {
if (options.model !== 'tui-scripted-model-pro' || !options.system?.includes('tui-scripted-model-pro')) {
throw new Error('the scripted TUI request did not apply the selected model to routing and prompt variables')
diff --git a/examples/tui-agent/tests/tui.snapshot.ts b/examples/tui-agent/tests/tui.snapshot.ts
index cc8e9847cb..1ac3f5b55e 100644
--- a/examples/tui-agent/tests/tui.snapshot.ts
+++ b/examples/tui-agent/tests/tui.snapshot.ts
@@ -33,7 +33,7 @@ import { HeadlessTerminal } from '../../../packages/ui/tui/tests/headless-termin
const SNAPSHOTS_DIR = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
// Keep pre-normalization layout widths identical across macOS and Linux.
const SNAPSHOT_TMP_ROOT = process.platform === 'win32' ? tmpdir() : '/tmp'
-const PROVIDERS = [{ id: 'deepseek', models: [{ id: 'deepseek-v4-flash' }] }]
+const PROVIDERS = [{ id: 'deepseek', models: [{ id: 'deepseek-v4-flash', contextWindow: 128_000 }] }]
const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
type SnapshotMode = 'replay' | 'record' | 'refresh'
diff --git a/knip.json b/knip.json
index 1704ccf210..b95a4243f4 100644
--- a/knip.json
+++ b/knip.json
@@ -55,23 +55,19 @@
"project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/util/brand": {
- "project": ["src/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts"]
},
"packages/util/home": {
"entry": ["tests/**/*.spec.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/util/timeout": {
"entry": ["tests/**/*.spec.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/util/retention": {
"entry": ["tests/**/*.spec.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/support/acp-snapshot": {
"entry": ["tests/**/*.spec.ts", "tests/fixtures/fake-acp-agent.ts"],
@@ -79,8 +75,7 @@
},
"packages/support/loader-smoke": {
"entry": ["tests/**/*.spec.ts", "tests/fixtures/*.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/core/agent-loop": {
"entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
@@ -116,8 +111,7 @@
},
"packages/util/paths": {
"entry": ["tests/**/*.spec.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/web/web-search-exa": {
"entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
@@ -181,8 +175,7 @@
},
"packages/subagent/subagent-subprocess": {
"entry": ["tests/**/*.spec.ts"],
- "project": ["src/**/*.ts", "tests/**/*.ts"],
- "ignoreDependencies": ["cordis"]
+ "project": ["src/**/*.ts", "tests/**/*.ts"]
},
"packages/fs/tool-fs": {
"entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
diff --git a/package.json b/package.json
index 5c831f6497..5f1441c115 100644
--- a/package.json
+++ b/package.json
@@ -40,6 +40,8 @@
"verify-md-links": "tsx scripts/verify-md-links.ts",
"verify-doc-refs": "tsx scripts/verify-doc-refs.ts",
"verify-package-paths": "tsx scripts/verify-package-paths.ts",
+ "verify-package-invariants": "tsx scripts/verify-package-invariants.ts",
+ "verify-built-package-invariants": "node scripts/verify-built-package-invariants.mjs",
"verify-package-readme-model-experience": "tsx scripts/verify-package-readme-model-experience.ts",
"verify-mermaid": "tsx scripts/verify-mermaid.ts",
"verify-agent-note-classification": "tsx scripts/verify-agent-note-classification.ts",
@@ -77,7 +79,7 @@
"verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
"constraints": "tsx scripts/check-workspace-constraints.ts",
"doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-agent-note-classification && pnpm run verify-agent-note-format && pnpm run verify-type-equiv && pnpm run verify-translation-prompt && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations && pnpm run docs:check",
- "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
+ "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
"demo:headless": "node --expose-internals --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
"demo:tui": "node --expose-internals --import tsx packages/examples/tui-demo/src/bin.ts examples/tui-agent/cordis.yml",
"demo:code-mode": "node scripts/demo-code-mode.mjs",
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 400436a9f1..77a4712e04 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -15,7 +15,8 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
- **Enforce at the operation boundary that owns the decision.** Schema omission, prompt filtering, facades, wrappers, and listener order are not enforcement when direct or alternate callers can bypass them; test denial through the executor.
- **Publish state only at its commit point.** Emit each notification and update derived state only after the success boundary that makes it true; derive caches, prompts, UI echoes, replay, and query views from one authoritative source.
- **Apply bounds to the complete result.** Enforce byte, token, item, and time limits where the complete emitted or retained value, including wrappers and metadata, is known; test tiny and exact limits, oversized single chunks, and multibyte byte limits.
-- **Registry contributions prove disposal.** Add the HMR-safety test required by the [testing policy](../docs/testing.md): dispose the contributing fiber and observe removal.
+- **Registry contributions prove disposal** through the HMR-safety test required by [testing policy](../docs/testing.md): dispose the fiber and observe removal.
+- **Every package owns `./invariant`.** Register the manifest name; check an event/data relation or give empty installers package-specific `No runtime invariant:` reasons. Generated companions, unexplained empties, and ignored reporters fail [`verify-package-invariants`](../.agents/notes/implemented/architecture/2026-07-19-package-invariant-runtime-contracts.md).
Naming notes:
diff --git a/packages/bash/bash-local/package.json b/packages/bash/bash-local/package.json
index 381855b465..152c2db28b 100644
--- a/packages/bash/bash-local/package.json
+++ b/packages/bash/bash-local/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-bash": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
@@ -31,6 +37,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-bash": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/bash/bash-local/src/invariant.ts b/packages/bash/bash-local/src/invariant.ts
new file mode 100644
index 0000000000..3cc7bd62e2
--- /dev/null
+++ b/packages/bash/bash-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-bash-local`.
+ * @module @deepseek-ai/dsh-bash-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-bash-local'
+
+/** Cordis companion plugin name. */
+export const name = 'bash-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/bash/bash-local/tsconfig.json b/packages/bash/bash-local/tsconfig.json
index 02448770f4..a55c76f00a 100644
--- a/packages/bash/bash-local/tsconfig.json
+++ b/packages/bash/bash-local/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../bash/bash"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/bash/bash-sandbox/package.json b/packages/bash/bash-sandbox/package.json
index d4ac641f8d..9faf613c71 100644
--- a/packages/bash/bash-sandbox/package.json
+++ b/packages/bash/bash-sandbox/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-bash": "^0.0.1",
"@deepseek-ai/dsh-bash-local": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -31,10 +37,11 @@
"devDependencies": {
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"@deepseek-ai/dsh-sandbox-local": "workspace:^",
"@deepseek-ai/dsh-sandbox-policy": "workspace:^",
- "node-addon-landlock-run": "0.0.0-test.0",
- "cordis": "^4.0.0-rc.7"
+ "cordis": "^4.0.0-rc.7",
+ "node-addon-landlock-run": "0.0.0-test.0"
}
}
diff --git a/packages/bash/bash-sandbox/src/invariant.ts b/packages/bash/bash-sandbox/src/invariant.ts
new file mode 100644
index 0000000000..b79b626033
--- /dev/null
+++ b/packages/bash/bash-sandbox/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-bash-sandbox`.
+ * @module @deepseek-ai/dsh-bash-sandbox/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-bash-sandbox'
+
+/** Cordis companion plugin name. */
+export const name = 'bash-sandbox-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/bash/bash-sandbox/tsconfig.json b/packages/bash/bash-sandbox/tsconfig.json
index 531ae140ea..fcd79e0296 100644
--- a/packages/bash/bash-sandbox/tsconfig.json
+++ b/packages/bash/bash-sandbox/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../bash/bash-local"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/bash/bash/package.json b/packages/bash/bash/package.json
index 5fab273e39..93497df719 100644
--- a/packages/bash/bash/package.json
+++ b/packages/bash/bash/package.json
@@ -11,21 +11,28 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/bash/bash/src/invariant.ts b/packages/bash/bash/src/invariant.ts
new file mode 100644
index 0000000000..f54f280f5d
--- /dev/null
+++ b/packages/bash/bash/src/invariant.ts
@@ -0,0 +1,22 @@
+/** Package-owned invariant companion for the bash seam. @module @deepseek-ai/dsh-bash/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-bash'
+
+/** Cordis companion plugin name. */
+export const name = 'bash-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** No runtime invariant: this stateless seam owns request/result types, while executors and policy own observations. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register the bash invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/bash/bash/tsconfig.json b/packages/bash/bash/tsconfig.json
index de6feb55b9..51175e6080 100644
--- a/packages/bash/bash/tsconfig.json
+++ b/packages/bash/bash/tsconfig.json
@@ -16,6 +16,9 @@
},
{
"path": "../../sandbox/sandbox"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/bash/tool-bash/package.json b/packages/bash/tool-bash/package.json
index 1ce1103e48..5ef96794af 100644
--- a/packages/bash/tool-bash/package.json
+++ b/packages/bash/tool-bash/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -25,9 +30,10 @@
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-bash": "^0.0.1",
"@deepseek-ai/dsh-home": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
- "@deepseek-ai/dsh-session-persistence": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
+ "@deepseek-ai/dsh-session-persistence": "^0.0.1",
"@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
"@deepseek-ai/dsh-tasks": "^0.0.1",
@@ -42,10 +48,10 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
- "@deepseek-ai/dsh-user-approval": "workspace:^",
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
"@deepseek-ai/dsh-home": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"@deepseek-ai/dsh-sandbox-policy": "workspace:^",
diff --git a/packages/bash/tool-bash/src/invariant.ts b/packages/bash/tool-bash/src/invariant.ts
new file mode 100644
index 0000000000..0620f0cfa9
--- /dev/null
+++ b/packages/bash/tool-bash/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-bash`.
+ * @module @deepseek-ai/dsh-tool-bash/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-bash'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-bash-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the environment registry validates ownership and collected values at each
+ * mutation/read; it publishes no independent snapshot that a companion could cross-check.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/bash/tool-bash/tsconfig.json b/packages/bash/tool-bash/tsconfig.json
index c17b10ab8d..a3145c2f52 100644
--- a/packages/bash/tool-bash/tsconfig.json
+++ b/packages/bash/tool-bash/tsconfig.json
@@ -47,6 +47,9 @@
{
"path": "../../sandbox/sandbox"
},
+ {
+ "path": "../../support/invariants"
+ },
{
"path": "../../sandbox/sandbox-policy"
}
diff --git a/packages/code-runtime/code-runtime-worker/package.json b/packages/code-runtime/code-runtime-worker/package.json
index c65eae4508..e173842fc1 100644
--- a/packages/code-runtime/code-runtime-worker/package.json
+++ b/packages/code-runtime/code-runtime-worker/package.json
@@ -11,6 +11,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./worker": {
"types": "./lib/types/worker.d.ts",
"default": "./lib/worker.cjs"
@@ -19,6 +23,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/worker.cjs",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -27,6 +32,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-code-runtime": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
@@ -35,6 +41,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-code-runtime": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/code-runtime/code-runtime-worker/src/invariant.ts b/packages/code-runtime/code-runtime-worker/src/invariant.ts
new file mode 100644
index 0000000000..3455104441
--- /dev/null
+++ b/packages/code-runtime/code-runtime-worker/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime-worker`.
+ * @module @deepseek-ai/dsh-code-runtime-worker/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime-worker'
+
+/** Cordis companion plugin name. */
+export const name = 'code-runtime-worker-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this process-boundary implementation exposes no same-process event relation;
+ * worker protocol and built-worker tests cover it.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/code-runtime/code-runtime-worker/tsconfig.json b/packages/code-runtime/code-runtime-worker/tsconfig.json
index dc7bb2ac45..b739c7c3bc 100644
--- a/packages/code-runtime/code-runtime-worker/tsconfig.json
+++ b/packages/code-runtime/code-runtime-worker/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../code-runtime"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/code-runtime/code-runtime-worker/tsdown.config.ts b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
index 6fee724195..1c40637722 100644
--- a/packages/code-runtime/code-runtime-worker/tsdown.config.ts
+++ b/packages/code-runtime/code-runtime-worker/tsdown.config.ts
@@ -7,7 +7,7 @@ import { defineConfig } from 'tsdown'
*/
export default defineConfig([
{
- entry: ['lib/types/index.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/code-runtime/code-runtime/package.json b/packages/code-runtime/code-runtime/package.json
index 5380d26ace..2d59302ec9 100644
--- a/packages/code-runtime/code-runtime/package.json
+++ b/packages/code-runtime/code-runtime/package.json
@@ -11,20 +11,27 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/code-runtime/code-runtime/src/invariant.ts b/packages/code-runtime/code-runtime/src/invariant.ts
new file mode 100644
index 0000000000..9c4019699b
--- /dev/null
+++ b/packages/code-runtime/code-runtime/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-code-runtime`.
+ * @module @deepseek-ai/dsh-code-runtime/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-code-runtime'
+
+/** Cordis companion plugin name. */
+export const name = 'code-runtime-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/code-runtime/code-runtime/tests/service.spec.ts b/packages/code-runtime/code-runtime/tests/service.spec.ts
index 4fc83f7552..605b51934f 100644
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -84,4 +84,5 @@ describe('CodeRuntime service seam', () => {
const { ctx } = await setup()
await expect(ctx.plugin(StubRuntime)).rejects.toThrow(/registered/)
})
+
})
diff --git a/packages/code-runtime/code-runtime/tsconfig.json b/packages/code-runtime/code-runtime/tsconfig.json
index 754725418e..9966c8ca8a 100644
--- a/packages/code-runtime/code-runtime/tsconfig.json
+++ b/packages/code-runtime/code-runtime/tsconfig.json
@@ -13,6 +13,9 @@
},
{
"path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/compact/compact-basic/README.md b/packages/compact/compact-basic/README.md
index d789bf2328..2948518398 100644
--- a/packages/compact/compact-basic/README.md
+++ b/packages/compact/compact-basic/README.md
@@ -9,32 +9,39 @@ This is the implementation tier of the compaction capability — see the [interf
This backend owns the compaction policy:
- **Measurement** — the singleton `ctx.tokenMeter` prices the latest canonical logged envelope and current surface at one consumed-log revision. Post-step pressure therefore includes the actual system prompt, tools, prefix, routing, assistant completion, tool results, buffered context, and steering.
+- **Routed policy** — proactive pressure resolves capacity from the adapter that owns the latest durable provider/model route, then scales the default policy plus an optional exact-target override into concrete token budgets. Model discovery remains advisory and is not consulted.
- **Model-free pruning** — after pressure or canonical overflow qualifies, the optional [`ctx.toolResultPrune`](../compact-tool-result-prune/README.md) service rewrites oversized tool results before range selection. Compact-basic remeasures through `ctx.tokenMeter`, skips summarization when pressure becomes safe, and otherwise summarizes the pruned surface. Below-pressure post-step checks never prune.
- **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. The optional pruner can repair an oversized closed tool unit when its text-bearing result is the removable bulk; indivisible non-tool units and non-prunable tool remainders remain 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()` mutates `agent.session` and records its start, summary, replacement, and end. The serial `agent/post-step` listener checks pressure after successful output and tool work are durable but before `step/end`. Canonical provider overflow is handled through `agent/request-error` after the failed step closes.
-- **Overflow recovery** — below-threshold overflow bypasses normal retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
+- **Overflow recovery** — provider-confirmed overflow needs no capacity metadata: it bypasses normal pressure and retention, prunes, then attempts one maximal balanced head reduction while leaving the newest indivisible unit. Retry is authorized whenever `surface.replaceGeneration` advances, including when pruning lands before later summary work throws. No replacement, an exhausted target-specific cap, cancellation, or an unknown/noncanonical error preserves the original provider failure.
- **Failure handling** — an unmatched `compact/start` is an inert crash marker because no summary replacement landed. A region failure records an error end; the surface remains unchanged unless pruning already landed. Operational post-step failures warn and continue, while overflow-recovery failure preserves the original provider error only when no earlier replacement advanced the surface. Cancellation remains authoritative after any progress.
The protected `summarize()` method 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 setting is optional. The pressure and retention policy applies to the token meter's single context window. Unrecognized top-level keys are rejected.
+Every setting is optional. Top-level policy fields are defaults for every routed model; `modelPolicies` applies partial overrides to exact provider/model pairs. At pressure time, compact-basic asks the owning LLM adapter for that route's context capacity and resolves absolute budgets. Unrecognized keys, duplicate targets, mutually exclusive retention forms, and a merged `retainRatio` that is not below `thresholdRatio` fail plugin load. An absolute `retainTokens` budget that is not below its scaled threshold fails on the first resolvable target because that comparison requires model capacity.
| Key | Required | Meaning |
|---|---|---|
-| `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. |
+| `thresholdRatio` | no (default `0.8`) | Compact at `floor(routedContextWindow × ratio)`. |
+| `retainRatio` | no (default `0.16`) | Recent surface budget kept verbatim as a fraction of the routed context window; mutually exclusive with `retainTokens`. |
+| `retainTokens` | no | Absolute recent surface budget kept verbatim; mutually exclusive with `retainRatio` and must be below the resolved 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. |
| `maxOverflowRetries` | no (default `1`) | Maximum retries after canonical context-window overflow; `0` disables recovery only. |
+| `modelPolicies` | no (default `[]`) | Exact `{ provider, model, ...partialPolicy }` overrides; matching uses both fields and does not depend on `listModels()`. |
| `auto` | no (default `true`) | Register post-step pressure and overflow-recovery listeners. Set `false` for manual-only. |
+Every `modelPolicies` entry accepts the policy fields above except `auto` and `modelPolicies` itself. If an entry supplies either retention field, it replaces the default policy's retention choice; otherwise retention is inherited. Summarization provider/model remain a pair inside each entry.
+
+An adapter may return no capacity for a valid dynamic route, and resolved capacity may expose an invalid absolute retention budget. Manual pressure checks then throw a target-specific configuration error; the automatic listener warns once for that exact target and continues with full history. Unrelated operational failures remain independently visible. Canonical provider overflow still attempts recovery because the provider has already established that compaction is necessary.
+
## Usage
```ts
@@ -53,6 +60,20 @@ export function apply(ctx: Context): void {
Loading the plugin registers `ctx.compact`. Add [`dsh-compact-tool-result-prune`](../compact-tool-result-prune/README.md) as a sibling before this plugin to enable the optional model-free pass. With `auto: true` (the default) it compacts automatically under token pressure; a consumer (a future `/compact` tool) can also call `ctx.compact.compactIfNeeded(...)` or `ctx.compact.compactRegion(...)` directly.
+For example, the same compact plugin can safely serve models with different capacities and one target-specific policy:
+
+```yaml
+- name: '@deepseek-ai/dsh-compact-basic'
+ config:
+ thresholdRatio: 0.8
+ retainRatio: 0.16
+ modelPolicies:
+ - provider: local
+ model: small-context
+ thresholdRatio: 0.7
+ retainTokens: 2048
+```
+
## Model Experience
### Conversation history
diff --git a/packages/compact/compact-basic/package.json b/packages/compact/compact-basic/package.json
index a8844b1820..6a93e249a3 100644
--- a/packages/compact/compact-basic/package.json
+++ b/packages/compact/compact-basic/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-compact": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^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",
diff --git a/packages/compact/compact-basic/src/config.ts b/packages/compact/compact-basic/src/config.ts
index 1587fac272..b954537af8 100644
--- a/packages/compact/compact-basic/src/config.ts
+++ b/packages/compact/compact-basic/src/config.ts
@@ -1,111 +1,310 @@
/**
- * Runtime defaulting and policy validation for compact-basic.
+ * Load-time validation and routed-model policy resolution 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'
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+import type {
+ BasicCompactConfig,
+ CompactPolicyConfig,
+ ModelCompactPolicyConfig,
+ ResolvedCompactSpec,
+ ResolvedConfig,
+ ResolvedRetention,
+ ResolvedTargetPolicy,
+} from './types.ts'
-/** Default request-pressure fraction of the token meter's context window. */
+/** Default request-pressure fraction for every routed model. */
const DEFAULT_THRESHOLD_RATIO = 0.8
-/** Default verbatim-tail fraction of the token meter's context window. */
+/** Default verbatim-tail fraction for every routed model. */
const DEFAULT_RETAIN_RATIO = 0.16
-/** Complete public configuration key set. */
-const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet = new Set([
+/** Fields shared by top-level defaults and exact-target overrides. */
+const POLICY_CONFIG_KEYS = [
'thresholdRatio',
+ 'retainRatio',
'retainTokens',
'summarizationProvider',
'summarizationModel',
'maxTokens',
'compactionRetries',
'maxOverflowRetries',
+] as const
+
+/** Complete public top-level configuration key set. */
+const BASIC_COMPACT_CONFIG_KEYS: ReadonlySet = new Set([
+ ...POLICY_CONFIG_KEYS,
+ 'modelPolicies',
'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, maxOverflowRetries, auto)',
- )
- }
+/** Complete exact-target override key set. */
+const MODEL_POLICY_KEYS: ReadonlySet = new Set([
+ 'provider',
+ 'model',
+ ...POLICY_CONFIG_KEYS,
+])
+
+/** Target-specific pressure configuration failure eligible for warning suppression. */
+export class TargetPressureConfigError extends Error {
+ /**
+ * @param targetKey - exact provider/model route used as the warning key.
+ * @param message - actionable configuration failure detail.
+ */
+ constructor(readonly targetKey: string, message: string) {
+ super(message)
}
}
/**
- * 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.
+ * Resolve and validate service defaults plus exact-target partial overrides.
+ * @param config - untrusted plugin configuration after Loader normalization.
+ * @returns detached immutable defaults and validated exact-target overrides.
*/
-export function resolveConfig(
- config: BasicCompactConfig = {},
- tokenMeter: TokenMeterService,
-): ResolvedConfig {
- validateConfigKeys(config)
+export function resolveConfig(config: BasicCompactConfig = {}): ResolvedConfig {
+ validateKeys(config, BASIC_COMPACT_CONFIG_KEYS, 'BasicCompactConfig')
+ validatePolicy(config, 'BasicCompactConfig')
+ if (config.auto !== undefined && typeof config.auto !== 'boolean') {
+ throw new Error('BasicCompactConfig: auto must be a boolean')
+ }
+
const thresholdRatio = config.thresholdRatio ?? DEFAULT_THRESHOLD_RATIO
- const retainTokens = config.retainTokens
- ?? Math.floor(tokenMeter.contextWindow * DEFAULT_RETAIN_RATIO)
- const resolved: ResolvedConfig = {
+ const retention = resolveRetention(config, { retainRatio: DEFAULT_RETAIN_RATIO })
+ validateRatioRetention(thresholdRatio, retention, 'BasicCompactConfig')
+ const modelPolicies = resolveModelPolicies(config.modelPolicies)
+ for (const [index, policy] of modelPolicies.entries()) {
+ validateRatioRetention(
+ policy.thresholdRatio ?? thresholdRatio,
+ resolveRetention(policy, retention),
+ `BasicCompactConfig: modelPolicies[${index}]`,
+ )
+ }
+
+ return deepFreeze({
thresholdRatio,
- retainTokens,
+ ...retention,
summarizationProvider: config.summarizationProvider ?? '',
summarizationModel: config.summarizationModel ?? '',
maxTokens: config.maxTokens ?? 8192,
compactionRetries: config.compactionRetries ?? 1,
maxOverflowRetries: config.maxOverflowRetries ?? 1,
+ modelPolicies,
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}`,
+/**
+ * Merge the exact provider/model override over the validated default policy.
+ * @param config - validated service defaults and override table.
+ * @param target - exact durable provider/model route to match.
+ * @returns detached immutable policy before model-capacity scaling.
+ */
+export function resolveTargetPolicy(
+ config: ResolvedConfig,
+ target: Pick,
+): ResolvedTargetPolicy {
+ const override = config.modelPolicies.find(policy => (
+ policy.provider === target.provider && policy.model === target.model
+ ))
+ const inheritedRetention: ResolvedRetention = config.retainTokens === undefined
+ ? { retainRatio: config.retainRatio }
+ : { retainTokens: config.retainTokens }
+ return deepFreeze({
+ target: { provider: target.provider, model: target.model },
+ thresholdRatio: override?.thresholdRatio ?? config.thresholdRatio,
+ ...resolveRetention(override ?? {}, inheritedRetention),
+ summarizationProvider: override?.summarizationProvider ?? config.summarizationProvider,
+ summarizationModel: override?.summarizationModel ?? config.summarizationModel,
+ maxTokens: override?.maxTokens ?? config.maxTokens,
+ compactionRetries: override?.compactionRetries ?? config.compactionRetries,
+ maxOverflowRetries: override?.maxOverflowRetries ?? config.maxOverflowRetries,
+ })
+}
+
+/**
+ * Scale one routed policy into concrete token budgets for its model capacity.
+ * @param policy - merged policy for the exact routed target.
+ * @param contextWindow - positive adapter-owned capacity for that target.
+ * @returns detached immutable pressure and retention budgets.
+ */
+export function resolveCompactSpec(
+ policy: ResolvedTargetPolicy,
+ contextWindow: number,
+): ResolvedCompactSpec {
+ const targetKey = `${policy.target.provider}/${policy.target.model}`
+ if (!Number.isInteger(contextWindow) || contextWindow <= 0) {
+ throw new TargetPressureConfigError(
+ targetKey,
+ `BasicCompactConfig: contextWindow (${contextWindow}) must be a positive integer`,
)
}
- assertPositiveInteger('maxTokens', resolved.maxTokens)
- assertNonNegativeInteger('compactionRetries', resolved.compactionRetries)
- assertNonNegativeInteger('maxOverflowRetries', resolved.maxOverflowRetries)
- 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',
+ const thresholdTokens = Math.floor(contextWindow * policy.thresholdRatio)
+ const retainTokens = policy.retainTokens === undefined
+ ? Math.floor(contextWindow * policy.retainRatio)
+ : policy.retainTokens
+ if (retainTokens >= thresholdTokens) {
+ throw new TargetPressureConfigError(
+ targetKey,
+ `BasicCompactConfig: ${policy.target.provider}/${policy.target.model} retainTokens `
+ + `(${retainTokens}) must be less than threshold tokens ${thresholdTokens}`,
)
}
- if (typeof resolved.auto !== 'boolean') {
- throw new Error('BasicCompactConfig: auto must be a boolean')
- }
- return deepFreeze(resolved)
+ return deepFreeze({
+ target: { ...policy.target },
+ contextWindow,
+ thresholdRatio: policy.thresholdRatio,
+ thresholdTokens,
+ retainTokens,
+ summarizationProvider: policy.summarizationProvider,
+ summarizationModel: policy.summarizationModel,
+ maxTokens: policy.maxTokens,
+ compactionRetries: policy.compactionRetries,
+ maxOverflowRetries: policy.maxOverflowRetries,
+ })
}
-function assertPositiveInteger(name: string, value: number): void {
- if (!Number.isInteger(value) || value <= 0) {
- throw new Error(`BasicCompactConfig: ${name} (${value}) must be a positive integer`)
+/** Choose an explicit retention form or inherit the already-resolved fallback. */
+function resolveRetention(
+ config: CompactPolicyConfig,
+ fallback: ResolvedRetention,
+): ResolvedRetention {
+ if (config.retainTokens !== undefined) return { retainTokens: config.retainTokens }
+ if (config.retainRatio !== undefined) return { retainRatio: config.retainRatio }
+ return fallback
+}
+
+/** Reject a capacity-independent retention conflict at plugin load. */
+function validateRatioRetention(
+ thresholdRatio: number,
+ retention: ResolvedRetention,
+ name: string,
+): void {
+ if (retention.retainRatio !== undefined && retention.retainRatio >= thresholdRatio) {
+ throw new Error(
+ `${name}: retainRatio (${retention.retainRatio}) must be less than `
+ + `the resolved thresholdRatio (${thresholdRatio})`,
+ )
}
}
-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`)
+/** Validate, detach, and reject duplicate exact-target policies. */
+function resolveModelPolicies(configured: unknown): ModelCompactPolicyConfig[] {
+ if (configured === undefined) return []
+ if (!Array.isArray(configured)) {
+ throw new Error('BasicCompactConfig: modelPolicies must be an array')
+ }
+ const seen = new Set()
+ return configured.map((source: unknown, index) => {
+ const name = `BasicCompactConfig: modelPolicies[${index}]`
+ assertModelPolicy(source, name)
+ const key = `${source.provider}\u0000${source.model}`
+ if (seen.has(key)) {
+ throw new Error(
+ `BasicCompactConfig: duplicate model policy for ${source.provider}/${source.model}`,
+ )
+ }
+ seen.add(key)
+ return { ...source }
+ })
+}
+
+/** Validate one untrusted exact-target override and narrow its public type. */
+function assertModelPolicy(
+ source: unknown,
+ name: string,
+): asserts source is ModelCompactPolicyConfig {
+ if (!isUnknownRecord(source)) throw new Error(`${name} must be an object`)
+ validateKeys(source, MODEL_POLICY_KEYS, name)
+ assertNonEmptyString(`${name}.provider`, source.provider)
+ assertNonEmptyString(`${name}.model`, source.model)
+ validatePolicy(source, name)
+}
+
+/** Validate the fields common to defaults and exact-target partial overrides. */
+function validatePolicy(
+ config: CompactPolicyConfig | Record,
+ name: string,
+): void {
+ const thresholdRatio = config.thresholdRatio
+ const retainRatio = config.retainRatio
+ const retainTokens = config.retainTokens
+ const maxTokens = config.maxTokens
+ const compactionRetries = config.compactionRetries
+ const maxOverflowRetries = config.maxOverflowRetries
+ if (thresholdRatio !== undefined) assertRatio(`${name}.thresholdRatio`, thresholdRatio)
+ if (retainRatio !== undefined) assertRatio(`${name}.retainRatio`, retainRatio)
+ if (retainTokens !== undefined) assertNonNegativeInteger(`${name}.retainTokens`, retainTokens)
+ if (retainRatio !== undefined && retainTokens !== undefined) {
+ throw new Error(`${name}: retainRatio and retainTokens are mutually exclusive`)
+ }
+ if (maxTokens !== undefined) assertPositiveInteger(`${name}.maxTokens`, maxTokens)
+ if (compactionRetries !== undefined) {
+ assertNonNegativeInteger(`${name}.compactionRetries`, compactionRetries)
+ }
+ if (maxOverflowRetries !== undefined) {
+ assertNonNegativeInteger(`${name}.maxOverflowRetries`, maxOverflowRetries)
+ }
+
+ validateSummarizationPair(config, name)
+}
+
+/** Require one scope to omit, clear, or replace the summarization target as a pair. */
+function validateSummarizationPair(
+ config: CompactPolicyConfig | Record,
+ name: string,
+): void {
+ const provider = config.summarizationProvider
+ const model = config.summarizationModel
+ if (provider !== undefined && typeof provider !== 'string') {
+ throw new Error(`${name}.summarizationProvider must be a string`)
+ }
+ if (model !== undefined && typeof model !== 'string') {
+ throw new Error(`${name}.summarizationModel must be a string`)
+ }
+ if (provider === undefined && model === undefined) return
+ if (provider === undefined || model === undefined
+ || (provider.length === 0) !== (model.length === 0)) {
+ throw new Error(
+ `${name}: summarizationProvider and summarizationModel must be set together `
+ + 'as an empty or non-empty pair',
+ )
}
}
-function assertRatio(name: string, value: number): void {
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateKeys(config: object, keys: ReadonlySet, name: string): void {
+ for (const key of Object.keys(config)) {
+ if (!keys.has(key)) throw new Error(`${name}: unknown key "${key}"`)
+ }
+}
+
+function isUnknownRecord(value: unknown): value is Record {
+ return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function assertNonEmptyString(name: string, value: unknown): asserts value is string {
+ if (typeof value !== 'string' || value.length === 0) {
+ throw new Error(`${name} must be a non-empty string`)
+ }
+}
+
+function assertPositiveInteger(name: string, value: unknown): asserts value is number {
+ if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+ throw new Error(`${name} (${String(value)}) must be a positive integer`)
+ }
+}
+
+function assertNonNegativeInteger(name: string, value: unknown): asserts value is number {
+ if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+ throw new Error(`${name} (${String(value)}) must be a non-negative integer`)
+ }
+}
+
+function assertRatio(name: string, value: unknown): asserts value is number {
if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
- throw new Error(`BasicCompactConfig: ${name} (${value}) must be a number in (0, 1]`)
+ throw new Error(`${name} (${String(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 5fc02964b8..1bf6bc5459 100644
--- a/packages/compact/compact-basic/src/index.ts
+++ b/packages/compact/compact-basic/src/index.ts
@@ -10,29 +10,78 @@ import { CompactService } from '@deepseek-ai/dsh-compact'
import type { CompactionResult, CompactionTrigger } from '@deepseek-ai/dsh-compact'
import type { Session } from '@deepseek-ai/dsh-session'
import { CONTEXT_WINDOW_EXCEEDED_CODE, assertNever } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import type { ContentBlock, LlmCallConfig } from '@deepseek-ai/dsh-llm'
import type { Agent } from '@deepseek-ai/dsh-agent'
// Type-only: makes the optional sibling service available to `ctx.get()`.
import type {} from '@deepseek-ai/dsh-compact-tool-result-prune'
-import { resolveConfig } from './config.ts'
+import {
+ resolveCompactSpec,
+ resolveConfig,
+ resolveTargetPolicy,
+ TargetPressureConfigError,
+} from './config.ts'
import { compactSurfaceRegion, selectCompactableRange } from './region.ts'
import { summarizeWithLlm } from './summarizer.ts'
import type {
BasicCompactConfig,
+ ModelCompactPolicyConfig,
ResolvedConfig,
} from './types.ts'
export type {
BasicCompactConfig,
+ CompactPolicyConfig,
+ ModelCompactPolicyConfig,
+ ResolvedCompactSpec,
ResolvedConfig,
+ ResolvedRetention,
+ ResolvedTargetPolicy,
} from './types.ts'
-/** Resolve the exact model durably routed for the latest provider request. */
-function routedModel(session: Session): string | undefined {
- const model = session.requestHeader()?.config.model
- return model === undefined || model.length === 0 ? undefined : model
+/** Resolve the exact provider/model durably routed for the latest request. */
+function routedTarget(
+ session: Session,
+): Pick | undefined {
+ const config = session.requestHeader()?.config
+ if (config === undefined || config.provider.length === 0 || config.model.length === 0) {
+ return undefined
+ }
+ return { provider: config.provider, model: config.model }
}
+/** Resolve the conversation target used to select an optional policy override. */
+function conversationTarget(
+ agent: Agent,
+): Pick | undefined {
+ const routed = routedTarget(agent.session)
+ if (routed !== undefined) return routed
+ if (agent.options.provider === undefined || agent.options.provider.length === 0
+ || agent.options.model === undefined || agent.options.model.length === 0) return undefined
+ return { provider: agent.options.provider, model: agent.options.model }
+}
+
+const thresholdRatioSchema = z.number()
+const retainRatioSchema = z.number()
+const retainTokensSchema = z.number().step(1).min(0)
+const summarizationProviderSchema = z.string()
+const summarizationModelSchema = z.string()
+const maxTokensSchema = z.number().step(1).min(1)
+const compactionRetriesSchema = z.number().step(1).min(0)
+const maxOverflowRetriesSchema = z.number().step(1).min(0)
+
+const modelPolicy: z = z.object({
+ provider: z.string().required(),
+ model: z.string().required(),
+ thresholdRatio: thresholdRatioSchema,
+ retainRatio: retainRatioSchema,
+ retainTokens: retainTokensSchema,
+ summarizationProvider: summarizationProviderSchema,
+ summarizationModel: summarizationModelSchema,
+ maxTokens: maxTokensSchema,
+ compactionRetries: compactionRetriesSchema,
+ maxOverflowRetries: maxOverflowRetriesSchema,
+})
+
/**
* Dependency-light compaction backend using `ctx.tokenMeter` for pressure,
* retention, provenance, and summary-convergence pricing.
@@ -45,22 +94,26 @@ export class BasicCompactService extends CompactService {
static inject = ['llm', 'tokenMeter']
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),
- maxOverflowRetries: z.number().step(1).min(0).default(1),
- auto: z.boolean().default(true),
+ thresholdRatio: thresholdRatioSchema,
+ retainRatio: retainRatioSchema,
+ retainTokens: retainTokensSchema,
+ summarizationProvider: summarizationProviderSchema,
+ summarizationModel: summarizationModelSchema,
+ maxTokens: maxTokensSchema,
+ compactionRetries: compactionRetriesSchema,
+ maxOverflowRetries: maxOverflowRetriesSchema,
+ modelPolicies: z.array(modelPolicy),
+ auto: z.boolean(),
})
/** Resolved and validated compaction configuration. */
readonly config: ResolvedConfig
+ private readonly warnedPressureConfigTargets = new Set()
+
constructor(ctx: Context, config: BasicCompactConfig = {}) {
super(ctx)
- this.config = resolveConfig(config, ctx.tokenMeter)
+ this.config = resolveConfig(config)
if (this.config.auto) this._registerAutomaticCompaction()
}
@@ -90,16 +143,33 @@ export class BasicCompactService extends CompactService {
const result = await this.compactIfNeeded(agent, 'pressure', signal)
if (result !== null) logResult(result, 'post-step pressure')
} catch (error: unknown) {
+ if (error instanceof TargetPressureConfigError) {
+ if (this.warnedPressureConfigTargets.has(error.targetKey)) return
+ this.warnedPressureConfigTargets.add(error.targetKey)
+ }
const message = error instanceof Error ? error.message : String(error)
ctx.logger.warn(`post-step compaction failed: ${message}; continuing the turn`)
}
})
- ctx.on('agent/request-error', async (agent, _turn, _step, _error, failure, priorFailures, signal, next) => {
- const priorOverflowFailures = priorFailures.filter(item => item.code === CONTEXT_WINDOW_EXCEEDED_CODE).length
- if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE
- || priorOverflowFailures >= this.config.maxOverflowRetries
- || signal.aborted) return next()
+ ctx.on('agent/request-error', async (
+ agent,
+ _turn,
+ _step,
+ _error,
+ failure,
+ priorFailures,
+ signal,
+ next,
+ ) => {
+ const priorOverflowFailures = priorFailures.filter(
+ item => item.code === CONTEXT_WINDOW_EXCEEDED_CODE,
+ ).length
+ if (failure.code !== CONTEXT_WINDOW_EXCEEDED_CODE || signal.aborted) return next()
+ const target = routedTarget(agent.session)
+ if (target === undefined) return next()
+ const policy = resolveTargetPolicy(this.config, target)
+ if (priorOverflowFailures >= policy.maxOverflowRetries) return next()
const generation = agent.session.surface.replaceGeneration
let result: CompactionResult | null
@@ -147,7 +217,11 @@ export class BasicCompactService extends CompactService {
agent: Agent,
signal?: AbortSignal,
): Promise<{ summary: ContentBlock[]; provider: string; model: string; maxTokens?: number }> {
- return summarizeWithLlm(this.ctx, this.config, text, agent, signal)
+ const target = conversationTarget(agent)
+ const config = target === undefined
+ ? this.config
+ : resolveTargetPolicy(this.config, target)
+ return summarizeWithLlm(this.ctx, config, text, agent, signal)
}
/**
@@ -165,16 +239,15 @@ export class BasicCompactService extends CompactService {
trigger: CompactionTrigger,
signal: AbortSignal,
): Promise {
- const model = routedModel(agent.session)
- if (model === undefined) return null
+ const target = routedTarget(agent.session)
+ if (target === undefined) return null
+ const policy = resolveTargetPolicy(this.config, target)
const meter = this.ctx.tokenMeter
- const threshold = Math.floor(meter.contextWindow * this.config.thresholdRatio)
let measurement = meter.measure(agent.session)
switch (trigger) {
case 'context-overflow':
break
case 'pressure':
- if (measurement.totalTokens < threshold) return null
break
/* v8 ignore next -- closed-union exhaustiveness guard */
default:
@@ -182,25 +255,43 @@ export class BasicCompactService extends CompactService {
}
// Pruning is optional so compact-basic remains independently composable.
- // Once either trigger qualifies, land the model-free pass before choosing
- // a summary range, then remeasure through the singleton replay fold.
+ // Overflow always qualifies; pressure first resolves the routed model's
+ // capacity and checks its target-specific threshold.
const prune = this.ctx.get('toolResultPrune')
- if (prune !== undefined) {
- prune.pruneSession(agent.session)
- measurement = meter.measure(agent.session)
- }
if (trigger === 'context-overflow') {
+ if (prune !== undefined) {
+ prune.pruneSession(agent.session)
+ measurement = meter.measure(agent.session)
+ }
const range = selectCompactableRange(agent.session, measurement, 0)
if (range === null) return null
return this.compactRegion(range.start, range.end, agent, signal)
}
- if (measurement.totalTokens < threshold) return null
+ const context = await this.ctx.llm.resolveModelContext(target.provider, target.model)
+ const targetKey = `${target.provider}/${target.model}`
+ if (context === undefined) {
+ throw new TargetPressureConfigError(
+ targetKey,
+ `compact-basic: no context capacity for ${targetKey}; `
+ + 'configure contextWindow on that adapter model',
+ )
+ }
+ const spec = resolveCompactSpec(policy, context.contextWindow)
+ if (measurement.totalTokens < spec.thresholdTokens) return null
+
+ // Once pressure qualifies, land the model-free pass before choosing a
+ // summary range, then remeasure through the singleton replay fold.
+ if (prune !== undefined) {
+ prune.pruneSession(agent.session)
+ measurement = meter.measure(agent.session)
+ }
+ if (measurement.totalTokens < spec.thresholdTokens) return null
let result: CompactionResult | null = null
- for (let attempt = 0; attempt <= this.config.compactionRetries; attempt += 1) {
- const range = selectCompactableRange(agent.session, measurement, this.config.retainTokens)
+ for (let attempt = 0; attempt <= spec.compactionRetries; attempt += 1) {
+ const range = selectCompactableRange(agent.session, measurement, spec.retainTokens)
if (range === null) {
/* v8 ignore else -- concrete replacement preserves a compactable checkpoint; subclass hooks cannot mutate it. */
if (result === null) return null
@@ -209,12 +300,12 @@ export class BasicCompactService extends CompactService {
}
result = await this.compactRegion(range.start, range.end, agent, signal)
measurement = meter.measure(agent.session)
- if (measurement.totalTokens < threshold) return result
+ if (measurement.totalTokens < spec.thresholdTokens) return result
}
throw new Error(
- `compaction still above threshold after ${this.config.compactionRetries + 1} compaction attempts `
- + `(${measurement.totalTokens} estimated tokens >= threshold ${threshold})`,
+ `compaction still above threshold after ${spec.compactionRetries + 1} compaction attempts `
+ + `(${measurement.totalTokens} estimated tokens >= threshold ${spec.thresholdTokens})`,
)
}
diff --git a/packages/compact/compact-basic/src/invariant.ts b/packages/compact/compact-basic/src/invariant.ts
new file mode 100644
index 0000000000..172790d233
--- /dev/null
+++ b/packages/compact/compact-basic/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-compact-basic`.
+ * @module @deepseek-ai/dsh-compact-basic/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-compact-basic'
+
+/** Cordis companion plugin name. */
+export const name = 'compact-basic-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/compact/compact-basic/src/summarizer.ts b/packages/compact/compact-basic/src/summarizer.ts
index 32e308bce4..247224eb75 100644
--- a/packages/compact/compact-basic/src/summarizer.ts
+++ b/packages/compact/compact-basic/src/summarizer.ts
@@ -8,7 +8,12 @@ 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'
+
+interface SummaryConfig {
+ readonly summarizationProvider: string
+ readonly summarizationModel: string
+ readonly maxTokens: number
+}
/** Tags wrapping the structured summary inside the landed checkpoint node. */
const SUMMARY_OPEN_TAG = ''
@@ -74,7 +79,7 @@ export interface SummaryResult {
*/
export async function summarizeWithLlm(
ctx: Context,
- config: ResolvedConfig,
+ config: SummaryConfig,
text: string,
agent: Agent,
signal?: AbortSignal,
diff --git a/packages/compact/compact-basic/src/types.ts b/packages/compact/compact-basic/src/types.ts
index 6ed0165226..c322f508ac 100644
--- a/packages/compact/compact-basic/src/types.ts
+++ b/packages/compact/compact-basic/src/types.ts
@@ -4,15 +4,19 @@
* @module @deepseek-ai/dsh-compact-basic/types
*/
-/** Basic compaction configuration; every common field has a deployment default. */
-export interface BasicCompactConfig {
- /** Compact at this fraction of the token meter's context window. Defaults to `0.8`. */
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+
+/** Policy fields shared by the default policy and exact model overrides. */
+export interface CompactPolicyConfig {
+ /** Compact at this fraction of the model's context window. Defaults to `0.8`. */
thresholdRatio?: number
- /** Recent surface tokens retained verbatim. Defaults to `floor(contextWindow * 0.16)`. */
+ /** Recent context retained as a fraction of the model's window. Defaults to `0.16`. */
+ retainRatio?: number
+ /** Absolute recent-context budget; mutually exclusive with `retainRatio`. */
retainTokens?: number
- /** Summary provider; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+ /** Summary provider; set together with `summarizationModel`, or inherit the conversation target. */
summarizationProvider?: string
- /** Summary model; `''` resolves the latest routed pair, then the agent pair. Defaults to `''`. */
+ /** Summary model; set together with `summarizationProvider`, or inherit the conversation target. */
summarizationModel?: string
/** Provider generation cap for summarization. Defaults to `8192`. */
maxTokens?: number
@@ -20,18 +24,53 @@ export interface BasicCompactConfig {
compactionRetries?: number
/** Maximum retries after canonical context overflow; `0` disables recovery. Defaults to `1`. */
maxOverflowRetries?: number
+}
+
+/** Exact provider/model override merged over the default compaction policy. */
+export interface ModelCompactPolicyConfig extends CompactPolicyConfig {
+ /** Registered provider route to match. */
+ provider: string
+ /** Exact routed model id to match within `provider`. */
+ model: string
+}
+
+/** Basic compaction configuration with an optional exact-target policy table. */
+export interface BasicCompactConfig extends CompactPolicyConfig {
+ /** Exact provider/model overrides; duplicate targets fail plugin load. */
+ modelPolicies?: ModelCompactPolicyConfig[]
/** Enable automatic post-step pressure and overflow-recovery listeners. Defaults to `true`. */
auto?: boolean
}
-/** Validated and detached compaction configuration. */
-export interface ResolvedConfig {
+/** Exactly one validated retention form. */
+export type ResolvedRetention =
+ | { readonly retainRatio: number; readonly retainTokens?: never }
+ | { readonly retainRatio?: never; readonly retainTokens: number }
+
+/** Validated policy fields shared before and after exact-target matching. */
+interface ResolvedPolicyFields {
readonly thresholdRatio: number
- readonly retainTokens: number
readonly summarizationProvider: string
readonly summarizationModel: string
readonly maxTokens: number
readonly compactionRetries: number
readonly maxOverflowRetries: number
+}
+
+/** Validated immutable config whose target-specific defaults remain unresolved. */
+export type ResolvedConfig = ResolvedPolicyFields & ResolvedRetention & {
+ readonly modelPolicies: readonly Readonly[]
readonly auto: boolean
}
+
+/** Fully merged policy for one routed conversation target, before capacity scaling. */
+export type ResolvedTargetPolicy = ResolvedPolicyFields & ResolvedRetention & {
+ readonly target: Pick
+}
+
+/** One routed model's concrete pressure and retention budget. */
+export type ResolvedCompactSpec = Omit & {
+ readonly contextWindow: number
+ readonly thresholdTokens: number
+ readonly retainTokens: number
+}
diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts
index d0340e8b0d..01e0e62da9 100644
--- a/packages/compact/compact-basic/tests/compact-basic.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts
@@ -4,21 +4,62 @@ import BasicCompactService 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 { toolPairingBalancedAfter, toolPairingBalancedBefore } from '@deepseek-ai/dsh-compact'
-import { resolveConfig } from '@deepseek-ai/dsh-compact-basic/src/config.ts'
+import {
+ resolveCompactSpec,
+ resolveConfig,
+ resolveTargetPolicy,
+} from '@deepseek-ai/dsh-compact-basic/src/config.ts'
import type { CompactionResult } from '@deepseek-ai/dsh-compact'
import LlmService, { CallId, CONTEXT_WINDOW_EXCEEDED_CODE, LlmAdapter } from '@deepseek-ai/dsh-llm'
-import type { ContentBlock, GenerateOptions, LlmFailure, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type {
+ ContentBlock,
+ GenerateOptions,
+ LlmFailure,
+ LlmModelContext,
+ StreamChunk,
+} from '@deepseek-ai/dsh-llm'
import { Session, SessionId } from '@deepseek-ai/dsh-session'
import TokenMeterService from '@deepseek-ai/dsh-token-meter'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
import ToolResultPruneService from '@deepseek-ai/dsh-compact-tool-result-prune'
-import type { Agent } from '@deepseek-ai/dsh-agent'
const SIGNAL = new AbortController().signal
const MODEL = 'test-model'
+class ContextAdapter extends LlmAdapter {
+ constructor(private readonly contextWindow: number) {
+ super()
+ }
+
+ override resolveModelContext(): Promise {
+ return Promise.resolve({ contextWindow: this.contextWindow })
+ }
+
+ override async * stream(): AsyncIterable {
+ yield { type: 'finish', reason: { kind: 'stop' } }
+ }
+}
+
+class RoutedContextAdapter extends LlmAdapter {
+ constructor(private readonly windows: Readonly>) {
+ super()
+ }
+
+ override resolveModelContext(provider: string): Promise {
+ const contextWindow = this.windows[provider]
+ return Promise.resolve(contextWindow === undefined ? undefined : { contextWindow })
+ }
+
+ override async * stream(): AsyncIterable {
+ yield { type: 'finish', reason: { kind: 'stop' } }
+ }
+}
+
function createContext(contextWindow = 1_000): Context {
const ctx = new Context()
- void new TokenMeterService(ctx, { contextWindow })
+ void new LlmService(ctx)
+ void new TokenMeterService(ctx)
+ ctx.llm.registerAdapter([MODEL, 'actual', 'unlisted-provider'], new ContextAdapter(contextWindow))
return ctx
}
@@ -178,43 +219,131 @@ async function compactIfNeeded(
describe('compact configuration and defaults', () => {
it('uses low-friction service-wide defaults', () => {
- const ctx = createContext()
- const resolved = resolveConfig({}, ctx.tokenMeter)
+ const resolved = resolveConfig({})
expect(resolved).toEqual({
thresholdRatio: 0.8,
- retainTokens: 160,
+ retainRatio: 0.16,
summarizationProvider: '',
summarizationModel: '',
maxTokens: 8192,
compactionRetries: 1,
maxOverflowRetries: 1,
+ modelPolicies: [],
auto: true,
})
expect(Object.isFrozen(resolved)).toBe(true)
})
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,
+ retainRatio: 0.16,
})
const retentionOnly = resolveConfig({
retainTokens: 70,
- }, ctx.tokenMeter)
+ })
expect(retentionOnly).toMatchObject({
thresholdRatio: 0.8,
retainTokens: 70,
})
+ expect(retentionOnly).not.toHaveProperty('retainRatio')
+ })
+
+ it('merges exact provider/model policy overrides and scales ratios per model', () => {
+ const config = resolveConfig({
+ thresholdRatio: 0.8,
+ retainRatio: 0.1,
+ modelPolicies: [{
+ provider: 'small-provider',
+ model: 'shared-id',
+ thresholdRatio: 0.5,
+ retainTokens: 120,
+ }],
+ })
+ const small = resolveTargetPolicy(config, {
+ provider: 'small-provider',
+ model: 'shared-id',
+ })
+ const otherProvider = resolveTargetPolicy(config, {
+ provider: 'large-provider',
+ model: 'shared-id',
+ })
+
+ expect(resolveCompactSpec(small, 1_000)).toMatchObject({
+ thresholdTokens: 500,
+ retainTokens: 120,
+ })
+ expect(resolveCompactSpec(otherProvider, 2_000)).toMatchObject({
+ thresholdTokens: 1_600,
+ retainTokens: 200,
+ })
+
+ const ratioOverride = resolveTargetPolicy(resolveConfig({
+ retainTokens: 200,
+ modelPolicies: [{
+ provider: 'ratio-provider',
+ model: 'ratio-model',
+ thresholdRatio: 0.6,
+ retainRatio: 0.2,
+ summarizationProvider: 'summary-provider',
+ summarizationModel: 'summary-model',
+ maxTokens: 512,
+ compactionRetries: 2,
+ maxOverflowRetries: 3,
+ }],
+ }), { provider: 'ratio-provider', model: 'ratio-model' })
+ expect(resolveCompactSpec(ratioOverride, 2_000)).toMatchObject({
+ thresholdTokens: 1_200,
+ retainTokens: 400,
+ summarizationProvider: 'summary-provider',
+ summarizationModel: 'summary-model',
+ maxTokens: 512,
+ compactionRetries: 2,
+ maxOverflowRetries: 3,
+ })
+ })
+
+ it('inherits, clears, and replaces the summarization target as a pair', () => {
+ const config = resolveConfig({
+ summarizationProvider: 'default-provider',
+ summarizationModel: 'default-model',
+ modelPolicies: [
+ { provider: 'inherit-provider', model: MODEL },
+ {
+ provider: 'clear-provider',
+ model: MODEL,
+ summarizationProvider: '',
+ summarizationModel: '',
+ },
+ {
+ provider: 'replace-provider',
+ model: MODEL,
+ summarizationProvider: 'replacement-provider',
+ summarizationModel: 'replacement-model',
+ },
+ ],
+ })
+
+ expect(resolveTargetPolicy(config, { provider: 'inherit-provider', model: MODEL }))
+ .toMatchObject({
+ summarizationProvider: 'default-provider',
+ summarizationModel: 'default-model',
+ })
+ expect(resolveTargetPolicy(config, { provider: 'clear-provider', model: MODEL }))
+ .toMatchObject({ summarizationProvider: '', summarizationModel: '' })
+ expect(resolveTargetPolicy(config, { provider: 'replace-provider', model: MODEL }))
+ .toMatchObject({
+ summarizationProvider: 'replacement-provider',
+ summarizationModel: 'replacement-model',
+ })
})
it('validates common values and pressure-policy invariants', () => {
- const ctx = createContext()
const bad = [
[{ maxTokens: 0 }, /maxTokens/],
[{ compactionRetries: -1 }, /compactionRetries/],
@@ -222,20 +351,62 @@ describe('compact configuration and defaults', () => {
[{ 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/],
+ [{ summarizationProvider: MODEL }, /must be set together/],
+ [{ summarizationModel: MODEL }, /must be set together/],
+ [{ summarizationProvider: '' }, /must be set together/],
+ [{ summarizationModel: '' }, /must be set together/],
[{ thresholdRatio: 0 }, /number in \(0, 1\]/],
[{ thresholdRatio: 1.1 }, /number in \(0, 1\]/],
+ [{ retainRatio: 0.9 }, /retainRatio \(0.9\) must be less than the resolved thresholdRatio \(0.8\)/],
+ [{ thresholdRatio: 0.1 }, /retainRatio \(0.16\) must be less than the resolved thresholdRatio \(0.1\)/],
[{ retainTokens: -1 }, /non-negative integer/],
- [{ thresholdRatio: 0.5, retainTokens: 500 }, /less than threshold/],
+ [{ retainRatio: 0.2, retainTokens: 100 }, /mutually exclusive/],
+ [{ modelPolicies: {} }, /modelPolicies must be an array/],
+ [{ modelPolicies: [1] }, /modelPolicies\[0\] must be an object/],
+ [{ modelPolicies: [null] }, /modelPolicies\[0\] must be an object/],
+ [{ modelPolicies: [[]] }, /modelPolicies\[0\] must be an object/],
+ [{ modelPolicies: [{ provider: 1, model: MODEL }] }, /provider must be a non-empty string/],
+ [{ modelPolicies: [{ provider: '', model: MODEL }] }, /provider must be a non-empty string/],
+ [{ modelPolicies: [{ provider: MODEL, model: 1 }] }, /model must be a non-empty string/],
+ [{ modelPolicies: [{ provider: MODEL, model: '' }] }, /model must be a non-empty string/],
+ [{ modelPolicies: [{ provider: MODEL, model: MODEL, summarizationProvider: 1 }] }, /summarizationProvider must be a string/],
+ [{
+ summarizationProvider: 'default-provider',
+ summarizationModel: 'default-model',
+ modelPolicies: [{ provider: MODEL, model: MODEL, summarizationModel: '' }],
+ }, /modelPolicies\[0\].*must be set together/],
+ [{
+ summarizationProvider: 'default-provider',
+ summarizationModel: 'default-model',
+ modelPolicies: [{ provider: MODEL, model: MODEL, summarizationProvider: '' }],
+ }, /modelPolicies\[0\].*must be set together/],
+ [{ modelPolicies: [{ provider: MODEL, model: MODEL, retainRatio: 0.2, retainTokens: 100 }] }, /mutually exclusive/],
+ [
+ { modelPolicies: [{ provider: MODEL, model: MODEL, thresholdRatio: 0.1 }] },
+ /modelPolicies\[0\]: retainRatio \(0.16\).*thresholdRatio \(0.1\)/,
+ ],
+ [
+ { modelPolicies: [{ provider: MODEL, model: MODEL, retainRatio: 0.9 }] },
+ /modelPolicies\[0\]: retainRatio \(0.9\).*thresholdRatio \(0.8\)/,
+ ],
+ [{ modelPolicies: [{ provider: MODEL, model: MODEL }, { provider: MODEL, model: MODEL }] }, /duplicate model policy/],
[{ 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)
+ expect(() => resolveConfig(config as BasicCompactConfig)).toThrow(pattern)
}
+
+ const invalidPressure = resolveTargetPolicy(resolveConfig({
+ thresholdRatio: 0.5,
+ retainTokens: 500,
+ }), { provider: MODEL, model: MODEL })
+ expect(() => resolveCompactSpec(invalidPressure, 1_000)).toThrow(/less than threshold/)
+ expect(() => resolveCompactSpec(invalidPressure, 1.5)).toThrow(/positive integer/)
+ expect(() => resolveCompactSpec(invalidPressure, 0)).toThrow(/positive integer/)
})
+
})
describe('pressure measurement and retention', () => {
@@ -254,7 +425,7 @@ describe('pressure measurement and retention', () => {
expect(compact.calls).toHaveLength(0)
})
- it('meters any routed model without profile resolution', async () => {
+ it('meters an unlisted model when its provider adapter supplies context metadata', async () => {
const compact = service(compactConfig)
const session = conversation()
session.append('request/header', {
@@ -265,6 +436,52 @@ describe('pressure measurement and retention', () => {
.resolves.not.toBeNull()
})
+ it('re-resolves capacity after a same-model-id provider switch in one session', async () => {
+ const ctx = new Context()
+ void new LlmService(ctx)
+ void new TokenMeterService(ctx)
+ ctx.llm.registerAdapter(['large', 'small'], new RoutedContextAdapter({
+ large: 10_000,
+ small: 1_000,
+ }))
+ const compact = service({
+ auto: false,
+ thresholdRatio: 0.5,
+ retainRatio: 0.1,
+ }, ctx)
+ const session = conversation(4)
+ session.append('request/header', {
+ header: { config: { provider: 'large', model: 'shared-id' } },
+ reason: 'resume',
+ })
+ await expect(compactIfNeeded(compact, session)).resolves.toBeNull()
+
+ session.append('request/header', {
+ header: { config: { provider: 'small', model: 'shared-id' } },
+ reason: 'change',
+ })
+ await expect(compactIfNeeded(compact, session)).resolves.not.toBeNull()
+ })
+
+ it('requires capacity only for proactive pressure, not provider-confirmed overflow', async () => {
+ const ctx = new Context()
+ void new LlmService(ctx)
+ void new TokenMeterService(ctx)
+ ctx.llm.registerAdapter(['unknown-context'], new ContextAdapter(1_000))
+ vi.spyOn(ctx.llm, 'resolveModelContext').mockResolvedValue(undefined)
+ const compact = service(compactConfig, ctx)
+ const session = conversation(4)
+ session.append('request/header', {
+ header: { config: { provider: 'unknown-context', model: 'model' } },
+ reason: 'resume',
+ })
+
+ await expect(compactIfNeeded(compact, session, 'pressure'))
+ .rejects.toThrow(/no context capacity for unknown-context\/model/)
+ await expect(compactIfNeeded(compact, session, 'context-overflow'))
+ .resolves.not.toBeNull()
+ })
+
it('declines forced overflow when the whole surface is one indivisible tool pair', async () => {
const compact = service(compactConfig)
const session = new Session(SessionId('single-tool-pair'))
@@ -788,7 +1005,7 @@ async function summarizerHarness(
): Promise<{ ctx: Context; adapter: ScriptedAdapter; compact: ExposedCompactService }> {
const ctx = new Context()
await ctx.plugin(LlmService)
- void new TokenMeterService(ctx, { contextWindow: 1_000 })
+ void new TokenMeterService(ctx)
const adapter = new ScriptedAdapter(blocks, finish)
ctx.llm.registerAdapter([model], adapter)
const compact = new ExposedCompactService(ctx, config)
@@ -871,6 +1088,31 @@ describe('default one-shot summarizer', () => {
.rejects.toThrow(/no provider\/model available for summarization/)
})
+ it('uses a complete AgentOptions target when no durable route exists', async () => {
+ const { adapter, compact } = await summarizerHarness([{ type: 'text', text: 'summary' }])
+ const session = new Session(SessionId('headerless-summary'))
+
+ await expect(compact.runSummarize('history', agent(session, MODEL))).resolves.toMatchObject({
+ provider: MODEL,
+ model: MODEL,
+ })
+ expect(adapter.lastOptions).toMatchObject({ provider: MODEL, model: MODEL })
+ })
+
+ it.each([
+ { provider: '', model: MODEL },
+ { provider: MODEL },
+ { provider: MODEL, model: '' },
+ ])('rejects incomplete AgentOptions target %#', async (options) => {
+ const { compact } = await summarizerHarness([{ type: 'text', text: 'unused' }])
+ const owner = {
+ session: new Session(SessionId(`incomplete-${String(options.model)}`)),
+ options,
+ } as Agent
+ await expect(compact.runSummarize('history', owner))
+ .rejects.toThrow(/no provider\/model available for summarization/)
+ })
+
it.each([
[{ kind: 'error', failure: { message: 'provider failed', code: 'PROVIDER' } }, 'PROVIDER', /provider failed/],
[{ kind: 'error', failure: { message: 'opaque', code: 'UNKNOWN' } }, 'UNKNOWN', /opaque/],
@@ -901,7 +1143,7 @@ describe('default one-shot summarizer', () => {
describe('automatic listener and loader composition', () => {
function postStep(ctx: Context, owner: Agent, signal = SIGNAL): Promise {
- return ctx.serial('agent/post-step', owner, 1, 1, signal)
+ return agentEvents(ctx, owner).serial('agent/post-step', 1, 1, signal)
}
function recover(
@@ -914,7 +1156,9 @@ describe('automatic listener and loader composition', () => {
): Promise<{ action: 'fail' | 'retry' }> {
const failure: LlmFailure = { message: error.message, code: error.code ?? 'UNKNOWN' }
const priorFailures = Object.freeze(Array.from({ length: retryAttempt }, () => failure))
- return ctx.waterfall('agent/request-error', owner, 1, 1, error, failure, priorFailures, signal, next)
+ return agentEvents(ctx, owner).waterfall(
+ 'agent/request-error', 1, 1, error, failure, priorFailures, signal, next,
+ )
}
function overflow(message = 'provider overflow'): Error & { code: string } {
@@ -969,6 +1213,43 @@ describe('automatic listener and loader composition', () => {
expect(session.events.some(event => event.type === 'compact/summary')).toBe(false)
})
+ it('warns once per routed target when proactive pressure has no context metadata', async () => {
+ const ctx = createContext()
+ const warnings: string[] = []
+ ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn
+ vi.spyOn(ctx.llm, 'resolveModelContext').mockResolvedValue(undefined)
+ void new TestCompactService(ctx, {
+ thresholdRatio: 0.5,
+ retainTokens: 180,
+ })
+ const session = conversation(4)
+
+ await postStep(ctx, agent(session, MODEL))
+ await postStep(ctx, agent(session, MODEL))
+
+ expect(warnings).toEqual([
+ expect.stringContaining(`no context capacity for ${MODEL}/${MODEL}`),
+ ])
+ })
+
+ it('warns once per routed target when absolute retention exceeds its resolved threshold', async () => {
+ const ctx = createContext()
+ const warnings: string[] = []
+ ctx.logger.warn = ((message: string) => void warnings.push(message)) as typeof ctx.logger.warn
+ void new TestCompactService(ctx, {
+ thresholdRatio: 0.5,
+ retainTokens: 500,
+ })
+ const session = conversation(4)
+
+ await postStep(ctx, agent(session, MODEL))
+ await postStep(ctx, agent(session, MODEL))
+
+ expect(warnings).toEqual([
+ expect.stringContaining('retainTokens (500) must be less than threshold tokens 500'),
+ ])
+ })
+
it('force-compacts below normal pressure for canonical overflow and retries only after replacement', async () => {
const ctx = createContext(10_000)
void new TestCompactService(ctx, {
@@ -1184,6 +1465,18 @@ describe('automatic listener and loader composition', () => {
.toEqual({ action: 'retry' })
})
+ it('delegates canonical overflow when no durable routed target exists', async () => {
+ const ctx = createContext()
+ void new TestCompactService(ctx)
+ const session = new Session(SessionId('headerless-overflow'))
+ session.append('turn/start', {
+ turn: 1,
+ trigger: { kind: 'message', source: { kind: 'user' } },
+ })
+
+ await expect(recover(ctx, agent(session, MODEL), overflow())).resolves.toEqual({ action: 'fail' })
+ })
+
it('honors retry caps, non-context failures, and cancellation', async () => {
const ctx = createContext()
const compact = new TestCompactService(ctx, { maxOverflowRetries: 1 })
@@ -1199,6 +1492,23 @@ describe('automatic listener and loader composition', () => {
expect(compactSpy).not.toHaveBeenCalled()
})
+ it('applies the routed model override to the overflow retry cap', async () => {
+ const ctx = createContext()
+ const compact = new TestCompactService(ctx, {
+ maxOverflowRetries: 2,
+ modelPolicies: [{
+ provider: MODEL,
+ model: MODEL,
+ maxOverflowRetries: 1,
+ }],
+ })
+ const compactSpy = vi.spyOn(compact, 'compactIfNeeded')
+
+ expect(await recover(ctx, agent(conversation(3), MODEL), overflow(), 1))
+ .toEqual({ action: 'fail' })
+ expect(compactSpy).not.toHaveBeenCalled()
+ })
+
it('does not retry when cancellation lands during an awaited compaction', async () => {
const ctx = createContext()
const compact = new TestCompactService(ctx)
@@ -1246,7 +1556,6 @@ describe('automatic listener and loader composition', () => {
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()
@@ -1257,7 +1566,7 @@ describe('automatic listener and loader composition', () => {
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 })
+ await ctx.plugin(TokenMeterService)
const fiber = await ctx.plugin(TestCompactService, {
thresholdRatio: 0.5,
retainTokens: 180,
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 273bfb3987..1ac28969c0 100644
--- a/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
+++ b/packages/compact/compact-basic/tests/compact-loop-repro.spec.ts
@@ -8,7 +8,10 @@ import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
import type { Agent } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
import TokenMeterService from '@deepseek-ai/dsh-token-meter'
import * as LlmRetry from '@deepseek-ai/dsh-llm-retry'
@@ -38,6 +41,10 @@ class StepwiseToolAdapter extends LlmAdapter {
super()
}
+ override resolveModelContext(): Promise<{ contextWindow: number }> {
+ return Promise.resolve({ contextWindow: 400 })
+ }
+
async * stream(_options: GenerateOptions): AsyncIterable {
const n = this.calls
this.calls += 1
@@ -69,6 +76,10 @@ class OverflowRecoveryAdapter extends LlmAdapter {
super()
}
+ override resolveModelContext(): Promise<{ contextWindow: number }> {
+ return Promise.resolve({ contextWindow: 128 })
+ }
+
override async * stream(options: GenerateOptions): AsyncIterable {
if (options.system?.includes('You are a compaction engine')) {
this.summaryRequests.push(options)
@@ -104,12 +115,19 @@ class OverflowRecoveryAdapter extends LlmAdapter {
}
}
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
async function harness(toolSteps: number): Promise<{ ctx: Context; compact: ReproCompactService }> {
const ctx = new Context()
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(TokenMeterService, { contextWindow: 400 })
+ await ctx.plugin(TokenMeterService)
ctx.llm.registerAdapter(['mock'], new StepwiseToolAdapter(toolSteps))
ctx.tools.register(defineContentToolFixture({
name: 'work',
@@ -125,7 +143,6 @@ async function harness(toolSteps: number): Promise<{ ctx: Context; compact: Repr
auto: true,
thresholdRatio: 0.5,
retainTokens: 50,
- summarizationModel: '',
maxTokens: 8192,
compactionRetries: 1,
})
@@ -255,9 +272,9 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
const ctx = new Context()
const adapter = new OverflowRecoveryAdapter(delivery)
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(TokenMeterService, { contextWindow: 128 })
+ await ctx.plugin(TokenMeterService)
ctx.llm.registerAdapter(['mock'], adapter)
ctx.on('agent/request', async (_agent, _turn, _step, config) => ({ ...config, provider: 'mock', model: 'mock' }))
await ctx.plugin(BasicCompactService, {
@@ -317,7 +334,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
const ctx = new Context()
const adapter = new OverflowRecoveryAdapter('thrown', true)
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(LlmRetry, {
maxTransientRetries: 1,
initialDelayMs: 1,
@@ -325,7 +342,7 @@ describe('context-overflow recovery across the real loop and compact-basic', ()
jitterRatio: 0,
})
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(TokenMeterService, { contextWindow: 128 })
+ await ctx.plugin(TokenMeterService)
ctx.llm.registerAdapter(['mock'], adapter)
await ctx.plugin(BasicCompactService, {
thresholdRatio: 1,
diff --git a/packages/compact/compact-basic/tests/loader-composition.spec.ts b/packages/compact/compact-basic/tests/loader-composition.spec.ts
index 2035627f64..74f8423e52 100644
--- a/packages/compact/compact-basic/tests/loader-composition.spec.ts
+++ b/packages/compact/compact-basic/tests/loader-composition.spec.ts
@@ -56,8 +56,6 @@ describe('real Loader composition', () => {
const loaded = await loadYaml([
"- name: '@deepseek-ai/dsh-llm'",
"- name: '@deepseek-ai/dsh-token-meter'",
- ' config:',
- ' contextWindow: 4096',
"- name: '@deepseek-ai/dsh-compact-tool-result-prune'",
' config:',
' thresholdChars: 100',
@@ -66,7 +64,7 @@ describe('real Loader composition', () => {
"- name: '@deepseek-ai/dsh-compact-basic'",
' config:',
' thresholdRatio: 0.5',
- ' retainTokens: 512',
+ ' retainRatio: 0.125',
' auto: false',
])
@@ -74,12 +72,11 @@ describe('real Loader composition', () => {
.filter(entry => entry.fiber === undefined && !entry.disabled)
.map(entry => entry.options.name)
expect(unloaded).toEqual([])
- expect(loaded.tokenMeter.contextWindow).toBe(4096)
expect(loaded.get('toolResultPrune')).toBeInstanceOf(ToolResultPruneService)
expect(loaded.get('compact')).toBeInstanceOf(BasicCompactService)
expect((loaded.compact as BasicCompactService).config).toMatchObject({
thresholdRatio: 0.5,
- retainTokens: 512,
+ retainRatio: 0.125,
auto: false,
})
})
@@ -87,8 +84,8 @@ describe('real Loader composition', () => {
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"/)
+ contextWindow: 4096,
+ } as never)).rejects.toThrow(/TokenMeterConfig: unknown key "contextWindow"/)
})
it('rejects stale compact-basic config after Schemastery normalization', async () => {
@@ -99,4 +96,33 @@ describe('real Loader composition', () => {
models: { legacy: { thresholdRatio: 0.5 } },
} as never)).rejects.toThrow(/BasicCompactConfig: unknown key "models"/)
})
+
+ it('rejects a capacity-independent merged ratio conflict during plugin load', async () => {
+ context = new Context()
+ await context.plugin(LlmService)
+ await context.plugin(TokenMeterService)
+ await expect(context.plugin(BasicCompactService, {
+ retainRatio: 0.2,
+ modelPolicies: [{
+ provider: 'test-provider',
+ model: 'test-model',
+ thresholdRatio: 0.1,
+ }],
+ })).rejects.toThrow(/modelPolicies\[0\]: retainRatio \(0.2\).*thresholdRatio \(0.1\)/)
+ })
+
+ it('rejects an incomplete model-policy summarization pair during plugin load', async () => {
+ context = new Context()
+ await context.plugin(LlmService)
+ await context.plugin(TokenMeterService)
+ await expect(context.plugin(BasicCompactService, {
+ summarizationProvider: 'default-provider',
+ summarizationModel: 'default-model',
+ modelPolicies: [{
+ provider: 'test-provider',
+ model: 'test-model',
+ summarizationModel: '',
+ }],
+ })).rejects.toThrow(/modelPolicies\[0\].*must be set together/)
+ })
})
diff --git a/packages/compact/compact-basic/tsconfig.json b/packages/compact/compact-basic/tsconfig.json
index 47d552c3f0..bd1a440119 100644
--- a/packages/compact/compact-basic/tsconfig.json
+++ b/packages/compact/compact-basic/tsconfig.json
@@ -6,14 +6,35 @@
},
"include": ["src"],
"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" },
- { "path": "../compact-tool-result-prune" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../llm/token-meter"
+ },
+ {
+ "path": "../../core/session"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../compact"
+ },
+ {
+ "path": "../../support/invariants"
+ },
+ {
+ "path": "../compact-tool-result-prune"
+ }
]
}
diff --git a/packages/compact/compact-tool-result-prune/package.json b/packages/compact/compact-tool-result-prune/package.json
index 81c81eb894..7cd9ff6b98 100644
--- a/packages/compact/compact-tool-result-prune/package.json
+++ b/packages/compact/compact-tool-result-prune/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/compact/compact-tool-result-prune/src/invariant.ts b/packages/compact/compact-tool-result-prune/src/invariant.ts
new file mode 100644
index 0000000000..8c2b0a1133
--- /dev/null
+++ b/packages/compact/compact-tool-result-prune/src/invariant.ts
@@ -0,0 +1,27 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-compact-tool-result-prune`.
+ * @module @deepseek-ai/dsh-compact-tool-result-prune/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-compact-tool-result-prune'
+
+/** Cordis companion plugin name. */
+export const name = 'compact-tool-result-prune-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** No runtime invariant: Session validates each content-only rewrite and its companion owns cross-event enclosure. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
index bc382c8e4e..6c308665fd 100644
--- a/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
+++ b/packages/compact/compact-tool-result-prune/tests/tool-result-prune.spec.ts
@@ -4,7 +4,8 @@ import { CallId } from '@deepseek-ai/dsh-llm'
import type { ContentBlock } from '@deepseek-ai/dsh-llm'
import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
import type { SurfaceEvent } from '@deepseek-ai/dsh-session'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
import ToolResultPruneService, {
codePointLength,
DEFAULTS,
@@ -225,7 +226,8 @@ describe('ToolResultPruneService session transaction', () => {
it('runs under real invariants between closed steps but not outside a turn', async () => {
const ctx = new Context()
await ctx.plugin(SessionStore)
- await ctx.plugin(Invariants)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
const prune = new ToolResultPruneService(ctx, SMALL)
const session = ctx.sessions.create(SessionId('invariants'))
appendToolStep(session, 1, 'a', [{ type: 'text', text: 'A'.repeat(100) }])
diff --git a/packages/compact/compact-tool-result-prune/tsconfig.json b/packages/compact/compact-tool-result-prune/tsconfig.json
index e021fa336e..a6c2e5124b 100644
--- a/packages/compact/compact-tool-result-prune/tsconfig.json
+++ b/packages/compact/compact-tool-result-prune/tsconfig.json
@@ -10,6 +10,7 @@
{ "path": "../../../vendor/cordis" },
{ "path": "../../../vendor/schemastery" },
{ "path": "../../llm/llm" },
- { "path": "../../core/session" }
+ { "path": "../../core/session" },
+ { "path": "../../support/invariants" }
]
}
diff --git a/packages/compact/compact/package.json b/packages/compact/compact/package.json
index 985c42d3b2..135c688507 100644
--- a/packages/compact/compact/package.json
+++ b/packages/compact/compact/package.json
@@ -11,22 +11,29 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/compact/compact/src/invariant.ts b/packages/compact/compact/src/invariant.ts
new file mode 100644
index 0000000000..da5d5eba5a
--- /dev/null
+++ b/packages/compact/compact/src/invariant.ts
@@ -0,0 +1,111 @@
+/** Package-owned compaction log-stream invariants. @module @deepseek-ai/dsh-compact/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type {} from './types.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-compact'
+
+/** Cordis companion plugin name. */
+export const name = 'compact-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+interface CompactionTrace {
+ turn: number
+ summarized: boolean
+}
+
+type CompactionTransition =
+ | { kind: 'start'; turn: number }
+ | { kind: 'summary'; turn: number }
+ | { kind: 'end' }
+
+/** Validate one compaction event without advancing committed trace state. */
+function validateCompactionEvent(
+ open: CompactionTrace | undefined,
+ event: SessionEvent,
+ fail: InvariantFailure,
+): CompactionTransition | undefined {
+ if (event.type === 'compact/start') {
+ if (open !== undefined) fail(`compact/start for turn ${event.data.turn} while turn ${open.turn} is still compacting`)
+ return { kind: 'start', turn: event.data.turn }
+ }
+ if (event.type === 'compact/summary') {
+ if (open === undefined) fail('compact/summary has no matching compact/start')
+ if (open.summarized) fail('compact/summary repeated within one compaction')
+ const seqs = event.data.shadowedSeqs
+ if (seqs.length === 0) fail('compact/summary shadowedSeqs must be non-empty')
+ if (seqs[0] !== event.data.shadowedRange.start || seqs.at(-1) !== event.data.shadowedRange.end) {
+ fail('compact/summary shadowedRange must match the first and last shadowedSeqs')
+ }
+ if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
+ fail('compact/summary shadowedTokenCount must be a non-negative safe integer')
+ }
+ return { kind: 'summary', turn: open.turn }
+ }
+ if (event.type !== 'compact/end') return undefined
+ if (open === undefined) fail('compact/end has no matching compact/start')
+ if (event.data.turn !== open.turn) {
+ fail(`compact/end turn ${event.data.turn} does not match compact/start turn ${open.turn}`)
+ }
+ if (event.data.error === undefined && !open.summarized) {
+ fail('successful compact/end requires one compact/summary')
+ }
+ return { kind: 'end' }
+}
+
+/** Apply one committed compaction transition. */
+function applyCompactionTransition(
+ transition: CompactionTransition,
+): CompactionTrace | undefined {
+ if (transition.kind === 'start') return { turn: transition.turn, summarized: false }
+ if (transition.kind === 'summary') return { turn: transition.turn, summarized: true }
+ return undefined
+}
+
+/** Install compaction start/summary/end checks. */
+// Event owners keep precommit staging local so their vocabularies never move into a central helper.
+/* jscpd:ignore-start */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ const traces = new WeakMap()
+ const staged = new WeakMap()
+ const seed = (session: Session): void => {
+ let open: CompactionTrace | undefined
+ for (const event of session.events) {
+ const transition = validateCompactionEvent(open, event, fail)
+ if (transition !== undefined) open = applyCompactionTransition(transition)
+ }
+ if (open !== undefined) traces.set(session, open)
+ }
+ const traceFor = (session: Session): CompactionTrace | undefined => traces.get(session)
+
+ for (const session of ctx.sessions.list()) seed(session)
+ ctx.on('session/created', (session) => { seed(session) }, { global: true })
+ ctx.on('session/event', (session, event) => {
+ if (event.type !== 'compact/start' && event.type !== 'compact/summary' && event.type !== 'compact/end') return
+ const candidate = staged.get(event)
+ /* v8 ignore next -- internal/dispatch stages every compaction event */
+ if (candidate === undefined || candidate.session !== session) return fail('compaction event published without pre-commit validation')
+ staged.delete(event)
+ const next = applyCompactionTransition(candidate.transition)
+ if (next === undefined) traces.delete(session)
+ else traces.set(session, next)
+ }, { global: true })
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ const transition = validateCompactionEvent(traceFor(session), event, fail)
+ if (transition !== undefined) staged.set(event, { session, transition })
+ }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the compact invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/compact/compact/tests/compact.spec.ts b/packages/compact/compact/tests/compact.spec.ts
index 559d46bdc9..1ff03bdfb1 100644
--- a/packages/compact/compact/tests/compact.spec.ts
+++ b/packages/compact/compact/tests/compact.spec.ts
@@ -38,7 +38,7 @@ class StubCompactService extends CompactService {
const summaryEvent = session.append('compact/summary', {
summary,
shadowedRange: { start, end },
- shadowedSeqs: [],
+ shadowedSeqs: [start],
shadowedTokenCount: 0,
provider: 'mock',
model: 'stub',
@@ -50,7 +50,7 @@ class StubCompactService extends CompactService {
endSeq: endEvent.seq,
summary,
shadowedRange: { start, end },
- shadowedSeqs: [],
+ shadowedSeqs: [start],
shadowedTokenCount: 0,
}
}
diff --git a/packages/compact/compact/tests/invariant.spec.ts b/packages/compact/compact/tests/invariant.spec.ts
new file mode 100644
index 0000000000..2f4d10ff71
--- /dev/null
+++ b/packages/compact/compact/tests/invariant.spec.ts
@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore from '@deepseek-ai/dsh-session'
+import * as CompactInvariant from '@deepseek-ai/dsh-compact/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(CompactInvariant)
+ return ctx
+}
+
+const summary = (overrides: Record = {}) => ({
+ summary: [{ type: 'text' as const, text: 'short' }],
+ shadowedRange: { start: 2, end: 4 },
+ shadowedSeqs: [2, 3, 4],
+ shadowedTokenCount: 12,
+ provider: 'mock',
+ model: 'mock',
+ ...overrides,
+})
+
+describe('compaction invariants', () => {
+ it('accepts successful and failed compaction lifecycles', async () => {
+ const ctx = await setup()
+ const success = ctx.sessions.create()
+ success.append('compact/start', { turn: 1 })
+ success.append('compact/summary', summary())
+ success.append('compact/end', { turn: 1 })
+
+ const failed = ctx.sessions.create()
+ failed.append('compact/start', { turn: 2 })
+ failed.append('compact/end', { turn: 2, error: 'provider failed' })
+ })
+
+ it('rebuilds an open trace when the companion loads after the session', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create()
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('compact/start', { turn: 3 })
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(CompactInvariant)
+ expect(() => session.append('compact/end', { turn: 3, error: 'resume failed' })).not.toThrow()
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ })
+
+ it.each([
+ ['summary without start', (session: ReturnType) => {
+ session.append('compact/summary', summary())
+ }, /no matching compact\/start/],
+ ['nested start', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/start', { turn: 2 })
+ }, /still compacting/],
+ ['repeated summary', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/summary', summary())
+ session.append('compact/summary', summary())
+ }, /repeated within one compaction/],
+ ['empty shadow set', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/summary', summary({ shadowedSeqs: [] }))
+ }, /shadowedSeqs must be non-empty/],
+ ['wrong endpoints', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/summary', summary({ shadowedRange: { start: 1, end: 4 } }))
+ }, /shadowedRange must match/],
+ ['invalid token count', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/summary', summary({ shadowedTokenCount: -1 }))
+ }, /non-negative safe integer/],
+ ['end without start', (session: ReturnType) => {
+ session.append('compact/end', { turn: 1, error: 'failed' })
+ }, /no matching compact\/start/],
+ ['wrong end turn', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/end', { turn: 2, error: 'failed' })
+ }, /does not match/],
+ ['success without summary', (session: ReturnType) => {
+ session.append('compact/start', { turn: 1 })
+ session.append('compact/end', { turn: 1 })
+ }, /requires one compact\/summary/],
+ ])('rejects %s', async (_name, action, message) => {
+ const ctx = await setup()
+ expect(() => { action(ctx.sessions.create()) }).toThrow(message)
+ })
+})
diff --git a/packages/compact/compact/tsconfig.json b/packages/compact/compact/tsconfig.json
index 95245937ec..673ee51547 100644
--- a/packages/compact/compact/tsconfig.json
+++ b/packages/compact/compact/tsconfig.json
@@ -19,6 +19,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/context/time-context/README.md b/packages/context/time-context/README.md
index dc79fb6d23..2327da81b2 100644
--- a/packages/context/time-context/README.md
+++ b/packages/context/time-context/README.md
@@ -26,6 +26,8 @@ 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 separately published `./invariant` companion checks each plugin-attributed reading against the open turn, next pre-step position, elapsed baseline, and durable event time. Its rendered timestamp must parse and cannot postdate the event; process suspension between sampling and append does not invalidate the reading.
+
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 c0d69a75cb..2b3ad9fca6 100644
--- a/packages/context/time-context/package.json
+++ b/packages/context/time-context/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -26,12 +31,15 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
+ "@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-loader-smoke": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/context/time-context/src/invariant.ts b/packages/context/time-context/src/invariant.ts
new file mode 100644
index 0000000000..45fdb48cba
--- /dev/null
+++ b/packages/context/time-context/src/invariant.ts
@@ -0,0 +1,114 @@
+/** Package-owned durable clock-context invariants. @module @deepseek-ai/dsh-time-context/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-time-context'
+const SOURCE_NAME = 'time-context'
+const READING = new RegExp(
+ '^Time sampled while preparing turn (\\d+), step (\\d+): '
+ + '(\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:Z|[+-]\\d{2}:\\d{2})\\[[^\\]]+\\])\\n'
+ + 'Elapsed since the preceding (model-visible message|step context): '
+ + '(?:unavailable|(?:(?:\\d+d )?(?:\\d+h )?(?:\\d+m )?\\d+s))\\.$',
+)
+
+/** Cordis companion plugin name. */
+export const name = 'time-context-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Derive the pre-step position at which a time-context reading may append. */
+function preparationPosition(history: readonly SessionEvent[], fail: InvariantFailure): { turn: number; step: number } {
+ const currentTurnEvents: SessionEvent[] = []
+ let openTurn: number | undefined
+ for (const event of history.slice().reverse()) {
+ if (event.type === 'turn/end') {
+ fail('time-context reading must be appended inside an open turn')
+ }
+ if (event.type === 'turn/start') {
+ openTurn = event.data.turn
+ break
+ }
+ currentTurnEvents.push(event)
+ }
+ if (openTurn === undefined) fail('time-context reading must be appended inside an open turn')
+
+ for (const event of currentTurnEvents) {
+ if (event.type === 'step/start') {
+ fail(`time-context reading must precede step/start, but step ${event.data.step} is already open`)
+ }
+ if (event.type === 'step/end') {
+ return { turn: openTurn, step: event.data.step + 1 }
+ }
+ }
+ return { turn: openTurn, step: 1 }
+}
+
+/** Validate one plugin-attributed time reading against its session position and timestamp. */
+function validateReading(
+ history: readonly SessionEvent[],
+ event: SessionEvent<'context/message'>,
+ fail: InvariantFailure,
+): void {
+ const [block] = event.data.content
+ if (event.data.content.length !== 1 || block?.type !== 'text') {
+ fail('time-context messages must contain exactly one text block')
+ }
+ const match = READING.exec(block.text)
+ if (match === null) fail('time-context message does not match the durable reading format')
+ const turn = Number(match[1])
+ const step = Number(match[2])
+ if (!Number.isSafeInteger(turn) || turn < 1 || !Number.isSafeInteger(step) || step < 1) {
+ fail('time-context turn and step must be positive safe integers')
+ }
+ const expected = preparationPosition(history, fail)
+ if (turn !== expected.turn || step !== expected.step) {
+ fail(`time-context reading names turn ${turn}/step ${step}, expected turn ${expected.turn}/step ${expected.step}`)
+ }
+ const baseline = match[4]
+ if ((step === 1) !== (baseline === 'model-visible message')) {
+ fail(`time-context step ${step} uses the wrong elapsed-time baseline ${JSON.stringify(baseline)}`)
+ }
+ const rendered = match[3]
+ /* v8 ignore next -- the preceding fixed regexp always supplies capture group three. */
+ if (rendered === undefined) fail('time-context reading omitted its rendered timestamp')
+ const renderedTime = Date.parse(rendered.replace(/\[[^\]]+\]$/, ''))
+ if (!Number.isFinite(renderedTime) || !Number.isSafeInteger(event.time)
+ || event.time < renderedTime) {
+ fail('time-context rendered timestamp must parse and not postdate its durable event')
+ }
+}
+
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate all package-owned readings already present in one session. */
+function validateSession(session: Session, fail: InvariantFailure): void {
+ for (const [index, event] of session.events.entries()) {
+ if (event.type !== 'context/message'
+ || event.data.source.kind !== 'plugin'
+ || event.data.source.plugin !== SOURCE_NAME) continue
+ validateReading(session.events.slice(0, index), event, fail)
+ }
+}
+
+/** Install validation for loaded and newly appended context readings. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ for (const session of ctx.sessions.list()) validateSession(session, fail)
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ if (event.type !== 'context/message'
+ || event.data.source.kind !== 'plugin'
+ || event.data.source.plugin !== SOURCE_NAME) return
+ validateReading(session.events, event, fail)
+ }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the time-context invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts
new file mode 100644
index 0000000000..5da942603f
--- /dev/null
+++ b/packages/context/time-context/tests/invariant.spec.ts
@@ -0,0 +1,177 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
+import SessionStore, { Session, SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import * as TimeInvariant from '@deepseek-ai/dsh-time-context/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+const SECOND = Date.parse('2026-07-14T00:00:00Z')
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(TimeInvariant)
+ return ctx
+}
+
+function event(text: string, time = SECOND + 456, content?: unknown[]): SessionEvent {
+ return {
+ type: 'context/message',
+ seq: 0,
+ time,
+ data: {
+ content: (content ?? [{ type: 'text', text }]) as ContentBlock[],
+ source: { kind: 'plugin', plugin: 'time-context' },
+ },
+ }
+}
+
+function reading(
+ turn = '1',
+ step = '1',
+ baseline = 'model-visible message',
+ timestamp = '2026-07-14T00:00:00+00:00[UTC]',
+): string {
+ return `Time sampled while preparing turn ${turn}, step ${step}: ${timestamp}\n`
+ + `Elapsed since the preceding ${baseline}: unavailable.`
+}
+
+function preparing(turn: number, step: number): Session {
+ const session = new Session(SessionId(`time-invariant-${turn}-${step}`))
+ for (let priorTurn = 1; priorTurn < turn; priorTurn += 1) {
+ session.append('turn/start', { turn: priorTurn, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/end', { turn: priorTurn, reason: { kind: 'completed' } })
+ }
+ session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', {
+ content: [{ type: 'text', text: `turn ${turn}` }],
+ source: { kind: 'user' },
+ }, { surfaceOp: 'append' })
+ for (let priorStep = 1; priorStep < step; priorStep += 1) {
+ session.append('step/start', { turn, step: priorStep })
+ session.append('step/end', { turn, step: priorStep })
+ }
+ return session
+}
+
+function appendReading(session: Session, text: string): void {
+ session.append('context/message', {
+ content: [{ type: 'text', text }],
+ source: { kind: 'plugin', plugin: 'time-context' },
+ }, { surfaceOp: 'append' })
+}
+
+describe('time-context invariants', () => {
+ it('accepts a reading whose turn, step, baseline, and timestamp agree', async () => {
+ const ctx = await setup()
+ const text = 'Time sampled while preparing turn 2, step 3: 2026-07-14T00:00:00+00:00[UTC]\n'
+ + 'Elapsed since the preceding step context: 4m 2s.'
+ expect(() => { ctx.emit('session/event', preparing(2, 3), event(text)) }).not.toThrow()
+ })
+
+ it('accepts a reading durably appended after a long process pause', async () => {
+ const ctx = await setup()
+ expect(() => {
+ ctx.emit('session/event', preparing(1, 1), event(reading(), SECOND + 60_000))
+ }).not.toThrow()
+ })
+
+ it('validates each existing reading against its preceding durable prefix', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create(SessionId('time-invariant-late-valid'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'prepare' }],
+ source: { kind: 'user' },
+ }, { surfaceOp: 'append' })
+ appendReading(session, reading())
+ session.append('step/start', { turn: 1, step: 1 })
+
+ await ctx.plugin(InvariantService, { enabled: true })
+ await expect(ctx.plugin(TimeInvariant)).resolves.toBeDefined()
+ })
+
+ it('rejects an invalid existing reading on late registration', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create(SessionId('time-invariant-late-invalid'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'prepare' }],
+ source: { kind: 'user' },
+ }, { surfaceOp: 'append' })
+ appendReading(session, reading('1', '2', 'step context'))
+
+ await ctx.plugin(InvariantService, { enabled: true })
+ await expect(ctx.plugin(TimeInvariant).then(() => undefined)).rejects.toThrow(/expected turn 1\/step 1/)
+ })
+
+ it.each([
+ [reading('1', '3', 'step context'), /expected turn 2\/step 3/],
+ [reading('2', '2', 'step context'), /expected turn 2\/step 3/],
+ ])('rejects a reading that disagrees with its session position', async (text, message) => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('session/event', preparing(2, 3), event(text)) }).toThrow(message)
+ })
+
+ it('rejects a reading after cancellation closes the turn', async () => {
+ const ctx = await setup()
+ const session = preparing(1, 2)
+ session.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: 'cancelled' } })
+ expect(() => { ctx.emit('session/event', session, event(reading('1', '2', 'step context'))) })
+ .toThrow(/inside an open turn/)
+ })
+
+ it('rejects a reading after step/start or without any open turn', async () => {
+ const ctx = await setup()
+ const started = preparing(1, 1)
+ started.append('step/start', { turn: 1, step: 1 })
+ expect(() => { ctx.emit('session/event', started, event(reading())) }).toThrow(/must precede step\/start/)
+ expect(() => {
+ ctx.emit('session/event', new Session(SessionId('time-invariant-empty')), event(reading()))
+ }).toThrow(/inside an open turn/)
+ })
+
+ it.each([
+ ['not a reading', SECOND, undefined, /durable reading format/],
+ [reading('0'), SECOND, undefined, /positive safe integers/],
+ [reading('999999999999999999999'), SECOND, undefined, /positive safe integers/],
+ [reading('1', '0', 'step context'), SECOND, undefined, /positive safe integers/],
+ [reading('1', '999999999999999999999', 'step context'), SECOND, undefined, /positive safe integers/],
+ [reading('1', '1', 'step context'), SECOND, undefined, /wrong elapsed-time baseline/],
+ [reading('1', '2', 'model-visible message'), SECOND, undefined, /wrong elapsed-time baseline/],
+ [reading('1', '1', 'model-visible message', '2026-99-99T00:00:00+00:00[UTC]'), SECOND, undefined, /must parse and not postdate/],
+ [reading(), Number.NaN, undefined, /must parse and not postdate/],
+ [reading(), SECOND - 1, undefined, /must parse and not postdate/],
+ ['ignored', SECOND, [], /exactly one text block/],
+ ['ignored', SECOND, [{ type: 'image', data: 'x', mimeType: 'image/png' }], /exactly one text block/],
+ ['ignored', SECOND, [{ type: 'text', text: 'one' }, { type: 'text', text: 'two' }], /exactly one text block/],
+ ] as const)('rejects an incoherent durable reading', async (text, time, content, message) => {
+ const ctx = await setup()
+ const preparationStep = text.includes('turn 1, step 2:') ? 2 : 1
+ expect(() => {
+ ctx.emit('session/event', preparing(1, preparationStep), event(
+ text,
+ time,
+ content === undefined ? undefined : [...content],
+ ))
+ }).toThrow(message)
+ })
+
+ it('ignores context messages owned by another package', async () => {
+ const ctx = await setup()
+ const other = event('unrelated') as SessionEvent<'context/message'>
+ other.data.source = { kind: 'plugin', plugin: 'other' }
+ expect(() => { ctx.emit('session/event', preparing(1, 1), other) }).not.toThrow()
+ other.data.source = { kind: 'user' }
+ expect(() => { ctx.emit('session/event', preparing(1, 1), other) }).not.toThrow()
+ expect(() => {
+ ctx.emit('session/event', preparing(1, 1), {
+ type: 'turn/start', seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+ })
+ ctx.emit('tools/change')
+ }).not.toThrow()
+ })
+})
diff --git a/packages/context/time-context/tests/time-context.spec.ts b/packages/context/time-context/tests/time-context.spec.ts
index d69a7bb2ed..c25a2fae37 100644
--- a/packages/context/time-context/tests/time-context.spec.ts
+++ b/packages/context/time-context/tests/time-context.spec.ts
@@ -4,8 +4,7 @@ import Loader from '@cordisjs/plugin-loader'
import { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
import { Session, SessionId } from '@deepseek-ai/dsh-session'
-import AgentRegistry from '@deepseek-ai/dsh-agent'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
@@ -83,7 +82,7 @@ async function fire(
step: number,
signal: AbortSignal = SIGNAL,
): Promise {
- await ctx.serial('agent/pre-step', agent, turn, step, signal)
+ await agentEvents(ctx, agent).serial('agent/pre-step', turn, step, signal)
}
function textResponse(text: string): StreamChunk[] {
diff --git a/packages/context/time-context/tsconfig.json b/packages/context/time-context/tsconfig.json
index 7815242b55..3f3c553e98 100644
--- a/packages/context/time-context/tsconfig.json
+++ b/packages/context/time-context/tsconfig.json
@@ -6,13 +6,35 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../llm/llm" },
- { "path": "../../core/agent" },
- { "path": "../../core/system-prompt" },
- { "path": "../../core/agent" },
- { "path": "../../support/loader-smoke" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../../core/system-prompt"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../../support/loader-smoke"
+ },
+ {
+ "path": "../../support/invariants"
+ },
+ {
+ "path": "../../core/session"
+ }
]
}
diff --git a/packages/context/workspace-context/package.json b/packages/context/workspace-context/package.json
index 7f704c838a..0c50b8cc17 100644
--- a/packages/context/workspace-context/package.json
+++ b/packages/context/workspace-context/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-fs": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-paths": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -39,6 +45,7 @@
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-fs": "workspace:^",
"@deepseek-ai/dsh-fs-local": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-deepseek": "workspace:^",
"@deepseek-ai/dsh-paths": "workspace:^",
diff --git a/packages/context/workspace-context/src/invariant.ts b/packages/context/workspace-context/src/invariant.ts
new file mode 100644
index 0000000000..d9f56417b8
--- /dev/null
+++ b/packages/context/workspace-context/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-workspace-context`.
+ * @module @deepseek-ai/dsh-workspace-context/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-workspace-context'
+
+/** Cordis companion plugin name. */
+export const name = 'workspace-context-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: replay intentionally tolerates unknown or malformed workspace metadata,
+ * while focused pipeline tests own its private pending/cache state transitions.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/context/workspace-context/tests/workspace-context.spec.ts b/packages/context/workspace-context/tests/workspace-context.spec.ts
index f87bf4f5c3..2dd1af6417 100644
--- a/packages/context/workspace-context/tests/workspace-context.spec.ts
+++ b/packages/context/workspace-context/tests/workspace-context.spec.ts
@@ -7,8 +7,9 @@ import Loader from '@cordisjs/plugin-loader'
import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
import LlmService, { CallId, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
import SessionStore, { Session, SessionId, SESSION_FORMAT_VERSION, type SessionEvent } from '@deepseek-ai/dsh-session'
-import AgentRegistry, { type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { agentEvents, type Agent, type HookContext } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
import { FileSystem, FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
import type {
FsDirEntry,
@@ -23,7 +24,12 @@ import type {
import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
-import type { ToolExecution, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+import type {
+ PostToolDecision,
+ ToolExecution,
+ ToolExecutionResult,
+ ToolExecutionToken,
+} from '@deepseek-ai/dsh-tools'
import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
import {
discoverBaselineInstructionFiles,
@@ -225,14 +231,31 @@ const composedPrefixes = new WeakMap()
async function composeBaselinePrefix(ctx: Context, agent: Agent): Promise {
const empty: Message[] = []
- const prefix = await ctx.waterfall(
- 'agent/session-prefix', agent, empty, AbortSignal.timeout(1000),
+ const prefix = await agentEvents(ctx, agent).waterfall(
+ 'agent/session-prefix', empty, AbortSignal.timeout(1000),
() => Promise.resolve(empty),
)
composedPrefixes.set(agent, prefix)
return prefix
}
+function toolEventCarrier(ctx: Context, exec: ToolExecution) {
+ return scopeTarget(ctx.get('tools') ?? ctx as unknown as ToolRegistry, exec.agent)
+}
+
+function postExecute(
+ ctx: Context,
+ exec: ToolExecution,
+ result: Readonly,
+ next: () => Promise,
+): Promise {
+ return ctx.waterfall(toolEventCarrier(ctx, exec), 'tools/post-execute', exec, result, next)
+}
+
+function emitToolResult(ctx: Context, exec: ToolExecution, result: Readonly): void {
+ ctx.emit(toolEventCarrier(ctx, exec), 'tools/result', exec, result)
+}
+
function derivedText(agent: Agent): string {
return blocksText(composedPrefixes.get(agent)?.[0]?.content)
}
@@ -795,7 +818,7 @@ describe('workspace context request injection', () => {
try {
await ctx.plugin(workspaceContext, { maxBytes: 65536 })
- const decision = await ctx.waterfall('tools/post-execute', stubToolExecution({
+ const decision = await postExecute(ctx, stubToolExecution({
callId: CallId('no-fs-post-execute'),
name: 'read',
arguments: { file_path: 'pkg/file.txt' },
@@ -844,7 +867,7 @@ describe('workspace context request injection', () => {
}
// A later PostToolUse-style policy blocks this otherwise-successful read.
- const blocked = await ctx.waterfall('tools/post-execute', exec, result, async () => ({
+ const blocked = await postExecute(ctx, exec, result, async () => ({
kind: 'block' as const,
feedback: [{ type: 'text' as const, text: 'blocked by policy' }],
}))
@@ -858,7 +881,7 @@ describe('workspace context request injection', () => {
// The same read, when the downstream accepts, DOES surface the nested
// instructions — proving the block branch above is what suppressed them,
// and that the block did not consume the pending nested change.
- const accepted = await ctx.waterfall('tools/post-execute', exec, result, async () => ({
+ const accepted = await postExecute(ctx, exec, result, async () => ({
kind: 'accept' as const,
}))
expect(accepted.kind).toBe('accept')
@@ -1170,8 +1193,9 @@ describe('workspace context request injection', () => {
const controller = new AbortController()
const reason = new Error('cancel prefix')
const empty: Message[] = []
- const pending = ctx.waterfall(
- 'agent/session-prefix', stubAgent(root), empty, controller.signal,
+ const agent = stubAgent(root)
+ const pending = agentEvents(ctx, agent).waterfall(
+ 'agent/session-prefix', empty, controller.signal,
() => Promise.resolve(empty),
)
@@ -1661,7 +1685,7 @@ describe('dynamic nested workspace context injection', () => {
signal: controller.signal,
})
- const pending = ctx.waterfall('tools/post-execute', exec, {
+ const pending = postExecute(ctx, exec, {
content: [{ type: 'text', text: 'ok' }],
isError: false,
value: null,
@@ -2389,12 +2413,12 @@ describe('dynamic nested workspace context injection', () => {
value: null,
}
- const failedStat = await ctx.waterfall('tools/post-execute', stubToolExecution({
+ const failedStat = await postExecute(ctx, stubToolExecution({
callId: CallId('provider-stat-failure'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent,
}), result, async () => ({ kind: 'accept' as const }))
fs.throwOnStat.clear()
fs.entries.set(join(root, 'pkg/AGENTS.md'), { type: 'directory' })
- const mismatchedStat = await ctx.waterfall('tools/post-execute', stubToolExecution({
+ const mismatchedStat = await postExecute(ctx, stubToolExecution({
callId: CallId('provider-stat-mismatch'), name: 'read', arguments: { file_path: 'pkg/file.txt' }, agent,
}), result, async () => ({ kind: 'accept' as const }))
@@ -2641,19 +2665,19 @@ describe('dynamic nested workspace context injection', () => {
const parent = Symbol('parent') as ToolExecutionToken
const plainResult = { callId: CallId('plain'), content: [], isError: false as const, value: null }
- ctx.emit('tools/result', stubToolExecution({
+ emitToolResult(ctx, stubToolExecution({
callId: CallId('agentless-child'), name: 'read', arguments: {}, parent,
}), plainResult)
- ctx.emit('tools/result', stubToolExecution({
+ emitToolResult(ctx, stubToolExecution({
callId: CallId('contextless-child'), name: 'read', arguments: {}, agent, parent,
}), { ...plainResult, additionalContexts: [{ content: [], source: { kind: 'plugin', plugin: 'workspace-context' } }] })
- ctx.emit('tools/result', stubToolExecution({
+ emitToolResult(ctx, stubToolExecution({
callId: CallId('first-child'), name: 'read', arguments: {}, agent, parent,
}), { ...plainResult, additionalContexts: [workspaceChangeContext('first', 'one')] })
- ctx.emit('tools/result', stubToolExecution({
+ emitToolResult(ctx, stubToolExecution({
callId: CallId('second-child'), name: 'read', arguments: {}, agent, parent,
}), { ...plainResult, additionalContexts: [workspaceChangeContext('second', 'two')] })
- ctx.emit('tools/result', {
+ emitToolResult(ctx, {
...stubToolExecution({ callId: CallId('agentless-parent'), name: 'composite', arguments: {} }),
token: parent,
}, plainResult)
@@ -2690,7 +2714,7 @@ describe('dynamic nested workspace context injection', () => {
]
for (const item of cases) {
- const decision = await ctx.waterfall('tools/post-execute', stubToolExecution({
+ const decision = await postExecute(ctx, stubToolExecution({
callId: CallId(`manual-${item.name}-${cases.indexOf(item)}`),
name: item.name,
arguments: item.arguments,
diff --git a/packages/context/workspace-context/tsconfig.json b/packages/context/workspace-context/tsconfig.json
index b4807ded65..b5aca1dfc8 100644
--- a/packages/context/workspace-context/tsconfig.json
+++ b/packages/context/workspace-context/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../util/paths"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/cordis/tool-cordis/package.json b/packages/cordis/tool-cordis/package.json
index e13de3e58b..7e7b75cab3 100644
--- a/packages/cordis/tool-cordis/package.json
+++ b/packages/cordis/tool-cordis/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,16 +36,17 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+ "@cordisjs/plugin-timer": "workspace:^",
"@deepseek-ai/dsh-agent": "workspace:^",
- "@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
+ "@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
- "@cordisjs/plugin-loader": "^1.0.0-rc.5",
- "cordis": "^4.0.0-rc.7",
- "@cordisjs/plugin-timer": "workspace:^"
+ "cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 9bbd88b06f..55e930a4df 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -314,6 +314,16 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
},
],
},
+ {
+ key: 'invariants',
+ summary: 'Package-owned invariant registry with global and regex-based selection.',
+ methods: [
+ {
+ signature: 'register(packageName: string, installer: InvariantInstaller): () => void',
+ jsDoc: '/**\n * Register one package\'s invariant installer. The package name is reserved\n * even when filtering disables its checks. Enabled installers run in a child\n * fiber; failure disposes that fiber and releases the reservation.\n * @param packageName - full npm package name that owns the contribution.\n * @param installer - listener or startup-check installer for the child context.\n * @returns an effect-scoped disposer for the registration.\n */',
+ },
+ ],
+ },
{
key: 'llm',
summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
@@ -330,6 +340,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
signature: 'async listModels(provider: string): Promise',
jsDoc: '/**\n * Discover models advertised by one registered provider. Catalog membership\n * is advisory and never changes routing or request validation.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */',
},
+ {
+ signature: 'async resolveModelContext( provider: string, model: string, ): Promise',
+ jsDoc: '/**\n * Resolve context capacity from the adapter that owns one exact route.\n * This query is independent of the advisory model catalog: an unlisted model\n * may return metadata, while `undefined` never rejects later routing.\n * @param provider - registered provider route to inspect.\n * @param model - exact model id passed to the adapter.\n * @returns detached context metadata, or `undefined` when the adapter has none.\n */',
+ },
{
signature: 'stream(options: GenerateOptions): AsyncIterable',
jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Throws\n * `LlmError` with code `NO_ADAPTER` if no adapter is registered for\n * `options.provider`. Replay state is retained only when the same adapter\n * instance owns its historical provider and the target provider. Final\n * adapter selection, dispatch, and iteration failures retain their original\n * Error identity and are tagged in a call-local scope for narrow agent-loop\n * request recovery; middleware and nested-call failures remain untagged for\n * the outer call.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */',
@@ -1340,6 +1354,14 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'InjectOptions',
declaration: 'export interface InjectOptions extends SendOptions {\n meta?: JsonValue;\n}',
},
+ {
+ name: 'InvariantFailure',
+ declaration: 'export type InvariantFailure = (message: string) => never;',
+ },
+ {
+ name: 'InvariantInstaller',
+ declaration: 'export interface InvariantInstaller {\n (ctx: Context, fail: InvariantFailure): void | Promise;\n readonly inject?: Inject;\n}',
+ },
{
name: 'JsonSchemaNode',
declaration: 'export interface JsonSchemaNode {\n type?: JsonSchemaType;\n oneOf?: JsonSchemaNode[];\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: JsonSchemaNode;\n enum?: JsonSchemaScalar[];\n const?: JsonSchemaScalar;\n description?: string;\n title?: string;\n default?: JsonValue;\n examples?: JsonValue;\n}',
@@ -1364,6 +1386,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
name: 'LlmFailure',
declaration: 'export interface LlmFailure {\n readonly message: string;\n readonly code: string;\n readonly status?: number;\n readonly providerRetryAfterMs?: number;\n readonly requestId?: ProviderRequestId;\n}',
},
+ {
+ name: 'LlmModelContext',
+ declaration: 'export interface LlmModelContext {\n contextWindow: number;\n}',
+ },
{
name: 'LlmModelInfo',
declaration: 'export interface LlmModelInfo {\n provider: string;\n id: string;\n name: string;\n description?: string;\n}',
diff --git a/packages/cordis/tool-cordis/src/invariant.ts b/packages/cordis/tool-cordis/src/invariant.ts
new file mode 100644
index 0000000000..6fd73d0353
--- /dev/null
+++ b/packages/cordis/tool-cordis/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-cordis`.
+ * @module @deepseek-ai/dsh-tool-cordis/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-cordis'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-cordis-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+ * relations are owned by the capability seam it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/cordis/tool-cordis/tsconfig.json b/packages/cordis/tool-cordis/tsconfig.json
index cc9928d81f..4f10b49622 100644
--- a/packages/cordis/tool-cordis/tsconfig.json
+++ b/packages/cordis/tool-cordis/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index f4193d44ad..1197a018be 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -27,6 +27,10 @@ The config-driven `ctx.agentLoop.create()` path keeps its agent owned by the loo
`agents`, `sessions`, `llm`, `tools`, `systemPrompt` — all five interface services.
+### Invariant companion
+
+The optional `@deepseek-ai/dsh-agent-loop/invariant` companion registers request reconstruction with `ctx.invariants`. The loop marks each request with an internal non-enumerable identity before freezing it; the companion then requires a live session and independently rebuilds the message boundary and folded request header from the log. Direct one-shot calls remain outside this contract even when callers freeze them or attach a session id.
+
### Configuration (schemastery)
```ts
diff --git a/packages/core/agent-loop/package.json b/packages/core/agent-loop/package.json
index 7e2fb235a2..8e9a2b93bb 100644
--- a/packages/core/agent-loop/package.json
+++ b/packages/core/agent-loop/package.json
@@ -11,10 +11,15 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -22,6 +27,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
diff --git a/packages/core/agent-loop/src/invariant.ts b/packages/core/agent-loop/src/invariant.ts
new file mode 100644
index 0000000000..17e55af6ca
--- /dev/null
+++ b/packages/core/agent-loop/src/invariant.ts
@@ -0,0 +1,76 @@
+/**
+ * Package-owned request-reconstruction invariant for loop-built LLM calls.
+ * @module @deepseek-ai/dsh-agent-loop/invariant
+ */
+
+import type { Context } from 'cordis'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
+import { isLoopRequest } from './request-marker.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-loop-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Install the request-reconstruction contribution into its child registration fiber. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ // Prepend prevents a short-circuiting replay listener from silencing the
+ // check; correctness itself comes from the sequence-bounded reconstruction.
+ ctx.on('llm/stream', (options: GenerateOptions, next) => {
+ if (!isLoopRequest(options)) return next()
+ if (!Object.isFrozen(options)) fail('a loop-built request must be frozen')
+ if (options.sessionId === undefined) fail('a loop-built request must carry a session id')
+ const session = ctx.sessions.get(options.sessionId)
+ if (!session) fail(`a loop-built request must carry a live session id, got "${String(options.sessionId)}"`)
+ if (!Object.isFrozen(options.messages)) {
+ fail('a loop-built request must carry a frozen messages array')
+ }
+
+ const events = session.events
+ let boundary = -1
+ for (let index = events.length - 1; index >= 0; index -= 1) {
+ if (events[index]?.type === 'step/start') {
+ boundary = index
+ break
+ }
+ }
+ if (boundary === -1) {
+ return fail('a loop-built request with no step/start in its session log')
+ }
+ const header = foldRequestHeader(events)
+ if (header === undefined) {
+ return fail('a loop-built request with no request/header event in its session log')
+ }
+ const rebuilt = new Session(
+ SessionId(`${String(session.id)}-invariant-rebuild`),
+ structuredClone(events.slice(0, boundary)),
+ )
+ const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
+ if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
+ fail(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
+ }
+
+ const headerMatches = options.model === header.config.model
+ && options.system === header.system
+ && options.temperature === header.config.temperature
+ && options.maxTokens === header.config.maxTokens
+ && JSON.stringify(options.stop) === JSON.stringify(header.config.stop)
+ && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? [])
+ if (!headerMatches) {
+ fail(`llm request for session "${String(session.id)}" diverges from the folded request header`)
+ }
+ return next()
+ }, { global: true, prepend: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the agent-loop invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index 97a32e2f38..c14e126566 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -15,6 +15,7 @@ import { canonicalHeader } from '@deepseek-ai/dsh-session'
import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
import { createTransmissionLog, recordRequestHeader } from './request-log.ts'
import type { TransmissionLog } from './request-log.ts'
+import { markLoopRequest } from './request-marker.ts'
import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
import type {} from '@deepseek-ai/dsh-tools'
@@ -619,7 +620,7 @@ async function runStep(
recordRequestHeader(session, transmission, header)
// Freeze the logged header plus boundary snapshot; the prefix precedes derived history.
- const request: GenerateOptions = deepFreeze({
+ const request: GenerateOptions = deepFreeze(markLoopRequest({
provider: header.config.provider,
model: header.config.model,
messages: [...header.messagePrefix ?? [], ...boundaryMessages],
@@ -630,7 +631,7 @@ async function runStep(
...header.config.stop !== undefined ? { stop: header.config.stop } : {},
sessionId: session.id,
signal,
- })
+ }))
// --- Model call (streaming-first; raw chunks are the replay record) ---
const assembler = new BlockAssembler()
diff --git a/packages/core/agent-loop/src/request-marker.ts b/packages/core/agent-loop/src/request-marker.ts
new file mode 100644
index 0000000000..ac8c750ea1
--- /dev/null
+++ b/packages/core/agent-loop/src/request-marker.ts
@@ -0,0 +1,22 @@
+/** Internal identity shared by the independently bundled loop and invariant companion. */
+
+const LOOP_REQUEST = Symbol.for('@deepseek-ai/dsh-agent-loop/request')
+
+/**
+ * Mark a request as owned by the agent loop before it is frozen.
+ * @param request - mutable request object being assembled by the loop.
+ * @returns the same request with a non-enumerable loop identity.
+ */
+export function markLoopRequest(request: T): T {
+ Object.defineProperty(request, LOOP_REQUEST, { value: true })
+ return request
+}
+
+/**
+ * Test whether a request carries the agent loop's internal identity.
+ * @param request - request observed at the LLM stream boundary.
+ * @returns whether the loop marked this exact request object.
+ */
+export function isLoopRequest(request: object): boolean {
+ return Reflect.get(request, LOOP_REQUEST) === true
+}
diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts
index 97bf57ad72..2551879166 100644
--- a/packages/core/agent-loop/tests/contract-regressions.spec.ts
+++ b/packages/core/agent-loop/tests/contract-regressions.spec.ts
@@ -7,9 +7,19 @@ import ToolRegistry, { defineContentToolFixture, type PostToolDecision } from '@
import AgentRegistry, { type Agent, type ContinuationDecision } from '@deepseek-ai/dsh-agent'
import AgentLoop, { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from '@deepseek-ai/dsh-agent-loop'
import { prepareReactLoopAgent } from '../src/agent.ts'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import { maxTokensResponse, MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
function driverDone(agent: Agent): Promise {
return (agent as Agent & { done: Promise }).done
}
@@ -144,7 +154,7 @@ describe('successful provider completion survives agent/step-result failure', ()
): Promise {
const adapter = new MockAdapter([response])
const ctx = await harness(adapter)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
const agent = ctx.agentLoop.create(SessionId(id), { provider: 'mock', model: 'mock' })
const failure = new Error(`${id} result processing failed`)
const reported: Error[] = []
@@ -1041,7 +1051,7 @@ describe('step boundary publication order', () => {
})
describe('turn and step boundary recovery', () => {
- // The invariants plugin makes an unbalanced log fail the test.
+ // The session invariant companion makes an unbalanced log fail the test.
async function balancedHarness(adapter: MockAdapter) {
const ctx = new Context()
await ctx.plugin(LlmService)
@@ -1050,7 +1060,7 @@ describe('turn and step boundary recovery', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
return ctx
}
@@ -1468,7 +1478,7 @@ describe('surface: assistant/message records exact empty provenance when no chun
// stream from legacy events whose provenance was not recorded.
const adapter = new MockAdapter([[]])
const ctx = await harness(adapter)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
const agent = ctx.agentLoop.create(SessionId('a1'), { provider: 'mock', model: 'mock' })
ctx.on('agent/step-result', async (_agent, _turn, _step, _message, _next) => ({
@@ -1505,7 +1515,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
// Parent-owned listener survives agent-fiber disposal.
@@ -1556,7 +1566,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
const unlisten = ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
@@ -1611,7 +1621,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
ctx.on('agent/pre-step', async () => {
@@ -1662,7 +1672,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
ctx.on('agent/pre-step', async () => {
@@ -1711,7 +1721,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
await ctx.plugin(AgentLoop, { agents: [] })
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
ctx.llm.registerAdapter(['mock'], adapter)
ctx.on('system-prompt/assemble', async function (_assembly, _context, next) {
diff --git a/packages/core/agent-loop/tests/invariant.spec.ts b/packages/core/agent-loop/tests/invariant.spec.ts
new file mode 100644
index 0000000000..c5030bf161
--- /dev/null
+++ b/packages/core/agent-loop/tests/invariant.spec.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
+import { markLoopRequest } from '../src/request-marker.ts'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(AgentLoopInvariant)
+ return ctx
+}
+
+function dispatch(ctx: Context, options: unknown): void {
+ void ctx.waterfall('llm/stream', options as never, () => (async function* () {})() as never)
+}
+
+function loopRequest(options: T): Readonly {
+ return Object.freeze(markLoopRequest(options))
+}
+
+async function requestSetup() {
+ const ctx = await setup()
+ const session = ctx.sessions.create(SessionId('req-check'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+ const boundary = session.deriveMessages()
+ session.append('step/start', { turn: 1, step: 1 })
+ session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+ return { ctx, session, boundary }
+}
+
+describe('request-reconstruction invariant', () => {
+ it('accepts a frozen request equal to the boundary derivation and folded header', async () => {
+ const { ctx, session, boundary } = await requestSetup()
+ const options = loopRequest({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+ expect(() => { dispatch(ctx, options) }).not.toThrow()
+ })
+
+ it('uses the step boundary rather than content appended afterward', async () => {
+ const { ctx, session, boundary } = await requestSetup()
+ session.append('context/message', { content: [{ type: 'text', text: '[late]' }], source: { kind: 'plugin', plugin: 'x' } }, { surfaceOp: 'append' })
+ const options = loopRequest({ model: 'm', messages: Object.freeze(boundary), sessionId: session.id })
+ expect(() => { dispatch(ctx, options) }).not.toThrow()
+ })
+
+ it('requires the folded session prefix ahead of derived history', async () => {
+ const { ctx, session, boundary } = await requestSetup()
+ const prefix = { role: 'user' as const, content: [{ type: 'text' as const, text: 'catalog' }] }
+ session.append('request/header', { header: { config: { provider: 'mock', model: 'm' }, messagePrefix: [prefix] }, reason: 'change' })
+ expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([prefix, ...boundary]), sessionId: session.id })) })
+ .not.toThrow()
+ expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary]), sessionId: session.id })) })
+ .toThrow(/diverges from the boundary derivation/)
+ expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([...boundary, prefix]), sessionId: session.id })) })
+ .toThrow(/diverges from the boundary derivation/)
+ })
+
+ it('rejects message and header divergence', async () => {
+ const { ctx, session, boundary } = await requestSetup()
+ const divergent = [...boundary, { role: 'user', content: [{ type: 'text', text: 'phantom' }] }]
+ expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze(divergent), sessionId: session.id })) })
+ .toThrow(/diverges from the boundary derivation/)
+ expect(() => { dispatch(ctx, loopRequest({ model: 'other', messages: Object.freeze(boundary), sessionId: session.id })) })
+ .toThrow(/diverges from the folded request header/)
+ })
+
+ it('rejects loop requests with no boundary or header', async () => {
+ const ctx = await setup()
+ const session = ctx.sessions.create(SessionId('req-bare'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ const bare = loopRequest({ model: 'm', messages: Object.freeze([]), sessionId: session.id })
+ expect(() => { dispatch(ctx, bare) }).toThrow(/no step\/start/)
+ session.append('step/start', { turn: 1, step: 1 })
+ expect(() => { dispatch(ctx, bare) }).toThrow(/no request\/header event/)
+ })
+
+ it('rejects an unfrozen messages array but skips requests outside the loop contract', async () => {
+ const { ctx, session, boundary } = await requestSetup()
+ expect(() => { dispatch(ctx, loopRequest({ model: 'm', messages: [...boundary], sessionId: session.id })) })
+ .toThrow(/frozen messages array/)
+ expect(() => { dispatch(ctx, { model: 'summarizer', messages: [], sessionId: session.id }) }).not.toThrow()
+ expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]) })) }).not.toThrow()
+ expect(() => { dispatch(ctx, Object.freeze({ model: 'm', messages: Object.freeze([]), sessionId: SessionId('ghost') })) })
+ .not.toThrow()
+
+ const directSession = ctx.sessions.create(SessionId('direct-one-shot'))
+ expect(() => {
+ dispatch(ctx, Object.freeze({ model: 'one-shot', messages: Object.freeze([]), sessionId: directSession.id }))
+ }).not.toThrow()
+ })
+
+ it('rejects malformed requests carrying the loop marker', async () => {
+ const { ctx, session } = await requestSetup()
+ expect(() => {
+ dispatch(ctx, markLoopRequest({ model: 'm', messages: Object.freeze([]), sessionId: session.id }))
+ }).toThrow(/request must be frozen/)
+ expect(() => {
+ dispatch(ctx, loopRequest({ model: 'm', messages: Object.freeze([]) }))
+ }).toThrow(/carry a session id/)
+ expect(() => {
+ dispatch(ctx, loopRequest({
+ model: 'm',
+ messages: Object.freeze([]),
+ sessionId: SessionId('missing-loop-session'),
+ }))
+ }).toThrow(/live session id/)
+ })
+
+ it('prepends ahead of a short-circuiting stream listener', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ ctx.on('llm/stream', () => (async function* () {})() as never)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(AgentLoopInvariant)
+ const session = ctx.sessions.create(SessionId('prepend-check'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+ session.append('step/start', { turn: 1, step: 1 })
+ session.append('request/header', { header: { config: { provider: 'mock', model: 'm' } }, reason: 'initial' })
+ const divergent = loopRequest({
+ model: 'm',
+ messages: Object.freeze([{ role: 'user', content: [{ type: 'text', text: 'phantom' }] }]),
+ sessionId: session.id,
+ })
+ expect(() => { dispatch(ctx, divergent) }).toThrow(/diverges from the boundary derivation/)
+ })
+})
diff --git a/packages/core/agent-loop/tests/resume.spec.ts b/packages/core/agent-loop/tests/resume.spec.ts
index 0547388d96..a218987e0e 100644
--- a/packages/core/agent-loop/tests/resume.spec.ts
+++ b/packages/core/agent-loop/tests/resume.spec.ts
@@ -425,7 +425,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
seed,
meta: { cwd: '/w', parentSession: SessionId('parent-sess'), seedLength: seed.length, delegationDepth: 1 },
})
- await ctx1.parallel('session/flush', forked)
+ await ctx1.sessions.flush(forked)
await ctx1.fiber.dispose()
// Lifecycle 2: resume it; the parentSession + seedLength header survives the
@@ -485,7 +485,7 @@ describe('the session-persistence Agent Note: AgentLoop factory create/resume',
a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
await waitForIdle(ctx1, a1)
a1.inject([{ type: 'text', text: 'background task 42 finished' }], { source: { kind: 'plugin', plugin: 'tool-bash' } })
- await ctx1.parallel('session/flush', a1.session)
+ await ctx1.sessions.flush(a1.session)
await ctx1.fiber.dispose()
// Lifecycle 2: resume; the injected context is still in the derived history.
diff --git a/packages/core/agent-loop/tests/turn-stop.spec.ts b/packages/core/agent-loop/tests/turn-stop.spec.ts
index f7b59e3585..b6ee9e95fe 100644
--- a/packages/core/agent-loop/tests/turn-stop.spec.ts
+++ b/packages/core/agent-loop/tests/turn-stop.spec.ts
@@ -7,9 +7,19 @@ import ToolRegistry, { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
import AgentRegistry, { type Agent, type ContinuationStop } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
async function harness(adapter: MockAdapter): Promise {
const ctx = new Context()
await ctx.plugin(LlmService)
@@ -17,7 +27,7 @@ async function harness(adapter: MockAdapter): Promise {
await ctx.plugin(SystemPrompt)
await ctx.plugin(ToolRegistry)
await ctx.plugin(AgentRegistry)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
ctx.llm.registerAdapter(['mock'], adapter)
return ctx
diff --git a/packages/core/agent-loop/tsconfig.json b/packages/core/agent-loop/tsconfig.json
index 5d7cf98bb7..0949f18453 100644
--- a/packages/core/agent-loop/tsconfig.json
+++ b/packages/core/agent-loop/tsconfig.json
@@ -37,6 +37,9 @@
},
{
"path": "../../core/scope"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/agent-loop/tsdown.config.ts b/packages/core/agent-loop/tsdown.config.ts
new file mode 100644
index 0000000000..e92275a7f5
--- /dev/null
+++ b/packages/core/agent-loop/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 7a352c33e6..269190dab0 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -2,6 +2,8 @@
Agent interface, registry, process-local initiator scope, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
+The optional `@deepseek-ai/dsh-agent/invariant` companion registers this package's agent-status transition checks with `ctx.invariants`. The root agent service does not load diagnostics implicitly.
+
## Service: `AgentRegistry` (ctx key: `agents`)
Tracks live agents and carries the initiating Agent through asynchronous driver work without importing the concrete loop package.
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index bcf75ea7ca..f40a5da441 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -31,6 +37,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/core/agent/src/invariant.ts b/packages/core/agent/src/invariant.ts
new file mode 100644
index 0000000000..1902f3e746
--- /dev/null
+++ b/packages/core/agent/src/invariant.ts
@@ -0,0 +1,35 @@
+/** Package-owned agent lifecycle invariants. @module @deepseek-ai/dsh-agent/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Install the agent contribution into its child registration fiber. */
+const install: InvariantInstaller = (ctx, fail) => {
+ const lastStatus = new WeakMap()
+ ctx.on('agent/status', (agent, status) => {
+ const previous = lastStatus.get(agent)
+ if (previous === status) {
+ fail(`agent/status repeated ${status} (no-op transition)`)
+ }
+ if (previous === 'disposed') {
+ fail(`agent/status left terminal state disposed → ${status}`)
+ }
+ lastStatus.set(agent, status)
+ }, { global: true })
+}
+
+/**
+ * Register the agent invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/agent/tests/invariant.spec.ts b/packages/core/agent/tests/invariant.spec.ts
new file mode 100644
index 0000000000..3c0d147b9a
--- /dev/null
+++ b/packages/core/agent/tests/invariant.spec.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(AgentInvariant)
+ return ctx
+}
+
+function mockAgent(id: string): Agent {
+ return { id } as unknown as Agent
+}
+
+describe('agent status invariants', () => {
+ it('accepts lifecycle transitions through idle, running, and disposed', async () => {
+ const ctx = await setup()
+ const agent = mockAgent('a1')
+ expect(() => {
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle')
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+ }).not.toThrow()
+
+ const running = mockAgent('a2')
+ ctx.emit(scopeTarget(running, running), 'agent/status', running, 'running')
+ expect(() => { ctx.emit(scopeTarget(running, running), 'agent/status', running, 'disposed') }).not.toThrow()
+ })
+
+ it('rejects a no-op transition', async () => {
+ const ctx = await setup()
+ const agent = mockAgent('a3')
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running')
+ expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'running') })
+ .toThrow(/no-op transition/)
+ })
+
+ it('rejects leaving the terminal disposed state', async () => {
+ const ctx = await setup()
+ const agent = mockAgent('a4')
+ ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'disposed')
+ expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/status', agent, 'idle') })
+ .toThrow(/left terminal state disposed/)
+ })
+
+ it('tracks agents independently', async () => {
+ const ctx = await setup()
+ const a = mockAgent('a5')
+ const b = mockAgent('b5')
+ ctx.emit(scopeTarget(a, a), 'agent/status', a, 'running')
+ expect(() => { ctx.emit(scopeTarget(b, b), 'agent/status', b, 'running') }).not.toThrow()
+ })
+})
diff --git a/packages/core/agent/tsconfig.json b/packages/core/agent/tsconfig.json
index 2692e1b7f7..b6d6c9e6bf 100644
--- a/packages/core/agent/tsconfig.json
+++ b/packages/core/agent/tsconfig.json
@@ -28,6 +28,9 @@
},
{
"path": "../../core/system-prompt"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/agent/tsdown.config.ts b/packages/core/agent/tsdown.config.ts
new file mode 100644
index 0000000000..e92275a7f5
--- /dev/null
+++ b/packages/core/agent/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/core/scope/README.md b/packages/core/scope/README.md
index fd6d10c84c..7fc4a49102 100644
--- a/packages/core/scope/README.md
+++ b/packages/core/scope/README.md
@@ -13,6 +13,8 @@ Scoped registration primitive. `createScope(ctx, key)` creates a tagged Cordis c
- `Scoped` The compile-time opaque carrier brand: scope-filtered events demand it as their `this` type, so dispatching with a bare subject is a compile error. The type parameter records the subject type but does not expose its properties.
- `isScopeCarrier(value)` / `carrierKeyOf(value)` Runtime carrier marks, used by the dev invariants to assert every scope-filtered dispatch carries a carrier keyed to the subject its arguments name.
+The optional `@deepseek-ai/dsh-scope/invariant` companion owns that runtime assertion. It uses the generated `scoped-events.generated.ts` resolver map to require a carrier for every declared scoped event and, when the payload exposes its routing subject, require identity with the carrier key. The Program-backed generator derives the map from event declarations and real `scopeTarget(base, key)` calls.
+
## Design contract
The registration context determines both visibility and ownership, preventing a registration from being visible in one scope but disposed with another. Scopes route trusted same-process plugins; they are not sandboxes or authority boundaries. See the [agent-scope Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-agent-scope-contexts.md#security-and-authority-are-explicit-non-goals) for rationale and security non-goals.
diff --git a/packages/core/scope/package.json b/packages/core/scope/package.json
index 88d78ceb8b..4679e2755a 100644
--- a/packages/core/scope/package.json
+++ b/packages/core/scope/package.json
@@ -11,20 +11,27 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/core/scope/src/invariant.ts b/packages/core/scope/src/invariant.ts
new file mode 100644
index 0000000000..a5bd59f263
--- /dev/null
+++ b/packages/core/scope/src/invariant.ts
@@ -0,0 +1,41 @@
+/** Package-owned scoped-dispatch invariants. @module @deepseek-ai/dsh-scope/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { carrierKeyOf, isScopeCarrier } from '@deepseek-ai/dsh-scope'
+import { scopedSubjectResolverFor } from './scoped-events.generated.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-scope'
+
+/** Cordis companion plugin name. */
+export const name = 'scope-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** Install the scoped-dispatch contribution into its child registration fiber. */
+const install: InvariantInstaller = (ctx, fail) => {
+ ctx.on('internal/dispatch', (_mode, eventName, args, thisArg) => {
+ const subjectOf = scopedSubjectResolverFor(eventName)
+ if (subjectOf === undefined) return
+ if (!isScopeCarrier(thisArg)) {
+ fail(
+ `"${eventName}" is a scope-filtered event but was dispatched without a scope carrier — `
+ + 'pass scopeTarget(base, subject) as the dispatch thisArg (agent events: use agentEvents(ctx, agent))',
+ )
+ }
+ if (subjectOf !== null && carrierKeyOf(thisArg) !== subjectOf(args)) {
+ fail(
+ `"${eventName}" was dispatched with a scope carrier keyed to a DIFFERENT subject than its arguments name — `
+ + 'the carrier key and the event\'s subject must be the same object (use agentEvents(ctx, agent))',
+ )
+ }
+ }, { global: true })
+}
+
+/**
+ * Register the scope invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/scope/src/scoped-events.generated.ts b/packages/core/scope/src/scoped-events.generated.ts
new file mode 100644
index 0000000000..5988b58145
--- /dev/null
+++ b/packages/core/scope/src/scoped-events.generated.ts
@@ -0,0 +1,52 @@
+/**
+ * Generated scoped-event routing-subject resolvers for dsh-scope invariants.
+ * Do not edit by hand; run `pnpm run gen-scoped-events`.
+ *
+ * @module @deepseek-ai/dsh-scope/scoped-events.generated
+ */
+
+type ScopedSubjectResolver = (args: readonly unknown[]) => unknown
+
+const scopedSubjectResolvers: Readonly> = Object.freeze({
+ 'agent/cancel-requested': args => args[0],
+ 'agent/created': args => args[0],
+ 'agent/disposed': args => args[0],
+ 'agent/error': args => args[0],
+ 'agent/post-step': args => args[0],
+ 'agent/pre-step': args => args[0],
+ 'agent/prompt-submit': args => args[0],
+ 'agent/queued': args => args[0],
+ 'agent/request': args => args[0],
+ 'agent/request-error': args => args[0],
+ 'agent/session-prefix': args => args[0],
+ 'agent/session-start': args => args[0],
+ 'agent/status': args => args[0],
+ 'agent/step-result': args => args[0],
+ 'agent/turn-continuation': args => args[0],
+ 'agent/turn-stop': args => args[0],
+ 'approval/request': args => (args[0] as Record)['agent'],
+ 'goal/changed': args => args[0],
+ 'session/created': null,
+ 'session/disposed': null,
+ 'session/event': null,
+ 'session/flush': null,
+ 'subagent/end': null,
+ 'subagent/start': null,
+ 'system-prompt/assemble': args => (args[1] as Record)['scope'],
+ 'tools/execute': args => (args[0] as Record)['agent'],
+ 'tools/post-execute': args => (args[0] as Record)['agent'],
+ 'tools/pre-execute': args => (args[0] as Record)['agent'],
+ 'tools/result': args => (args[0] as Record)['agent'],
+})
+
+/**
+ * Resolve the routing key named by one scoped event payload. A null
+ * resolver means the payload cannot expose its external routing key, so the
+ * invariant checks carrier presence only.
+ * @param event - runtime Cordis event name.
+ * @returns the generated subject resolver, null for presence-only,
+ * or undefined when the event is not scope-filtered.
+ */
+export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {
+ return scopedSubjectResolvers[event]
+}
diff --git a/packages/core/scope/tests/invariant.spec.ts b/packages/core/scope/tests/invariant.spec.ts
new file mode 100644
index 0000000000..fd619402d0
--- /dev/null
+++ b/packages/core/scope/tests/invariant.spec.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import * as ScopeInvariant from '@deepseek-ai/dsh-scope/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(ScopeInvariant)
+ return ctx
+}
+
+function emit(ctx: Context, receiver: object | undefined, event: string, args: unknown[]): void {
+ const dispatch = ctx.emit.bind(ctx) as (...values: unknown[]) => void
+ if (receiver === undefined) dispatch(event, ...args)
+ else dispatch(receiver, event, ...args)
+}
+
+describe('scoped-dispatch invariants', () => {
+ it('ignores ordinary events and rejects a scoped dispatch without a carrier', async () => {
+ const ctx = await setup()
+ expect(() => { emit(ctx, undefined, 'ordinary/event', []) }).not.toThrow()
+ const agent = { id: 'a1' }
+ expect(() => { emit(ctx, undefined, 'agent/error', [agent, 1, 0, new Error('x')]) })
+ .toThrow(/dispatched without a scope carrier/)
+ })
+
+ it('checks every generated subject resolver against the carrier key', async () => {
+ const ctx = await setup()
+ const agent = { id: 'a1' }
+ const other = { id: 'a2' }
+ const rows: Array<[string, unknown[]]> = [
+ ['agent/created', [agent]],
+ ['agent/disposed', [agent]],
+ ['agent/error', [agent, 1, 0, new Error('x')]],
+ ['agent/post-step', [agent, 1, 1]],
+ ['agent/pre-step', [agent, 1, 1, new AbortController().signal]],
+ ['agent/prompt-submit', [agent, [], { kind: 'user' }, () => Promise.resolve({ kind: 'allow' })]],
+ ['agent/queued', [agent, [], { source: { kind: 'user' }, steering: false }]],
+ ['agent/request', [agent, 1, 1, { model: 'm' }, () => Promise.resolve({ model: 'm' })]],
+ ['agent/request-error', [agent, 1, 1, new Error('x')]],
+ ['agent/session-prefix', [agent, [], new AbortController().signal, () => Promise.resolve([])]],
+ ['agent/session-start', [agent, 'startup']],
+ ['agent/status', [agent, 'idle']],
+ ['agent/step-result', [agent, 1, 1, { role: 'assistant', content: [] }, () => Promise.resolve({ role: 'assistant', content: [] })]],
+ ['agent/turn-continuation', [agent, 1, { action: 'stop' }, () => Promise.resolve({ action: 'stop' })]],
+ ['agent/turn-stop', [agent, 1]],
+ ['approval/request', [{ agent, toolName: 'echo' }, () => Promise.resolve('unavailable')]],
+ ['goal/changed', [agent, { operation: 'create', ref: { id: 'goal-a', revision: 1 } }]],
+ ['system-prompt/assemble', [[], { scope: agent }]],
+ ['tools/execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ content: [], isError: false })]],
+ ['tools/post-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }, () => Promise.resolve({ kind: 'accept' })]],
+ ['tools/pre-execute', [{ callId: 'c', name: 't', arguments: {}, agent }, () => Promise.resolve({ kind: 'allow' })]],
+ ['tools/result', [{ callId: 'c', name: 't', arguments: {}, agent }, { content: [], isError: false }]],
+ ]
+
+ for (const [event, args] of rows) {
+ expect(() => { emit(ctx, scopeTarget(agent, agent), event, args) }, `${event} matching`).not.toThrow()
+ expect(() => { emit(ctx, scopeTarget(agent, other), event, args) }, `${event} mismatched`)
+ .toThrow(/DIFFERENT subject/)
+ }
+ })
+
+ it('requires carriers for generated presence-only scoped events without comparing a payload subject', async () => {
+ const ctx = await setup()
+ const agent = { id: 'a1' }
+ const rows: Array<[string, unknown[]]> = [
+ ['session/created', [{}]],
+ ['session/disposed', [{}]],
+ ['session/event', [{}, {}]],
+ ['session/flush', [{}]],
+ ['subagent/end', [{}]],
+ ['subagent/start', [{}]],
+ ]
+ for (const [event, args] of rows) {
+ expect(() => { emit(ctx, scopeTarget(agent, agent), event, args) }, `${event} carrier`).not.toThrow()
+ expect(() => { emit(ctx, undefined, event, args) }, `${event} no carrier`)
+ .toThrow(/dispatched without a scope carrier/)
+ }
+ })
+})
diff --git a/packages/core/scope/tsconfig.json b/packages/core/scope/tsconfig.json
index 754725418e..9966c8ca8a 100644
--- a/packages/core/scope/tsconfig.json
+++ b/packages/core/scope/tsconfig.json
@@ -13,6 +13,9 @@
},
{
"path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/scope/tsdown.config.ts b/packages/core/scope/tsdown.config.ts
new file mode 100644
index 0000000000..1dbbf38372
--- /dev/null
+++ b/packages/core/scope/tsdown.config.ts
@@ -0,0 +1,27 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ // Preserve the root entry's carrier WeakMap identity across bundles.
+ deps: { neverBundle: ['@deepseek-ai/dsh-scope'] },
+ },
+])
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index 107eaf25bf..a3eb4c9989 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -2,6 +2,8 @@
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.
+The optional `@deepseek-ai/dsh-session/invariant` companion registers this package's relational trace checks with `ctx.invariants`: monotonic sequence numbers, turn/step enclosure, and same-step tool call/result pairing. It replays existing sessions when loaded or reloaded; storage validation, snapshotting, freezing, provenance, and surface acceptance remain always-on responsibilities of the root session package.
+
## Service: `SessionStore` (ctx key: `sessions`)
Creates and holds event-sourced `Session` instances. Persistence is intentionally not implemented here — plugins subscribe to `session/event`, flush on `session/flush`, and may mirror the paired `session/created`/`session/disposed` lifecycle.
@@ -34,7 +36,7 @@ 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, complete replacement coverage, and content-only single-result `tool/result` rewrites, 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 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.deriveEventMessage(event)` is the canonical per-event projection used by reconstruction and request checks.
- `session.surface` exposes the readonly `SessionSurface` view owned by the session's single incremental surface manager; `replaceGeneration` changes on every committed rewrite.
- `session.events` is a cached frozen snapshot invalidated by append; accepted events remain deeply frozen.
- `session.seq`, `session.id` — current sequence and readonly typed identity.
diff --git a/packages/core/session/package.json b/packages/core/session/package.json
index 540c5cdc75..314eb6e0b5 100644
--- a/packages/core/session/package.json
+++ b/packages/core/session/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,12 +28,14 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/core/session/src/invariant.ts b/packages/core/session/src/invariant.ts
new file mode 100644
index 0000000000..aa8aa91531
--- /dev/null
+++ b/packages/core/session/src/invariant.ts
@@ -0,0 +1,238 @@
+/**
+ * Package-owned relational invariants for the session event log. Load this
+ * companion beside `@deepseek-ai/dsh-invariants` to enable the checks.
+ *
+ * @module @deepseek-ai/dsh-session/invariant
+ */
+
+import type { Context } from 'cordis'
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type { CallId } from '@deepseek-ai/dsh-llm'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session'
+
+/** Cordis companion plugin name. */
+export const name = 'session-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Per-session bookkeeping for relational log checks. */
+interface SessionTrace {
+ lastSeq: number
+ openTurn: number | null
+ openStep: number | null
+ nextTurn: number
+ nextStep: number
+ pendingCalls: Set
+}
+
+/** One accepted event's deferred mutation of a committed session trace. */
+interface SessionTraceTransition {
+ scalars: Pick
+ pendingCalls:
+ | { kind: 'none' }
+ | { kind: 'add' | 'delete'; callId: CallId }
+ | { kind: 'clear' }
+}
+
+/** Assert that a step-scoped event names the currently open turn and step. */
+function requireOpenStep(
+ trace: SessionTrace,
+ kind: string,
+ turn: number,
+ step: number,
+ fail: InvariantFailure,
+): void {
+ if (trace.openTurn !== turn || trace.openStep !== step) {
+ fail(`${kind} names turn ${turn}/step ${step} but open is turn ${trace.openTurn}/step ${trace.openStep}`)
+ }
+}
+
+/** Validate one candidate event without mutating the committed trace. */
+function validateEvent(
+ trace: SessionTrace,
+ event: SessionEvent,
+ fail: InvariantFailure,
+): SessionTraceTransition {
+ if (event.seq <= trace.lastSeq) {
+ fail(`seq must strictly increase: saw ${event.seq} after ${trace.lastSeq}`)
+ }
+ let openTurn = trace.openTurn
+ let openStep = trace.openStep
+ let nextTurn = trace.nextTurn
+ let nextStep = trace.nextStep
+ let pendingCalls: SessionTraceTransition['pendingCalls'] = { kind: 'none' }
+
+ // SessionEventMap is merge-extensible, so the default enforces turn
+ // enclosure for package-added events as well as the built-in variants.
+ switch (event.type) {
+ case 'turn/start': {
+ if (trace.openTurn !== null) {
+ fail(`turn/start ${event.data.turn} while turn ${trace.openTurn} is still open`)
+ }
+ if (event.data.turn !== trace.nextTurn) {
+ fail(`turn/start expected turn ${trace.nextTurn}, got ${event.data.turn}`)
+ }
+ openTurn = event.data.turn
+ nextStep = 1
+ break
+ }
+ case 'turn/end': {
+ if (trace.openTurn !== event.data.turn) {
+ fail(`turn/end ${event.data.turn} does not match open turn ${trace.openTurn}`)
+ }
+ if (trace.openStep !== null) {
+ fail(`turn/end ${event.data.turn} while step ${trace.openStep} is still open`)
+ }
+ openTurn = null
+ nextTurn += 1
+ break
+ }
+ case 'step/start': {
+ if (trace.openTurn !== event.data.turn) {
+ fail(`step/start in turn ${event.data.turn} but open turn is ${trace.openTurn}`)
+ }
+ if (trace.openStep !== null) {
+ fail(`step/start ${event.data.step} while step ${trace.openStep} is still open`)
+ }
+ if (event.data.step !== trace.nextStep) {
+ fail(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`)
+ }
+ openStep = event.data.step
+ break
+ }
+ case 'step/end': {
+ requireOpenStep(trace, 'step/end', event.data.turn, event.data.step, fail)
+ pendingCalls = { kind: 'clear' }
+ openStep = null
+ nextStep += 1
+ break
+ }
+ case 'assistant/chunk': {
+ requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step, fail)
+ break
+ }
+ case 'assistant/message': {
+ requireOpenStep(trace, 'assistant/message', event.data.turn, event.data.step, fail)
+ break
+ }
+ case 'tool/call': {
+ requireOpenStep(trace, 'tool/call', event.data.turn, event.data.step, fail)
+ pendingCalls = { kind: 'add', callId: event.data.callId }
+ break
+ }
+ case 'tool/result': {
+ // Session has already validated a provenance-backed content rewrite.
+ // It is durable turn work, not a second execution of the original call.
+ if (event.surfaceOp !== 'append') {
+ if (trace.openTurn === null) {
+ fail('tool/result surface replacement appended outside any open turn')
+ }
+ break
+ }
+ requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step, fail)
+ const syntheticInterrupted = event.data.isError && event.data.error?.code === 'interrupted'
+ if (!trace.pendingCalls.has(event.data.callId) && !syntheticInterrupted) {
+ fail(`tool/result for ${event.data.callId} with no prior tool/call in this step`)
+ }
+ pendingCalls = { kind: 'delete', callId: event.data.callId }
+ break
+ }
+ default: {
+ if (trace.openTurn === null) {
+ fail(`${event.type} appended outside any open turn (every event must be turn-enclosed)`)
+ }
+ break
+ }
+ }
+ return {
+ scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
+ pendingCalls,
+ }
+}
+
+/** Apply one already-validated transition after its event commits. */
+function applyTransition(trace: SessionTrace, transition: SessionTraceTransition): void {
+ Object.assign(trace, transition.scalars)
+ switch (transition.pendingCalls.kind) {
+ case 'none':
+ break
+ case 'add':
+ trace.pendingCalls.add(transition.pendingCalls.callId)
+ break
+ case 'delete':
+ trace.pendingCalls.delete(transition.pendingCalls.callId)
+ break
+ case 'clear':
+ trace.pendingCalls.clear()
+ break
+ /* v8 ignore next -- validateEvent produces this closed transition union */
+ default:
+ assertNever(transition.pendingCalls, 'session trace pending-call transition')
+ }
+}
+
+/** Install the session contribution into its child registration fiber. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ const traces = new WeakMap()
+ const stagedTransitions = new WeakMap()
+
+ const freshTrace = (): SessionTrace => ({
+ lastSeq: -1,
+ openTurn: null,
+ openStep: null,
+ nextTurn: 1,
+ nextStep: 1,
+ pendingCalls: new Set(),
+ })
+
+ const seedSession = (session: Session): SessionTrace => {
+ const trace = freshTrace()
+ traces.set(session, trace)
+ for (const event of session.events) {
+ applyTransition(trace, validateEvent(trace, event, fail))
+ }
+ return trace
+ }
+
+ /* v8 ignore next -- session/event always follows list() or session/created seeding */
+ const traceFor = (session: Session): SessionTrace => traces.get(session) ?? seedSession(session)
+
+ for (const session of ctx.sessions.list()) seedSession(session)
+
+ ctx.on('session/created', (session) => { seedSession(session) }, { global: true })
+
+ ctx.on('session/event', (session, event) => {
+ const staged = stagedTransitions.get(event)
+ /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
+ if (staged === undefined || staged.session !== session) {
+ return fail('session/event reached publication without matching pre-commit validation')
+ }
+ stagedTransitions.delete(event)
+ applyTransition(staged.trace, staged.transition)
+ }, { global: true })
+
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ const trace = traceFor(session)
+ const transition = validateEvent(trace, event, fail)
+ // A later dispatch listener may veto. Validation is pure, so abandoning
+ // this weakly keyed transition does not advance or retain the session.
+ stagedTransitions.set(event, { session, trace, transition })
+ }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the session invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/session/tests/invariant.spec.ts b/packages/core/session/tests/invariant.spec.ts
new file mode 100644
index 0000000000..bc0a79759d
--- /dev/null
+++ b/packages/core/session/tests/invariant.spec.ts
@@ -0,0 +1,344 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { createScope, scopeTarget } from '@deepseek-ai/dsh-scope'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise<{ ctx: Context; fiber: Awaited> }> {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ const fiber = await ctx.plugin(SessionInvariant)
+ return { ctx, fiber }
+}
+
+describe('session-log invariants', () => {
+ it('keeps registration global when the companion is mounted under a scope', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ let scopedCtx!: Context
+ await ctx.plugin(Object.assign((inner: Context) => {
+ scopedCtx = createScope(inner, {}).ctx
+ }, { inject: ['sessions', 'invariants'] }))
+ await scopedCtx.plugin(SessionInvariant)
+ const session = ctx.sessions.create(SessionId('global-under-scoped-invariants'))
+ expect(() => {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ }).not.toThrow()
+ })
+
+ it('accepts a well-formed turn, step, and tool sequence', async () => {
+ const { ctx } = await setup()
+ const session = ctx.sessions.create()
+ expect(() => {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
+ session.append('step/start', { turn: 1, step: 1 })
+ session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'h' } })
+ session.append('assistant/message', {
+ provenance: { provider: 'mock', model: 'mock' },
+ turn: 1,
+ step: 1,
+ content: [{ type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' }],
+ }, { surfaceOp: 'append' })
+ session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+ session.append('tool/result', { turn: 1, step: 1, callId: CallId('c1'), content: [], isError: false }, { surfaceOp: 'append' })
+ session.append('step/end', { turn: 1, step: 1 })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ }).not.toThrow()
+ })
+
+ it('does not advance committed trace state when a later dispatch listener vetoes', async () => {
+ const { ctx } = await setup()
+ const session = ctx.sessions.create(SessionId('dispatch-veto-rollback'))
+ let veto = true
+ ctx.on('internal/dispatch', (_mode, name) => {
+ if (name !== 'session/event' || !veto) return
+ veto = false
+ throw new Error('later dispatch veto')
+ })
+ expect(() => session.append('turn/start', {
+ turn: 1,
+ trigger: { kind: 'message', source: { kind: 'user' } },
+ })).toThrow('later dispatch veto')
+ expect(session.events).toEqual([])
+ expect(() => {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ }).not.toThrow()
+ })
+
+ it('applies the committed transition after another postcommit observer throws', async () => {
+ const { ctx } = await setup()
+ const warnings: string[] = []
+ ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
+ const session = ctx.sessions.create(SessionId('postcommit-peer'))
+ ctx.on('session/event', () => { throw new Error('hostile observer') }, { prepend: true })
+ expect(() => {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ }).not.toThrow()
+ expect(warnings).toHaveLength(2)
+ })
+
+ it('rejects non-monotonic event sequence numbers', async () => {
+ const { ctx } = await setup()
+ const session = ctx.sessions.create()
+ ctx.emit(scopeTarget(session, undefined), 'session/event', session, {
+ type: 'turn/start',
+ seq: 0,
+ time: 1,
+ data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+ } as never)
+ expect(() => { ctx.emit(scopeTarget(session, undefined), 'session/event', session, {
+ type: 'turn/end',
+ seq: 0,
+ time: 2,
+ data: { turn: 1, reason: { kind: 'completed' } },
+ } as never) }).toThrow(/seq must strictly increase/)
+ })
+
+ it('enforces turn numbering and enclosure', async () => {
+ const first = await setup()
+ const open = first.ctx.sessions.create()
+ open.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => open.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
+ .toThrow(/turn 1 is still open/)
+ expect(() => open.append('turn/end', { turn: 2, reason: { kind: 'completed' } }))
+ .toThrow(/does not match open turn 1/)
+
+ const second = (await setup()).ctx.sessions.create()
+ second.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ second.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ expect(() => second.append('turn/start', { turn: 3, trigger: { kind: 'message', source: { kind: 'user' } } }))
+ .toThrow(/expected turn 2, got 3/)
+
+ const outside = (await setup()).ctx.sessions.create()
+ expect(() => outside.append('user/message', {
+ content: [{ type: 'text', text: 'hi' }],
+ source: { kind: 'user' },
+ }, { surfaceOp: 'append' })).toThrow(/outside any open turn/)
+ expect(() => outside.append('steering/message', {
+ turn: 1,
+ content: [{ type: 'text', text: 'go' }],
+ source: { kind: 'user' },
+ }, { surfaceOp: 'append' })).toThrow(/outside any open turn/)
+ // Merge-extensible session events use the same default enclosure branch.
+ const appendUnknown = outside.append.bind(outside) as (type: string, data: unknown) => unknown
+ expect(() => { appendUnknown('plugin/marker', {}) }).toThrow(/outside any open turn/)
+ })
+
+ it('enforces open-step identity and numbering', async () => {
+ const wrongTurn = (await setup()).ctx.sessions.create()
+ wrongTurn.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => wrongTurn.append('step/start', { turn: 2, step: 1 })).toThrow(/open turn is 1/)
+
+ const nested = (await setup()).ctx.sessions.create()
+ nested.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ nested.append('step/start', { turn: 1, step: 1 })
+ expect(() => nested.append('step/start', { turn: 1, step: 2 })).toThrow(/while step 1 is still open/)
+ expect(() => nested.append('turn/end', { turn: 1, reason: { kind: 'completed' } }))
+ .toThrow(/while step 1 is still open/)
+ expect(() => nested.append('step/end', { turn: 1, step: 2 })).toThrow(/open is turn 1\/step 1/)
+ expect(() => nested.append('assistant/message', {
+ provenance: { provider: 'mock', model: 'mock' },
+ turn: 1,
+ step: 2,
+ content: [],
+ }, { surfaceOp: 'append' })).toThrow(/open is turn 1\/step 1/)
+
+ const skipped = (await setup()).ctx.sessions.create()
+ skipped.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ skipped.append('step/start', { turn: 1, step: 1 })
+ skipped.append('step/end', { turn: 1, step: 1 })
+ expect(() => skipped.append('step/start', { turn: 1, step: 3 }))
+ .toThrow(/expected step 2 in turn 1, got 3/)
+ })
+
+ it('requires step-scoped stream and tool events to name the open step', async () => {
+ const chunk = (await setup()).ctx.sessions.create()
+ chunk.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => chunk.append('assistant/chunk', {
+ turn: 1,
+ step: 1,
+ chunk: { type: 'text-delta', index: 0, text: 'x' },
+ })).toThrow(/open is turn 1\/step null/)
+
+ const tool = (await setup()).ctx.sessions.create()
+ tool.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ tool.append('step/start', { turn: 1, step: 1 })
+ expect(() => tool.append('tool/result', {
+ turn: 1,
+ step: 1,
+ callId: CallId('ghost'),
+ content: [],
+ isError: false,
+ }, { surfaceOp: 'append' })).toThrow(/no prior tool\/call/)
+ })
+
+ it('keeps fresh tool-result appends open-step checked', async () => {
+ const { ctx } = await setup()
+ const session = ctx.sessions.create()
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => session.append('tool/result', {
+ turn: 1,
+ step: 1,
+ callId: CallId('closed'),
+ content: [],
+ isError: false,
+ }, { surfaceOp: 'append' })).toThrow(/open is turn 1\/step null/)
+ })
+
+ it('treats a validated tool-result replacement as a turn-enclosed rewrite', 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 })
+ session.append('tool/call', {
+ turn: 1,
+ step: 1,
+ callId: CallId('rewrite'),
+ name: 'echo',
+ arguments: '{}',
+ })
+ const original = session.append('tool/result', {
+ turn: 1,
+ step: 1,
+ callId: CallId('rewrite'),
+ content: [{ type: 'text', text: 'original' }],
+ isError: false,
+ }, { 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' } } })
+ expect(() => session.append('tool/result', {
+ ...original.data,
+ content: [{ type: 'text', text: 'pruned' }],
+ }, {
+ surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+ sourceEventSeqs: [original.seq],
+ })).not.toThrow()
+ })
+
+ it('rejects a tool-result replacement outside a turn', 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 })
+ session.append('tool/call', {
+ turn: 1,
+ step: 1,
+ callId: CallId('rewrite'),
+ name: 'echo',
+ arguments: '{}',
+ })
+ const original = session.append('tool/result', {
+ turn: 1,
+ step: 1,
+ callId: CallId('rewrite'),
+ content: [{ type: 'text', text: 'original' }],
+ isError: false,
+ }, { surfaceOp: 'append' })
+ session.append('step/end', { turn: 1, step: 1 })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+ expect(() => session.append('tool/result', {
+ ...original.data,
+ content: [{ type: 'text', text: 'pruned' }],
+ }, {
+ surfaceOp: { op: 'replace', start: original.seq, end: original.seq },
+ sourceEventSeqs: [original.seq],
+ })).toThrow(/outside any open turn/)
+ })
+
+ it('allows interrupted repair results and unresolved calls at step end', async () => {
+ const repaired = (await setup()).ctx.sessions.create()
+ expect(() => {
+ repaired.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ repaired.append('step/start', { turn: 1, step: 1 })
+ repaired.append('tool/result', {
+ turn: 1,
+ step: 1,
+ callId: CallId('crashed'),
+ content: [],
+ isError: true,
+ error: { name: 'InterruptedError', code: 'interrupted' },
+ }, { surfaceOp: 'append' })
+ repaired.append('step/end', { turn: 1, step: 1 })
+ repaired.append('turn/end', { turn: 1, reason: { kind: 'interrupted' } })
+ }).not.toThrow()
+
+ const unresolved = (await setup()).ctx.sessions.create()
+ expect(() => {
+ unresolved.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ unresolved.append('step/start', { turn: 1, step: 1 })
+ unresolved.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+ unresolved.append('step/end', { turn: 1, step: 1 })
+ unresolved.append('turn/end', { turn: 1, reason: { kind: 'error', step: 1, message: 'boom' } })
+ }).not.toThrow()
+ })
+
+ it('does not let a result in a later step satisfy an earlier call', 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 })
+ session.append('tool/call', { turn: 1, step: 1, callId: CallId('c1'), name: 'echo', arguments: '{}' })
+ session.append('step/end', { turn: 1, step: 1 })
+ session.append('step/start', { turn: 1, step: 2 })
+ expect(() => session.append('tool/result', {
+ turn: 1,
+ step: 2,
+ callId: CallId('c1'),
+ content: [],
+ isError: false,
+ }, { surfaceOp: 'append' })).toThrow(/no prior tool\/call in this step/)
+ })
+
+ it('replays seeded sessions and tracks each session independently', async () => {
+ const { ctx } = await setup()
+ const badSeed = [
+ { type: 'turn/start' as const, seq: 0, time: 0, data: { turn: 1, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
+ { type: 'turn/start' as const, seq: 1, time: 0, data: { turn: 2, trigger: { kind: 'message' as const, source: { kind: 'user' as const } } } },
+ ]
+ expect(() => ctx.sessions.create(undefined, { seed: badSeed })).toThrow(InvariantError)
+
+ const a = ctx.sessions.create(SessionId('a'))
+ const b = ctx.sessions.create(SessionId('b'))
+ a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } }))
+ .not.toThrow()
+ })
+
+ it('rebuilds trace state for sessions that exist when the companion reloads', async () => {
+ const { ctx, fiber } = 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 })
+ await fiber.dispose()
+ await ctx.plugin(SessionInvariant)
+ expect(() => session.append('assistant/chunk', {
+ turn: 1,
+ step: 1,
+ chunk: { type: 'text-delta', index: 0, text: 'h' },
+ })).not.toThrow()
+ expect(() => session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } }))
+ .toThrow(/turn 1 is still open/)
+ })
+
+ it('removes all listeners when the companion is disposed', async () => {
+ const { ctx, fiber } = await setup()
+ const session = ctx.sessions.create()
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ await fiber.dispose()
+ expect(() => session.append('turn/start', {
+ turn: 2,
+ trigger: { kind: 'message', source: { kind: 'user' } },
+ })).not.toThrow()
+ })
+})
diff --git a/packages/core/session/tests/session.spec.ts b/packages/core/session/tests/session.spec.ts
index a17981146d..0c41af5b46 100644
--- a/packages/core/session/tests/session.spec.ts
+++ b/packages/core/session/tests/session.spec.ts
@@ -717,10 +717,11 @@ describe('SessionStore', () => {
// may create an unrelated property with the old implementation's name,
// but cannot suppress the durable event feed.
expect(Reflect.set(session, 'onAppend', undefined)).toBe(true)
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
- expect(events).toHaveLength(1)
- expect(events[0]![0]).toBe(session)
- expect(events[0]![1].type).toBe('user/message')
+ expect(events).toHaveLength(2)
+ expect(events[1]![0]).toBe(session)
+ expect(events[1]![1].type).toBe('user/message')
expect(ctx.sessions.get(session.id)).toBe(session)
expect(ctx.sessions.list()).toEqual([session])
@@ -732,6 +733,7 @@ describe('SessionStore', () => {
const a = ctx.sessions.create(SessionId('fixed'))
expect(() => ctx.sessions.create(SessionId('fixed'))).toThrow('already exists')
+ a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
a.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
const forked = ctx.sessions.create(SessionId('fork'), { seed: [...a.events] })
expect(forked.deriveMessages()).toEqual(a.deriveMessages())
@@ -973,8 +975,9 @@ describe('SessionStore', () => {
ctx.on('session/event', (_session, event) => void events.push(event))
const session = ctx.sessions.create(SessionId('fixed'))
expect(ctx.sessions.get(SessionId('fixed'))).toBe(session)
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
- expect(events).toHaveLength(1)
+ expect(events.at(-1)?.type).toBe('user/message')
})
it('contains session/event observer failures after the append commit point', async () => {
@@ -1058,6 +1061,8 @@ describe('SessionStore', () => {
const ctx = new Context()
await ctx.plugin(SessionStore)
const session = ctx.sessions.create(SessionId('surface-dispatch-veto'))
+ 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: 'source' }],
source: { kind: 'user' },
@@ -1077,19 +1082,19 @@ describe('SessionStore', () => {
step: 1,
content: [{ type: 'text', text: 'replacement' }],
}, {
- surfaceOp: { op: 'replace', start: 0, end: 0 },
- sourceEventSeqs: [0],
+ surfaceOp: { op: 'replace', start: 2, end: 2 },
+ sourceEventSeqs: [2],
})).toThrow('reject surface candidate')
- expect(session.events).toHaveLength(1)
- expect(surface.nodes).toEqual([0])
+ expect(session.events).toHaveLength(3)
+ expect(surface.nodes).toEqual([2])
expect(surface.replaceGeneration).toBe(0)
session.append('user/message', {
content: [{ type: 'text', text: 'next' }],
source: { kind: 'user' },
}, { surfaceOp: 'append' })
- expect(surface.nodes).toEqual([0, 1])
+ expect(surface.nodes).toEqual([2, 3])
expect(surface.replaceGeneration).toBe(0)
})
diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts
index fc8ebfcd10..5243564b6c 100644
--- a/packages/core/session/tests/surface.spec.ts
+++ b/packages/core/session/tests/surface.spec.ts
@@ -30,6 +30,28 @@ function provenanceEvent(seq: number, sourceEventSeqs: unknown): SessionEvent {
} as unknown as SessionEvent
}
+function toolResultEvent(
+ seq: number,
+ callId: string,
+ surfaceOp: SurfaceEvent['surfaceOp'] = 'append',
+ sourceEventSeqs?: number[],
+): SessionEvent {
+ return {
+ type: 'tool/result',
+ seq,
+ time: seq,
+ data: {
+ turn: 1,
+ step: 1,
+ callId: CallId(callId),
+ content: [{ type: 'text', text: `result ${seq}` }],
+ isError: false,
+ },
+ surfaceOp,
+ ...sourceEventSeqs === undefined ? {} : { sourceEventSeqs },
+ }
+}
+
describe('foldSurface provenance', () => {
it('accepts absent or valid provenance and complete replacement coverage', () => {
const events = [
@@ -94,6 +116,33 @@ describe('foldSurface provenance', () => {
)
})
+describe('foldSurface tool-result rewrites', () => {
+ it('rejects a replacement spanning multiple current nodes', () => {
+ const events = [
+ provenanceEvent(0, undefined),
+ provenanceEvent(1, undefined),
+ toolResultEvent(2, 'rewrite', { op: 'replace', start: 0, end: 1 }, [0, 1]),
+ ]
+ expect(() => foldSurface(events)).toThrow(/must rewrite exactly one current node/)
+ })
+
+ it('rejects a replacement targeting a non-result node', () => {
+ const events = [
+ provenanceEvent(0, undefined),
+ toolResultEvent(1, 'rewrite', { op: 'replace', start: 0, end: 0 }, [0]),
+ ]
+ expect(() => foldSurface(events)).toThrow(/must target a current tool\/result/)
+ })
+
+ it('rejects changes outside tool-result content', () => {
+ const events = [
+ toolResultEvent(0, 'original'),
+ toolResultEvent(1, 'changed', { op: 'replace', start: 0, end: 0 }, [0]),
+ ]
+ expect(() => foldSurface(events)).toThrow(/may change only content/)
+ })
+})
+
describe('SurfaceManager', () => {
it('shares ordered entries and nested replacement ranges with foldSurface', () => {
const s = new Session(SessionId('shared-fold'))
diff --git a/packages/core/session/tsconfig.json b/packages/core/session/tsconfig.json
index b19b98c5ad..253a1c8793 100644
--- a/packages/core/session/tsconfig.json
+++ b/packages/core/session/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../core/scope"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/session/tsdown.config.ts b/packages/core/session/tsdown.config.ts
new file mode 100644
index 0000000000..e92275a7f5
--- /dev/null
+++ b/packages/core/session/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and optional invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/core/system-prompt/package.json b/packages/core/system-prompt/package.json
index 67161b79b4..6cf94f477e 100644
--- a/packages/core/system-prompt/package.json
+++ b/packages/core/system-prompt/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/core/system-prompt/src/invariant.ts b/packages/core/system-prompt/src/invariant.ts
new file mode 100644
index 0000000000..e199cc98b4
--- /dev/null
+++ b/packages/core/system-prompt/src/invariant.ts
@@ -0,0 +1,52 @@
+/** Package-owned prompt-assembly invariants. @module @deepseek-ai/dsh-system-prompt/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { PromptAssembly } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-system-prompt'
+const VARIABLE_NAME = /^[a-z][a-z0-9_]*$/
+
+/** Cordis companion plugin name. */
+export const name = 'system-prompt-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Validate the authoritative assembly returned by the waterfall. */
+function validateAssembly(assembly: PromptAssembly, fail: InvariantFailure): void {
+ const sectionNames = new Set()
+ for (const section of assembly.sections) {
+ if (section.name.length === 0) fail('assembled section names must be non-empty')
+ if (sectionNames.has(section.name)) fail(`assembled section name ${JSON.stringify(section.name)} is duplicated`)
+ sectionNames.add(section.name)
+ if (typeof section.text !== 'string') fail(`assembled section ${JSON.stringify(section.name)} text must be a string`)
+ }
+
+ for (const tool of assembly.tools) {
+ if (tool.name.length === 0) fail('assembled tool names must be non-empty')
+ }
+
+ for (const [name, value] of Object.entries(assembly.variables)) {
+ if (!VARIABLE_NAME.test(name)) fail(`assembled variable name ${JSON.stringify(name)} is invalid`)
+ if (value !== undefined && typeof value !== 'string') {
+ fail(`assembled variable ${JSON.stringify(name)} must be a string or undefined`)
+ }
+ }
+}
+
+/** Install validation around the authoritative assembly waterfall result. */
+const install: InvariantInstaller = (ctx, fail) => {
+ ctx.on('system-prompt/assemble', async (_assembly, _context, next) => {
+ const assembled = await next()
+ validateAssembly(assembled, fail)
+ return assembled
+ }, { global: true, prepend: true })
+}
+
+/**
+ * Register the system-prompt invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/system-prompt/tests/invariant.spec.ts b/packages/core/system-prompt/tests/invariant.spec.ts
new file mode 100644
index 0000000000..ce03af0b9f
--- /dev/null
+++ b/packages/core/system-prompt/tests/invariant.spec.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
+import * as SystemPromptInvariant from '@deepseek-ai/dsh-system-prompt/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SystemPromptInvariant)
+ return ctx
+}
+
+const valid = (): PromptAssembly => ({
+ sections: [{ name: 'identity', text: 'prompt' }],
+ tools: [{ name: 'echo', description: 'Echo', parameters: {} }],
+ variables: { cwd: '/repo', optional: undefined },
+})
+
+async function assemble(ctx: Context, result: PromptAssembly): Promise {
+ return ctx.waterfall(
+ ctx as never, 'system-prompt/assemble', valid(), {},
+ () => Promise.resolve(result),
+ )
+}
+
+describe('system-prompt invariants', () => {
+ it('accepts a well-formed authoritative assembly', async () => {
+ const ctx = await setup()
+ await expect(assemble(ctx, valid())).resolves.toEqual(valid())
+ })
+
+ it.each([
+ [{ ...valid(), sections: [{ name: '', text: 'x' }] }, /section names must be non-empty/],
+ [{ ...valid(), sections: [{ name: 'x', text: 'a' }, { name: 'x', text: 'b' }] }, /section name "x" is duplicated/],
+ [{ ...valid(), sections: [{ name: 'x', text: 1 as never }] }, /section "x" text must be a string/],
+ [{ ...valid(), tools: [{ name: '', description: 'x', parameters: {} }] }, /tool names must be non-empty/],
+ [{ ...valid(), variables: { Bad: 'x' } }, /variable name "Bad" is invalid/],
+ [{ ...valid(), variables: { value: 1 as never } }, /variable "value" must be a string or undefined/],
+ ])('rejects malformed authoritative assembly %#', async (assembly, message) => {
+ const ctx = await setup()
+ await expect(assemble(ctx, assembly)).rejects.toThrow(message)
+ })
+})
diff --git a/packages/core/system-prompt/tsconfig.json b/packages/core/system-prompt/tsconfig.json
index 91e7bf1ba4..c7de9a1b69 100644
--- a/packages/core/system-prompt/tsconfig.json
+++ b/packages/core/system-prompt/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../core/scope"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/core/tools/package.json b/packages/core/tools/package.json
index 2fe3cbd448..535e60f60b 100644
--- a/packages/core/tools/package.json
+++ b/packages/core/tools/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,12 +28,13 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
- "@deepseek-ai/dsh-user-approval": "^0.0.1",
"@deepseek-ai/dsh-code-runtime": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
+ "@deepseek-ai/dsh-user-approval": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"dependencies": {
@@ -36,12 +42,13 @@
},
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
- "@deepseek-ai/dsh-user-approval": "workspace:^",
"@deepseek-ai/dsh-code-runtime": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
+ "@deepseek-ai/dsh-user-approval": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/core/tools/src/invariant.ts b/packages/core/tools/src/invariant.ts
new file mode 100644
index 0000000000..2f5f27a281
--- /dev/null
+++ b/packages/core/tools/src/invariant.ts
@@ -0,0 +1,69 @@
+/** Package-owned tool-pipeline invariants. @module @deepseek-ai/dsh-tools/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ToolExecution, ToolExecutionResult } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tools'
+
+/** Cordis companion plugin name. */
+export const name = 'tools-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+type ToolStage = 'pre' | 'execute' | 'post'
+
+/** Validate the immutable final execution/result snapshot. */
+function validateResult(
+ exec: Readonly,
+ result: Readonly,
+ fail: InvariantFailure,
+): void {
+ if (!Object.isFrozen(exec)) fail('tools/result execution must be frozen before publication')
+ if (!Object.isFrozen(result) || !Object.isFrozen(result.content)) {
+ fail('tools/result outcome and content must be frozen before publication')
+ }
+ if (exec.name.length === 0 || String(exec.callId).length === 0) {
+ fail('tools/result execution must carry non-empty name and callId')
+ }
+}
+
+/** Install monotonic pipeline and final-snapshot checks. */
+const install: InvariantInstaller = (ctx, fail) => {
+ const stages = new WeakMap()
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName === 'tools/pre-execute') {
+ const exec = args[0] as ToolExecution
+ if (stages.has(exec)) fail('tools/pre-execute repeated for one execution')
+ stages.set(exec, 'pre')
+ return
+ }
+ if (eventName === 'tools/execute') {
+ const exec = args[0] as ToolExecution
+ if (stages.get(exec) !== 'pre') fail('tools/execute must follow tools/pre-execute')
+ stages.set(exec, 'execute')
+ return
+ }
+ if (eventName === 'tools/post-execute') {
+ const exec = args[0] as ToolExecution
+ const previous = stages.get(exec)
+ if (previous !== 'pre' && previous !== 'execute') {
+ fail('tools/post-execute must follow tools/pre-execute or tools/execute')
+ }
+ stages.set(exec, 'post')
+ return
+ }
+ if (eventName !== 'tools/result') return
+ const [exec, result] = args as [Readonly, Readonly]
+ validateResult(exec, result, fail)
+ stages.delete(exec)
+ }, { global: true })
+}
+
+/**
+ * Register the tools invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/core/tools/tests/invariant.spec.ts b/packages/core/tools/tests/invariant.spec.ts
new file mode 100644
index 0000000000..660c2c6f10
--- /dev/null
+++ b/packages/core/tools/tests/invariant.spec.ts
@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { ToolExecution, ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
+import * as ToolsInvariant from '@deepseek-ai/dsh-tools/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(ToolsInvariant)
+ return ctx
+}
+
+const execution = (overrides: Partial = {}): ToolExecution => ({
+ token: Symbol('tool') as ToolExecutionToken,
+ callId: CallId('call-1'),
+ name: 'echo',
+ arguments: Object.freeze({ text: 'hi' }),
+ ...overrides,
+})
+
+const outcome = (): ToolExecutionResult => Object.freeze({
+ content: Object.freeze([{ type: 'text' as const, text: 'ok' }]) as never,
+ isError: false,
+ value: null,
+})
+
+function emitResult(ctx: Context, exec: ToolExecution, result: ToolExecutionResult): void {
+ ctx.emit(scopeTarget(ctx as never, undefined), 'tools/result', exec, result)
+}
+
+async function stage(ctx: Context, name: 'tools/pre-execute' | 'tools/execute', exec: ToolExecution): Promise {
+ if (name === 'tools/pre-execute') {
+ await ctx.waterfall(ctx as never, name, exec, () => Promise.resolve({ kind: 'allow' as const }))
+ } else {
+ await ctx.waterfall(ctx as never, name, exec, () => Promise.resolve(outcome()))
+ }
+}
+
+describe('tool-pipeline invariants', () => {
+ it('accepts dispatch and denial stage orders with frozen results', async () => {
+ const ctx = await setup()
+ const dispatched = execution()
+ await stage(ctx, 'tools/pre-execute', dispatched)
+ await stage(ctx, 'tools/execute', dispatched)
+ await ctx.waterfall(ctx as never, 'tools/post-execute', dispatched, outcome(), () => Promise.resolve({ kind: 'accept' as const }))
+ Object.freeze(dispatched)
+ emitResult(ctx, dispatched, outcome())
+
+ const denied = execution({ callId: CallId('call-2') })
+ await stage(ctx, 'tools/pre-execute', denied)
+ await ctx.waterfall(ctx as never, 'tools/post-execute', denied, outcome(), () => Promise.resolve({ kind: 'accept' as const }))
+ Object.freeze(denied)
+ emitResult(ctx, denied, outcome())
+ ctx.emit('tools/change')
+ })
+
+ it('rejects repeated and out-of-order pipeline stages', async () => {
+ const ctx = await setup()
+ const exec = execution()
+ await stage(ctx, 'tools/pre-execute', exec)
+ await expect(stage(ctx, 'tools/pre-execute', exec)).rejects.toThrow(/repeated/)
+
+ const noPre = execution({ callId: CallId('call-2') })
+ await expect(stage(ctx, 'tools/execute', noPre)).rejects.toThrow(/must follow tools\/pre-execute/)
+ expect(() => ctx.waterfall(
+ ctx as never, 'tools/post-execute', noPre, outcome(),
+ () => Promise.resolve({ kind: 'accept' as const }),
+ )).toThrow(/must follow tools\/pre-execute or tools\/execute/)
+ })
+
+ it('rejects mutable or anonymous final snapshots', async () => {
+ const ctx = await setup()
+ expect(() => { emitResult(ctx, execution(), outcome()) }).toThrow(/execution must be frozen/)
+
+ const exec = Object.freeze(execution())
+ expect(() => { emitResult(ctx, exec, { content: [], isError: false, value: null }) })
+ .toThrow(/outcome and content must be frozen/)
+
+ const anonymous = Object.freeze(execution({ name: '' }))
+ expect(() => { emitResult(ctx, anonymous, outcome()) }).toThrow(/non-empty name and callId/)
+ })
+})
diff --git a/packages/core/tools/tsconfig.json b/packages/core/tools/tsconfig.json
index c94b270c8c..918112d7d0 100644
--- a/packages/core/tools/tsconfig.json
+++ b/packages/core/tools/tsconfig.json
@@ -34,6 +34,9 @@
},
{
"path": "../../ui/user-approval"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/examples/acp-demo/package.json b/packages/examples/acp-demo/package.json
index 1343e9f713..370dd39fbf 100644
--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -14,6 +14,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./bin": {
"types": "./lib/types/bin.d.ts",
"default": "./lib/bin.js"
@@ -23,6 +27,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -32,32 +37,34 @@
"peerDependencies": {
"@cordisjs/plugin-include": "^1.0.4",
"@cordisjs/plugin-loader": "^1.0.0-rc.5",
- "@deepseek-ai/dsh-app-boot": "^0.0.1",
"@deepseek-ai/dsh-acp": "^0.0.1",
"@deepseek-ai/dsh-commands": "^0.0.1",
"@deepseek-ai/dsh-command-goal": "^0.0.1",
"@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
- "@deepseek-ai/dsh-workspace-context": "^0.0.1",
+ "@deepseek-ai/dsh-app-boot": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"@deepseek-ai/dsh-user-interaction": "^0.0.1",
+ "@deepseek-ai/dsh-workspace-context": "^0.0.1",
"cordis": "^4.0.0-rc.7",
"schemastery": "^3.17.0"
},
"devDependencies": {
"@cordisjs/plugin-include": "workspace:^",
"@cordisjs/plugin-loader": "workspace:^",
- "@deepseek-ai/dsh-app-boot": "workspace:^",
"@deepseek-ai/dsh-acp": "workspace:^",
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-command-goal": "workspace:^",
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
- "@deepseek-ai/dsh-tools": "workspace:^",
- "@deepseek-ai/dsh-system-prompt": "workspace:^",
- "@deepseek-ai/dsh-workspace-context": "workspace:^",
+ "@deepseek-ai/dsh-app-boot": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+ "@deepseek-ai/dsh-system-prompt": "workspace:^",
+ "@deepseek-ai/dsh-tools": "workspace:^",
"@deepseek-ai/dsh-user-interaction": "workspace:^",
+ "@deepseek-ai/dsh-workspace-context": "workspace:^",
"cordis": "^4.0.0-rc.7",
"schemastery": "^3.17.0"
}
diff --git a/packages/examples/acp-demo/src/invariant.ts b/packages/examples/acp-demo/src/invariant.ts
new file mode 100644
index 0000000000..95b57b57e1
--- /dev/null
+++ b/packages/examples/acp-demo/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-acp-demo`.
+ * @module @deepseek-ai/dsh-acp-demo/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-acp-demo'
+
+/** Cordis companion plugin name. */
+export const name = 'acp-demo-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this composition package owns no independent event stream or mutable data;
+ * Loader and built-entry tests cover its wiring.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/examples/acp-demo/tests/acp-agent.spec.ts b/packages/examples/acp-demo/tests/acp-agent.spec.ts
index 08c3927fe5..aab40173c7 100644
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -21,7 +21,14 @@ import * as acpAgent from '../src/index.ts'
*/
async function mount(config: acpAgent.Config, withBash = false): Promise {
const ctx = new Context()
- if (withBash) ctx.provide('bash', { sandboxMode: undefined })
+ if (withBash) {
+ ctx.provide('bash', {
+ sandboxMode: undefined,
+ resolve() { throw new Error('composition test does not execute bash') },
+ run() { throw new Error('composition test does not execute bash') },
+ start() { throw new Error('composition test does not execute bash') },
+ })
+ }
await ctx.plugin(acpAgent, config)
// The bundle mounts its children inside apply() (not awaited there); let their
// fibers settle so the spine services are ready.
diff --git a/packages/examples/acp-demo/tsconfig.json b/packages/examples/acp-demo/tsconfig.json
index d3fc190640..5bd1627345 100644
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -46,6 +46,9 @@
},
{
"path": "../../session-persistence/session-persistence-jsonl"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/examples/acp-demo/tsdown.config.ts b/packages/examples/acp-demo/tsdown.config.ts
index 9dd130b30d..2fa93780be 100644
--- a/packages/examples/acp-demo/tsdown.config.ts
+++ b/packages/examples/acp-demo/tsdown.config.ts
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
* matching every package.
*/
export default defineConfig({
- entry: ['lib/types/index.js', 'lib/types/bin.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index 4b271ccfbc..f7bc0a98c8 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -22,7 +22,12 @@ Read this package for the whole plugin tree and its composition order.
@deepseek-ai/dsh-goal-session optional same-session goal-round driver
@deepseek-ai/dsh-llm-retry bounded transient request retry policy
@deepseek-ai/dsh-tasks generic background-task registry
-@deepseek-ai/dsh-invariants dev-mode event-contract assertions
+@deepseek-ai/dsh-invariants configurable invariant registry service
+@deepseek-ai/dsh-session/invariant
+@deepseek-ai/dsh-agent/invariant
+@deepseek-ai/dsh-scope/invariant
+@deepseek-ai/dsh-agent-loop/invariant
+ package-owned relational checks
@deepseek-ai/dsh-tool-bash the model-facing bash schema
@deepseek-ai/dsh-workspace-context AGENTS.md/CLAUDE.md workspace context loader
@deepseek-ai/dsh-tool-skill session-prefix skill catalog + model-facing loader schema
@@ -46,11 +51,13 @@ This is the [interface/implementation/consumer seam](../../../.agents/notes/impl
```ts
import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, llmRetry? }
+// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants?, llmRetry? }
// workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
```
-The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `llmRetry` to the bounded retry policy; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `llmRetry` to the bounded retry policy; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-home`](../../util/home/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+
+For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` keeps the package-owned companions mounted but suppresses the blocked owner. Blocklist matches override allowlist matches; see [`dsh-invariants`](../../support/invariants/README.md) for regex and lifecycle rules.
## Why a code bundle, not a shared YAML include
@@ -69,4 +76,4 @@ No direct invalidation; the named consumer owns any request-prefix changes.
## Known Limitations and Deferred Work
- **Most of the spine set is fixed in code** — `apply()` always mounts the core services and `tool-bash`; config can omit bundled goals, skills, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
-- **`dsh-invariants` mounts unconditionally** — this bundle has no toggle, so every composition using it pays the dev-mode relational assertions; Session's always-on validation and freezing are separate.
+- **The invariant seam and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
diff --git a/packages/examples/agent-spine-demo/package.json b/packages/examples/agent-spine-demo/package.json
index caac8c051b..b39e0fd178 100644
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -27,11 +32,11 @@
"@deepseek-ai/dsh-agent-loop": "^0.0.1",
"@deepseek-ai/dsh-goal": "^0.0.1",
"@deepseek-ai/dsh-goal-session": "^0.0.1",
- "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-home": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-llm-retry": "^0.0.1",
- "@deepseek-ai/dsh-workspace-context": "^0.0.1",
+ "@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-skill": "^0.0.1",
"@deepseek-ai/dsh-skill-local": "^0.0.1",
@@ -42,6 +47,7 @@
"@deepseek-ai/dsh-tool-skill": "^0.0.1",
"@deepseek-ai/dsh-tool-tasks": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
+ "@deepseek-ai/dsh-workspace-context": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
@@ -51,11 +57,11 @@
"@deepseek-ai/dsh-goal": "workspace:^",
"@deepseek-ai/dsh-goal-session": "workspace:^",
"@deepseek-ai/dsh-fs-local": "workspace:^",
- "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-home": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-retry": "workspace:^",
- "@deepseek-ai/dsh-workspace-context": "workspace:^",
+ "@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-skill": "workspace:^",
"@deepseek-ai/dsh-skill-local": "workspace:^",
@@ -66,6 +72,7 @@
"@deepseek-ai/dsh-tool-skill": "workspace:^",
"@deepseek-ai/dsh-tool-tasks": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
+ "@deepseek-ai/dsh-workspace-context": "workspace:^",
"cordis": "^4.0.0-rc.7"
},
"dependencies": {
diff --git a/packages/examples/agent-spine-demo/src/index.ts b/packages/examples/agent-spine-demo/src/index.ts
index b4724ac607..049bdc9076 100644
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -22,7 +22,11 @@ import GoalService, { type Config as GoalDomainConfig } from '@deepseek-ai/dsh-g
import * as goalSession from '@deepseek-ai/dsh-goal-session'
import * as toolGoal from '@deepseek-ai/dsh-tool-goal'
import TaskService from '@deepseek-ai/dsh-tasks'
-import * as invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService, { type Config as InvariantConfig } from '@deepseek-ai/dsh-invariants'
+import * as sessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as scopeInvariant from '@deepseek-ai/dsh-scope/invariant'
+import * as agentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import * as toolBash from '@deepseek-ai/dsh-tool-bash'
import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
@@ -63,8 +67,9 @@ export interface GoalConfig {
* skill registry/local provider/tool consumer, `workspaceContext` to the
* workspace-context loader, `llmRetry` to the bounded request-recovery policy,
* and `toolBash`/`toolTasks` to the model-facing tool plugins this bundle owns.
- * `goals` opts into and configures the persisted goal
- * domain plus its model tool and same-session driver. Owner schemas supply defaults for optional input;
+ * `goals` opts into and configures the persisted goal domain plus its model tool
+ * and same-session driver; `invariants` configures global and package-filtered
+ * relational checks. Owner schemas supply defaults for optional input;
* workspace context instead requires an explicit byte budget or `false` because
* it changes model-visible input. Producer opt-in stays producer-local:
* `toolBash` configures bash only; independently composed producers keep their
@@ -91,6 +96,8 @@ export interface Config {
toolBash?: toolBash.Config
/** Generic background-task controls; set false to keep the task service without model-facing task tools. */
toolTasks?: toolTasks.Config | false
+ /** Global enablement and package-name filters for invariant companions. */
+ invariants?: InvariantConfig
/** Opt-in persisted same-session goal stack; set false or omit to leave it unmounted. */
goals?: GoalConfig | false
/** Bounded transient model-request retry policy. */
@@ -131,9 +138,10 @@ export const Config = z.intersect([
workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
toolBash: ToolBashConfigSchema,
toolTasks: z.union([z.const(false), ToolTasksConfigSchema]),
+ invariants: InvariantService.Config,
goals: z.union([z.const(false), GoalConfigSchema]),
llmRetry: LlmRetryConfigSchema,
- }) as unknown as z>,
+ }) as unknown as z>,
]) as unknown as z
/**
@@ -152,6 +160,7 @@ export function pickSpineConfig(config: Omit): Omit {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
index 19c35b5624..2f01b21382 100644
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -12,6 +12,10 @@ import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
import { CallId, LlmAdapter, LlmError, type GenerateOptions, type Message, type StreamChunk } from '@deepseek-ai/dsh-llm'
import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+import * as sessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as scopeInvariant from '@deepseek-ai/dsh-scope/invariant'
+import * as agentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
declare module '@deepseek-ai/dsh-tasks' {
interface TaskKindMap {
@@ -44,7 +48,14 @@ async function mount(config: agentCore.Config, withBash = false): Promise {
expect(ctx.get('skills')).toBeDefined()
expect(ctx.get('agents')).toBeDefined()
expect(ctx.get('tasks')).toBeDefined()
+ expect(ctx.get('invariants')).toBeDefined()
expect(ctx.get('agentLoop')).toBeDefined()
expect(ctx.get('goals')).toBeUndefined()
await ctx.fiber.dispose()
@@ -156,6 +168,28 @@ describe('dsh-agent-spine-demo bundle', () => {
await ctx.fiber.dispose()
})
+ it('mounts package companions and forwards invariant selection config', async () => {
+ const nestedTurn = (ctx: Context): void => {
+ const session = ctx.sessions.create()
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+ }
+
+ const enabled = await mount({ workspaceContext: false })
+ expect(() => { nestedTurn(enabled) }).toThrow(/turn 1 is still open/)
+ await enabled.fiber.dispose()
+
+ for (const invariants of [
+ { enabled: false },
+ { package_allowlist: ['^@deepseek-ai/dsh-agent$'] },
+ { package_blocklist: ['^@deepseek-ai/dsh-session$'] },
+ ]) {
+ const filtered = await mount({ workspaceContext: false, invariants })
+ expect(() => { nestedTurn(filtered) }).not.toThrow()
+ await filtered.fiber.dispose()
+ }
+ })
+
it('loads and configures bounded request recovery for every bundled front door', async () => {
const adapter = new TransientOnceAdapter()
const ctx = await mount({
@@ -457,6 +491,7 @@ describe('dsh-agent-spine-demo bundle', () => {
skills: { enabled: false },
toolBash: { enableRunInBackground: false },
toolTasks: false as const,
+ invariants: { enabled: false },
llmRetry: { maxTransientRetries: 1, jitterRatio: 0 },
}
@@ -469,6 +504,7 @@ describe('dsh-agent-spine-demo bundle', () => {
skills: appConfig.skills,
toolBash: appConfig.toolBash,
toolTasks: appConfig.toolTasks,
+ invariants: appConfig.invariants,
llmRetry: appConfig.llmRetry,
})
expect(agentCore.pickSpineConfig({ workspaceContext: false })).toEqual({ workspaceContext: false })
@@ -531,4 +567,16 @@ describe('dsh-agent-spine-demo bundle', () => {
expect(unwrapped.Config).toBeDefined()
expect(typeof unwrapped.apply).toBe('function')
})
+
+ it('keeps each standard-spine invariant companion loadable through the real Loader unwrap path', () => {
+ const loader = Object.create(Loader.prototype) as Loader
+ for (const companion of [sessionInvariant, agentInvariant, scopeInvariant, agentLoopInvariant]) {
+ expect('default' in companion).toBe(false)
+ const unwrapped = loader.unwrapExports(companion) as Record
+ expect(unwrapped).toBe(companion)
+ expect(typeof unwrapped.name).toBe('string')
+ expect(unwrapped.inject).toContain('invariants')
+ expect(typeof unwrapped.apply).toBe('function')
+ }
+ })
})
diff --git a/packages/examples/cli-demo/package.json b/packages/examples/cli-demo/package.json
index 7b035e2524..1c00a32891 100644
--- a/packages/examples/cli-demo/package.json
+++ b/packages/examples/cli-demo/package.json
@@ -14,6 +14,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./bin": {
"types": "./lib/types/bin.d.ts",
"default": "./lib/bin.js"
@@ -23,6 +27,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -35,6 +40,7 @@
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
"@deepseek-ai/dsh-app-boot": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
@@ -49,6 +55,7 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
"@deepseek-ai/dsh-app-boot": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
diff --git a/packages/examples/cli-demo/src/invariant.ts b/packages/examples/cli-demo/src/invariant.ts
new file mode 100644
index 0000000000..8eb40e9268
--- /dev/null
+++ b/packages/examples/cli-demo/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-cli-demo`.
+ * @module @deepseek-ai/dsh-cli-demo/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-cli-demo'
+
+/** Cordis companion plugin name. */
+export const name = 'cli-demo-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this composition package owns no independent event stream or mutable data;
+ * Loader and built-entry tests cover its wiring.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/examples/cli-demo/tests/cli-demo.spec.ts b/packages/examples/cli-demo/tests/cli-demo.spec.ts
index 1433645eb5..47b43299fe 100644
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts
@@ -22,7 +22,14 @@ async function skillConfig(catalogDescriptionMaxLength?: number): Promise {
const ctx = new Context()
- if (withBash) ctx.provide('bash', { sandboxMode: undefined })
+ if (withBash) {
+ ctx.provide('bash', {
+ sandboxMode: undefined,
+ resolve() { throw new Error('composition test does not execute bash') },
+ run() { throw new Error('composition test does not execute bash') },
+ start() { throw new Error('composition test does not execute bash') },
+ })
+ }
contexts.push(ctx)
await ctx.plugin(cliDemo, config)
await new Promise(resolve => setTimeout(resolve, 80))
diff --git a/packages/examples/cli-demo/tsconfig.json b/packages/examples/cli-demo/tsconfig.json
index f25b1592ca..c7e3aed914 100644
--- a/packages/examples/cli-demo/tsconfig.json
+++ b/packages/examples/cli-demo/tsconfig.json
@@ -8,15 +8,38 @@
},
"include": ["src/**/*.ts"],
"references": [
- { "path": "../../../vendor/schemastery" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../llm/llm" },
- { "path": "../../core/session" },
- { "path": "../../core/agent" },
- { "path": "../../core/system-prompt" },
- { "path": "../../core/tools" },
- { "path": "../agent-spine-demo" },
- { "path": "../../session-persistence/session-persistence-jsonl" },
- { "path": "../../ui/app-boot" }
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/session"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../../core/system-prompt"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../agent-spine-demo"
+ },
+ {
+ "path": "../../session-persistence/session-persistence-jsonl"
+ },
+ {
+ "path": "../../ui/app-boot"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/examples/cli-demo/tsdown.config.ts b/packages/examples/cli-demo/tsdown.config.ts
index e5b164d46f..646855bea9 100644
--- a/packages/examples/cli-demo/tsdown.config.ts
+++ b/packages/examples/cli-demo/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
/** Builds the plugin and executable entries from declarations emitted by `tsc -b`. */
export default defineConfig({
- entry: ['lib/types/index.js', 'lib/types/bin.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/examples/jsonrpc-demo/package.json b/packages/examples/jsonrpc-demo/package.json
index 3b04fcc977..d103e3bd00 100644
--- a/packages/examples/jsonrpc-demo/package.json
+++ b/packages/examples/jsonrpc-demo/package.json
@@ -14,6 +14,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./bin": {
"types": "./lib/types/bin.d.ts",
"default": "./lib/bin.js"
@@ -23,6 +27,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -33,9 +38,11 @@
"@deepseek-ai/dsh-app-boot": "workspace:^"
},
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/examples/jsonrpc-demo/src/invariant.ts b/packages/examples/jsonrpc-demo/src/invariant.ts
new file mode 100644
index 0000000000..dd093a5418
--- /dev/null
+++ b/packages/examples/jsonrpc-demo/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-jsonrpc-demo`.
+ * @module @deepseek-ai/dsh-jsonrpc-demo/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-jsonrpc-demo'
+
+/** Cordis companion plugin name. */
+export const name = 'jsonrpc-demo-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this composition package owns no independent event stream or mutable data;
+ * Loader and built-entry tests cover its wiring.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/examples/jsonrpc-demo/tsconfig.json b/packages/examples/jsonrpc-demo/tsconfig.json
index 83d6cf5aa2..aba279d405 100644
--- a/packages/examples/jsonrpc-demo/tsconfig.json
+++ b/packages/examples/jsonrpc-demo/tsconfig.json
@@ -16,6 +16,9 @@
},
{
"path": "../../ui/app-boot"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/examples/jsonrpc-demo/tsdown.config.ts b/packages/examples/jsonrpc-demo/tsdown.config.ts
index aaa860edd0..a8864a84a9 100644
--- a/packages/examples/jsonrpc-demo/tsdown.config.ts
+++ b/packages/examples/jsonrpc-demo/tsdown.config.ts
@@ -4,7 +4,7 @@ import { defineConfig } from 'tsdown'
* Build the doc-only module and CLI entry; `tsc -b` supplies declarations.
*/
export default defineConfig({
- entry: ['lib/types/index.js', 'lib/types/bin.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/examples/tui-demo/package.json b/packages/examples/tui-demo/package.json
index be1cc01889..bcaa64c984 100644
--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -14,6 +14,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./bin": {
"types": "./lib/types/bin.d.ts",
"default": "./lib/bin.js"
@@ -23,6 +27,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -37,15 +42,16 @@
"@deepseek-ai/dsh-agent-loop": "^0.0.1",
"@deepseek-ai/dsh-commands": "^0.0.1",
"@deepseek-ai/dsh-command-goal": "^0.0.1",
- "@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
- "@deepseek-ai/dsh-workspace-context": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
+ "@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
"@deepseek-ai/dsh-tui": "^0.0.1",
"@deepseek-ai/dsh-tool-ask-user": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"@deepseek-ai/dsh-user-interaction": "^0.0.1",
+ "@deepseek-ai/dsh-workspace-context": "^0.0.1",
"cordis": "^4.0.0-rc.7",
"schemastery": "^3.17.0"
},
@@ -57,16 +63,17 @@
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-command-goal": "workspace:^",
- "@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
- "@deepseek-ai/dsh-system-prompt": "workspace:^",
- "@deepseek-ai/dsh-workspace-context": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
+ "@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+ "@deepseek-ai/dsh-system-prompt": "workspace:^",
"@deepseek-ai/dsh-tui": "workspace:^",
"@deepseek-ai/dsh-tool-ask-user": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
"@deepseek-ai/dsh-user-interaction": "workspace:^",
+ "@deepseek-ai/dsh-workspace-context": "workspace:^",
"cordis": "^4.0.0-rc.7",
"schemastery": "^3.17.0"
}
diff --git a/packages/examples/tui-demo/src/invariant.ts b/packages/examples/tui-demo/src/invariant.ts
new file mode 100644
index 0000000000..1bb55546bf
--- /dev/null
+++ b/packages/examples/tui-demo/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tui-demo`.
+ * @module @deepseek-ai/dsh-tui-demo/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tui-demo'
+
+/** Cordis companion plugin name. */
+export const name = 'tui-demo-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this composition-only package delegates mutable state and event streams
+ * to the agent spine, persistence, and TUI packages that own their checks.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/examples/tui-demo/tsconfig.json b/packages/examples/tui-demo/tsconfig.json
index 7be6265128..21e6eff01f 100644
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -49,6 +49,9 @@
},
{
"path": "../../session-persistence/session-persistence-jsonl"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/examples/tui-demo/tsdown.config.ts b/packages/examples/tui-demo/tsdown.config.ts
index b3929c6d76..06efc0b4db 100644
--- a/packages/examples/tui-demo/tsdown.config.ts
+++ b/packages/examples/tui-demo/tsdown.config.ts
@@ -8,7 +8,7 @@ import { defineConfig } from 'tsdown'
* matching every package.
*/
export default defineConfig({
- entry: ['lib/types/index.js', 'lib/types/bin.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/fs/fs-local/package.json b/packages/fs/fs-local/package.json
index dd80cb4d9c..75a0400afb 100644
--- a/packages/fs/fs-local/package.json
+++ b/packages/fs/fs-local/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-fs": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"dependencies": {
@@ -30,6 +36,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-fs": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/fs/fs-local/src/invariant.ts b/packages/fs/fs-local/src/invariant.ts
new file mode 100644
index 0000000000..3e38550065
--- /dev/null
+++ b/packages/fs/fs-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-local`.
+ * @module @deepseek-ai/dsh-fs-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-local'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/fs-local/tsconfig.json b/packages/fs/fs-local/tsconfig.json
index 0808fd29ca..b249913d43 100644
--- a/packages/fs/fs-local/tsconfig.json
+++ b/packages/fs/fs-local/tsconfig.json
@@ -6,10 +6,23 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../llm/llm" },
- { "path": "../fs" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../fs"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/fs/fs-policy/package.json b/packages/fs/fs-policy/package.json
index e27302e4a6..e74852ef7d 100644
--- a/packages/fs/fs-policy/package.json
+++ b/packages/fs/fs-policy/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,10 +28,12 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-fs": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-fs": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/fs/fs-policy/src/invariant.ts b/packages/fs/fs-policy/src/invariant.ts
new file mode 100644
index 0000000000..369fa5ea84
--- /dev/null
+++ b/packages/fs/fs-policy/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-policy`.
+ * @module @deepseek-ai/dsh-fs-policy/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-policy'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-policy-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/fs-policy/tsconfig.json b/packages/fs/fs-policy/tsconfig.json
index fcc1307a36..3f22545107 100644
--- a/packages/fs/fs-policy/tsconfig.json
+++ b/packages/fs/fs-policy/tsconfig.json
@@ -6,9 +6,20 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../llm/llm" },
- { "path": "../fs" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../fs"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/fs/fs-sandbox/package.json b/packages/fs/fs-sandbox/package.json
index e0fc7656ef..2fa4ee3f5d 100644
--- a/packages/fs/fs-sandbox/package.json
+++ b/packages/fs/fs-sandbox/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-fs": "^0.0.1",
"@deepseek-ai/dsh-fs-local": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -31,6 +37,7 @@
"devDependencies": {
"@deepseek-ai/dsh-fs": "workspace:^",
"@deepseek-ai/dsh-fs-local": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"@deepseek-ai/dsh-sandbox-policy": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/fs/fs-sandbox/src/invariant.ts b/packages/fs/fs-sandbox/src/invariant.ts
new file mode 100644
index 0000000000..93806bd519
--- /dev/null
+++ b/packages/fs/fs-sandbox/src/invariant.ts
@@ -0,0 +1,27 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-fs-sandbox`.
+ * @module @deepseek-ai/dsh-fs-sandbox/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs-sandbox'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-sandbox-invariant'
+/** Services required before the companion can register. */
+export const inject = ['invariants']
+
+/** No runtime invariant: this stateless adapter delegates policy and filesystem relations to their owning seams. */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/fs-sandbox/tsconfig.json b/packages/fs/fs-sandbox/tsconfig.json
index c9e2f629d5..40213fd6e1 100644
--- a/packages/fs/fs-sandbox/tsconfig.json
+++ b/packages/fs/fs-sandbox/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../sandbox/sandbox-policy"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/fs/fs/package.json b/packages/fs/fs/package.json
index a88e89b72f..41de454488 100644
--- a/packages/fs/fs/package.json
+++ b/packages/fs/fs/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,12 +28,14 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/fs/fs/src/invariant.ts b/packages/fs/fs/src/invariant.ts
new file mode 100644
index 0000000000..429c1cec41
--- /dev/null
+++ b/packages/fs/fs/src/invariant.ts
@@ -0,0 +1,39 @@
+/** Package-owned filesystem event-data invariants. @module @deepseek-ai/dsh-fs/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { FsTarget, FsVersion } from './types.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-fs'
+
+/** Cordis companion plugin name. */
+export const name = 'fs-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Assert that an event carries a usable opaque target identity. */
+function validateTarget(target: FsTarget, fail: (message: string) => never): void {
+ if (target.targetKey.length === 0) fail('filesystem event targetKey must be non-empty')
+ if (target.displayPath.length === 0) fail('filesystem event displayPath must be non-empty')
+}
+
+/** Install checks over the filesystem decision and observation event stream. */
+const install: InvariantInstaller = (ctx, fail) => {
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'fs/write-intent'
+ && eventName !== 'fs/edit-intent'
+ && eventName !== 'fs/observed') return
+ validateTarget(args[0] as FsTarget, fail)
+ if (eventName === 'fs/observed' && (args[1] as FsVersion).length === 0) {
+ fail('fs/observed version must be non-empty')
+ }
+ }, { global: true })
+}
+
+/**
+ * Register the filesystem invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/fs/fs/tests/invariant.spec.ts b/packages/fs/fs/tests/invariant.spec.ts
new file mode 100644
index 0000000000..c160e3d238
--- /dev/null
+++ b/packages/fs/fs/tests/invariant.spec.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { FsTargetKey, FsVersion } from '@deepseek-ai/dsh-fs'
+import type { FsTarget } from '@deepseek-ai/dsh-fs'
+import * as FsInvariant from '@deepseek-ai/dsh-fs/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(FsInvariant)
+ return ctx
+}
+
+const target = (key = 'file:1', displayPath = 'file.txt'): FsTarget => ({
+ targetKey: FsTargetKey(key),
+ displayPath,
+})
+
+describe('filesystem invariants', () => {
+ it('accepts decision and observation events with usable identities', async () => {
+ const ctx = await setup()
+ await expect(ctx.waterfall(
+ ctx as never, 'fs/write-intent', target(), undefined,
+ () => Promise.resolve(undefined),
+ )).resolves.toBeUndefined()
+ await expect(ctx.waterfall(
+ ctx as never, 'fs/edit-intent', target(), undefined,
+ () => Promise.resolve(undefined),
+ )).resolves.toBeUndefined()
+ expect(() => { ctx.emit('fs/observed', target(), FsVersion('v1'), undefined) }).not.toThrow()
+ expect(() => { ctx.emit('tools/change') }).not.toThrow()
+ })
+
+ it('rejects empty target and version identities', async () => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('fs/observed', target(''), FsVersion('v1'), undefined) })
+ .toThrow(/targetKey must be non-empty/)
+ expect(() => { ctx.emit('fs/observed', target('file:1', ''), FsVersion('v1'), undefined) })
+ .toThrow(/displayPath must be non-empty/)
+ expect(() => { ctx.emit('fs/observed', target(), FsVersion(''), undefined) })
+ .toThrow(/version must be non-empty/)
+ })
+})
diff --git a/packages/fs/fs/tsconfig.json b/packages/fs/fs/tsconfig.json
index eb981277c7..9ba6411797 100644
--- a/packages/fs/fs/tsconfig.json
+++ b/packages/fs/fs/tsconfig.json
@@ -6,10 +6,23 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../util/brand" },
- { "path": "../../llm/llm" },
- { "path": "../../sandbox/sandbox" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../util/brand"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../support/invariants"
+ },
+ {
+ "path": "../../sandbox/sandbox"
+ }
]
}
diff --git a/packages/fs/tool-fs-search/package.json b/packages/fs/tool-fs-search/package.json
index 002d54569a..45de8f5e4a 100644
--- a/packages/fs/tool-fs-search/package.json
+++ b/packages/fs/tool-fs-search/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -26,6 +31,7 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-bash": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-retention": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -38,6 +44,7 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-retention": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/fs/tool-fs-search/src/invariant.ts b/packages/fs/tool-fs-search/src/invariant.ts
new file mode 100644
index 0000000000..f7f206896d
--- /dev/null
+++ b/packages/fs/tool-fs-search/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-fs-search`.
+ * @module @deepseek-ai/dsh-tool-fs-search/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-fs-search'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-fs-search-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+ * relations are owned by the capability seam it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/tool-fs-search/tsconfig.json b/packages/fs/tool-fs-search/tsconfig.json
index 9241aca15b..ad0c703117 100644
--- a/packages/fs/tool-fs-search/tsconfig.json
+++ b/packages/fs/tool-fs-search/tsconfig.json
@@ -6,15 +6,38 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../util/retention" },
- { "path": "../../llm/llm" },
- { "path": "../../core/session" },
- { "path": "../../core/tools" },
- { "path": "../../core/system-prompt" },
- { "path": "../../bash/bash" },
- { "path": "../../spill/spill" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../util/retention"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/session"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../../core/system-prompt"
+ },
+ {
+ "path": "../../bash/bash"
+ },
+ {
+ "path": "../../spill/spill"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/fs/tool-fs/package.json b/packages/fs/tool-fs/package.json
index 2b8d0871ad..737f7ac26b 100644
--- a/packages/fs/tool-fs/package.json
+++ b/packages/fs/tool-fs/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -27,6 +32,7 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-fs": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-sandbox-policy": "^0.0.1",
@@ -40,9 +46,10 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
- "@deepseek-ai/dsh-fs-policy": "workspace:^",
"@deepseek-ai/dsh-fs": "workspace:^",
"@deepseek-ai/dsh-fs-local": "workspace:^",
+ "@deepseek-ai/dsh-fs-policy": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-deepseek": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
diff --git a/packages/fs/tool-fs/src/invariant.ts b/packages/fs/tool-fs/src/invariant.ts
new file mode 100644
index 0000000000..eaa2485c06
--- /dev/null
+++ b/packages/fs/tool-fs/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-fs`.
+ * @module @deepseek-ai/dsh-tool-fs/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-fs'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-fs-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+ * relations are owned by the capability seam it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/fs/tool-fs/tsconfig.json b/packages/fs/tool-fs/tsconfig.json
index d2adddae03..fb420b553c 100644
--- a/packages/fs/tool-fs/tsconfig.json
+++ b/packages/fs/tool-fs/tsconfig.json
@@ -6,16 +6,41 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../llm/llm" },
- { "path": "../../core/tools" },
- { "path": "../../core/system-prompt" },
- { "path": "../fs" },
- { "path": "../fs-policy" },
- { "path": "../../sandbox/sandbox" },
- { "path": "../../sandbox/sandbox-policy" },
- { "path": "../../ui/user-approval" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../../core/system-prompt"
+ },
+ {
+ "path": "../fs"
+ },
+ {
+ "path": "../fs-policy"
+ },
+ {
+ "path": "../../support/invariants"
+ },
+ {
+ "path": "../../sandbox/sandbox"
+ },
+ {
+ "path": "../../sandbox/sandbox-policy"
+ },
+ {
+ "path": "../../ui/user-approval"
+ }
]
}
diff --git a/packages/goal/command-goal/package.json b/packages/goal/command-goal/package.json
index 87da2ffaea..b1007d79f3 100644
--- a/packages/goal/command-goal/package.json
+++ b/packages/goal/command-goal/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-commands": "^0.0.1",
"@deepseek-ai/dsh-goal": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
@@ -31,6 +37,7 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-goal": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/goal/command-goal/src/invariant.ts b/packages/goal/command-goal/src/invariant.ts
new file mode 100644
index 0000000000..795294b4e8
--- /dev/null
+++ b/packages/goal/command-goal/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-command-goal`.
+ * @module @deepseek-ai/dsh-command-goal/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-command-goal'
+
+/** Cordis companion plugin name. */
+export const name = 'command-goal-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this command adapter owns no event stream or state projection; accepted
+ * mutations are checked by the goal domain and command dispatch behavior is covered by package tests.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/goal/command-goal/tsconfig.json b/packages/goal/command-goal/tsconfig.json
index 914a50c326..8b03235814 100644
--- a/packages/goal/command-goal/tsconfig.json
+++ b/packages/goal/command-goal/tsconfig.json
@@ -19,6 +19,9 @@
},
{
"path": "../goal"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/goal/goal-session/package.json b/packages/goal/goal-session/package.json
index 48a77019a3..190cb795ad 100644
--- a/packages/goal/goal-session/package.json
+++ b/packages/goal/goal-session/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-goal": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -33,6 +39,7 @@
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
"@deepseek-ai/dsh-goal": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/goal/goal-session/src/invariant.ts b/packages/goal/goal-session/src/invariant.ts
new file mode 100644
index 0000000000..53cdd9b20b
--- /dev/null
+++ b/packages/goal/goal-session/src/invariant.ts
@@ -0,0 +1,84 @@
+/** Package-owned goal-round prompt invariants. @module @deepseek-ai/dsh-goal-session/invariant */
+
+import { isDeepStrictEqual } from 'node:util'
+import type { Context } from 'cordis'
+import { foldGoal, type FoldedGoal, type GoalMessageSource, type GoalView } from '@deepseek-ai/dsh-goal'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { renderGoalRoundPrompt } from './prompt.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-goal-session'
+
+/** Cordis companion plugin name. */
+export const name = 'goal-session-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Attribute strict goal-fold failures to this companion's reconstruction. */
+function foldChecked(events: readonly SessionEvent[], fail: InvariantFailure): FoldedGoal {
+ try {
+ return foldGoal(events)
+ } catch (error: unknown) {
+ /* v8 ignore next -- the strict goal decoder throws Error instances */
+ const message = error instanceof Error ? error.message : String(error)
+ return fail(`cannot reconstruct the goal before a continuation message: ${message}`)
+ }
+}
+
+/** Recreate the live-shaped view consumed by the package's pure prompt renderer. */
+function goalView(folded: FoldedGoal, source: GoalMessageSource, fail: InvariantFailure): GoalView {
+ const goal = folded.goal
+ if (goal === undefined || folded.createdAt === undefined || folded.updatedAt === undefined
+ || goal.phase !== 'active' || goal.id !== source.goalId || goal.revision !== source.revision
+ || source.round !== folded.roundsStarted + 1 || source.round > goal.maxGoalRounds) {
+ return fail(`goal round ${source.round} cannot be reconstructed from the preceding durable goal state`)
+ }
+ return {
+ ...goal,
+ roundsStarted: folded.roundsStarted,
+ createdAt: folded.createdAt,
+ updatedAt: folded.updatedAt,
+ activation: 'armed',
+ }
+}
+
+/** Validate one package-owned continuation message against its durable prefix. */
+function validateEvent(
+ prior: readonly SessionEvent[],
+ event: SessionEvent,
+ fail: InvariantFailure,
+): void {
+ if (event.type !== 'user/message') return
+ const source = event.data.source
+ if (source.kind !== 'goal' || source.round <= 0) return
+ const expected = renderGoalRoundPrompt(goalView(foldChecked(prior, fail), source, fail), source.round)
+ if (!isDeepStrictEqual(event.data.content, expected)) {
+ fail(`goal round ${source.round} content does not match the package-owned continuation prompt`)
+ }
+}
+
+/** Check existing sessions and every candidate event before Session publishes it. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ for (const session of ctx.sessions.list()) {
+ const prior: SessionEvent[] = []
+ for (const event of session.events) {
+ validateEvent(prior, event, fail)
+ prior.push(event)
+ }
+ }
+ /* jscpd:ignore-start -- package companions share dispatch and registration plumbing */
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ validateEvent(session.events, event, fail)
+ }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the goal-session invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/goal/goal-session/tests/invariant.spec.ts b/packages/goal/goal-session/tests/invariant.spec.ts
new file mode 100644
index 0000000000..19200747e8
--- /dev/null
+++ b/packages/goal/goal-session/tests/invariant.spec.ts
@@ -0,0 +1,143 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import {
+ GoalId,
+ renderGoalChange,
+ type GoalSnapshotChangeMeta,
+ type GoalView,
+} from '@deepseek-ai/dsh-goal'
+import * as GoalSessionInvariant from '@deepseek-ai/dsh-goal-session/invariant'
+import { renderGoalRoundPrompt } from '@deepseek-ai/dsh-goal-session'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+import SessionStore, { SessionId, type Session } from '@deepseek-ai/dsh-session'
+
+const change: GoalSnapshotChangeMeta = {
+ kind: 'goal/change',
+ version: 1,
+ operation: 'create',
+ goal: {
+ id: GoalId('goal-session-invariant'),
+ revision: 1,
+ objective: 'verify every continuation prompt',
+ phase: 'active',
+ maxGoalRounds: 2,
+ },
+ roundsStarted: 0,
+ createdAt: 1,
+ updatedAt: 1,
+}
+
+const changeSource = {
+ kind: 'goal',
+ goalId: change.goal.id,
+ revision: change.goal.revision,
+ round: 0,
+} as const
+
+function view(roundsStarted: number): GoalView {
+ return { ...change.goal, roundsStarted, createdAt: 1, updatedAt: 1, activation: 'armed' }
+}
+
+function appendChange(session: Session): void {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
+ session.append('context/message', {
+ content: renderGoalChange(change),
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+}
+
+function appendRound(session: Session, turn: number, content = renderGoalRoundPrompt(view(turn - 2), turn - 1)): void {
+ const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: turn - 1 } as const
+ session.append('turn/start', { turn, trigger: { kind: 'message', source } })
+ session.append('user/message', { content, source }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn, reason: { kind: 'completed' } })
+}
+
+async function mount(sessionFirst = false): Promise<{ ctx: Context; session: Session }> {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create(SessionId('goal-session-invariant'))
+ if (!sessionFirst) {
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(GoalSessionInvariant)
+ }
+ return { ctx, session }
+}
+
+describe('goal-session prompt invariants', () => {
+ it('reconstructs existing rounds and accepts the next canonical prompt', async () => {
+ const { ctx, session } = await mount(true)
+ appendChange(session)
+ appendRound(session, 2)
+
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(GoalSessionInvariant)
+
+ expect(() => { appendRound(session, 3) }).not.toThrow()
+ ctx.sessions.create(SessionId('goal-session-invariant-dispatch'))
+
+ const userSource = { kind: 'user' } as const
+ session.append('turn/start', { turn: 4, trigger: { kind: 'message', source: userSource } })
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'ordinary human message' }],
+ source: userSource,
+ }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn: 4, reason: { kind: 'completed' } })
+
+ const stateSource = { ...changeSource, round: 0 } as const
+ session.append('turn/start', { turn: 5, trigger: { kind: 'message', source: stateSource } })
+ expect(() => {
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'round zero is not a driver continuation' }],
+ source: stateSource,
+ }, { surfaceOp: 'append' })
+ }).not.toThrow()
+ })
+
+ it('rejects a continuation whose content differs from the package renderer', async () => {
+ const { session } = await mount()
+ appendChange(session)
+
+ expect(() => {
+ appendRound(session, 2, [{ type: 'text', text: 'counterfeit continuation' }])
+ }).toThrow(expect.objectContaining>({
+ code: 'INVARIANT',
+ packageName: '@deepseek-ai/dsh-goal-session',
+ }))
+ })
+
+ it('rejects a goal round without a reconstructable active goal', async () => {
+ const { session } = await mount()
+ const source = { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 } as const
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source } })
+
+ expect(() => {
+ session.append('user/message', {
+ content: renderGoalRoundPrompt(view(0), 1),
+ source,
+ }, { surfaceOp: 'append' })
+ }).toThrow(expect.objectContaining>({
+ packageName: '@deepseek-ai/dsh-goal-session',
+ }))
+ })
+
+ it('attributes an invalid durable prefix during late loading', async () => {
+ const { ctx, session } = await mount(true)
+ session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
+ session.append('context/message', {
+ content: [{ type: 'text', text: 'counterfeit goal state' }],
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ appendRound(session, 2)
+ await ctx.plugin(InvariantService, { enabled: true })
+
+ await expect(ctx.plugin(GoalSessionInvariant)).rejects.toMatchObject({
+ code: 'INVARIANT',
+ packageName: '@deepseek-ai/dsh-goal-session',
+ })
+ })
+})
diff --git a/packages/goal/goal-session/tsconfig.json b/packages/goal/goal-session/tsconfig.json
index d3cf5d5294..34ec1510e8 100644
--- a/packages/goal/goal-session/tsconfig.json
+++ b/packages/goal/goal-session/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/goal/goal-session/tsdown.config.ts b/packages/goal/goal-session/tsdown.config.ts
new file mode 100644
index 0000000000..ab8dc26ee8
--- /dev/null
+++ b/packages/goal/goal-session/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/goal/goal/README.md b/packages/goal/goal/README.md
index a71308d5f2..e50044d135 100644
--- a/packages/goal/goal/README.md
+++ b/packages/goal/goal/README.md
@@ -25,6 +25,8 @@ Injection may append immediately or wait in an active tool-batch FIFO. The servi
Activation is never persisted. A fresh cache and every `agent/session-start` edge disarm it even when replay finds an active durable phase. A continuation driver also calls `disarm()` before unload or after durability uncertainty. Session resume, fork, and driver replacement therefore retain the objective, phase, revisions, and admitted-round count without initiating work; a later explicit resume mutation must arm continuation.
+The separately published `./invariant` companion maintains an independent fold of each attached session. It rejects malformed goal metadata, source or model-visible content drift, discontinuous revisions, illegal lifecycle transitions, timestamp regressions, and non-sequential admitted rounds before the candidate event enters the durable log.
+
## Extension points
Policy plugins call the service verbs and react to the scoped `goal/changed` event. A continuation consumer admits rounds as `user/message` events with `GoalMessageSource`; ordinary human turns never increment `roundsStarted`. Consumers use the `Agent` interface and events rather than importing `dsh-agent-loop`.
diff --git a/packages/goal/goal/package.json b/packages/goal/goal/package.json
index 534c258c6b..2427ccfa5e 100644
--- a/packages/goal/goal/package.json
+++ b/packages/goal/goal/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -35,6 +41,7 @@
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-loader-smoke": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
diff --git a/packages/goal/goal/src/invariant.ts b/packages/goal/goal/src/invariant.ts
new file mode 100644
index 0000000000..42c83c65f0
--- /dev/null
+++ b/packages/goal/goal/src/invariant.ts
@@ -0,0 +1,79 @@
+/** Package-owned durable goal-stream invariants. @module @deepseek-ai/dsh-goal/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { applyGoalEvent, emptyGoalFoldState } from './fold.ts'
+import type { GoalFoldState } from './fold.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-goal'
+
+/** Cordis companion plugin name. */
+export const name = 'goal-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Copy the independent fold before validating one candidate event. */
+function cloneState(state: GoalFoldState): GoalFoldState {
+ return {
+ goal: state.goal,
+ roundsStarted: state.roundsStarted,
+ createdAt: state.createdAt,
+ updatedAt: state.updatedAt,
+ lastRef: state.lastRef,
+ seenGoalIds: new Set(state.seenGoalIds),
+ }
+}
+
+/** Apply one event through the strict goal decoder and attribute failures. */
+function applyChecked(state: GoalFoldState, event: SessionEvent, fail: InvariantFailure): void {
+ try {
+ applyGoalEvent(state, event)
+ } catch (error) {
+ /* v8 ignore next -- the strict goal decoder throws Error instances */
+ const message = error instanceof Error ? error.message : String(error)
+ fail(`session event ${event.seq} violates the durable goal stream: ${message}`)
+ }
+}
+
+/** Install an independent incremental fold over every attached session. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ const states = new WeakMap()
+ const staged = new WeakMap()
+
+ const seed = (session: Session): GoalFoldState => {
+ const state = emptyGoalFoldState()
+ for (const event of session.events) applyChecked(state, event, fail)
+ states.set(session, state)
+ return state
+ }
+ /* v8 ignore next -- session/event always follows list() or session/created seeding */
+ const stateFor = (session: Session): GoalFoldState => states.get(session) ?? seed(session)
+
+ for (const session of ctx.sessions.list()) seed(session)
+ ctx.on('session/created', (session) => { seed(session) }, { global: true })
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ const state = cloneState(stateFor(session))
+ applyChecked(state, event, fail)
+ staged.set(event, { session, state })
+ }, { global: true })
+ ctx.on('session/event', (session, event) => {
+ const candidate = staged.get(event)
+ /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
+ if (candidate === undefined || candidate.session !== session) {
+ return fail('session/event reached publication without matching goal-fold validation')
+ }
+ staged.delete(event)
+ states.set(session, candidate.state)
+ }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the goal-stream invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/goal/goal/tests/invariant.spec.ts b/packages/goal/goal/tests/invariant.spec.ts
new file mode 100644
index 0000000000..85f0b839d1
--- /dev/null
+++ b/packages/goal/goal/tests/invariant.spec.ts
@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import {
+ GoalId,
+ renderGoalChange,
+ type GoalSnapshotChangeMeta,
+} from '@deepseek-ai/dsh-goal'
+import * as GoalInvariantCompanion from '@deepseek-ai/dsh-goal/invariant'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+
+const change: GoalSnapshotChangeMeta = {
+ kind: 'goal/change',
+ version: 1,
+ operation: 'create',
+ goal: {
+ id: GoalId('goal-invariant'),
+ revision: 1,
+ objective: 'check the stream',
+ phase: 'active',
+ maxGoalRounds: 2,
+ },
+ roundsStarted: 0,
+ createdAt: 1,
+ updatedAt: 1,
+}
+
+const changeSource = {
+ kind: 'goal',
+ goalId: change.goal.id,
+ revision: change.goal.revision,
+ round: 0,
+} as const
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(GoalInvariantCompanion)
+ return ctx
+}
+
+describe('goal stream invariants', () => {
+ it('accepts canonical goal snapshots and sequential admitted rounds', async () => {
+ const ctx = await setup()
+ const session = ctx.sessions.create(SessionId('goal-invariant-valid'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
+ session.append('context/message', {
+ content: renderGoalChange(change),
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ session.append('turn/start', {
+ turn: 2,
+ trigger: {
+ kind: 'message',
+ source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 },
+ },
+ })
+ expect(() => {
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'continue' }],
+ source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 },
+ }, { surfaceOp: 'append' })
+ }).not.toThrow()
+ })
+
+ it('rejects model-visible drift before committing it and keeps the fold reusable', async () => {
+ const ctx = await setup()
+ const session = ctx.sessions.create(SessionId('goal-invariant-invalid'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
+ expect(() => {
+ session.append('context/message', {
+ content: [{ type: 'text', text: 'counterfeit' }],
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ }).toThrow(expect.objectContaining>({
+ code: 'INVARIANT',
+ packageName: '@deepseek-ai/dsh-goal',
+ }))
+ expect(session.seq).toBe(1)
+ expect(() => {
+ session.append('context/message', {
+ content: renderGoalChange(change),
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ }).not.toThrow()
+ })
+
+ it('reconstructs an existing durable goal before checking later rounds', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create(SessionId('goal-invariant-late-load'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: changeSource } })
+ session.append('context/message', {
+ content: renderGoalChange(change),
+ source: changeSource,
+ meta: change as never,
+ }, { surfaceOp: 'append' })
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(GoalInvariantCompanion)
+ session.append('turn/start', {
+ turn: 2,
+ trigger: {
+ kind: 'message',
+ source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 },
+ },
+ })
+ expect(() => {
+ session.append('user/message', {
+ content: [{ type: 'text', text: 'continue after load' }],
+ source: { kind: 'goal', goalId: change.goal.id, revision: 1, round: 1 },
+ }, { surfaceOp: 'append' })
+ }).not.toThrow()
+ })
+})
diff --git a/packages/goal/goal/tsconfig.json b/packages/goal/goal/tsconfig.json
index 8a97b2a5e0..a06b59ed0e 100644
--- a/packages/goal/goal/tsconfig.json
+++ b/packages/goal/goal/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../core/agent"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/goal/goal/tsdown.config.ts b/packages/goal/goal/tsdown.config.ts
new file mode 100644
index 0000000000..ab8dc26ee8
--- /dev/null
+++ b/packages/goal/goal/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/goal/tool-goal/package.json b/packages/goal/tool-goal/package.json
index b9b4912cf4..3fcc0c61a9 100644
--- a/packages/goal/tool-goal/package.json
+++ b/packages/goal/tool-goal/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-goal": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -37,6 +43,7 @@
"@cordisjs/plugin-loader": "workspace:^",
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-goal": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/goal/tool-goal/src/invariant.ts b/packages/goal/tool-goal/src/invariant.ts
new file mode 100644
index 0000000000..d3ea60f049
--- /dev/null
+++ b/packages/goal/tool-goal/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-goal`.
+ * @module @deepseek-ai/dsh-tool-goal/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-goal'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-goal-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter owns no independent state or event protocol;
+ * accepted mutations are checked by the goal domain and authority behavior is package-tested.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/goal/tool-goal/tsconfig.json b/packages/goal/tool-goal/tsconfig.json
index d5c34d4e29..f3026b0aff 100644
--- a/packages/goal/tool-goal/tsconfig.json
+++ b/packages/goal/tool-goal/tsconfig.json
@@ -34,6 +34,9 @@
},
{
"path": "../goal"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/guard/repeat-tool-guard/package.json b/packages/guard/repeat-tool-guard/package.json
index 92d49c548f..c892ca99e4 100644
--- a/packages/guard/repeat-tool-guard/package.json
+++ b/packages/guard/repeat-tool-guard/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -26,6 +31,7 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
@@ -33,6 +39,7 @@
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-tools": "workspace:^",
diff --git a/packages/guard/repeat-tool-guard/src/invariant.ts b/packages/guard/repeat-tool-guard/src/invariant.ts
new file mode 100644
index 0000000000..5d8544b9aa
--- /dev/null
+++ b/packages/guard/repeat-tool-guard/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-repeat-tool-guard`.
+ * @module @deepseek-ai/dsh-repeat-tool-guard/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-repeat-tool-guard'
+
+/** Cordis companion plugin name. */
+export const name = 'repeat-tool-guard-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the repeat chain is private to one post-execute listener and exposes no
+ * package-owned event or snapshot that an independent companion can observe.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/guard/repeat-tool-guard/tsconfig.json b/packages/guard/repeat-tool-guard/tsconfig.json
index 66439bcd5f..9ca11b7119 100644
--- a/packages/guard/repeat-tool-guard/tsconfig.json
+++ b/packages/guard/repeat-tool-guard/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../llm/llm"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/hooks/hook-protocol/package.json b/packages/hooks/hook-protocol/package.json
index 201c744219..f357278db3 100644
--- a/packages/hooks/hook-protocol/package.json
+++ b/packages/hooks/hook-protocol/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,11 +28,13 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-bash": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-bash": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/hooks/hook-protocol/src/invariant.ts b/packages/hooks/hook-protocol/src/invariant.ts
new file mode 100644
index 0000000000..6972d109da
--- /dev/null
+++ b/packages/hooks/hook-protocol/src/invariant.ts
@@ -0,0 +1,101 @@
+/** Package-owned hook provenance-stream invariants. @module @deepseek-ai/dsh-hook-protocol/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type {} from './types.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-hook-protocol'
+
+/** Cordis companion plugin name. */
+export const name = 'hook-protocol-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+interface HookTransition {
+ key: string
+ delta: 1 | -1
+}
+
+/** Correlation key shared by an invoked/result pair. */
+function hookKey(data: { turn: number; point: string; handlerId: string }): string {
+ return `${data.turn}\0${data.point}\0${data.handlerId}`
+}
+
+/** Validate one hook event against committed pending invocations. */
+function validateHookEvent(
+ pending: ReadonlyMap,
+ event: SessionEvent,
+ fail: InvariantFailure,
+): HookTransition | undefined {
+ if (event.type === 'hook/invoked') {
+ if (event.data.point.length === 0 || event.data.handlerId.length === 0) {
+ fail('hook/invoked point and handlerId must be non-empty')
+ }
+ const dialect: string = event.data.dialect
+ if (dialect !== 'claude' && dialect !== 'codex') {
+ fail(`hook/invoked carries unknown dialect ${JSON.stringify(dialect)}`)
+ }
+ return { key: hookKey(event.data), delta: 1 }
+ }
+ if (event.type !== 'hook/result') return undefined
+ const key = hookKey(event.data)
+ if ((pending.get(key) ?? 0) === 0) {
+ fail(`hook/result has no matching hook/invoked for ${JSON.stringify(event.data.handlerId)}`)
+ }
+ if (!Number.isFinite(event.data.durationMs) || event.data.durationMs < 0) {
+ fail('hook/result durationMs must be a non-negative finite number')
+ }
+ return { key, delta: -1 }
+}
+
+/** Apply one committed hook-pair transition. */
+function applyHookTransition(pending: Map, transition: HookTransition): void {
+ const next = (pending.get(transition.key) ?? 0) + transition.delta
+ if (next === 0) pending.delete(transition.key)
+ else pending.set(transition.key, next)
+}
+
+/** Install hook invoked/result pairing checks. */
+// Event owners keep precommit staging local so their vocabularies never move into a central helper.
+/* jscpd:ignore-start */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ const traces = new WeakMap>()
+ const staged = new WeakMap()
+ const seed = (session: Session): Map => {
+ const pending = new Map()
+ traces.set(session, pending)
+ for (const event of session.events) {
+ const transition = validateHookEvent(pending, event, fail)
+ if (transition !== undefined) applyHookTransition(pending, transition)
+ }
+ return pending
+ }
+ const traceFor = (session: Session): Map => traces.get(session) ?? seed(session)
+
+ for (const session of ctx.sessions.list()) seed(session)
+ ctx.on('session/created', (session) => { seed(session) }, { global: true })
+ ctx.on('session/event', (session, event) => {
+ if (event.type !== 'hook/invoked' && event.type !== 'hook/result') return
+ const candidate = staged.get(event)
+ /* v8 ignore next -- internal/dispatch stages every hook provenance event */
+ if (candidate === undefined || candidate.session !== session) return fail('hook event published without pre-commit validation')
+ staged.delete(event)
+ applyHookTransition(traceFor(session), candidate.transition)
+ }, { global: true })
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ const transition = validateHookEvent(traceFor(session), event, fail)
+ if (transition !== undefined) staged.set(event, { session, transition })
+ }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register the hook-protocol invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/hooks/hook-protocol/tests/invariant.spec.ts b/packages/hooks/hook-protocol/tests/invariant.spec.ts
new file mode 100644
index 0000000000..dc7b1d38bb
--- /dev/null
+++ b/packages/hooks/hook-protocol/tests/invariant.spec.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import * as HookInvariant from '@deepseek-ai/dsh-hook-protocol/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(HookInvariant)
+ return ctx
+}
+
+const invoked = (overrides: Record = {}) => ({
+ turn: 1,
+ point: 'PreToolUse',
+ dialect: 'claude' as const,
+ handlerId: 'hook-1',
+ ...overrides,
+})
+
+const result = (overrides: Record = {}) => ({
+ turn: 1,
+ point: 'PreToolUse',
+ handlerId: 'hook-1',
+ decision: 'pass',
+ durationMs: 3,
+ ...overrides,
+})
+
+describe('hook-protocol invariants', () => {
+ it('pairs serial and repeated handler invocations', async () => {
+ const ctx = await setup()
+ const session = ctx.sessions.create()
+ session.append('hook/invoked', invoked())
+ session.append('hook/invoked', invoked())
+ session.append('hook/result', result())
+ session.append('hook/result', result())
+ })
+
+ it('rebuilds pending hook provenance from an existing session', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create()
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('hook/invoked', invoked())
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(HookInvariant)
+ expect(() => session.append('hook/result', result())).not.toThrow()
+ session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+ })
+
+ it('adopts a bare session first observed through publication', async () => {
+ const ctx = await setup()
+ const session = new Session(SessionId('bare-hook-session'))
+ expect(() => {
+ ctx.emit('session/event', session, {
+ type: 'hook/invoked', seq: 0, time: 0, data: invoked(),
+ })
+ ctx.emit('session/event', session, {
+ type: 'hook/result', seq: 1, time: 1, data: result(),
+ })
+ }).not.toThrow()
+ })
+
+ it.each([
+ [invoked({ point: '' }), /point and handlerId must be non-empty/],
+ [invoked({ handlerId: '' }), /point and handlerId must be non-empty/],
+ [invoked({ dialect: 'other' }), /unknown dialect/],
+ ])('rejects malformed hook invocation %#', async (data, message) => {
+ const ctx = await setup()
+ expect(() => ctx.sessions.create().append('hook/invoked', data as never)).toThrow(message)
+ })
+
+ it('rejects unmatched and malformed results', async () => {
+ const ctx = await setup()
+ const session = ctx.sessions.create()
+ expect(() => session.append('hook/result', result())).toThrow(/no matching hook\/invoked/)
+ session.append('hook/invoked', invoked())
+ expect(() => session.append('hook/result', result({ durationMs: -1 })))
+ .toThrow(/durationMs must be a non-negative finite number/)
+ expect(() => session.append('hook/result', result({ point: 'Stop' })))
+ .toThrow(/no matching hook\/invoked/)
+ })
+})
diff --git a/packages/hooks/hook-protocol/tsconfig.json b/packages/hooks/hook-protocol/tsconfig.json
index dc4f8d9e16..220748cb0f 100644
--- a/packages/hooks/hook-protocol/tsconfig.json
+++ b/packages/hooks/hook-protocol/tsconfig.json
@@ -19,6 +19,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/hooks/hooks-claude/package.json b/packages/hooks/hooks-claude/package.json
index c6870a6471..34696ab625 100644
--- a/packages/hooks/hooks-claude/package.json
+++ b/packages/hooks/hooks-claude/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -27,6 +32,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-hook-protocol": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
@@ -41,6 +47,7 @@
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
"@deepseek-ai/dsh-hook-protocol": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
diff --git a/packages/hooks/hooks-claude/src/invariant.ts b/packages/hooks/hooks-claude/src/invariant.ts
new file mode 100644
index 0000000000..18bc942e9f
--- /dev/null
+++ b/packages/hooks/hooks-claude/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-hooks-claude`.
+ * @module @deepseek-ai/dsh-hooks-claude/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-hooks-claude'
+
+/** Cordis companion plugin name. */
+export const name = 'hooks-claude-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
+ * their cross-event provenance relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/hooks/hooks-claude/tests/bridge.spec.ts b/packages/hooks/hooks-claude/tests/bridge.spec.ts
index fd2b018a51..e59ae24e31 100644
--- a/packages/hooks/hooks-claude/tests/bridge.spec.ts
+++ b/packages/hooks/hooks-claude/tests/bridge.spec.ts
@@ -10,7 +10,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import SubagentService, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
import * as HooksClaude from '@deepseek-ai/dsh-hooks-claude'
import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -25,6 +26,10 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
const dirs: string[] = []
afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+function subagentCarrier(ctx: Context) {
+ return scopeTarget(ctx as unknown as SubagentService, undefined)
+}
+
/** Write a hooks.json + named executable scripts into a fresh temp dir. */
function writeConfig(hooks: unknown, scripts: Record = {}): string {
const dir = mkdtempSync(join(tmpdir(), 'dsh-hooks-claude-'))
@@ -290,8 +295,8 @@ describe('hooks-claude bridge — SubagentStart / SubagentStop (observe)', () =>
// Drive the observe-only lifecycle events directly (no real child needed — the
// bridge just listens). No child agent is registered, so SubagentStart's
// child lookup yields undefined and it simply runs the hook.
- ctx.emit('subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
- ctx.emit('subagent/end', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false, stopReason: 'completed', lastAssistantMessage: [{ type: 'text', text: 'done' }] })
+ ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
+ ctx.emit(subagentCarrier(ctx), 'subagent/end', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false, stopReason: 'completed', lastAssistantMessage: [{ type: 'text', text: 'done' }] })
// Both hooks run async (detached .then); poll for their marker files rather
// than a fixed sleep that flakes under load.
@@ -326,7 +331,7 @@ describe('hooks-claude bridge — SubagentStart / SubagentStop (observe)', () =>
const { ctx, hooks } = await harnessWithFiber(dir, new MockAdapter([]))
const warn = vi.fn()
ctx.logger.warn = warn as never
- ctx.emit('subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
+ ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-1'), provider: 'inproc', id: SessionId('child-1'), local: false })
await waitFor(() => existsSync(marker))
const pid = Number(readFileSync(pidFile, 'utf8').trim())
await hooks.dispose()
diff --git a/packages/hooks/hooks-claude/tests/coverage-cases.ts b/packages/hooks/hooks-claude/tests/coverage-cases.ts
index ae6347e31d..71e5608cb1 100644
--- a/packages/hooks/hooks-claude/tests/coverage-cases.ts
+++ b/packages/hooks/hooks-claude/tests/coverage-cases.ts
@@ -10,7 +10,8 @@ import type { Agent } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
-import { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import SubagentService, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
import * as HooksClaude from '@deepseek-ai/dsh-hooks-claude'
import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -20,6 +21,10 @@ import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent
const dirs: string[] = []
afterEach(() => { for (const d of dirs.splice(0)) rmSync(d, { recursive: true, force: true }) })
+function subagentCarrier(ctx: Context) {
+ return scopeTarget(ctx as unknown as SubagentService, undefined)
+}
+
function dir(): string { const d = mkdtempSync(join(tmpdir(), 'dsh-hc-cov-')); dirs.push(d); return d }
function sh(d: string, name: string, body: string): string {
const p = join(d, name); writeFileSync(p, body); chmodSync(p, 0o755); return p
@@ -233,7 +238,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
const injected: string[] = []
const child = { id: SessionId('child-x'), inject: (content: { type: string; text?: string }[]) => { injected.push(content.map(b => b.text ?? '').join('')) }, session: { id: SessionId('child-x'), header: { id: 'child-x' } } } as unknown as Parameters[0]
ctx.agents.register(child)
- ctx.emit('subagent/start', { runId: SubagentRunId('run-x'), provider: 'p', id: SessionId('child-x'), local: true })
+ ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-x'), provider: 'p', id: SessionId('child-x'), local: true })
await waitFor(() => injected.includes('child guidance'))
expect(injected).toContain('child guidance')
})
@@ -249,7 +254,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
const warn = vi.fn(); ctx.logger.warn = warn as never
const child = { id: SessionId('child-y'), inject: () => { throw new Error('inject boom') }, session: { id: SessionId('child-y'), header: { id: 'child-y' } } } as unknown as Parameters[0]
ctx.agents.register(child)
- ctx.emit('subagent/start', { runId: SubagentRunId('run-y'), provider: 'p', id: SessionId('child-y'), local: true })
+ ctx.emit(subagentCarrier(ctx), 'subagent/start', { runId: SubagentRunId('run-y'), provider: 'p', id: SessionId('child-y'), local: true })
await waitFor(() => warn.mock.calls.some(c => String(c[0]).includes('SubagentStart hook failed')))
expect(warn).toHaveBeenCalledWith(expect.stringContaining('SubagentStart hook failed'))
})
@@ -293,7 +298,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
const s = sh(d, 'stop.sh', `#!/usr/bin/env bash\ntouch "${marker}"\n`)
const path = hooks(d, { SubagentStop: [{ hooks: [{ type: 'command', command: s }] }] })
const ctx = await harness(path, new MockAdapter([]))
- ctx.emit('subagent/end', { runId: SubagentRunId('run-z'), provider: 'p', id: SessionId('child-z'), local: false, stopReason: 'completed' })
+ ctx.emit(subagentCarrier(ctx), 'subagent/end', { runId: SubagentRunId('run-z'), provider: 'p', id: SessionId('child-z'), local: false, stopReason: 'completed' })
await waitFor(() => existsSync(marker))
expect(existsSync(marker)).toBe(true)
})
@@ -689,7 +694,7 @@ export function defineCoverageCases(group: CoverageGroup): void {
// Register a live child on its own session cwd; emit subagent/end with its id.
const { SessionId } = await import('@deepseek-ai/dsh-session')
const childHandle = await ctx.agents.create({ sessionId: SessionId('child-stop-session'), meta: { cwd: childDir }, agentOptions: { provider: 'mock', model: 'mock' } })
- ctx.emit('subagent/end', { runId: SubagentRunId('run-stop'), provider: 'inproc', id: childHandle.agent.id, local: true, stopReason: 'completed' })
+ ctx.emit(subagentCarrier(ctx), 'subagent/end', { runId: SubagentRunId('run-stop'), provider: 'inproc', id: childHandle.agent.id, local: true, stopReason: 'completed' })
await waitFor(() => existsSync(marker))
expect(existsSync(marker)).toBe(true) // the marker landed in the CHILD dir
diff --git a/packages/hooks/hooks-claude/tsconfig.json b/packages/hooks/hooks-claude/tsconfig.json
index 07c88610f9..445d0f68b1 100644
--- a/packages/hooks/hooks-claude/tsconfig.json
+++ b/packages/hooks/hooks-claude/tsconfig.json
@@ -40,6 +40,9 @@
},
{
"path": "../../bash/bash"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/hooks/hooks-codex/package.json b/packages/hooks/hooks-codex/package.json
index 8c8686c539..5d583baafe 100644
--- a/packages/hooks/hooks-codex/package.json
+++ b/packages/hooks/hooks-codex/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -27,6 +32,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-hook-protocol": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
@@ -40,6 +46,7 @@
"@deepseek-ai/dsh-bash": "workspace:^",
"@deepseek-ai/dsh-bash-local": "workspace:^",
"@deepseek-ai/dsh-hook-protocol": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
diff --git a/packages/hooks/hooks-codex/src/invariant.ts b/packages/hooks/hooks-codex/src/invariant.ts
new file mode 100644
index 0000000000..5f0f6ed173
--- /dev/null
+++ b/packages/hooks/hooks-codex/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-hooks-codex`.
+ * @module @deepseek-ai/dsh-hooks-codex/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-hooks-codex'
+
+/** Cordis companion plugin name. */
+export const name = 'hooks-codex-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this bridge publishes hook-protocol session events, whose companion owns
+ * their cross-event provenance relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/hooks/hooks-codex/tsconfig.json b/packages/hooks/hooks-codex/tsconfig.json
index ae3c91e9dd..3bd9bd91e5 100644
--- a/packages/hooks/hooks-codex/tsconfig.json
+++ b/packages/hooks/hooks-codex/tsconfig.json
@@ -37,6 +37,9 @@
},
{
"path": "../../bash/bash"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/llm/README.md b/packages/llm/README.md
index 405c2f18f4..0c937c17dc 100644
--- a/packages/llm/README.md
+++ b/packages/llm/README.md
@@ -10,4 +10,4 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
| `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, retry policy, and 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](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the contract-validation origin of the two shipping implementations and the [replay token meter Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership.
+The interface lives at `llm/llm/`; adapters, retry policy, and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. The route-owning adapter optionally resolves exact provider/model context capacity; the token meter remains model-agnostic. A new provider adapter registers one or more provider routes on `ctx.llm` without touching the interface or consumers. See [twin LLM adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the two shipping implementations, the [replay token meter Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership, and the [routed model context Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) for capacity and compaction-policy ownership.
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index d4fa19af3d..ad7916f918 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -20,11 +20,15 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
models: # optional; defaults to V4 Flash and V4 Pro
- id: deepseek-v4-flash
name: DeepSeek V4 Flash
+ contextWindow: 128000
- id: private-reasoner
description: Company-hosted reasoning model
+ contextWindow: 64000
```
-The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
+The plugin registers the single provider route `deepseek`. A request selects it with `provider: deepseek`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` and `deepseek-v4-pro`, each with a 128,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek')` for clients such as ACP editors, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
+
+`contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelContext('deepseek', model)` returns it only for an exact configured id; omission or an unlisted pass-through model returns `undefined` without invalidating routing. Pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek` throws `LlmError('DUPLICATE_ADAPTER')`.
`reasoningEffort` is **omitted by default** — when unset, the `reasoning_effort` wire field is not sent and the server applies its own default for the model. The only accepted values are `high` and `max` (DeepSeek's official effort levels). It is meaningful only with thinking enabled (the provider default).
diff --git a/packages/llm/llm-deepseek/package.json b/packages/llm/llm-deepseek/package.json
index 02e8cb85ac..4946c2bcd9 100644
--- a/packages/llm/llm-deepseek/package.json
+++ b/packages/llm/llm-deepseek/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 74adafb225..237751fc39 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -6,7 +6,13 @@
*/
import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type {
+ GenerateOptions,
+ LlmModelContext,
+ LlmModelInfo,
+ LlmProviderInfo,
+ StreamChunk,
+} from '@deepseek-ai/dsh-llm'
import { idleWatchdog, MAX_TIMER_DELAY_MS, timeoutOf } from '@deepseek-ai/dsh-timeout'
import { serializeRequest } from './serialize.ts'
import type { RequestDefaults } from './serialize.ts'
@@ -22,6 +28,8 @@ export interface DeepSeekCatalogModel {
name?: string
/** Optional selector detail for deployments with similar model variants. */
description?: string
+ /** Known combined request/response context capacity; omitted when deployment metadata is unavailable. */
+ contextWindow?: number
}
/** Constructor options for {@link DeepSeekAdapter}; the plugin's `apply` resolves them from Config + environment. */
@@ -111,6 +119,14 @@ export class DeepSeekAdapter extends LlmAdapter {
})))
}
+ override resolveModelContext(
+ _provider: string,
+ model: string,
+ ): Promise {
+ const contextWindow = this.options.models?.find(entry => entry.id === model)?.contextWindow
+ return Promise.resolve(contextWindow === undefined ? undefined : { contextWindow })
+ }
+
async * stream(options: GenerateOptions): AsyncIterable {
const consumer = new AbortController()
const upstream = options.signal === undefined
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index c0d0df0f08..ed374f6ecc 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -21,8 +21,8 @@ export const name = 'llm-deepseek'
export const inject = ['llm']
const DEFAULT_MODELS: DeepSeekCatalogModel[] = [
- { id: 'deepseek-v4-flash' },
- { id: 'deepseek-v4-pro' },
+ { id: 'deepseek-v4-flash', contextWindow: 128_000 },
+ { id: 'deepseek-v4-pro', contextWindow: 128_000 },
]
/**
@@ -50,6 +50,7 @@ const catalogModel: z = z.object({
id: z.string().required(),
name: z.string(),
description: z.string(),
+ contextWindow: z.number().step(1).min(1),
})
export const Config: z = z.object({
@@ -72,12 +73,19 @@ function resolveModels(models: readonly DeepSeekCatalogModel[] | undefined): Dee
if (model.name !== undefined && model.name.length === 0) {
throw new Error(`llm-deepseek: catalog model "${model.id}" has an empty name`)
}
+ if (model.contextWindow !== undefined
+ && (!Number.isInteger(model.contextWindow) || model.contextWindow <= 0)) {
+ throw new Error(
+ `llm-deepseek: catalog model "${model.id}" contextWindow must be a positive integer`,
+ )
+ }
if (seen.has(model.id)) throw new Error(`llm-deepseek: duplicate catalog model "${model.id}"`)
seen.add(model.id)
return {
id: model.id,
...model.name === undefined ? {} : { name: model.name },
...model.description === undefined ? {} : { description: model.description },
+ ...model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow },
}
})
}
diff --git a/packages/llm/llm-deepseek/src/invariant.ts b/packages/llm/llm-deepseek/src/invariant.ts
new file mode 100644
index 0000000000..dd2df6e99c
--- /dev/null
+++ b/packages/llm/llm-deepseek/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-deepseek`.
+ * @module @deepseek-ai/dsh-llm-deepseek/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-deepseek'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-deepseek-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 0b2dae67bf..ffceaacd2d 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -517,6 +517,8 @@ describe('plugin registration and config', () => {
{ provider: 'deepseek', id: 'deepseek-v4-flash', name: 'deepseek-v4-flash' },
{ provider: 'deepseek', id: 'deepseek-v4-pro', name: 'deepseek-v4-pro' },
])
+ await expect(ctx.llm.resolveModelContext('deepseek', 'deepseek-v4-flash'))
+ .resolves.toEqual({ contextWindow: 128_000 })
})
it('uses the default model catalog when apply is called directly', async () => {
@@ -536,14 +538,23 @@ describe('plugin registration and config', () => {
apiKey: 'k',
baseURL: 'http://127.0.0.1:1',
models: [
- { id: 'private-fast' },
- { id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
+ { id: 'private-fast', contextWindow: 32_000 },
+ {
+ id: 'private-reasoner',
+ name: 'Private Reasoner',
+ description: 'Higher reasoning budget',
+ contextWindow: 64_000,
+ },
],
})
await expect(ctx.llm.listModels('deepseek')).resolves.toEqual([
{ provider: 'deepseek', id: 'private-fast', name: 'private-fast' },
{ provider: 'deepseek', id: 'private-reasoner', name: 'Private Reasoner', description: 'Higher reasoning budget' },
])
+ await expect(ctx.llm.resolveModelContext('deepseek', 'private-fast'))
+ .resolves.toEqual({ contextWindow: 32_000 })
+ await expect(ctx.llm.resolveModelContext('deepseek', 'arbitrary-unlisted'))
+ .resolves.toBeUndefined()
})
it('allows an explicit empty model catalog', async () => {
@@ -560,6 +571,8 @@ describe('plugin registration and config', () => {
it.each([
[[{ id: '' }], /ids must be non-empty/],
[[{ id: 'm', name: '' }], /empty name/],
+ [[{ id: 'm', contextWindow: 0 }], /contextWindow/],
+ [[{ id: 'm', contextWindow: 1.5 }], /contextWindow/],
[[{ id: 'm' }, { id: 'm' }], /duplicate catalog model/],
] as const)('rejects invalid advisory model config', async (models, message) => {
const ctx = new Context()
@@ -572,6 +585,19 @@ describe('plugin registration and config', () => {
expect(ctx.llm.listProviders()).toEqual([])
})
+ it('rejects invalid context capacity when apply is called directly', async () => {
+ const ctx = new Context()
+ await ctx.plugin(LlmService)
+ expect(() => {
+ LlmDeepSeek.apply(ctx, {
+ apiKey: 'k',
+ baseURL: 'http://127.0.0.1:1',
+ models: [{ id: 'invalid-context', contextWindow: 0 }],
+ })
+ }).toThrow(/contextWindow must be a positive integer/)
+ expect(ctx.llm.listProviders()).toEqual([])
+ })
+
it('falls back to DEEPSEEK_API_KEY and DEEPSEEK_BASE_URL env vars', async () => {
vi.stubEnv('DEEPSEEK_API_KEY', 'env-key')
vi.stubEnv('DEEPSEEK_BASE_URL', 'http://127.0.0.1:1')
diff --git a/packages/llm/llm-deepseek/tsconfig.json b/packages/llm/llm-deepseek/tsconfig.json
index 5e427d88b9..45c2af21a5 100644
--- a/packages/llm/llm-deepseek/tsconfig.json
+++ b/packages/llm/llm-deepseek/tsconfig.json
@@ -20,6 +20,9 @@
{
"path": "../../llm/llm"
},
+ {
+ "path": "../../support/invariants"
+ },
{
"path": "../../util/timeout"
}
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index bedfc5517d..8a6736f112 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -28,7 +28,7 @@ Configure credentials and deployment-specific transport settings per provider. O
Each provider name must exist in pi-ai's installed catalog and may appear only once in this plugin instance. Registration with `ctx.llm` is atomic: a collision with any provider route already owned by another adapter fails plugin loading without registering the remaining routes. Model ids are not lifecycle config; an unknown model fails before any provider request with `LlmError('UNKNOWN_MODEL')`.
-The adapter exposes each configured provider's installed pi-ai models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata derived from `getModels(provider)`; request-time resolution still performs the authoritative catalog lookup, so discovery does not create a second model registry.
+The adapter exposes each configured provider's installed pi-ai models through `ctx.llm.listModels(provider)`. This is provider-neutral selector metadata derived from `getModels(provider)`; request-time resolution still performs the authoritative catalog lookup, so discovery does not create a second model registry. `ctx.llm.resolveModelContext(provider, model)` performs the same exact descriptor lookup and returns its context window, keeping capacity metadata on the route-owning adapter rather than a consuming plugin.
Supported profile fields are `provider`, `apiKey`, `baseURL`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, and `streamIdleTimeoutMs`. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. Harness app attribution wins a conflicting configured header name.
diff --git a/packages/llm/llm-pi-ai/package.json b/packages/llm/llm-pi-ai/package.json
index 2a5aed1d76..06b4cbeb3a 100644
--- a/packages/llm/llm-pi-ai/package.json
+++ b/packages/llm/llm-pi-ai/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -31,6 +37,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-deepseek": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
diff --git a/packages/llm/llm-pi-ai/src/adapter.ts b/packages/llm/llm-pi-ai/src/adapter.ts
index 25240109bb..7d91e9c351 100644
--- a/packages/llm/llm-pi-ai/src/adapter.ts
+++ b/packages/llm/llm-pi-ai/src/adapter.ts
@@ -15,7 +15,7 @@ import type {
SimpleStreamOptions,
} from '@earendil-works/pi-ai'
import { attributionHeaders, LlmAdapter, LlmError } from '@deepseek-ai/dsh-llm'
-import type { GenerateOptions, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, LlmModelContext, LlmModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm'
import { idleWatchdog, timeoutOf } from '@deepseek-ai/dsh-timeout'
import { resolveProfiles } from './config.ts'
import type { PiAiProviderProfile, ResolvedPiAiProviderProfile } from './config.ts'
@@ -89,6 +89,22 @@ export class PiAiAdapter extends LlmAdapter {
})))
}
+ override resolveModelContext(
+ provider: string,
+ model: string,
+ ): Promise {
+ const profile = this.profiles.get(provider)
+ if (profile === undefined) {
+ return Promise.reject(new LlmError(
+ `pi-ai adapter does not own provider "${provider}"`,
+ 'NO_ADAPTER',
+ ))
+ }
+ return Promise.resolve().then(() => ({
+ contextWindow: resolveModel(profile, model).contextWindow,
+ }))
+ }
+
async * stream(options: GenerateOptions): AsyncIterable {
if (options.stop !== undefined) {
throw new LlmError('llm-pi-ai does not support GenerateOptions.stop', 'UNSUPPORTED_OPTION')
diff --git a/packages/llm/llm-pi-ai/src/invariant.ts b/packages/llm/llm-pi-ai/src/invariant.ts
new file mode 100644
index 0000000000..a096804fd2
--- /dev/null
+++ b/packages/llm/llm-pi-ai/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-llm-pi-ai`.
+ * @module @deepseek-ai/dsh-llm-pi-ai/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-pi-ai'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-pi-ai-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index 1b7445fa56..7b28cdc1b5 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -322,6 +322,9 @@ describe('provider profile lifecycle', () => {
provider: 'openai', id: 'gpt-4.1', name: 'GPT-4.1',
})
expect(models.every(model => model.provider === 'openai')).toBe(true)
+ const context = await ctx.llm.resolveModelContext('openai', 'gpt-4.1')
+ expect(context).toBeDefined()
+ expect(typeof context?.contextWindow).toBe('number')
})
it('accepts absent credentials for pi-ai ambient authentication', async () => {
@@ -373,6 +376,10 @@ describe('provider profile lifecycle', () => {
it('constructs the adapter directly and rejects routes it does not own', async () => {
const adapter = new PiAiAdapter({ profiles: [{ provider: 'openai' }] })
await expect(adapter.listModels('anthropic')).rejects.toMatchObject({ code: 'NO_ADAPTER' })
+ await expect(adapter.resolveModelContext('anthropic', 'claude-sonnet-4'))
+ .rejects.toMatchObject({ code: 'NO_ADAPTER' })
+ await expect(adapter.resolveModelContext('openai', 'not-a-catalog-model'))
+ .rejects.toMatchObject({ code: 'UNKNOWN_MODEL' })
await expect((async () => {
for await (const _chunk of adapter.stream({ provider: 'anthropic', model: 'claude-sonnet-4', messages: [] })) { /* drain */ }
})()).rejects.toMatchObject({ code: 'NO_ADAPTER' })
diff --git a/packages/llm/llm-pi-ai/tsconfig.json b/packages/llm/llm-pi-ai/tsconfig.json
index 5e427d88b9..45c2af21a5 100644
--- a/packages/llm/llm-pi-ai/tsconfig.json
+++ b/packages/llm/llm-pi-ai/tsconfig.json
@@ -20,6 +20,9 @@
{
"path": "../../llm/llm"
},
+ {
+ "path": "../../support/invariants"
+ },
{
"path": "../../util/timeout"
}
diff --git a/packages/llm/llm-retry/README.md b/packages/llm/llm-retry/README.md
index f84fdba09a..699e7e3dad 100644
--- a/packages/llm/llm-retry/README.md
+++ b/packages/llm/llm-retry/README.md
@@ -6,6 +6,8 @@ The default policy permits two retries for `RATE_LIMIT`, `SERVER`, `TIMEOUT`, an
Before waiting, the plugin appends a non-surface `llm/retry` event with the failure and scheduled delay. Cancellation and plugin disposal abort the wait; disposal drains the plugin's active backoffs, and a callback captured before disposal fails closed if invoked afterward.
+The separately published `./invariant` companion checks that every retry record names the current open turn and its latest closed step, has a unique step record and increasing retry number, and carries a positive bounded retry budget and non-negative bounded timer delay. Full jitter may schedule zero milliseconds at its lower boundary.
+
```yaml
- name: '@deepseek-ai/dsh-llm-retry'
config:
diff --git a/packages/llm/llm-retry/package.json b/packages/llm/llm-retry/package.json
index fce40dbe33..6d6c27636c 100644
--- a/packages/llm/llm-retry/package.json
+++ b/packages/llm/llm-retry/package.json
@@ -11,10 +11,15 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -22,6 +27,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
@@ -35,6 +41,7 @@
"@cordisjs/plugin-loader": "workspace:^",
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
diff --git a/packages/llm/llm-retry/src/invariant.ts b/packages/llm/llm-retry/src/invariant.ts
new file mode 100644
index 0000000000..784f459606
--- /dev/null
+++ b/packages/llm/llm-retry/src/invariant.ts
@@ -0,0 +1,97 @@
+/** Package-owned durable retry-event invariants. @module @deepseek-ai/dsh-llm-retry/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type {} from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm-retry'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-retry-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Validate one retry record against the open turn and most recently closed step. */
+function validateRetry(
+ history: readonly SessionEvent[],
+ event: SessionEvent<'llm/retry'>,
+ fail: InvariantFailure,
+): void {
+ const { turn, step, retry, maxRetries, delayMs } = event.data
+ if (!Number.isSafeInteger(retry) || retry < 1) {
+ fail('llm/retry retry must be a positive safe integer')
+ }
+ if (!Number.isSafeInteger(maxRetries) || maxRetries < 1 || retry > maxRetries) {
+ fail(`llm/retry retry ${retry} must not exceed a positive safe maxRetries ${maxRetries}`)
+ }
+ if (!(delayMs >= 0 && delayMs <= MAX_TIMER_DELAY_MS)) {
+ fail(`llm/retry delayMs must be within 0..${MAX_TIMER_DELAY_MS}`)
+ }
+
+ const currentTurnEvents: SessionEvent[] = []
+ let openTurn: number | undefined
+ for (const prior of history.slice().reverse()) {
+ if (prior.type === 'turn/end') fail('llm/retry must be appended inside an open turn')
+ if (prior.type === 'turn/start') {
+ openTurn = prior.data.turn
+ break
+ }
+ currentTurnEvents.push(prior)
+ }
+ if (openTurn === undefined) fail('llm/retry must be appended inside an open turn')
+ if (turn !== openTurn) {
+ fail(`llm/retry names turn ${turn}, but the open turn is ${openTurn}`)
+ }
+
+ let closedStep: number | undefined
+ for (const prior of currentTurnEvents) {
+ if (prior.type === 'step/start') {
+ fail(`llm/retry must follow step/end, but step ${prior.data.step} is still open`)
+ }
+ if (prior.type === 'step/end') {
+ closedStep = prior.data.step
+ break
+ }
+ }
+ if (closedStep === undefined || step !== closedStep) {
+ fail(`llm/retry names step ${step}, but the latest closed step is ${String(closedStep)}`)
+ }
+
+ const priorRetries = currentTurnEvents
+ .filter((prior): prior is SessionEvent<'llm/retry'> => prior.type === 'llm/retry')
+ if (priorRetries.some(prior => prior.data.step === step)) {
+ fail(`llm/retry duplicates the retry record for turn ${turn}/step ${step}`)
+ }
+ const priorRetry = priorRetries[0]
+ if (priorRetry !== undefined && retry <= priorRetry.data.retry) {
+ fail(`llm/retry retry ${retry} must increase after retry ${priorRetry.data.retry}`)
+ }
+}
+
+/** Validate every retry record already present in one loaded session. */
+function validateSession(session: Session, fail: InvariantFailure): void {
+ for (const [index, event] of session.events.entries()) {
+ if (event.type === 'llm/retry') validateRetry(session.events.slice(0, index), event, fail)
+ }
+}
+
+/** Install validation for loaded and newly appended retry records. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ for (const session of ctx.sessions.list()) validateSession(session, fail)
+ ctx.on('session/created', (session) => { validateSession(session, fail) }, { global: true })
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const [session, event] = args as [Session, SessionEvent]
+ if (event.type === 'llm/retry') validateRetry(session.events, event, fail)
+ }, { global: true })
+}, { inject: ['sessions'] })
+
+/**
+ * Register the LLM retry invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/llm/llm-retry/tests/invariant.spec.ts b/packages/llm/llm-retry/tests/invariant.spec.ts
new file mode 100644
index 0000000000..81b1aca16d
--- /dev/null
+++ b/packages/llm/llm-retry/tests/invariant.spec.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as RetryInvariant from '@deepseek-ai/dsh-llm-retry/invariant'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(RetryInvariant)
+ return ctx
+}
+
+function closeStep(ctx: Context, id: string, turn = 1, step = 1) {
+ const session = ctx.sessions.create(SessionId(id))
+ session.append('turn/start', { turn, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('step/start', { turn, step })
+ session.append('step/end', { turn, step })
+ return session
+}
+
+const failure = { message: 'provider busy', code: 'RATE_LIMIT', status: 429 }
+
+describe('llm-retry invariants', () => {
+ it('accepts increasing retry records for successive closed steps and ignores unrelated events', async () => {
+ const ctx = await setup()
+ const session = closeStep(ctx, 'retry-invariant-valid')
+ expect(() => {
+ session.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 500, failure,
+ })
+ session.append('step/start', { turn: 1, step: 2 })
+ session.append('step/end', { turn: 1, step: 2 })
+ session.append('llm/retry', {
+ turn: 1, step: 2, retry: 2, maxRetries: 2, delayMs: 1_000, failure,
+ })
+ const zeroDelay = closeStep(ctx, 'retry-invariant-zero-delay')
+ zeroDelay.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 1, delayMs: 0, failure,
+ })
+ }).not.toThrow()
+ expect(() => { ctx.emit('tools/change') }).not.toThrow()
+ })
+
+ it.each([
+ [{ retry: 0, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
+ [{ retry: 1.5, maxRetries: 2, delayMs: 1 }, /positive safe integer/],
+ [{ retry: 1, maxRetries: 0, delayMs: 1 }, /positive safe maxRetries/],
+ [{ retry: 1, maxRetries: 1.5, delayMs: 1 }, /positive safe maxRetries/],
+ [{ retry: 3, maxRetries: 2, delayMs: 1 }, /must not exceed/],
+ [{ retry: 1, maxRetries: 2, delayMs: -1 }, /delayMs/],
+ [{ retry: 1, maxRetries: 2, delayMs: MAX_TIMER_DELAY_MS + 1 }, /delayMs/],
+ ])('rejects invalid retry bounds %#', async (data, message) => {
+ const ctx = await setup()
+ const session = closeStep(ctx, `retry-invariant-bounds-${data.retry}-${data.maxRetries}-${data.delayMs}`)
+ expect(() => {
+ session.append('llm/retry', { turn: 1, step: 1, ...data, failure })
+ }).toThrow(message)
+ })
+
+ it('rejects retry records outside the matching closed-step boundary', async () => {
+ const ctx = await setup()
+ const absent = ctx.sessions.create(SessionId('retry-invariant-no-turn'))
+ expect(() => {
+ absent.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/inside an open turn/)
+
+ const wrongTurn = closeStep(ctx, 'retry-invariant-wrong-turn')
+ expect(() => {
+ wrongTurn.append('llm/retry', {
+ turn: 2, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/open turn is 1/)
+
+ const openStep = ctx.sessions.create(SessionId('retry-invariant-open-step'))
+ openStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ openStep.append('step/start', { turn: 1, step: 1 })
+ expect(() => {
+ openStep.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/step 1 is still open/)
+
+ const noStep = ctx.sessions.create(SessionId('retry-invariant-no-step'))
+ noStep.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ expect(() => {
+ noStep.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/latest closed step is undefined/)
+
+ const wrongStep = closeStep(ctx, 'retry-invariant-wrong-step')
+ expect(() => {
+ wrongStep.append('llm/retry', {
+ turn: 1, step: 2, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/latest closed step is 1/)
+
+ const closedTurn = closeStep(ctx, 'retry-invariant-closed-turn')
+ closedTurn.append('turn/end', { turn: 1, reason: { kind: 'aborted', reason: 'cancelled' } })
+ expect(() => {
+ closedTurn.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ }).toThrow(/inside an open turn/)
+ })
+
+ it('rejects duplicate and non-increasing retry records', async () => {
+ const ctx = await setup()
+ const duplicate = closeStep(ctx, 'retry-invariant-duplicate')
+ duplicate.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
+ })
+ expect(() => {
+ duplicate.append('llm/retry', {
+ turn: 1, step: 1, retry: 2, maxRetries: 3, delayMs: 1, failure,
+ })
+ }).toThrow(/duplicates the retry record/)
+
+ const nonIncreasing = closeStep(ctx, 'retry-invariant-non-increasing')
+ nonIncreasing.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 3, delayMs: 1, failure,
+ })
+ nonIncreasing.append('step/start', { turn: 1, step: 2 })
+ nonIncreasing.append('step/end', { turn: 1, step: 2 })
+ expect(() => {
+ nonIncreasing.append('llm/retry', {
+ turn: 1, step: 2, retry: 1, maxRetries: 3, delayMs: 1, failure,
+ })
+ }).toThrow(/must increase/)
+ })
+
+ it('validates existing histories on late registration', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ const session = ctx.sessions.create(SessionId('retry-invariant-late'))
+ session.append('step/end', { turn: 1, step: 1 })
+ session.append('llm/retry', {
+ turn: 1, step: 1, retry: 1, maxRetries: 2, delayMs: 1, failure,
+ })
+ await ctx.plugin(InvariantService)
+ await expect(ctx.plugin(RetryInvariant)).rejects.toThrow(/inside an open turn/)
+ })
+})
diff --git a/packages/llm/llm-retry/tests/retry.spec.ts b/packages/llm/llm-retry/tests/retry.spec.ts
index 18669920e0..f81f69cf10 100644
--- a/packages/llm/llm-retry/tests/retry.spec.ts
+++ b/packages/llm/llm-retry/tests/retry.spec.ts
@@ -232,6 +232,29 @@ describe('bounded transient retry policy', () => {
})
})
+ it('accepts the zero-delay lower jitter bound', async () => {
+ vi.useFakeTimers()
+ const adapter = new ScriptedAdapter([
+ new LlmError('busy', 'SERVER'),
+ textResponse('done'),
+ ])
+ ;({ ctx: context } = await harness(adapter, {
+ initialDelayMs: 1,
+ maxDelayMs: 1,
+ jitterRatio: 1,
+ }, undefined, { random: () => 0 }))
+ const agent = context.agentLoop.create(SessionId('retry-zero-delay'), { provider: 'mock', model: 'mock' })
+ const scheduled = waitForRetry(context, agent, 1)
+
+ agent.send([{ type: 'text', text: 'go' }])
+ expect((await scheduled).data.delayMs).toBe(0)
+
+ const idle = waitForIdle(context, agent)
+ await vi.runAllTimersAsync()
+ await idle
+ expect(adapter.requests).toHaveLength(2)
+ })
+
it('uses a bounded provider Retry-After verbatim and delegates an over-cap instruction', async () => {
vi.useFakeTimers()
const accepted = new ScriptedAdapter([
diff --git a/packages/llm/llm-retry/tsconfig.json b/packages/llm/llm-retry/tsconfig.json
index 44310af6e9..48c858951a 100644
--- a/packages/llm/llm-retry/tsconfig.json
+++ b/packages/llm/llm-retry/tsconfig.json
@@ -26,6 +26,9 @@
{
"path": "../../core/agent"
},
+ {
+ "path": "../../support/invariants"
+ },
{
"path": "../../util/timeout"
}
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index a5ccd42b43..e92527d7c8 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -11,12 +11,15 @@ An adapter registry plus a single streaming call surface, interceptable via a wa
- `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): () => void` Register one adapter instance for the given provider routes. Registration is all-or-nothing, and is disposed with the calling fiber.
- `ctx.llm.listProviders(): LlmProviderInfo[]` Describe registered provider routes in registration order.
- `ctx.llm.listModels(provider: string): Promise` Discover the models one registered provider currently advertises.
+- `ctx.llm.resolveModelContext(provider: string, model: string): Promise` Resolve authoritative context capacity for one exact route from its owning adapter.
- `ctx.llm.stream(options: GenerateOptions): AsyncIterable` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
`LlmService` preserves errors from final adapter selection, synchronous dispatch, iterator construction, and iteration, and binds their provenance to the exact stream handle returned for that model call. `isLlmAdapterFailure(stream, value)` reports only errors from that call's final adapter boundary; `llmFailureOf(stream, value)` returns the adjacent immutable `LlmFailure`. Nested model calls, `llm/stream` middleware, and downstream consumer failures remain unclassified for the outer call. Classification never replaces or mutates the adapter's original coded `Error`.
Provider and model metadata is a discovery surface, not a routing whitelist. `registerAdapter()` still owns provider exclusivity, while an adapter may accept model ids absent from `listModels()`; consumers must not reject a request because its model is unlisted. Returned metadata is detached and invalid or duplicate adapter entries fail with `INVALID_ADAPTER` or `INVALID_CATALOG`.
+Context capacity is a separate correctness query, not a catalog decoration or global LLM setting. `resolveModelContext()` asks the adapter that owns the exact provider/model route; an adapter can describe an unlisted dynamic model, and `undefined` means only that capacity is unavailable. Invalid returned capacity fails with `INVALID_MODEL_CONTEXT`.
+
### Events
| Event | Mode | Purpose |
@@ -25,7 +28,7 @@ Provider and model metadata is a discovery surface, not a routing whitelist. `re
### Extension points
-- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(providers, adapter)` to add one or more provider routes. `GenerateOptions.provider` selects the adapter; `GenerateOptions.model` is adapter-owned and may be resolved dynamically. Override `providerInfo()` and asynchronous `listModels()` to expose selector metadata; their defaults use the route id as its name and advertise no models.
+- Subclass `LlmAdapter` and call `ctx.llm.registerAdapter(providers, adapter)` to add one or more provider routes. `GenerateOptions.provider` selects the adapter; `GenerateOptions.model` is adapter-owned and may be resolved dynamically. Override `providerInfo()` and asynchronous `listModels()` to expose selector metadata, and `resolveModelContext()` when exact capacity is known; the defaults use the route id as its name, advertise no models, and return no capacity.
- Wrap `llm/stream` via `ctx.on()` waterfall listeners for caching, logging, or routing. A wrapper that retries after emitting a chunk has no durable attempt boundary; shipped agent retry policy therefore uses `agent/request-error` instead.
### Content-block vocabulary (`types.ts`)
diff --git a/packages/llm/llm/package.json b/packages/llm/llm/package.json
index ab11c8574f..9ef3e3323e 100644
--- a/packages/llm/llm/package.json
+++ b/packages/llm/llm/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,10 +28,12 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index fb431a308c..ce8b85f08c 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -7,7 +7,15 @@
*/
import { Context, Service } from 'cordis'
-import type { GenerateOptions, LlmFailure, LlmModelInfo, LlmProviderInfo, Message, StreamChunk } from './types.ts'
+import type {
+ GenerateOptions,
+ LlmFailure,
+ LlmModelContext,
+ LlmModelInfo,
+ LlmProviderInfo,
+ Message,
+ StreamChunk,
+} from './types.ts'
import type { ProviderRequestId } from './brand.ts'
import { deepFreeze } from './call-config.ts'
import { HarnessError } from './error.ts'
@@ -122,6 +130,20 @@ export abstract class LlmAdapter {
return Promise.resolve([])
}
+ /**
+ * Resolve context capacity for one model accepted by this adapter. Absence
+ * means the adapter does not know the capacity, not that routing is invalid.
+ * @param _provider - one provider route owned by this adapter.
+ * @param _model - exact model id passed to {@link GenerateOptions.model}.
+ * @returns provider-owned context metadata, or `undefined` when unavailable.
+ */
+ resolveModelContext(
+ _provider: string,
+ _model: string,
+ ): Promise {
+ return Promise.resolve(undefined)
+ }
+
/**
* Stream one model call as raw chunks. The only required method.
* @param options - the fully-assembled request; implementations must honor `options.signal`.
@@ -217,6 +239,29 @@ export class LlmService extends Service {
})
}
+ /**
+ * Resolve context capacity from the adapter that owns one exact route.
+ * This query is independent of the advisory model catalog: an unlisted model
+ * may return metadata, while `undefined` never rejects later routing.
+ * @param provider - registered provider route to inspect.
+ * @param model - exact model id passed to the adapter.
+ * @returns detached context metadata, or `undefined` when the adapter has none.
+ */
+ async resolveModelContext(
+ provider: string,
+ model: string,
+ ): Promise {
+ const context = await this.registration(provider).adapter.resolveModelContext(provider, model)
+ if (context === undefined) return undefined
+ if (!Number.isInteger(context.contextWindow) || context.contextWindow <= 0) {
+ throw new LlmError(
+ `adapter returned invalid context metadata for provider "${provider}" model "${model}"`,
+ 'INVALID_MODEL_CONTEXT',
+ )
+ }
+ return { contextWindow: context.contextWindow }
+ }
+
private registration(provider: string): { adapter: LlmAdapter; provider: LlmProviderInfo } {
const registration = this.adapters.get(provider)
if (!registration) throw new LlmError(`no adapter registered for provider "${provider}"`, 'NO_ADAPTER')
diff --git a/packages/llm/llm/src/invariant.ts b/packages/llm/llm/src/invariant.ts
new file mode 100644
index 0000000000..76d55509cb
--- /dev/null
+++ b/packages/llm/llm/src/invariant.ts
@@ -0,0 +1,95 @@
+/** Package-owned LLM stream-protocol invariants. @module @deepseek-ai/dsh-llm/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { ContentBlockType, StreamChunk } from './types.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-llm'
+
+/** Cordis companion plugin name. */
+export const name = 'llm-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Require one chunk index to be a non-negative safe integer. */
+function validateIndex(index: number, fail: InvariantFailure): void {
+ if (!Number.isSafeInteger(index) || index < 0) {
+ fail(`LLM stream block index must be a non-negative safe integer, got ${index}`)
+ }
+}
+
+/** Require a delta to address an open block of its matching type. */
+function validateDelta(
+ open: ReadonlyMap,
+ index: number,
+ expected: ContentBlockType,
+ fail: InvariantFailure,
+): void {
+ validateIndex(index, fail)
+ const actual = open.get(index)
+ if (actual !== expected) {
+ fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`)
+ }
+}
+
+/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
+async function* validateStream(
+ source: AsyncIterable,
+ fail: InvariantFailure,
+): AsyncIterable {
+ const open = new Map()
+ let usageSeen = false
+ let finished = false
+ for await (const chunk of source) {
+ if (finished) fail(`LLM stream emitted ${chunk.type} after terminal finish`)
+ switch (chunk.type) {
+ case 'block-start':
+ validateIndex(chunk.index, fail)
+ if (open.has(chunk.index)) fail(`LLM stream repeated block-start index ${chunk.index}`)
+ open.set(chunk.index, chunk.blockType)
+ break
+ case 'text-delta':
+ validateDelta(open, chunk.index, 'text', fail)
+ break
+ case 'reasoning-delta':
+ validateDelta(open, chunk.index, 'reasoning', fail)
+ break
+ case 'tool-call-delta':
+ validateDelta(open, chunk.index, 'tool-call', fail)
+ break
+ case 'block-end': {
+ validateIndex(chunk.index, fail)
+ const blockType = open.get(chunk.index)
+ if (blockType === undefined) fail(`LLM stream block-end index ${chunk.index} has no open block`)
+ if (chunk.block.type !== blockType) {
+ fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`)
+ }
+ open.delete(chunk.index)
+ break
+ }
+ case 'usage':
+ if (usageSeen) fail('LLM stream emitted usage more than once')
+ usageSeen = true
+ break
+ case 'finish':
+ if (open.size > 0) fail(`LLM stream finished with ${open.size} open block(s)`)
+ finished = true
+ break
+ }
+ yield chunk
+ }
+ if (!finished) fail('LLM stream ended without a terminal finish chunk')
+}
+
+/** Install validation around every provider stream. */
+const install: InvariantInstaller = (ctx, fail) => {
+ ctx.on('llm/stream', (_options, next) => validateStream(next(), fail), { global: true, prepend: true })
+}
+
+/**
+ * Register the LLM invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts
index bbe2e09b59..0cb8fa6935 100644
--- a/packages/llm/llm/src/types.ts
+++ b/packages/llm/llm/src/types.ts
@@ -155,6 +155,12 @@ export interface LlmModelInfo {
description?: string
}
+/** Provider-owned context capacity for one exact provider/model route. */
+export interface LlmModelContext {
+ /** Maximum combined request and response context in tokens. */
+ contextWindow: number
+}
+
/**
* Raw streaming protocol emitted by adapters.
* Block indexes correlate interleaved deltas, and `block-end` carries the
diff --git a/packages/llm/llm/tests/invariant.spec.ts b/packages/llm/llm/tests/invariant.spec.ts
new file mode 100644
index 0000000000..9eb868df1c
--- /dev/null
+++ b/packages/llm/llm/tests/invariant.spec.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import * as LlmInvariant from '@deepseek-ai/dsh-llm/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(LlmInvariant)
+ return ctx
+}
+
+const options: GenerateOptions = { provider: 'mock', model: 'mock', messages: [] }
+
+async function* source(chunks: readonly StreamChunk[]): AsyncIterable {
+ yield* chunks
+}
+
+async function consume(ctx: Context, chunks: readonly StreamChunk[]): Promise {
+ const stream = ctx.waterfall(ctx as never, 'llm/stream', options, () => source(chunks))
+ const consumed: StreamChunk[] = []
+ for await (const chunk of stream) consumed.push(chunk)
+ return consumed
+}
+
+const finish: StreamChunk = { type: 'finish', reason: { kind: 'stop' } }
+
+describe('LLM stream invariants', () => {
+ it('accepts a complete interleaved stream grammar', async () => {
+ const ctx = await setup()
+ const chunks: StreamChunk[] = [
+ { type: 'block-start', index: 0, blockType: 'text' },
+ { type: 'text-delta', index: 0, text: 'a' },
+ { type: 'block-start', index: 1, blockType: 'reasoning' },
+ { type: 'reasoning-delta', index: 1, text: 'b' },
+ { type: 'block-end', index: 1, block: { type: 'reasoning', text: 'b' } },
+ { type: 'block-end', index: 0, block: { type: 'text', text: 'a' } },
+ { type: 'block-start', index: 2, blockType: 'tool-call' },
+ { type: 'tool-call-delta', index: 2, id: CallId('c1'), name: 'echo', argumentsDelta: '{}' },
+ { type: 'block-end', index: 2, block: { type: 'tool-call', id: CallId('c1'), name: 'echo', arguments: '{}' } },
+ { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+ finish,
+ ]
+ await expect(consume(ctx, chunks)).resolves.toEqual(chunks)
+ })
+
+ it.each([
+ [[{ type: 'block-start', index: -1, blockType: 'text' }, finish], /non-negative safe integer/],
+ [[
+ { type: 'block-start', index: 0, blockType: 'text' },
+ { type: 'block-start', index: 0, blockType: 'text' },
+ ], /repeated block-start/],
+ [[{ type: 'text-delta', index: 0, text: 'x' }], /requires an open text block/],
+ [[
+ { type: 'block-start', index: 0, blockType: 'reasoning' },
+ { type: 'text-delta', index: 0, text: 'x' },
+ ], /got reasoning/],
+ [[{ type: 'block-end', index: 0, block: { type: 'text', text: '' } }], /has no open block/],
+ [[
+ { type: 'block-start', index: 0, blockType: 'text' },
+ { type: 'block-end', index: 0, block: { type: 'reasoning', text: '' } },
+ ], /closes reasoning, expected text/],
+ [[
+ { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+ { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } },
+ ], /usage more than once/],
+ [[{ type: 'block-start', index: 0, blockType: 'text' }, finish], /finished with 1 open block/],
+ [[finish, { type: 'usage', usage: { inputTokens: 1, outputTokens: 1 } }], /usage after terminal finish/],
+ [[], /ended without a terminal finish/],
+ ] as Array<[StreamChunk[], RegExp]>)('rejects malformed stream %#', async (chunks, message) => {
+ const ctx = await setup()
+ await expect(consume(ctx, chunks)).rejects.toThrow(message)
+ })
+
+ it('preserves provider exceptions without inventing a missing-finish failure', async () => {
+ const ctx = await setup()
+ const stream = ctx.waterfall(ctx as never, 'llm/stream', options, async function* () {
+ throw new Error('provider failed')
+ })
+ await expect((async () => {
+ for await (const _chunk of stream) { /* consume */ }
+ })()).rejects.toThrow('provider failed')
+ })
+})
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index 9f90a2b7cd..90be1ffcb0 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -13,7 +13,7 @@ import LlmService, {
ProviderRequestId,
StreamChunk,
} from '@deepseek-ai/dsh-llm'
-import type { LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
+import type { LlmModelContext, LlmModelInfo, LlmProviderInfo } from '@deepseek-ai/dsh-llm'
class ScriptedAdapter extends LlmAdapter {
constructor(private script: StreamChunk[]) {
@@ -48,6 +48,7 @@ class CatalogAdapter extends ScriptedAdapter {
constructor(
private readonly provider: LlmProviderInfo,
private readonly models: readonly LlmModelInfo[],
+ private readonly contexts: Readonly> = {},
) {
super(SCRIPT)
}
@@ -59,11 +60,19 @@ class CatalogAdapter extends ScriptedAdapter {
override listModels(_provider: string): Promise {
return Promise.resolve(this.models)
}
+
+ override resolveModelContext(
+ _provider: string,
+ model: string,
+ ): Promise {
+ return Promise.resolve(this.contexts[model])
+ }
}
const SCRIPT: StreamChunk[] = [
{ type: 'block-start', index: 0, blockType: 'text' },
{ type: 'text-delta', index: 0, text: 'hi' },
+ { type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } },
{ type: 'finish', reason: { kind: 'stop' } },
]
@@ -644,8 +653,42 @@ describe('LlmService', () => {
expect(ctx.llm.listProviders()).toEqual([{ id: 'plain', name: 'plain' }])
await expect(ctx.llm.listModels('plain')).resolves.toEqual([])
await expect(ctx.llm.listModels('missing')).rejects.toMatchObject({ code: 'NO_ADAPTER' })
+ await expect(ctx.llm.resolveModelContext('plain', 'unlisted')).resolves.toBeUndefined()
+ await expect(ctx.llm.resolveModelContext('missing', 'm')).rejects.toMatchObject({ code: 'NO_ADAPTER' })
})
+ it('resolves detached model context independently of advisory catalog membership', async () => {
+ const ctx = new Context()
+ await ctx.plugin(LlmService)
+ const source = { contextWindow: 32_000 }
+ ctx.llm.registerAdapter(['route'], new CatalogAdapter(
+ { id: 'route', name: 'Route' },
+ [],
+ { unlisted: source },
+ ))
+
+ const resolved = await ctx.llm.resolveModelContext('route', 'unlisted')
+ expect(resolved).toEqual({ contextWindow: 32_000 })
+ source.contextWindow = 64_000
+ expect(resolved).toEqual({ contextWindow: 32_000 })
+ await expect(ctx.llm.resolveModelContext('route', 'other')).resolves.toBeUndefined()
+ })
+
+ it.each([0, -1, 1.5, Number.NaN])(
+ 'rejects invalid adapter model context %s',
+ async (contextWindow) => {
+ const ctx = new Context()
+ await ctx.plugin(LlmService)
+ ctx.llm.registerAdapter(['route'], new CatalogAdapter(
+ { id: 'route', name: 'Route' },
+ [],
+ { model: { contextWindow } },
+ ))
+ await expect(ctx.llm.resolveModelContext('route', 'model'))
+ .rejects.toMatchObject({ code: 'INVALID_MODEL_CONTEXT' })
+ },
+ )
+
it.each([
[{ id: 1, name: 'Name' }, 'non-string id'],
[{ id: 'other', name: 'Name' }, 'mismatched id'],
@@ -694,13 +737,14 @@ describe('LlmService', () => {
const inner = next()
return (async function * () {
yield { type: 'block-start', index: 99, blockType: 'text' } satisfies StreamChunk
+ yield { type: 'block-end', index: 99, block: { type: 'text', text: '' } } satisfies StreamChunk
yield * inner
})()
})
const chunks: StreamChunk[] = []
for await (const chunk of ctx.llm.stream({ provider: 'test-model', model: 'dynamic-model', messages: [] })) chunks.push(chunk)
- expect(chunks).toHaveLength(4)
+ expect(chunks).toHaveLength(6)
expect(chunks[0]).toMatchObject({ index: 99 })
})
diff --git a/packages/llm/llm/tsconfig.json b/packages/llm/llm/tsconfig.json
index 342f636170..5bc7a9fcf5 100644
--- a/packages/llm/llm/tsconfig.json
+++ b/packages/llm/llm/tsconfig.json
@@ -16,6 +16,9 @@
},
{
"path": "../../util/brand"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/llm/token-meter/README.md b/packages/llm/token-meter/README.md
index 20539de6a4..18f828ddd4 100644
--- a/packages/llm/token-meter/README.md
+++ b/packages/llm/token-meter/README.md
@@ -4,11 +4,7 @@ Replay-aware token measurement through the singleton `ctx.tokenMeter` service. I
## 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.
+The estimator has no settings. It intentionally uses one fixed heuristic: four characters per token plus structural overhead for roles, blocks, and request-envelope fields. Any key is rejected, including the obsolete global `contextWindow`; model capacity belongs to the adapter that owns an exact provider/model route and is available through `ctx.llm.resolveModelContext()`.
## Measurement contract
@@ -30,13 +26,7 @@ Usage accounting sums disjoint input, cache-read, cache-write, and output bucket
- 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
-```
+Both plugins have usable defaults. The meter remains independent of model routing and optional compaction. A deployment configures capacity on its LLM adapter and compaction policy on `dsh-compact-basic`.
## Model Experience
diff --git a/packages/llm/token-meter/package.json b/packages/llm/token-meter/package.json
index 13fa4e3cdc..dadd5e8f8d 100644
--- a/packages/llm/token-meter/package.json
+++ b/packages/llm/token-meter/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@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
index 0c18dee74b..e17b0c06b6 100644
--- a/packages/llm/token-meter/src/index.ts
+++ b/packages/llm/token-meter/src/index.ts
@@ -19,12 +19,6 @@ import type {
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
@@ -74,28 +68,10 @@ function optionalHeaderEquals(
/** 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)`,
- )
- }
+ throw new Error(`TokenMeterConfig: unknown key "${key}" (no settings are supported)`)
}
}
-/** 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
@@ -104,18 +80,15 @@ declare module 'cordis' {
/** 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
+ // Schemastery preserves untrusted loader keys on an empty object schema;
+ // the public type excludes settings while validateConfigKeys rejects them.
+ static Config: z = z.object({}) as unknown as z
private readonly states = new WeakMap()
constructor(ctx: Context, config: TokenMeterConfig = {}) {
super(ctx, 'tokenMeter')
- this.contextWindow = resolveContextWindow(config)
+ validateConfigKeys(config)
// Readers catch up independently, while eager observation bounds ordinary
// read latency without creating state for sessions no consumer has read.
diff --git a/packages/llm/token-meter/src/invariant.ts b/packages/llm/token-meter/src/invariant.ts
new file mode 100644
index 0000000000..b8f0cc385a
--- /dev/null
+++ b/packages/llm/token-meter/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-token-meter`.
+ * @module @deepseek-ai/dsh-token-meter/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-token-meter'
+
+/** Cordis companion plugin name. */
+export const name = 'token-meter-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: token estimates are per-call outputs and the private session cache is
+ * invalidated at its event mutation boundary; neither exposes an independent observation stream.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/llm/token-meter/src/types.ts b/packages/llm/token-meter/src/types.ts
index 7fb35af997..255425b639 100644
--- a/packages/llm/token-meter/src/types.ts
+++ b/packages/llm/token-meter/src/types.ts
@@ -6,11 +6,8 @@
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
-}
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record
/** The baseline from which a signed surface delta produces current pressure. */
export type TokenMeasurementBaseline =
diff --git a/packages/llm/token-meter/tests/token-meter.spec.ts b/packages/llm/token-meter/tests/token-meter.spec.ts
index e7ddca6696..e3618474e2 100644
--- a/packages/llm/token-meter/tests/token-meter.spec.ts
+++ b/packages/llm/token-meter/tests/token-meter.spec.ts
@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { describe, expect, expectTypeOf, it } from 'vitest'
import { Context } from 'cordis'
import { CallId } from '@deepseek-ai/dsh-llm'
import type { ContentBlock, Message, TokenUsage } from '@deepseek-ai/dsh-llm'
@@ -87,29 +87,18 @@ function expectSurfaceTotal(measurement: TokenMeasurement): void {
}
describe('TokenMeterService configuration and registration', () => {
- it('provides one zero-config context window', () => {
- const service = meter()
- expect(service.contextWindow).toBe(128_000)
+ it('exposes an empty public configuration type', () => {
+ expectTypeOf<{}>().toExtend()
+ expectTypeOf<{ contextWindow: number }>().not.toExtend()
})
- 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.each(['models', 'contextWindow', 'contextWidow'])(
+ 'rejects stale or unknown top-level config key %s',
+ (key) => {
+ expect(() => meter({ [key]: {} } as unknown as TokenMeterConfig))
+ .toThrow(`TokenMeterConfig: unknown key "${key}"`)
+ },
+ )
it('registers and unregisters ctx.tokenMeter with its plugin fiber', async () => {
const ctx = new Context()
@@ -123,7 +112,7 @@ describe('TokenMeterService configuration and registration', () => {
describe('TokenMeterService pricing', () => {
it('prices every built-in content shape and merge-extended blocks with one fixed heuristic', () => {
- const service = meter({ contextWindow: 100 })
+ const service = meter()
const blocks: ContentBlock[] = [
{ type: 'text', text: 'abcd' },
{ type: 'reasoning', text: 'ab' },
@@ -331,7 +320,7 @@ describe('replay anchors and surface folds', () => {
})
it('keeps only the latest successful request anchor across model switches', () => {
- const service = meter({ contextWindow: 1_000 })
+ const service = meter()
const session = new Session(SessionId('switch'))
const alphaHeader = header('alpha', { system: 'same envelope' })
appendSuccessfulCall(session, alphaHeader, { usage: USAGE, providerText: 'alpha' })
@@ -631,19 +620,24 @@ describe('malformed replay and listener lifecycle', () => {
})
const firstFiber = await ctx.plugin(TokenMeterService)
activeMeter = ctx.tokenMeter
- const session = ctx.sessions.create(SessionId('listener-order'))
+ const session = ctx.sessions.create(SessionId('listener-order'), { seed: [{
+ type: 'turn/start',
+ seq: 0,
+ time: 1,
+ data: { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } },
+ }] })
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)
+ expect(revisions).toEqual([2])
+ expect(activeMeter.measure(session).logRevision).toBe(2)
await firstFiber.dispose()
const secondFiber = await ctx.plugin(TokenMeterService)
activeMeter = ctx.tokenMeter
- expect(activeMeter.measure(session).logRevision).toBe(1)
+ expect(activeMeter.measure(session).logRevision).toBe(2)
await secondFiber.dispose()
})
})
diff --git a/packages/llm/token-meter/tsconfig.json b/packages/llm/token-meter/tsconfig.json
index 5e1604e02f..481fad6e15 100644
--- a/packages/llm/token-meter/tsconfig.json
+++ b/packages/llm/token-meter/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/lsp/lsp-local/package.json b/packages/lsp/lsp-local/package.json
index 68e6cf7764..6815b1c917 100644
--- a/packages/lsp/lsp-local/package.json
+++ b/packages/lsp/lsp-local/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-lsp": "^0.0.1",
"@deepseek-ai/dsh-timeout": "^0.0.1",
@@ -33,6 +39,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-lsp": "workspace:^",
"@deepseek-ai/dsh-timeout": "workspace:^",
diff --git a/packages/lsp/lsp-local/src/invariant.ts b/packages/lsp/lsp-local/src/invariant.ts
new file mode 100644
index 0000000000..52ebd16dc0
--- /dev/null
+++ b/packages/lsp/lsp-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-lsp-local`.
+ * @module @deepseek-ai/dsh-lsp-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-lsp-local'
+
+/** Cordis companion plugin name. */
+export const name = 'lsp-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: process pools and per-workspace queues are private implementation state,
+ * and this provider publishes no independent lifecycle event stream or enumerable snapshot.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/lsp/lsp-local/tsconfig.json b/packages/lsp/lsp-local/tsconfig.json
index 281a8cebbf..3a631ae288 100644
--- a/packages/lsp/lsp-local/tsconfig.json
+++ b/packages/lsp/lsp-local/tsconfig.json
@@ -28,6 +28,9 @@
},
{
"path": "../lsp"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/lsp/lsp/package.json b/packages/lsp/lsp/package.json
index 04de5b2506..6a96dfdf70 100644
--- a/packages/lsp/lsp/package.json
+++ b/packages/lsp/lsp/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,11 +28,13 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/lsp/lsp/src/invariant.ts b/packages/lsp/lsp/src/invariant.ts
new file mode 100644
index 0000000000..27481309f4
--- /dev/null
+++ b/packages/lsp/lsp/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-lsp`.
+ * @module @deepseek-ai/dsh-lsp/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-lsp'
+
+/** Cordis companion plugin name. */
+export const name = 'lsp-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: provider ids and extension routes are private, atomically updated state;
+ * the seam exposes neither an enumerable snapshot nor lifecycle events to compare independently.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/lsp/lsp/tsconfig.json b/packages/lsp/lsp/tsconfig.json
index 7ca1556695..14fcb74d1b 100644
--- a/packages/lsp/lsp/tsconfig.json
+++ b/packages/lsp/lsp/tsconfig.json
@@ -19,6 +19,9 @@
},
{
"path": "../../llm/llm"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/lsp/tool-lsp/package.json b/packages/lsp/tool-lsp/package.json
index abedad1e53..febc303a48 100644
--- a/packages/lsp/tool-lsp/package.json
+++ b/packages/lsp/tool-lsp/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-lsp": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -34,6 +40,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-lsp": "workspace:^",
"@deepseek-ai/dsh-lsp-local": "workspace:^",
diff --git a/packages/lsp/tool-lsp/src/invariant.ts b/packages/lsp/tool-lsp/src/invariant.ts
new file mode 100644
index 0000000000..a2516e059b
--- /dev/null
+++ b/packages/lsp/tool-lsp/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-lsp`.
+ * @module @deepseek-ai/dsh-tool-lsp/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-lsp'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-lsp-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this stateless adapter contributes one tool and prompt section, while query
+ * lifecycle and result relations remain owned by the tool and LSP seams it composes.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/lsp/tool-lsp/tsconfig.json b/packages/lsp/tool-lsp/tsconfig.json
index e53735f570..f99783e94e 100644
--- a/packages/lsp/tool-lsp/tsconfig.json
+++ b/packages/lsp/tool-lsp/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../lsp"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/mcp/mcp-client/package.json b/packages/mcp/mcp-client/package.json
index ff34be015c..3480b48e52 100644
--- a/packages/mcp/mcp-client/package.json
+++ b/packages/mcp/mcp-client/package.json
@@ -11,19 +11,25 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
- "@deepseek-ai/dsh-tools": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
+ "@deepseek-ai/dsh-tools": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"dependencies": {
@@ -32,8 +38,9 @@
"zod": "^4.4.3"
},
"devDependencies": {
- "@deepseek-ai/dsh-tools": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
+ "@deepseek-ai/dsh-tools": "workspace:^",
"@modelcontextprotocol/server-everything": "^2026.7.4",
"@modelcontextprotocol/server-filesystem": "^2026.7.4",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/mcp/mcp-client/src/invariant.ts b/packages/mcp/mcp-client/src/invariant.ts
new file mode 100644
index 0000000000..e2d8ac22cb
--- /dev/null
+++ b/packages/mcp/mcp-client/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-mcp-client`.
+ * @module @deepseek-ai/dsh-mcp-client/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-mcp-client'
+
+/** Cordis companion plugin name. */
+export const name = 'mcp-client-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: MCP generations contribute through the tool registry, but the bridge
+ * exposes no independent server-to-tool snapshot after an asynchronous resync.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/mcp/mcp-client/tsconfig.json b/packages/mcp/mcp-client/tsconfig.json
index e9c9266415..668ee2c3cb 100644
--- a/packages/mcp/mcp-client/tsconfig.json
+++ b/packages/mcp/mcp-client/tsconfig.json
@@ -6,10 +6,23 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../llm/llm" },
- { "path": "../../core/tools" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/sandbox/sandbox-local/package.json b/packages/sandbox/sandbox-local/package.json
index 9dd90a3e9a..6750b92577 100644
--- a/packages/sandbox/sandbox-local/package.json
+++ b/packages/sandbox/sandbox-local/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -31,6 +37,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/sandbox/sandbox-local/src/invariant.ts b/packages/sandbox/sandbox-local/src/invariant.ts
new file mode 100644
index 0000000000..e990d46acc
--- /dev/null
+++ b/packages/sandbox/sandbox-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sandbox-local`.
+ * @module @deepseek-ai/dsh-sandbox-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sandbox-local'
+
+/** Cordis companion plugin name. */
+export const name = 'sandbox-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
index 8519357c1b..9fcfe23de8 100644
--- a/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
+++ b/packages/sandbox/sandbox-local/tests/packed-install.e2e.ts
@@ -26,6 +26,7 @@ const WORKSPACE_CLOSURE = [
'packages/sandbox/sandbox',
'packages/llm/llm',
'packages/util/brand',
+ 'packages/support/invariants',
]
/** ELF `e_machine` (offset 18, LE) for this host: x86-64 = 62, AArch64 = 183. */
diff --git a/packages/sandbox/sandbox-local/tsconfig.json b/packages/sandbox/sandbox-local/tsconfig.json
index c756b6af69..608f0e9568 100644
--- a/packages/sandbox/sandbox-local/tsconfig.json
+++ b/packages/sandbox/sandbox-local/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../sandbox"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/sandbox/sandbox-policy/README.md b/packages/sandbox/sandbox-policy/README.md
index 4ea562b376..5f2d748bc9 100644
--- a/packages/sandbox/sandbox-policy/README.md
+++ b/packages/sandbox/sandbox-policy/README.md
@@ -18,6 +18,8 @@ Two families enforce the same mode vocabulary: the sandboxed bash executor (`@de
- `setSandboxMode(session, mode)` — THE write path for a per-session override: appends exactly one `sandbox/mode` event. The switch IS its event; nothing mutates the mode out of band.
- `SANDBOX_MODES` — every mode, for option advertisement and runtime validation.
+The optional `./invariant` companion rejects a forged durable `sandbox/mode` event whose value falls outside that closed vocabulary; Session and its companion own the surrounding storage and turn-enclosure rules.
+
## The per-session store
A runtime switch (an ACP `session/set_config_option`, a test scenario) is one log-only `sandbox/mode` event on the session it applies to. `effective = fold(events) ?? the deployment default`, so an override survives restart by replay, two sessions never see each other's state, and there is no external config store. The event is log-only (the `approval/*` precedent): the model learns the mode from the enforcing tools' denial markers, never from the event. Execution honors the fold in each tool layer, weakest-precedence beneath an escalation grant.
diff --git a/packages/sandbox/sandbox-policy/package.json b/packages/sandbox/sandbox-policy/package.json
index e5a318e3e1..f8a7235247 100644
--- a/packages/sandbox/sandbox-policy/package.json
+++ b/packages/sandbox/sandbox-policy/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-sandbox": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-sandbox": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/sandbox/sandbox-policy/src/invariant.ts b/packages/sandbox/sandbox-policy/src/invariant.ts
new file mode 100644
index 0000000000..90b8bf65fd
--- /dev/null
+++ b/packages/sandbox/sandbox-policy/src/invariant.ts
@@ -0,0 +1,42 @@
+/** Package-owned session-event invariants for sandbox policy. @module @deepseek-ai/dsh-sandbox-policy/invariant */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { SANDBOX_MODES } from './session-mode.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sandbox-policy'
+
+/** Cordis companion plugin name. */
+export const name = 'sandbox-policy-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Validate the package-owned event shape and ignore unrelated events. */
+function validateEvent(event: SessionEvent, fail: InvariantFailure): void {
+ if (event.type === 'sandbox/mode' && !SANDBOX_MODES.includes(event.data.mode)) {
+ fail(`sandbox/mode carries unknown mode ${JSON.stringify(event.data.mode)}`)
+ }
+}
+
+/** Install validation for loaded and newly appended sandbox modes. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ for (const session of ctx.sessions.list()) {
+ for (const event of session.events) validateEvent(event, fail)
+ }
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName !== 'session/event') return
+ const event = (args as [Session, SessionEvent])[1]
+ validateEvent(event, fail)
+ }, { global: true })
+}, { inject: ['sessions'] })
+/* jscpd:ignore-end */
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/sandbox/sandbox-policy/tests/invariant.spec.ts b/packages/sandbox/sandbox-policy/tests/invariant.spec.ts
new file mode 100644
index 0000000000..d3255b305e
--- /dev/null
+++ b/packages/sandbox/sandbox-policy/tests/invariant.spec.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { type Session, type SessionEvent } from '@deepseek-ai/dsh-session'
+import InvariantService, { InvariantError } from '@deepseek-ai/dsh-invariants'
+import * as SandboxPolicyInvariant from '@deepseek-ai/dsh-sandbox-policy/invariant'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ await ctx.plugin(InvariantService, { enabled: true })
+ await ctx.plugin(SandboxPolicyInvariant)
+ return ctx
+}
+
+function modeEvent(mode: string): SessionEvent {
+ return { type: 'sandbox/mode', seq: 0, time: 0, data: { mode } } as SessionEvent
+}
+
+describe('sandbox-policy invariants', () => {
+ it.each(['read-only', 'workspace-write', 'danger-full-access'])(
+ 'accepts the durable %s mode',
+ async (mode) => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('session/event', {} as Session, modeEvent(mode)) }).not.toThrow()
+ },
+ )
+
+ it('ignores unrelated event streams', async () => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('session/event', {} as Session, {
+ type: 'turn/start', seq: 0, time: 0, data: {},
+ } as SessionEvent) }).not.toThrow()
+ expect(() => { ctx.emit('tools/change') }).not.toThrow()
+ })
+
+ it('rejects and attributes an unknown durable sandbox mode', async () => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('session/event', {} as Session, modeEvent('host-root')) })
+ .toThrow(new InvariantError('@deepseek-ai/dsh-sandbox-policy', 'sandbox/mode carries unknown mode "host-root"'))
+ })
+
+ it('rejects an unknown mode already present on late registration', async () => {
+ const ctx = new Context()
+ await ctx.plugin(SessionStore)
+ ctx.sessions.create().append('sandbox/mode', { mode: 'host-root' as never })
+ await ctx.plugin(InvariantService, { enabled: true })
+
+ await expect(ctx.plugin(SandboxPolicyInvariant).then(() => undefined)).rejects.toMatchObject({
+ code: 'INVARIANT',
+ packageName: '@deepseek-ai/dsh-sandbox-policy',
+ })
+ })
+})
diff --git a/packages/sandbox/sandbox-policy/tsconfig.json b/packages/sandbox/sandbox-policy/tsconfig.json
index fc0c96c6de..cb6fc623d0 100644
--- a/packages/sandbox/sandbox-policy/tsconfig.json
+++ b/packages/sandbox/sandbox-policy/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/sandbox/sandbox-policy/tsdown.config.ts b/packages/sandbox/sandbox-policy/tsdown.config.ts
new file mode 100644
index 0000000000..ab8dc26ee8
--- /dev/null
+++ b/packages/sandbox/sandbox-policy/tsdown.config.ts
@@ -0,0 +1,25 @@
+import { defineConfig } from 'tsdown'
+
+/** Build the package root and invariant companion as independent bundles. */
+export default defineConfig([
+ {
+ entry: ['lib/types/index.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+ {
+ entry: ['lib/types/invariant.js'],
+ outDir: 'lib',
+ format: ['esm'],
+ platform: 'node',
+ target: 'es2024',
+ fixedExtension: false,
+ dts: false,
+ clean: false,
+ },
+])
diff --git a/packages/sandbox/sandbox/package.json b/packages/sandbox/sandbox/package.json
index 50c5b443ba..84266499b3 100644
--- a/packages/sandbox/sandbox/package.json
+++ b/packages/sandbox/sandbox/package.json
@@ -11,21 +11,28 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/sandbox/sandbox/src/invariant.ts b/packages/sandbox/sandbox/src/invariant.ts
new file mode 100644
index 0000000000..7ee5be733f
--- /dev/null
+++ b/packages/sandbox/sandbox/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-sandbox`.
+ * @module @deepseek-ai/dsh-sandbox/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-sandbox'
+
+/** Cordis companion plugin name. */
+export const name = 'sandbox-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sandbox/sandbox/tsconfig.json b/packages/sandbox/sandbox/tsconfig.json
index 9f687793d7..af4de1c016 100644
--- a/packages/sandbox/sandbox/tsconfig.json
+++ b/packages/sandbox/sandbox/tsconfig.json
@@ -16,6 +16,9 @@
},
{
"path": "../../llm/llm"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/sdk/create-sdk/package.json b/packages/sdk/create-sdk/package.json
index e23415f8dc..27102154fc 100644
--- a/packages/sdk/create-sdk/package.json
+++ b/packages/sdk/create-sdk/package.json
@@ -13,10 +13,15 @@
".": {
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
+ },
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
}
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/assets",
"lib/types/**/*.d.ts",
@@ -29,9 +34,11 @@
"commander": "^15.0.0"
},
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/sdk/create-sdk/src/invariant.ts b/packages/sdk/create-sdk/src/invariant.ts
new file mode 100644
index 0000000000..368b46fc70
--- /dev/null
+++ b/packages/sdk/create-sdk/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/create-sdk`.
+ * @module @deepseek-ai/create-sdk/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/create-sdk'
+
+/** Cordis companion plugin name. */
+export const name = 'create-sdk-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sdk/create-sdk/tsconfig.json b/packages/sdk/create-sdk/tsconfig.json
index f77f711880..e2ed951fa4 100644
--- a/packages/sdk/create-sdk/tsconfig.json
+++ b/packages/sdk/create-sdk/tsconfig.json
@@ -6,7 +6,14 @@
},
"include": ["src"],
"references": [
- { "path": "../helper" },
- { "path": "../../../vendor/cordis" }
+ {
+ "path": "../helper"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/sdk/create-sdk/tsdown.config.ts b/packages/sdk/create-sdk/tsdown.config.ts
index cdf9ef6d4f..08d522590e 100644
--- a/packages/sdk/create-sdk/tsdown.config.ts
+++ b/packages/sdk/create-sdk/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
/** Bundle the library and create bin, then mirror package-owned terminal templates. */
export default defineConfig({
- entry: ['lib/types/index.js', 'lib/types/bin.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/sdk/helper/package.json b/packages/sdk/helper/package.json
index 8d95dafe66..1d9c6a2be2 100644
--- a/packages/sdk/helper/package.json
+++ b/packages/sdk/helper/package.json
@@ -10,10 +10,15 @@
".": {
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
+ },
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
}
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/assets",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
@@ -29,12 +34,14 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
"@deepseek-ai/dsh-hooks-claude": "workspace:^",
"@deepseek-ai/dsh-hooks-codex": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
"@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
"@deepseek-ai/dsh-tool-subagent": "workspace:^",
diff --git a/packages/sdk/helper/src/features/builtin/helpers.ts b/packages/sdk/helper/src/features/builtin/helpers.ts
index 60f7530c61..9b21c7f64f 100644
--- a/packages/sdk/helper/src/features/builtin/helpers.ts
+++ b/packages/sdk/helper/src/features/builtin/helpers.ts
@@ -15,8 +15,19 @@ import type {
PackageScriptResource,
} from '../resources.ts'
+/** Return the installable package name for a bare package or package subpath. */
+function installablePackageName(specifier: string): string {
+ const segments = specifier.split('/')
+ const expectedSegments = specifier.startsWith('@') ? 2 : 1
+ if (segments.length < expectedSegments || segments.slice(0, expectedSegments).some(segment => segment.length === 0)) {
+ throw new Error(`invalid bare package specifier: ${JSON.stringify(specifier)}`)
+ }
+ return segments.slice(0, expectedSegments).join('/')
+}
+
/** Create a runtime NPM dependency resource. */
-function npmDependency(_owner: string, name: string): NpmDependencyResource {
+function npmDependency(_owner: string, specifier: string): NpmDependencyResource {
+ const name = installablePackageName(specifier)
return {
kind: 'npm-dependency',
key: resourceKey(`npm-dependency:${name}`),
@@ -52,7 +63,7 @@ export function cordisConfigEntry(
}
}
-/** Couple one bare-package Cordis config entry to its mandatory runtime NPM dependency. */
+/** Couple one bare-package or subpath Cordis entry to its installable NPM package. */
export function npmCordisConfigEntry(
owner: string,
value: CordisConfigEntry,
diff --git a/packages/sdk/helper/src/features/builtin/spine.ts b/packages/sdk/helper/src/features/builtin/spine.ts
index caf066865e..3e1acb98fb 100644
--- a/packages/sdk/helper/src/features/builtin/spine.ts
+++ b/packages/sdk/helper/src/features/builtin/spine.ts
@@ -9,7 +9,7 @@ import type { ProjectProfile } from '../../project/types.ts'
import { loadHelperTemplate } from '../../templates/template-assets.ts'
import { FeatureOption, FixedFeature } from '../feature.ts'
import { ProjectContribution } from '../resources.ts'
-import { npmCordisConfigEntry, requiredString } from './helpers.ts'
+import { cordisConfigEntry, npmCordisConfigEntry, requiredString } from './helpers.ts'
const ID = featureId('spine')
const PERSONA = loadHelperTemplate>('persona.txt.tpl').render({}).trimEnd()
@@ -37,6 +37,10 @@ class SpineOption extends FeatureOption {
...npmCordisConfigEntry(ID, { id: 'tools', name: '@deepseek-ai/dsh-tools' }, []),
...npmCordisConfigEntry(ID, { id: 'agent', name: '@deepseek-ai/dsh-agent' }),
...npmCordisConfigEntry(ID, { id: 'invariants', name: '@deepseek-ai/dsh-invariants' }),
+ cordisConfigEntry(ID, { id: 'session-invariant', name: '@deepseek-ai/dsh-session/invariant' }),
+ cordisConfigEntry(ID, { id: 'agent-invariant', name: '@deepseek-ai/dsh-agent/invariant' }),
+ ...npmCordisConfigEntry(ID, { id: 'scope-invariant', name: '@deepseek-ai/dsh-scope/invariant' }),
+ cordisConfigEntry(ID, { id: 'agent-loop-invariant', name: '@deepseek-ai/dsh-agent-loop/invariant' }),
...npmCordisConfigEntry(ID, {
id: 'agent-loop',
name: '@deepseek-ai/dsh-agent-loop',
diff --git a/packages/sdk/helper/src/invariant.ts b/packages/sdk/helper/src/invariant.ts
new file mode 100644
index 0000000000..9185ac8867
--- /dev/null
+++ b/packages/sdk/helper/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-helper`.
+ * @module @deepseek-ai/dsh-helper/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-helper'
+
+/** Cordis companion plugin name. */
+export const name = 'helper-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sdk/helper/tests/project.spec.ts b/packages/sdk/helper/tests/project.spec.ts
index 4df8c5d3f2..bc3e5ebe12 100644
--- a/packages/sdk/helper/tests/project.spec.ts
+++ b/packages/sdk/helper/tests/project.spec.ts
@@ -188,9 +188,15 @@ describe('SdkProject and ProjectEditSession', () => {
.toContain('sessionId: !!js process.env.DSH_SDK_SESSION_ID')
expect(project.cordis.entry('tui')?.config).not.toHaveProperty('model')
expect(project.cordis.entry('agent-loop')?.config).toEqual({ agents: [] })
+ expect(project.cordis.entry('session-invariant')?.name).toBe('@deepseek-ai/dsh-session/invariant')
+ expect(project.cordis.entry('agent-invariant')?.name).toBe('@deepseek-ai/dsh-agent/invariant')
+ expect(project.cordis.entry('scope-invariant')?.name).toBe('@deepseek-ai/dsh-scope/invariant')
+ expect(project.cordis.entry('agent-loop-invariant')?.name).toBe('@deepseek-ai/dsh-agent-loop/invariant')
expect(project.cordis.entry('system-prompt')?.config?.persona).toContain('{{cwd}}')
expect(project.packageManifest().dependencies?.['@cordisjs/plugin-timer']).toBe('^1.1.2')
expect(project.packageManifest().dependencies?.['@cordisjs/plugin-hmr']).toBe('^1.0.15')
+ expect(project.packageManifest().dependencies?.['@deepseek-ai/dsh-scope']).toBe('^0.0.1')
+ expect(project.packageManifest().dependencies).not.toHaveProperty('@deepseek-ai/dsh-scope/invariant')
expect(project.packageManifest().dependencies).not.toHaveProperty('node-addon-require-builtin')
expect(project.cordis.entry('hmr')).toMatchObject({ name: '@cordisjs/plugin-hmr' })
expect(project.cordis.entry('llm-deepseek')?.config).not.toHaveProperty('baseURL')
@@ -888,6 +894,11 @@ describe('extension points', () => {
expect(stringArray({ value: [1] }, 'value')).toHaveLength(1)
expect(cordisConfigEntry('owner', { id: 'entry', name: 'pkg' }).ownedConfigKeys).toEqual([])
expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg' })[1].ownedConfigKeys).toEqual([])
+ expect(npmCordisConfigEntry('owner', { id: 'entry', name: '@scope/pkg/subpath' })[0].name).toBe('@scope/pkg')
+ expect(npmCordisConfigEntry('owner', { id: 'entry', name: 'pkg/subpath' })[0].name).toBe('pkg')
+ for (const invalid of ['', '@scope', '@scope/']) {
+ expect(() => npmCordisConfigEntry('owner', { id: 'entry', name: invalid })).toThrow('invalid bare package specifier')
+ }
expect(environmentResource('owner', 'EMPTY', undefined)).not.toHaveProperty('value')
const builtins = createBuiltinRegistry(profile)
expect(builtins.get(featureId('app')).defaultOptions(profile)).toEqual(['embed'])
diff --git a/packages/sdk/helper/tsconfig.json b/packages/sdk/helper/tsconfig.json
index e4a8604575..18e79898c7 100644
--- a/packages/sdk/helper/tsconfig.json
+++ b/packages/sdk/helper/tsconfig.json
@@ -6,14 +6,35 @@
},
"include": ["src"],
"references": [
- { "path": "../../util/brand" },
- { "path": "../../compact/compact-basic" },
- { "path": "../../hooks/hooks-claude" },
- { "path": "../../hooks/hooks-codex" },
- { "path": "../../session-persistence/session-persistence-jsonl" },
- { "path": "../../session-persistence/session-persistence-sqlite" },
- { "path": "../../subagent/tool-subagent" },
- { "path": "../../web/tool-web" },
- { "path": "../../../vendor/cordis" }
+ {
+ "path": "../../util/brand"
+ },
+ {
+ "path": "../../compact/compact-basic"
+ },
+ {
+ "path": "../../hooks/hooks-claude"
+ },
+ {
+ "path": "../../hooks/hooks-codex"
+ },
+ {
+ "path": "../../session-persistence/session-persistence-jsonl"
+ },
+ {
+ "path": "../../session-persistence/session-persistence-sqlite"
+ },
+ {
+ "path": "../../subagent/tool-subagent"
+ },
+ {
+ "path": "../../web/tool-web"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/sdk/helper/tsdown.config.ts b/packages/sdk/helper/tsdown.config.ts
index cb8b9fafef..b8ba9cb652 100644
--- a/packages/sdk/helper/tsdown.config.ts
+++ b/packages/sdk/helper/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
/** Bundle helper runtime and mirror template assets beside the bundle. */
export default defineConfig({
- entry: ['lib/types/index.js'],
+ entry: ['lib/types/index.js', 'lib/types/invariant.js'],
outDir: 'lib',
format: ['esm'],
platform: 'node',
diff --git a/packages/sdk/scripts/package.json b/packages/sdk/scripts/package.json
index 6fdbcbc3da..63afe96d08 100644
--- a/packages/sdk/scripts/package.json
+++ b/packages/sdk/scripts/package.json
@@ -14,6 +14,10 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./dev/tsdown-config": {
"types": "./lib/types/dev/tsdown-config.d.ts",
"default": "./lib/dev/tsdown-config.js"
@@ -21,6 +25,7 @@
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/bin.js",
"lib/dev/tsdown-config.js",
"lib/local-plugin-loader-hooks.js",
@@ -38,16 +43,22 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-app-boot": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7",
"tsdown": "^0.22.2",
"tsx": "^4.22.4"
},
"peerDependenciesMeta": {
- "tsdown": { "optional": true },
- "tsx": { "optional": true }
+ "tsdown": {
+ "optional": true
+ },
+ "tsx": {
+ "optional": true
+ }
},
"devDependencies": {
"@deepseek-ai/dsh-app-boot": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7",
"tsdown": "^0.22.2",
"tsx": "^4.22.4"
diff --git a/packages/sdk/scripts/src/invariant.ts b/packages/sdk/scripts/src/invariant.ts
new file mode 100644
index 0000000000..72e97f3628
--- /dev/null
+++ b/packages/sdk/scripts/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-scripts`.
+ * @module @deepseek-ai/dsh-scripts/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-scripts'
+
+/** Cordis companion plugin name. */
+export const name = 'scripts-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sdk/scripts/tests/scripts.spec.ts b/packages/sdk/scripts/tests/scripts.spec.ts
index a6ec4f4a4f..fa8eb00d41 100644
--- a/packages/sdk/scripts/tests/scripts.spec.ts
+++ b/packages/sdk/scripts/tests/scripts.spec.ts
@@ -135,6 +135,7 @@ describe('Commander launcher arguments', () => {
expect(parseDshSdkArgs(['start'])).toEqual({ command: 'start', forwarded: [], help: false })
expect(parseDshSdkArgs(['dev', 'index.ts'])).toMatchObject({ command: 'dev', target: 'index.ts' })
expect(parseDshSdkArgs(['-h'])).toMatchObject({ help: true })
+ expect(parseDshSdkArgs(['--help'])).toMatchObject({ help: true })
expect(() => parseDshSdkArgs(['unknown'])).toThrow()
expect(() => parseDshSdkArgs(['config', 'extra'])).toThrow()
expect(() => parseDshSdkArgs(['config', '--', 'extra'])).toThrow('does not accept forwarded')
diff --git a/packages/sdk/scripts/tsconfig.json b/packages/sdk/scripts/tsconfig.json
index 461c86c06d..d3dacea10b 100644
--- a/packages/sdk/scripts/tsconfig.json
+++ b/packages/sdk/scripts/tsconfig.json
@@ -9,6 +9,7 @@
{ "path": "../helper" },
{ "path": "../telemetry" },
{ "path": "../../ui/app-boot" },
- { "path": "../../../vendor/cordis" }
+ { "path": "../../../vendor/cordis" },
+ { "path": "../../support/invariants" }
]
}
diff --git a/packages/sdk/scripts/tsdown.config.ts b/packages/sdk/scripts/tsdown.config.ts
index 2218faa7be..14bb59b8bc 100644
--- a/packages/sdk/scripts/tsdown.config.ts
+++ b/packages/sdk/scripts/tsdown.config.ts
@@ -7,6 +7,10 @@ export default defineConfig([
fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
copy: [{ from: 'src/templates/assets/*', to: 'lib/assets' }],
},
+ {
+ entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+ fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+ },
{
entry: ['lib/types/bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
diff --git a/packages/sdk/telemetry/package.json b/packages/sdk/telemetry/package.json
index fcb6efb797..7dd1ffd0de 100644
--- a/packages/sdk/telemetry/package.json
+++ b/packages/sdk/telemetry/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -26,10 +31,12 @@
},
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/sdk/telemetry/src/invariant.ts b/packages/sdk/telemetry/src/invariant.ts
new file mode 100644
index 0000000000..c3676a1384
--- /dev/null
+++ b/packages/sdk/telemetry/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-telemetry`.
+ * @module @deepseek-ai/dsh-telemetry/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-telemetry'
+
+/** Cordis companion plugin name. */
+export const name = 'telemetry-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this SDK build-time package owns no live event stream or mutable data;
+ * generated output and consumer tests cover its contract.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/sdk/telemetry/tsconfig.json b/packages/sdk/telemetry/tsconfig.json
index 8acc8f11c5..4667bad772 100644
--- a/packages/sdk/telemetry/tsconfig.json
+++ b/packages/sdk/telemetry/tsconfig.json
@@ -8,6 +8,7 @@
"src"
],
"references": [
- { "path": "../../util/brand" }
+ { "path": "../../util/brand" },
+ { "path": "../../support/invariants" }
]
}
diff --git a/packages/session-persistence/session-persistence-jsonl/package.json b/packages/session-persistence/session-persistence-jsonl/package.json
index ddb9f2af4d..bc5c6d2c4c 100644
--- a/packages/session-persistence/session-persistence-jsonl/package.json
+++ b/packages/session-persistence/session-persistence-jsonl/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/session-persistence/session-persistence-jsonl/src/invariant.ts b/packages/session-persistence/session-persistence-jsonl/src/invariant.ts
new file mode 100644
index 0000000000..94d7c2b494
--- /dev/null
+++ b/packages/session-persistence/session-persistence-jsonl/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence-jsonl`.
+ * @module @deepseek-ai/dsh-session-persistence-jsonl/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-persistence-jsonl'
+
+/** Cordis companion plugin name. */
+export const name = 'session-persistence-jsonl-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+ * this package exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
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 90d6fe9e36..8a06fa6409 100644
--- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -21,17 +21,15 @@ function mutableHeader(header: SessionHeader): MutableSessionHeader {
return header
}
-async function expectParallelFlushError(promise: Promise, message: RegExp): Promise {
+async function expectFlushError(promise: Promise, message: RegExp): Promise {
try {
await promise
} catch (error) {
- expect(error).toBeInstanceOf(AggregateError)
- const [cause] = (error as AggregateError).errors as unknown[]
- expect(cause).toBeInstanceOf(Error)
- expect((cause as Error).message).toMatch(message)
+ expect(error).toBeInstanceOf(Error)
+ expect((error as Error).message).toMatch(message)
return
}
- throw new Error('expected parallel flush to reject')
+ throw new Error('expected flush to reject')
}
async function freshRoot(): Promise {
@@ -257,7 +255,7 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
appendClosedTurn(source)
const child = ctx.sessions.fork(source, undefined, SessionId('persist-child'))
- await ctx.parallel('session/flush', child)
+ await ctx.sessions.flush(child)
const loaded = await ctx.sessionPersistence.load(child.id)
expect(loaded.events).toEqual(source.events)
@@ -436,12 +434,14 @@ describe('SessionPersistenceJsonl: write path (session/event → flush)', () =>
const a = ctx.sessions.create(SessionId('sa'))
const b = ctx.sessions.create(SessionId('sb'))
+ a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ b.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
a.append('user/message', { content: [{ type: 'text', text: 'A' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
b.append('user/message', { content: [{ type: 'text', text: 'B' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
b.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', a)
- await ctx.parallel('session/flush', b)
+ await ctx.sessions.flush(a)
+ await ctx.sessions.flush(b)
const la = await ctx.sessionPersistence.load(SessionId('sa'))
const lb = await ctx.sessionPersistence.load(SessionId('sb'))
@@ -635,7 +635,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
}, { inject: ['sessions'] }))
// Drain A, then dispose ITS fiber (the live session A is gone) while the
// backend stays loaded.
- for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
+ for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
await sessFiberA.dispose()
// A new Session object reuses the id. Object-keyed initialization must run independently,
@@ -703,7 +703,7 @@ describe('SessionPersistenceJsonl: edge cases', () => {
a.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
a.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
}, { inject: ['sessions'] }))
- for (const s of ctx.sessions.list()) await ctx.parallel('session/flush', s)
+ for (const s of ctx.sessions.list()) await ctx.sessions.flush(s)
await firstFiber.dispose()
let second!: Session
@@ -814,18 +814,19 @@ describe('SessionPersistenceJsonl: edge cases', () => {
await ctx2.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
const session = ctx2.sessions.create(SessionId('flush-fail'))
// A full turn lands in the write-behind buffer.
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
// Make the durable materialize fail on the next flush.
const backend = ctx2.sessionPersistence as unknown as { materialize: (...args: unknown[]) => Promise }
const origMat = backend.materialize.bind(backend)
backend.materialize = () => Promise.reject(new Error('disk full'))
- await expectParallelFlushError(ctx2.parallel('session/flush', session), /disk full/)
+ await expectFlushError(ctx2.sessions.flush(session), /disk full/)
// The events are STILL buffered (not silently dropped): a retry persists them.
backend.materialize = origMat
- await ctx2.parallel('session/flush', session)
+ await ctx2.sessions.flush(session)
const loaded = await ctx2.sessionPersistence.load(SessionId('flush-fail'))
- expect(loaded.events.map(e => e.seq)).toEqual([0, 1])
+ expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2])
await ctx2.fiber.dispose()
})
diff --git a/packages/session-persistence/session-persistence-jsonl/tsconfig.json b/packages/session-persistence/session-persistence-jsonl/tsconfig.json
index 23970f5a57..044156938b 100644
--- a/packages/session-persistence/session-persistence-jsonl/tsconfig.json
+++ b/packages/session-persistence/session-persistence-jsonl/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../session-persistence/session-persistence"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/session-persistence/session-persistence-sqlite/package.json b/packages/session-persistence/session-persistence-sqlite/package.json
index f367b737b3..f65bdebd16 100644
--- a/packages/session-persistence/session-persistence-sqlite/package.json
+++ b/packages/session-persistence/session-persistence-sqlite/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
"cordis": "^4.0.0-rc.7"
diff --git a/packages/session-persistence/session-persistence-sqlite/src/invariant.ts b/packages/session-persistence/session-persistence-sqlite/src/invariant.ts
new file mode 100644
index 0000000000..9d841a053d
--- /dev/null
+++ b/packages/session-persistence/session-persistence-sqlite/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence-sqlite`.
+ * @module @deepseek-ai/dsh-session-persistence-sqlite/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-persistence-sqlite'
+
+/** Cordis companion plugin name. */
+export const name = 'session-persistence-sqlite-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+ * this package exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
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 83d16b3315..e054f9fa9c 100644
--- a/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
+++ b/packages/session-persistence/session-persistence-sqlite/tests/sqlite.spec.ts
@@ -14,17 +14,15 @@ import { runCoordinatorContract, type CoordinatorFixture } from '../../session-p
const dirs: string[] = []
afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
-async function expectParallelFlushError(promise: Promise, message: RegExp): Promise {
+async function expectFlushError(promise: Promise, message: RegExp): Promise {
try {
await promise
} catch (error) {
- expect(error).toBeInstanceOf(AggregateError)
- const [cause] = (error as AggregateError).errors as unknown[]
- expect(cause).toBeInstanceOf(Error)
- expect((cause as Error).message).toMatch(message)
+ expect(error).toBeInstanceOf(Error)
+ expect((error as Error).message).toMatch(message)
return
}
- throw new Error('expected parallel flush to reject')
+ throw new Error('expected flush to reject')
}
async function freshDbPath(): Promise {
@@ -502,7 +500,7 @@ describe('SessionPersistenceSqlite: edge cases', () => {
const b1 = await backend(path)
const s1 = b1.ctx.sessions.create(SessionId('hmr-collide'))
appendLog(s1, oneTurnLog())
- await b1.ctx.parallel('session/flush', s1)
+ await b1.ctx.sessions.flush(s1)
await b1.dispose()
// A fresh context with an UNRELATED live session reusing the id meets a
@@ -513,9 +511,9 @@ describe('SessionPersistenceSqlite: edge cases', () => {
await ctx.plugin(Object.assign((inner: Context) => {
session = inner.sessions.create(SessionId('hmr-collide'))
}, { inject: ['sessions'] }))
- session.append('turn/start', { turn: 9, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
await ctx.plugin(SessionPersistenceSqlite, { path })
- await expectParallelFlushError(ctx.parallel('session/flush', session), /id collision/)
+ await expectFlushError(ctx.sessions.flush(session), /id collision/)
await ctx.fiber.dispose()
})
})
@@ -567,18 +565,20 @@ describe('surface field round-trip', () => {
const fiber = await ctx.plugin(SessionPersistenceSqlite, { path: ':memory:' })
const session = ctx.sessions.create(SessionId('roundtrip-surface'))
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: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
- session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [0] })
+ session.append('assistant/message', { provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [] }, { surfaceOp: 'append', sourceEventSeqs: [2] })
+ session.append('step/end', { turn: 1, step: 1 })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('roundtrip-surface'))
- expect(loaded.events).toHaveLength(4)
- const um = loaded.events[1]!
+ expect(loaded.events).toHaveLength(6)
+ const um = loaded.events[2]!
expect((um as SurfaceEvent).surfaceOp).toBe('append')
expect((um as SurfaceEvent).sourceEventSeqs).toBeUndefined()
- const am = loaded.events[2]!
+ const am = loaded.events[3]!
expect((am as SurfaceEvent).surfaceOp).toBe('append')
- expect((am as SurfaceEvent).sourceEventSeqs).toEqual([0])
+ expect((am as SurfaceEvent).sourceEventSeqs).toEqual([2])
await fiber.dispose()
})
@@ -590,7 +590,7 @@ describe('surface field round-trip', () => {
session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('steering/message', { turn: 1, content: [], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('surface-noseq'))
expect((loaded.events[1]! as SurfaceEvent).surfaceOp).toBe('append')
expect((loaded.events[1]! as SurfaceEvent).sourceEventSeqs).toBeUndefined()
diff --git a/packages/session-persistence/session-persistence-sqlite/tsconfig.json b/packages/session-persistence/session-persistence-sqlite/tsconfig.json
index 23970f5a57..044156938b 100644
--- a/packages/session-persistence/session-persistence-sqlite/tsconfig.json
+++ b/packages/session-persistence/session-persistence-sqlite/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../../session-persistence/session-persistence"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/session-persistence/session-persistence/package.json b/packages/session-persistence/session-persistence/package.json
index 91eef09007..a503b146ae 100644
--- a/packages/session-persistence/session-persistence/package.json
+++ b/packages/session-persistence/session-persistence/package.json
@@ -11,21 +11,29 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
+ "@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/session-persistence/session-persistence/src/invariant.ts b/packages/session-persistence/session-persistence/src/invariant.ts
new file mode 100644
index 0000000000..316774f3fd
--- /dev/null
+++ b/packages/session-persistence/session-persistence/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-persistence`.
+ * @module @deepseek-ai/dsh-session-persistence/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-persistence'
+
+/** Cordis companion plugin name. */
+export const name = 'session-persistence-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: persistence correctness requires backend round-trip and crash-tail tests;
+ * this package exposes no continuously observable in-process relation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts b/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
index 5ef2ce2fad..620d069d32 100644
--- a/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
+++ b/packages/session-persistence/session-persistence/tests/coordinator-contract.ts
@@ -11,6 +11,7 @@
import { describe, expect, it, vi } from 'vitest'
import { Context, type Fiber } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
import SessionStore, { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import { meta, oneTurnLog, appendLog } from './contract.ts'
@@ -76,7 +77,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
try {
const session = ctx.sessions.create(SessionId('live'), { meta: { cwd: WORK } })
send(session, oneTurnLog())
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('live'))
expect(loaded.events).toHaveLength(6)
@@ -96,7 +97,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
try {
const session = ctx.sessions.create(SessionId('forked-child'), { meta: { cwd: WORK, seedLength: 3 } })
send(session, oneTurnLog())
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('forked-child'))
expect(loaded.meta.seedLength).toBe(3)
@@ -132,17 +133,17 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
const { ctx, fiber } = await freshCtx(fix)
try {
const session = ctx.sessions.create(SessionId('mutate'), { meta: { cwd: WORK } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
const ev = session.append('user/message', { content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
expect(() => {
;(ev.data as { content: { type: 'text'; text: string }[] }).content[0]!.text = 'HACKED'
}).toThrow(TypeError)
- session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('mutate'))
- const first = loaded.events[0]
- expect(first?.type === 'user/message' && (first.data.content[0] as { text: string }).text).toBe('original')
+ const message = loaded.events.find(event => event.type === 'user/message')
+ expect(message?.type === 'user/message' && (message.data.content[0] as { text: string }).text).toBe('original')
} finally {
await fiber.dispose()
await fix.cleanup()
@@ -187,7 +188,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
const loaded = await ctx.sessionPersistence.load(SessionId('forked'))
expect(loaded.events).toEqual(seed)
// A flush with no NEW events must not double-write.
- await ctx.parallel('session/flush', forked)
+ await ctx.sessions.flush(forked)
const reloaded = await ctx.sessionPersistence.load(SessionId('forked'))
expect(reloaded.events).toEqual(seed)
} finally {
@@ -203,7 +204,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
try {
const s1 = first.ctx.sessions.create(SessionId('resumed'), { meta: { cwd: WORK } })
send(s1, oneTurnLog())
- await first.ctx.parallel('session/flush', s1)
+ await first.ctx.sessions.flush(s1)
} finally {
await first.fiber.dispose()
}
@@ -215,7 +216,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
await second.ctx.sessions.flush(s2) // let onCreated adopt
s2.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
s2.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
- await second.ctx.parallel('session/flush', s2)
+ await second.ctx.sessions.flush(s2)
const reloaded = await second.ctx.sessionPersistence.load(SessionId('resumed'))
expect(reloaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
@@ -233,13 +234,14 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
await ctx.plugin(SessionStore)
// A session exists BEFORE the persistence plugin is applied.
const session = ctx.sessions.create(SessionId('pre-existing'), { meta: { cwd: WORK } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
const fiber = await fix.mount(ctx)
try {
// The plugin seeded it on apply; a subsequent flush persists its events.
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('pre-existing'))
expect(loaded.events.length).toBeGreaterThanOrEqual(2)
} finally {
@@ -254,6 +256,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
await ctx.plugin(SessionStore)
const fiber = await fix.mount(ctx)
const session = await liveSessionInFiber(ctx, 'drain', WORK)
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'buffered' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
// No explicit flush — dispose must drain.
@@ -282,7 +285,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
// Hot-reload: dispose instance 1, mount instance 2 over the same storage while the
// session stays live. The new instance has no coordinator state but must adopt the
@@ -292,7 +295,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'again' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
- await expect(ctx.parallel('session/flush', session)).resolves.not.toThrow()
+ await expect(ctx.sessions.flush(session)).resolves.not.toThrow()
const loaded = await ctx.sessionPersistence.load(SessionId('hmr-adopt'))
expect(loaded.events.filter(e => e.type === 'turn/start')).toHaveLength(2)
@@ -312,7 +315,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
const backend1 = await fix.mount(ctx)
session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
// Append turn 2 to the LIVE session, then dispose instance 1 WITHOUT
// flushing turn 2: it is now ONLY in the live session's events; the new
@@ -324,7 +327,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
// Instance 2 adopts the stored prefix (turn 1) and MUST also persist the
// live suffix (turn 2) carried in the session's events.
await fix.mount(ctx)
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('hmr-suffix'))
expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3])
expect(loaded.events.filter(e => e.type === 'turn/start')).toHaveLength(2)
@@ -343,7 +346,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
const first = await fix.mount(ctx)
session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('step/start', { turn: 1, step: 1 })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
// Crash-tail a torn fragment past the (open) committed turn, then reload.
await first.dispose()
@@ -353,7 +356,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
// end. Adoption must truncate the torn tail but NOT synthesize closers.
session.append('step/end', { turn: 1, step: 1 })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('hmr-open'))
expect(loaded.events.map(e => e.type)).toEqual(['turn/start', 'step/start', 'step/end', 'turn/end'])
@@ -373,7 +376,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
try {
const s1 = first.ctx.sessions.create(SessionId('collide'), { meta: { cwd: WORK } })
send(s1, oneTurnLog())
- await first.ctx.parallel('session/flush', s1)
+ await first.ctx.sessions.flush(s1)
} finally {
await first.fiber.dispose()
}
@@ -413,7 +416,7 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
await expect(ctx.sessions.flush(reuse)).resolves.toBeUndefined()
reuse.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
reuse.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', reuse)
+ await ctx.sessions.flush(reuse)
const loaded = await ctx.sessionPersistence.load(SessionId('abandoned'))
expect(loaded.events.map(e => e.seq)).toEqual([0, 1])
} finally {
@@ -459,14 +462,15 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
const { ctx, fiber } = await freshCtx(fix)
try {
const session = ctx.sessions.create(SessionId('idem'), { meta: { cwd: WORK } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
// Re-emit session/created for the SAME live session (idempotent initFor).
- ctx.emit('session/created', session)
- await ctx.parallel('session/flush', session)
+ ctx.emit(scopeTarget(session, undefined), 'session/created', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('idem'))
- expect(loaded.events).toHaveLength(2) // not doubled
+ expect(loaded.events).toHaveLength(3) // not doubled
} finally {
await fiber.dispose()
await fix.cleanup()
@@ -711,11 +715,12 @@ export function runCoordinatorContract(name: string, makeFixture: () => Promise<
// async onCreated init has necessarily set state (exercises the
// state-undefined cursor path).
const session = ctx.sessions.create(SessionId('flush-nostate'), { meta: { cwd: WORK } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
session.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } }, { surfaceOp: 'append' })
session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
- await ctx.parallel('session/flush', session)
+ await ctx.sessions.flush(session)
const loaded = await ctx.sessionPersistence.load(SessionId('flush-nostate'))
- expect(loaded.events).toHaveLength(2)
+ expect(loaded.events).toHaveLength(3)
} finally {
await fiber.dispose()
await fix.cleanup()
diff --git a/packages/session-persistence/session-persistence/tsconfig.json b/packages/session-persistence/session-persistence/tsconfig.json
index e817086a6a..cbd74a19e7 100644
--- a/packages/session-persistence/session-persistence/tsconfig.json
+++ b/packages/session-persistence/session-persistence/tsconfig.json
@@ -16,6 +16,9 @@
},
{
"path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/session-query/session-query/package.json b/packages/session-query/session-query/package.json
index ae2767598a..040697391f 100644
--- a/packages/session-query/session-query/package.json
+++ b/packages/session-query/session-query/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-session-persistence": "^0.0.1",
@@ -36,6 +42,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-session-persistence": "workspace:^",
diff --git a/packages/session-query/session-query/src/invariant.ts b/packages/session-query/session-query/src/invariant.ts
new file mode 100644
index 0000000000..d087dd2378
--- /dev/null
+++ b/packages/session-query/session-query/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-query`.
+ * @module @deepseek-ai/dsh-session-query/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-query'
+
+/** Cordis companion plugin name. */
+export const name = 'session-query-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: query results are immutable per-call projections whose lineage and event
+ * relations are validated while they are built; the service retains no observable result state.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/session-query/session-query/tests/session-query.spec.ts b/packages/session-query/session-query/tests/session-query.spec.ts
index f532edf168..658eb709d9 100644
--- a/packages/session-query/session-query/tests/session-query.spec.ts
+++ b/packages/session-query/session-query/tests/session-query.spec.ts
@@ -101,6 +101,8 @@ describe('session-query exact reads', () => {
it('classifies current, shadowed, and raw-log-only events through foldSurface', async () => {
const ctx = await liveContext()
const session = ctx.sessions.create(SessionId('surface'))
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('step/start', { turn: 1, step: 1 })
const first = session.append(
'user/message',
{ content: [{ type: 'text', text: 'first' }], source: { kind: 'user' } },
@@ -117,13 +119,14 @@ describe('session-query exact reads', () => {
{ surfaceOp: { op: 'replace', start: first.seq, end: first.seq }, sourceEventSeqs: [first.seq] },
)
- expect((await ctx.sessionQuery.listEvents(session.id)).map(record => record.surface))
+ expect((await ctx.sessionQuery.listEvents(session.id)).slice(2).map(record => record.surface))
.toEqual(['shadowed', 'log-only', 'current'])
})
it('returns a bounded detached raw-event window and validates the request', async () => {
const ctx = await liveContext({ readWindowMax: 1 })
const session = ctx.sessions.create(SessionId('window'), { meta: { cwd: '/work' } })
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
for (const text of ['one', 'two', 'three']) {
session.append(
'user/message',
@@ -132,14 +135,14 @@ describe('session-query exact reads', () => {
)
}
- const result = await ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 1, before: 1, after: 1 })
- expect([result.startSeq, result.endSeq, result.target.seq]).toEqual([0, 2, 1])
+ const result = await ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 2, before: 1, after: 1 })
+ expect([result.startSeq, result.endSeq, result.target.seq]).toEqual([1, 3, 2])
expect(result.session).toEqual(session.header)
Object.assign(result.session, { createdAt: -1 })
if (result.events[0]?.type !== 'user/message') throw new Error('expected user message')
result.events[0].data.content = []
expect(session.header.createdAt).not.toBe(-1)
- expect(session.events[0]?.type === 'user/message' && session.events[0].data.content).toHaveLength(1)
+ expect(session.events[1]?.type === 'user/message' && session.events[1].data.content).toHaveLength(1)
await expect(ctx.sessionQuery.readEvent({ sessionId: session.id, seq: 9 }))
.rejects.toThrow(expectCode('SESSION_QUERY_EVENT_NOT_FOUND'))
@@ -161,6 +164,7 @@ describe('session-query exact reads', () => {
])
const ctx = await liveContext()
const live = ctx.sessions.create(shared.id, { meta: { createdAt: 3, cwd: '/same' } })
+ live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
live.append(
'user/message',
{ content: [{ type: 'text', text: 'live' }], source: { kind: 'user' } },
@@ -170,7 +174,7 @@ describe('session-query exact reads', () => {
expect((await ctx.sessionQuery.listSessions()).map(record => [record.header.id, record.live, record.persisted]))
.toEqual([[shared.id, true, true], [durable.id, false, true]])
- const liveRead = await ctx.sessionQuery.readEvent({ sessionId: shared.id, seq: 0 })
+ const liveRead = await ctx.sessionQuery.readEvent({ sessionId: shared.id, seq: 1 })
expect(liveRead.target.type === 'user/message' && liveRead.target.data.content[0])
.toMatchObject({ text: 'live' })
await expect(ctx.sessionQuery.readEvent({ sessionId: durable.id, seq: 0 }))
@@ -189,6 +193,7 @@ describe('session-query exact reads', () => {
TestPersistence.reset()
const ctx = await liveContext()
const live = ctx.sessions.create(SessionId('live'))
+ live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
live.append(
'user/message',
{ content: [{ type: 'text', text: 'available' }], source: { kind: 'user' } },
@@ -198,8 +203,8 @@ describe('session-query exact reads', () => {
TestPersistence.listFailure = new Error('list unavailable')
TestPersistence.loadFailure = new Error('load unavailable')
- await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(1)
- await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 0 })).resolves.toMatchObject({ target: { seq: 0 } })
+ await expect(ctx.sessionQuery.listEvents(live.id)).resolves.toHaveLength(2)
+ await expect(ctx.sessionQuery.readEvent({ sessionId: live.id, seq: 1 })).resolves.toMatchObject({ target: { seq: 1 } })
await expect(ctx.sessionQuery.listSessions()).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
await expect(ctx.sessionQuery.listEvents(SessionId('durable'))).rejects.toThrow(expectCode('SESSION_QUERY_PERSISTENCE_FAILED'))
})
@@ -228,19 +233,8 @@ describe('session-query exact reads', () => {
.rejects.toThrow(expectCode('SESSION_QUERY_SOURCE_CONFLICT'))
})
- it('turns malformed surfaces and direct invalid config into typed errors', async () => {
+ it('turns persisted malformed surfaces and direct invalid config into typed errors', async () => {
const ctx = await liveContext()
- const session = ctx.sessions.create(SessionId('bad-surface'))
- ;(session as unknown as { log: SessionEvent[] }).log.push({
- type: 'assistant/message',
- seq: 0,
- time: 1,
- data: { turn: 1, step: 1, content: [], provenance: { provider: 'mock', model: 'mock' } },
- surfaceOp: { op: 'replace', start: 9, end: 9 },
- })
- await expect(ctx.sessionQuery.listEvents(session.id))
- .rejects.toThrow(expectCode('SESSION_QUERY_INVALID_SURFACE'))
-
const persisted = header('bad-persisted-surface')
TestPersistence.reset([{
meta: persisted,
diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts
index 03e1adad89..ee8b1d833f 100644
--- a/packages/session-query/session-query/tests/tracing.spec.ts
+++ b/packages/session-query/session-query/tests/tracing.spec.ts
@@ -89,6 +89,8 @@ function expectCode(code: SessionQueryErrorCode): Error {
}
function appendTraceEvents(session: Session): void {
+ session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+ session.append('step/start', { turn: 1, step: 1 })
session.append('assistant/chunk', {
turn: 1,
step: 1,
@@ -97,22 +99,24 @@ function appendTraceEvents(session: Session): void {
session.append(
'user/message',
{ content: [{ type: 'text', text: 'original' }], source: { kind: 'user' } },
- { surfaceOp: 'append', sourceEventSeqs: [0] },
+ { surfaceOp: 'append', sourceEventSeqs: [2] },
)
session.append(
'assistant/message',
{ provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 1, content: [{ type: 'text', text: 'summary one' }] },
- { surfaceOp: { op: 'replace', start: 1, end: 1 }, sourceEventSeqs: [1, 0] },
+ { surfaceOp: { op: 'replace', start: 3, end: 3 }, sourceEventSeqs: [3, 2] },
)
session.append(
'context/message',
{ content: [{ type: 'text', text: 'context' }], source: { kind: 'plugin', plugin: 'test' } },
{ surfaceOp: 'append' },
)
+ session.append('step/end', { turn: 1, step: 1 })
+ session.append('step/start', { turn: 1, step: 2 })
session.append(
'assistant/message',
{ provenance: { provider: 'mock', model: 'mock' }, turn: 1, step: 2, content: [{ type: 'text', text: 'summary two' }] },
- { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [0, 2] },
+ { surfaceOp: { op: 'replace', start: 4, end: 4 }, sourceEventSeqs: [2, 4] },
)
}
@@ -235,40 +239,40 @@ describe('session event tracing', () => {
const session = ctx.sessions.create(SessionId('trace'))
appendTraceEvents(session)
- const original = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 1 })
+ const original = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 3 })
expect(original.target).toMatchObject({
sessionId: session.id,
- seq: 1,
+ seq: 3,
type: 'user/message',
surface: 'shadowed',
})
expect(original).toMatchObject({
- replacedBy: 2,
- replacementChain: [2, 4],
+ replacedBy: 4,
+ replacementChain: [4, 8],
replacedEventSeqs: [],
- sourceEventSeqs: [0],
- derivedEventSeqs: [2],
+ sourceEventSeqs: [2],
+ derivedEventSeqs: [4],
})
- await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 2 }))
+ await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 }))
.resolves.toMatchObject({
- replacedBy: 4,
- replacementChain: [4],
- replacedEventSeqs: [1],
- sourceEventSeqs: [1, 0],
- derivedEventSeqs: [4],
+ replacedBy: 8,
+ replacementChain: [8],
+ replacedEventSeqs: [3],
+ sourceEventSeqs: [3, 2],
+ derivedEventSeqs: [8],
})
- await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 0 }))
+ await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 2 }))
.resolves.toMatchObject({
target: { surface: 'log-only' },
replacementChain: [],
sourceEventSeqs: [],
- derivedEventSeqs: [1, 2, 4],
+ derivedEventSeqs: [3, 4, 8],
})
- await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 }))
+ await expect(ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 8 }))
.resolves.toMatchObject({
replacementChain: [],
- replacedEventSeqs: [2],
- sourceEventSeqs: [0, 2],
+ replacedEventSeqs: [4],
+ sourceEventSeqs: [2, 4],
derivedEventSeqs: [],
})
})
@@ -278,18 +282,18 @@ describe('session event tracing', () => {
const session = ctx.sessions.create(SessionId('detached'))
appendTraceEvents(session)
- const first = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 2 })
+ const first = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 })
first.target.time = -1
first.replacementChain.push(99)
first.replacedEventSeqs.push(99)
first.sourceEventSeqs.push(99)
first.derivedEventSeqs.push(99)
- const repeated = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 2 })
+ const repeated = await ctx.sessionQuery.traceEvent({ sessionId: session.id, seq: 4 })
expect(repeated.target.time).not.toBe(-1)
- expect(repeated.replacementChain).toEqual([4])
- expect(repeated.replacedEventSeqs).toEqual([1])
- expect(repeated.sourceEventSeqs).toEqual([1, 0])
- expect(repeated.derivedEventSeqs).toEqual([4])
+ expect(repeated.replacementChain).toEqual([8])
+ expect(repeated.replacedEventSeqs).toEqual([3])
+ expect(repeated.sourceEventSeqs).toEqual([3, 2])
+ expect(repeated.derivedEventSeqs).toEqual([8])
})
it('loads persisted logs once, prefers live logs, and preserves failures and conflicts', async () => {
@@ -303,6 +307,7 @@ describe('session event tracing', () => {
expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
const live = ctx.sessions.create(durable.id, { meta: { createdAt: 1, cwd: '/same' } })
+ live.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
live.append(
'context/message',
{ content: [{ type: 'text', text: 'live' }], source: { kind: 'plugin', plugin: 'test' } },
@@ -310,7 +315,7 @@ describe('session event tracing', () => {
)
TracePersistence.listFailure = new Error('list unavailable')
TracePersistence.loadFailure = new Error('load unavailable')
- await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 0 }))
+ await expect(ctx.sessionQuery.traceEvent({ sessionId: durable.id, seq: 1 }))
.resolves.toMatchObject({ target: { type: 'context/message' } })
expect([TracePersistence.listCalls, TracePersistence.loadCalls]).toEqual([1, 1])
diff --git a/packages/session-query/session-query/tsconfig.json b/packages/session-query/session-query/tsconfig.json
index 7153dae8bb..d7205907e1 100644
--- a/packages/session-query/session-query/tsconfig.json
+++ b/packages/session-query/session-query/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../session-persistence/session-persistence"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/skill/skill-local/package.json b/packages/skill/skill-local/package.json
index d490438c51..be7c7baae2 100644
--- a/packages/skill/skill-local/package.json
+++ b/packages/skill/skill-local/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-fs": "^0.0.1",
"@deepseek-ai/dsh-home": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-skill": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
@@ -34,6 +40,7 @@
"devDependencies": {
"@deepseek-ai/dsh-fs": "workspace:^",
"@deepseek-ai/dsh-home": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-skill": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
diff --git a/packages/skill/skill-local/src/invariant.ts b/packages/skill/skill-local/src/invariant.ts
new file mode 100644
index 0000000000..6d4917a4d9
--- /dev/null
+++ b/packages/skill/skill-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-skill-local`.
+ * @module @deepseek-ai/dsh-skill-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-skill-local'
+
+/** Cordis companion plugin name. */
+export const name = 'skill-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/skill/skill-local/tsconfig.json b/packages/skill/skill-local/tsconfig.json
index f51147abce..d471e269d0 100644
--- a/packages/skill/skill-local/tsconfig.json
+++ b/packages/skill/skill-local/tsconfig.json
@@ -6,11 +6,26 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../util/home" },
- { "path": "../../fs/fs" },
- { "path": "../skill" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../util/home"
+ },
+ {
+ "path": "../../fs/fs"
+ },
+ {
+ "path": "../skill"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/skill/skill/package.json b/packages/skill/skill/package.json
index c025de6ee9..3148a3f577 100644
--- a/packages/skill/skill/package.json
+++ b/packages/skill/skill/package.json
@@ -11,23 +11,30 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"dependencies": {
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/skill/skill/src/invariant.ts b/packages/skill/skill/src/invariant.ts
new file mode 100644
index 0000000000..5145dee6da
--- /dev/null
+++ b/packages/skill/skill/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-skill`.
+ * @module @deepseek-ai/dsh-skill/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-skill'
+
+/** Cordis companion plugin name. */
+export const name = 'skill-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: provider/runtime maps and revisioned caches mutate atomically inside the
+ * registry, which exposes no independent change event or snapshot for cross-checking them.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/skill/skill/tsconfig.json b/packages/skill/skill/tsconfig.json
index 1b1855dcc4..e882ed2d72 100644
--- a/packages/skill/skill/tsconfig.json
+++ b/packages/skill/skill/tsconfig.json
@@ -6,8 +6,17 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/skill/tool-skill/package.json b/packages/skill/tool-skill/package.json
index 3d6ddc6b7e..47421bf19c 100644
--- a/packages/skill/tool-skill/package.json
+++ b/packages/skill/tool-skill/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-skill": "^0.0.1",
"@deepseek-ai/dsh-tools": "^0.0.1",
@@ -33,6 +39,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-skill": "workspace:^",
diff --git a/packages/skill/tool-skill/src/invariant.ts b/packages/skill/tool-skill/src/invariant.ts
new file mode 100644
index 0000000000..68d70fa2d2
--- /dev/null
+++ b/packages/skill/tool-skill/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-skill`.
+ * @module @deepseek-ai/dsh-tool-skill/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-skill'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-skill-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+ * relations are owned by the capability seam it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/skill/tool-skill/tsconfig.json b/packages/skill/tool-skill/tsconfig.json
index 52ebb8bf9d..fed1ffa5f5 100644
--- a/packages/skill/tool-skill/tsconfig.json
+++ b/packages/skill/tool-skill/tsconfig.json
@@ -6,13 +6,32 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../core/scope" },
- { "path": "../../llm/llm" },
- { "path": "../../core/agent" },
- { "path": "../skill" },
- { "path": "../../core/tools" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../core/scope"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/agent"
+ },
+ {
+ "path": "../skill"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/spill/spill-local/package.json b/packages/spill/spill-local/package.json
index a75c4bfc0b..25a20db1d5 100644
--- a/packages/spill/spill-local/package.json
+++ b/packages/spill/spill-local/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-spill": "^0.0.1",
"cordis": "^4.0.0-rc.6"
},
@@ -30,6 +36,7 @@
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-spill": "workspace:^",
diff --git a/packages/spill/spill-local/src/invariant.ts b/packages/spill/spill-local/src/invariant.ts
new file mode 100644
index 0000000000..4b44ddbebf
--- /dev/null
+++ b/packages/spill/spill-local/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-spill-local`.
+ * @module @deepseek-ai/dsh-spill-local/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-spill-local'
+
+/** Cordis companion plugin name. */
+export const name = 'spill-local-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/spill/spill-local/tsconfig.json b/packages/spill/spill-local/tsconfig.json
index 8e818212f5..0cb209d8d0 100644
--- a/packages/spill/spill-local/tsconfig.json
+++ b/packages/spill/spill-local/tsconfig.json
@@ -6,9 +6,20 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../spill" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../spill"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/spill/spill-policy/package.json b/packages/spill/spill-policy/package.json
index 7dc4631818..e8e9fb4631 100644
--- a/packages/spill/spill-policy/package.json
+++ b/packages/spill/spill-policy/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-retention": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -35,6 +41,7 @@
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-retention": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/spill/spill-policy/src/invariant.ts b/packages/spill/spill-policy/src/invariant.ts
new file mode 100644
index 0000000000..82a4bee211
--- /dev/null
+++ b/packages/spill/spill-policy/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-spill-policy`.
+ * @module @deepseek-ai/dsh-spill-policy/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-spill-policy'
+
+/** Cordis companion plugin name. */
+export const name = 'spill-policy-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/spill/spill-policy/tests/spill-policy.spec.ts b/packages/spill/spill-policy/tests/spill-policy.spec.ts
index ec40743db3..f55985f179 100644
--- a/packages/spill/spill-policy/tests/spill-policy.spec.ts
+++ b/packages/spill/spill-policy/tests/spill-policy.spec.ts
@@ -110,6 +110,7 @@ describe('config validation', () => {
it('rejects a fractional maxInlineBytes at load', async () => {
await expect(setup({ maxInlineBytes: 1.5 })).rejects.toThrow(/non-negative integer/)
})
+
})
describe('oversized plain-text replacement', () => {
diff --git a/packages/spill/spill-policy/tsconfig.json b/packages/spill/spill-policy/tsconfig.json
index 6a81ab2f3c..71f19d381c 100644
--- a/packages/spill/spill-policy/tsconfig.json
+++ b/packages/spill/spill-policy/tsconfig.json
@@ -6,13 +6,32 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../../vendor/schemastery" },
- { "path": "../../util/retention" },
- { "path": "../../llm/llm" },
- { "path": "../../core/session" },
- { "path": "../spill" },
- { "path": "../../core/tools" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../../vendor/schemastery"
+ },
+ {
+ "path": "../../util/retention"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/session"
+ },
+ {
+ "path": "../spill"
+ },
+ {
+ "path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/spill/spill/package.json b/packages/spill/spill/package.json
index 3103c9cd11..c66306ff0a 100644
--- a/packages/spill/spill/package.json
+++ b/packages/spill/spill/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,12 +28,14 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.6"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"cordis": "^4.0.0-rc.6"
diff --git a/packages/spill/spill/src/invariant.ts b/packages/spill/spill/src/invariant.ts
new file mode 100644
index 0000000000..5011ac1d52
--- /dev/null
+++ b/packages/spill/spill/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-spill`.
+ * @module @deepseek-ai/dsh-spill/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-spill'
+
+/** Cordis companion plugin name. */
+export const name = 'spill-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/spill/spill/tsconfig.json b/packages/spill/spill/tsconfig.json
index 0c2fd5c57f..30d0d29f0f 100644
--- a/packages/spill/spill/tsconfig.json
+++ b/packages/spill/spill/tsconfig.json
@@ -6,10 +6,23 @@
},
"include": ["src"],
"references": [
- { "path": "../../../vendor/cosmokit" },
- { "path": "../../../vendor/cordis" },
- { "path": "../../util/brand" },
- { "path": "../../llm/llm" },
- { "path": "../../core/session" }
+ {
+ "path": "../../../vendor/cosmokit"
+ },
+ {
+ "path": "../../../vendor/cordis"
+ },
+ {
+ "path": "../../util/brand"
+ },
+ {
+ "path": "../../llm/llm"
+ },
+ {
+ "path": "../../core/session"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/subagent/subagent-acp/package.json b/packages/subagent/subagent-acp/package.json
index fa16edcf60..2564afa8da 100644
--- a/packages/subagent/subagent-acp/package.json
+++ b/packages/subagent/subagent-acp/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-subagent": "^0.0.1",
@@ -34,13 +40,14 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"@deepseek-ai/dsh-agent": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-loader-smoke": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-subagent": "workspace:^",
"@deepseek-ai/dsh-subagent-subprocess": "workspace:^",
- "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/subagent/subagent-acp/src/invariant.ts b/packages/subagent/subagent-acp/src/invariant.ts
new file mode 100644
index 0000000000..85c1601348
--- /dev/null
+++ b/packages/subagent/subagent-acp/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-acp`.
+ * @module @deepseek-ai/dsh-subagent-acp/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-acp'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-acp-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-acp/tsconfig.json b/packages/subagent/subagent-acp/tsconfig.json
index 5aa28528ac..175eb78e2f 100644
--- a/packages/subagent/subagent-acp/tsconfig.json
+++ b/packages/subagent/subagent-acp/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../support/loader-smoke"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/subagent/subagent-fork/package.json b/packages/subagent/subagent-fork/package.json
index 63f548d217..aa93b83e03 100644
--- a/packages/subagent/subagent-fork/package.json
+++ b/packages/subagent/subagent-fork/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-subagent": "^0.0.1",
"@deepseek-ai/dsh-subagent-inprocess": "^0.0.1",
@@ -32,6 +38,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
@@ -41,7 +48,6 @@
"@deepseek-ai/dsh-subagent": "workspace:^",
"@deepseek-ai/dsh-subagent-inprocess": "workspace:^",
"@deepseek-ai/dsh-subagent-spawn": "workspace:^",
- "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/subagent/subagent-fork/src/invariant.ts b/packages/subagent/subagent-fork/src/invariant.ts
new file mode 100644
index 0000000000..e3d65701b1
--- /dev/null
+++ b/packages/subagent/subagent-fork/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-fork`.
+ * @module @deepseek-ai/dsh-subagent-fork/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-fork'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-fork-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
index df3b74d346..6f091c2bf6 100644
--- a/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
+++ b/packages/subagent/subagent-fork/tests/multi-subagent.spec.ts
@@ -3,7 +3,10 @@ import { Context } from 'cordis'
import { SessionId } from '@deepseek-ai/dsh-session'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
import * as Spawn from '@deepseek-ai/dsh-subagent-spawn'
import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
@@ -11,6 +14,13 @@ import * as fork from '../src/index.ts'
type Script = ConstructorParameters[0]
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
function start(ctx: Context, provider: string, request: Omit & { signal?: AbortSignal }) {
return ctx.subagents.start(provider, { signal: request.signal ?? new AbortController().signal, ...request })
}
@@ -24,7 +34,7 @@ function start(ctx: Context, provider: string, request: Omit[0]
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
function start(ctx: Context, provider: string, request: Omit & { signal?: AbortSignal }) {
return ctx.subagents.start(provider, { signal: request.signal ?? new AbortController().signal, ...request })
}
@@ -24,14 +34,14 @@ const emptyStop: StreamChunk[] = [{ type: 'finish', reason: { kind: 'stop' } }]
/**
* Drives the REAL fork backend with a real loop + scripted mock MODEL + the
- * real dsh-invariants plugin. The plugin replays a seeded child log on
+ * real invariant service and package companions. The session contribution replays a seeded child log on
* `session/created`, so a malformed (unbalanced) fork seed makes these tests
* THROW — that is the regression guard for the completed-turn-prefix boundary.
*/
async function setup(script: Script) {
const ctx = new Context()
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
await ctx.plugin(SubagentService)
await ctx.plugin(fork, { providerName: 'fork' })
diff --git a/packages/subagent/subagent-fork/tsconfig.json b/packages/subagent/subagent-fork/tsconfig.json
index bac12550af..a07a2319ef 100644
--- a/packages/subagent/subagent-fork/tsconfig.json
+++ b/packages/subagent/subagent-fork/tsconfig.json
@@ -28,6 +28,9 @@
},
{
"path": "../subagent-inprocess"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/subagent/subagent-inprocess/package.json b/packages/subagent/subagent-inprocess/package.json
index b9397e300c..69b573ecdd 100644
--- a/packages/subagent/subagent-inprocess/package.json
+++ b/packages/subagent/subagent-inprocess/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-subagent": "^0.0.1",
diff --git a/packages/subagent/subagent-inprocess/src/invariant.ts b/packages/subagent/subagent-inprocess/src/invariant.ts
new file mode 100644
index 0000000000..7b8bfc36e2
--- /dev/null
+++ b/packages/subagent/subagent-inprocess/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-inprocess`.
+ * @module @deepseek-ai/dsh-subagent-inprocess/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-inprocess'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-inprocess-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-inprocess/tests/structured.spec.ts b/packages/subagent/subagent-inprocess/tests/structured.spec.ts
index 114cebdd40..b0689a0eaa 100644
--- a/packages/subagent/subagent-inprocess/tests/structured.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/structured.spec.ts
@@ -5,7 +5,10 @@ import type { ContinuationDecision } from '@deepseek-ai/dsh-agent'
import { SessionId } from '@deepseek-ai/dsh-session'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
import type { Config as ToolConfig, ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
import { defineContentToolFixture, RUN_CODE_NAME } from '@deepseek-ai/dsh-tools'
@@ -18,6 +21,13 @@ import {
type Script = ConstructorParameters[0]
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
interface CodeRunRequestLike {
bindings: { global: string; functions: Record Promise> }[]
}
@@ -51,7 +61,7 @@ async function setup(script: Script, options: SetupOptions = {}) {
run: options.codeRun ?? (() => Promise.resolve({ logs: [] })),
} as never)
}
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
await ctx.plugin(SubagentService)
const disposeProvider = ctx.subagents.registerProvider({
diff --git a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
index e82c1ad028..4826931e9d 100644
--- a/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
+++ b/packages/subagent/subagent-inprocess/tests/subagent-inprocess.spec.ts
@@ -4,17 +4,27 @@ import { type Agent } from '@deepseek-ai/dsh-agent'
import { SessionId } from '@deepseek-ai/dsh-session'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import SubagentService from '@deepseek-ai/dsh-subagent'
import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
import { startInProcessRun } from '../src/index.ts'
type Script = ConstructorParameters[0]
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
async function setup(script: Script) {
const ctx = new Context()
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
await ctx.plugin(SubagentService)
ctx.llm.registerAdapter(['mock'], new MockAdapter(script))
diff --git a/packages/subagent/subagent-inprocess/tsconfig.json b/packages/subagent/subagent-inprocess/tsconfig.json
index 7b7a015cc9..02fd8e53d0 100644
--- a/packages/subagent/subagent-inprocess/tsconfig.json
+++ b/packages/subagent/subagent-inprocess/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/subagent/subagent-spawn/package.json b/packages/subagent/subagent-spawn/package.json
index 1a986e69aa..f429025a5d 100644
--- a/packages/subagent/subagent-spawn/package.json
+++ b/packages/subagent/subagent-spawn/package.json
@@ -11,17 +11,23 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-subagent": "^0.0.1",
"@deepseek-ai/dsh-subagent-inprocess": "^0.0.1",
"cordis": "^4.0.0-rc.7"
@@ -30,6 +36,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
+ "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
@@ -42,7 +49,6 @@
"@deepseek-ai/dsh-subagent-inprocess": "workspace:^",
"@deepseek-ai/dsh-tool-bash": "workspace:^",
"@deepseek-ai/dsh-tool-subagent": "workspace:^",
- "@cordisjs/plugin-loader": "^1.0.0-rc.5",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/subagent/subagent-spawn/src/invariant.ts b/packages/subagent/subagent-spawn/src/invariant.ts
new file mode 100644
index 0000000000..0ba0182f9f
--- /dev/null
+++ b/packages/subagent/subagent-spawn/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-spawn`.
+ * @module @deepseek-ai/dsh-subagent-spawn/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-spawn'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-spawn-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
index 368e3700c9..8952c29be7 100644
--- a/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
+++ b/packages/subagent/subagent-spawn/tests/subagent-spawn.spec.ts
@@ -5,7 +5,10 @@ import AgentRegistry from '@deepseek-ai/dsh-agent'
import { SessionId } from '@deepseek-ai/dsh-session'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'
import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
+import * as AgentInvariant from '@deepseek-ai/dsh-agent/invariant'
+import * as AgentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
import SubagentService, { type SubagentStartRequest } from '@deepseek-ai/dsh-subagent'
import { MockAdapter, maxTokensResponse, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
import * as spawn from '../src/index.ts'
@@ -14,10 +17,17 @@ import { defineContentToolFixture } from '@deepseek-ai/dsh-tools'
type Script = ConstructorParameters[0]
+async function mountInvariants(ctx: Context): Promise {
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SessionInvariant)
+ await ctx.plugin(AgentInvariant)
+ await ctx.plugin(AgentLoopInvariant)
+}
+
/**
* Drives the REAL spawn backend end-to-end: a real agent loop + a scripted mock
* MODEL (the only mocked boundary) + the real SubagentService + the real
- * dsh-invariants plugin (so a malformed child session log would fail the test).
+ * invariant service plus package companions (so a malformed child session log would fail the test).
* The parent is a real config agent; the spawn provider creates a real child
* agent on the same context and we assert its output.
*/
@@ -25,7 +35,7 @@ async function setup(script: Script) {
const ctx = new Context()
const adapter = new MockAdapter(script)
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
await ctx.plugin(SubagentService)
await ctx.plugin(spawn, { providerName: 'spawn' })
@@ -296,7 +306,7 @@ describe('dsh-subagent-spawn', () => {
const ctx = new Context()
const adapter = new MockAdapter(['hang'])
await mountAgentLoopTestDependencies(ctx)
- await ctx.plugin(Invariants)
+ await mountInvariants(ctx)
await ctx.plugin(AgentLoop, { agents: [] })
await ctx.plugin(SubagentService)
const fiber = await ctx.plugin(spawn, { providerName: 'spawn' })
diff --git a/packages/subagent/subagent-spawn/tsconfig.json b/packages/subagent/subagent-spawn/tsconfig.json
index 219bf2a0c9..ee9ab096c2 100644
--- a/packages/subagent/subagent-spawn/tsconfig.json
+++ b/packages/subagent/subagent-spawn/tsconfig.json
@@ -22,6 +22,9 @@
},
{
"path": "../subagent-inprocess"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/subagent/subagent-subprocess/package.json b/packages/subagent/subagent-subprocess/package.json
index 5f17459276..bd573b3c0c 100644
--- a/packages/subagent/subagent-subprocess/package.json
+++ b/packages/subagent/subagent-subprocess/package.json
@@ -11,20 +11,27 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/subagent/subagent-subprocess/src/invariant.ts b/packages/subagent/subagent-subprocess/src/invariant.ts
new file mode 100644
index 0000000000..c273ce5209
--- /dev/null
+++ b/packages/subagent/subagent-subprocess/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-subagent-subprocess`.
+ * @module @deepseek-ai/dsh-subagent-subprocess/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent-subprocess'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-subprocess-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this package exposes no independent event sequence or mutable data relation
+ * beyond contracts enforced at its owning seam.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/subagent-subprocess/tsconfig.json b/packages/subagent/subagent-subprocess/tsconfig.json
index 749cb0208e..d970a00263 100644
--- a/packages/subagent/subagent-subprocess/tsconfig.json
+++ b/packages/subagent/subagent-subprocess/tsconfig.json
@@ -7,5 +7,9 @@
"include": [
"src"
],
- "references": []
+ "references": [
+ {
+ "path": "../../support/invariants"
+ }
+ ]
}
diff --git a/packages/subagent/subagent/package.json b/packages/subagent/subagent/package.json
index aea05553e4..58b51d1888 100644
--- a/packages/subagent/subagent/package.json
+++ b/packages/subagent/subagent/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -24,6 +29,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-brand": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-scope": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -33,6 +39,7 @@
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-brand": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-scope": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
diff --git a/packages/subagent/subagent/src/invariant.ts b/packages/subagent/subagent/src/invariant.ts
new file mode 100644
index 0000000000..3c350c13a1
--- /dev/null
+++ b/packages/subagent/subagent/src/invariant.ts
@@ -0,0 +1,91 @@
+/** Package-owned subagent registry and lifecycle invariants. @module @deepseek-ai/dsh-subagent/invariant */
+
+import type { Context } from 'cordis'
+import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import type { SubagentProvider } from './types.ts'
+import type { SubagentRunEndInfo, SubagentRunInfo } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-subagent'
+
+/** Cordis companion plugin name. */
+export const name = 'subagent-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/** Assert that a terminal lifecycle payload matches its start identity. */
+function validateRunEnd(start: SubagentRunInfo, end: SubagentRunEndInfo, fail: InvariantFailure): void {
+ if (start.provider !== end.provider || start.id !== end.id || start.local !== end.local) {
+ fail(`subagent/end identity diverges from subagent/start for run ${JSON.stringify(end.runId)}`)
+ }
+}
+
+/** Install provider-registry and start/end pairing checks. */
+const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
+ const providers = new Set(ctx.subagents.list())
+ const runs = new Map()
+ const stagedProviders = new WeakSet()
+ const stagedRemovals = new Set()
+ const stagedStarts = new WeakSet()
+ const stagedEnds = new WeakSet()
+
+ ctx.on('internal/dispatch', (_mode, eventName, args) => {
+ if (eventName === 'subagent/provider-added') {
+ const provider = args[0] as SubagentProvider
+ if (provider.name.length === 0) fail('subagent provider names must be non-empty')
+ if (providers.has(provider.name)) fail(`subagent/provider-added repeated ${JSON.stringify(provider.name)}`)
+ stagedProviders.add(provider)
+ return
+ }
+ if (eventName === 'subagent/provider-removed') {
+ const providerName = args[0] as string
+ if (!providers.has(providerName)) fail(`subagent/provider-removed names unknown provider ${JSON.stringify(providerName)}`)
+ stagedRemovals.add(providerName)
+ return
+ }
+ if (eventName === 'subagent/start') {
+ const info = args[0] as SubagentRunInfo
+ if (!providers.has(info.provider)) fail(`subagent/start names inactive provider ${JSON.stringify(info.provider)}`)
+ if (String(info.runId).length === 0 || String(info.id).length === 0) {
+ fail('subagent/start runId and child id must be non-empty')
+ }
+ if (runs.has(info.runId)) fail(`subagent/start repeated run id ${JSON.stringify(info.runId)}`)
+ stagedStarts.add(info)
+ return
+ }
+ if (eventName !== 'subagent/end') return
+ const info = args[0] as SubagentRunEndInfo
+ const start = runs.get(info.runId)
+ if (start === undefined) fail(`subagent/end has no matching subagent/start for run ${JSON.stringify(info.runId)}`)
+ validateRunEnd(start, info, fail)
+ stagedEnds.add(info)
+ }, { global: true })
+
+ ctx.on('subagent/provider-added', (provider) => {
+ /* v8 ignore next -- internal/dispatch stages the same provider object */
+ if (!stagedProviders.delete(provider)) return
+ providers.add(provider.name)
+ }, { global: true })
+ ctx.on('subagent/provider-removed', (providerName) => {
+ /* v8 ignore next -- internal/dispatch stages the same provider name */
+ if (!stagedRemovals.delete(providerName)) return
+ providers.delete(providerName)
+ }, { global: true })
+ ctx.on('subagent/start', (info) => {
+ /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+ if (!stagedStarts.delete(info)) return
+ runs.set(info.runId, info)
+ }, { global: true })
+ ctx.on('subagent/end', (info) => {
+ /* v8 ignore next -- internal/dispatch stages the same lifecycle object */
+ if (!stagedEnds.delete(info)) return
+ runs.delete(info.runId)
+ }, { global: true })
+}, { inject: ['subagents'] })
+
+/**
+ * Register the subagent invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
diff --git a/packages/subagent/subagent/tests/invariant.spec.ts b/packages/subagent/subagent/tests/invariant.spec.ts
new file mode 100644
index 0000000000..ac3a919862
--- /dev/null
+++ b/packages/subagent/subagent/tests/invariant.spec.ts
@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import SubagentService, { SubagentRunId } from '@deepseek-ai/dsh-subagent'
+import type {
+ SubagentProvider,
+ SubagentRunEndInfo,
+ SubagentRunInfo,
+} from '@deepseek-ai/dsh-subagent'
+import * as SubagentInvariant from '@deepseek-ai/dsh-subagent/invariant'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+async function setup(): Promise {
+ const ctx = new Context()
+ await ctx.plugin(SubagentService)
+ await ctx.plugin(InvariantService)
+ await ctx.plugin(SubagentInvariant)
+ return ctx
+}
+
+const provider = (name: string): SubagentProvider => ({
+ name,
+ capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+ inheritsParentContext: false,
+ start: async () => { throw new Error('not used') },
+})
+
+const start = (overrides: Partial = {}): SubagentRunInfo => ({
+ runId: SubagentRunId('run-1'),
+ provider: 'mock',
+ id: SessionId('child-1'),
+ local: false,
+ ...overrides,
+})
+
+const end = (overrides: Partial = {}): SubagentRunEndInfo => ({
+ ...start(),
+ stopReason: 'completed',
+ ...overrides,
+})
+
+function emitRun(ctx: Context, name: 'subagent/start', info: SubagentRunInfo): void
+function emitRun(ctx: Context, name: 'subagent/end', info: SubagentRunEndInfo): void
+function emitRun(ctx: Context, name: 'subagent/start' | 'subagent/end', info: SubagentRunInfo | SubagentRunEndInfo): void {
+ ctx.emit(scopeTarget(ctx.subagents, {}), name as 'subagent/start', info)
+}
+
+describe('subagent invariants', () => {
+ it('accepts provider and run lifecycle pairs', async () => {
+ const ctx = await setup()
+ const mock = provider('mock')
+ ctx.emit('subagent/provider-added', mock)
+ emitRun(ctx, 'subagent/start', start())
+ emitRun(ctx, 'subagent/end', end())
+ ctx.emit('subagent/provider-removed', 'mock')
+ ctx.emit('tools/change')
+ })
+
+ it('rejects malformed provider transitions', async () => {
+ const ctx = await setup()
+ expect(() => { ctx.emit('subagent/provider-added', provider('')) }).toThrow(/names must be non-empty/)
+ const mock = provider('mock')
+ ctx.emit('subagent/provider-added', mock)
+ expect(() => { ctx.emit('subagent/provider-added', mock) }).toThrow(/repeated "mock"/)
+ expect(() => { ctx.emit('subagent/provider-removed', 'missing') }).toThrow(/unknown provider/)
+ })
+
+ it('rejects malformed and unpaired run transitions', async () => {
+ const ctx = await setup()
+ expect(() => { emitRun(ctx, 'subagent/start', start()) }).toThrow(/inactive provider/)
+ ctx.emit('subagent/provider-added', provider('mock'))
+ expect(() => { emitRun(ctx, 'subagent/start', start({ runId: SubagentRunId('') })) })
+ .toThrow(/runId and child id must be non-empty/)
+ emitRun(ctx, 'subagent/start', start())
+ expect(() => { emitRun(ctx, 'subagent/start', start()) }).toThrow(/repeated run id/)
+ expect(() => { emitRun(ctx, 'subagent/end', end({ runId: SubagentRunId('missing') })) })
+ .toThrow(/no matching subagent\/start/)
+ expect(() => { emitRun(ctx, 'subagent/end', end({ id: SessionId('other') })) })
+ .toThrow(/identity diverges/)
+ })
+})
diff --git a/packages/subagent/subagent/tsconfig.json b/packages/subagent/subagent/tsconfig.json
index f93f929241..713e214f04 100644
--- a/packages/subagent/subagent/tsconfig.json
+++ b/packages/subagent/subagent/tsconfig.json
@@ -25,6 +25,9 @@
},
{
"path": "../../core/scope"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/subagent/tool-subagent/package.json b/packages/subagent/tool-subagent/package.json
index e2d4378743..6ed447dd56 100644
--- a/packages/subagent/tool-subagent/package.json
+++ b/packages/subagent/tool-subagent/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-subagent": "^0.0.1",
"@deepseek-ai/dsh-tasks": "^0.0.1",
@@ -35,6 +41,7 @@
"devDependencies": {
"@cordisjs/plugin-loader": "^1.0.0-rc.5",
"@deepseek-ai/dsh-agent": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-subagent": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/subagent/tool-subagent/src/invariant.ts b/packages/subagent/tool-subagent/src/invariant.ts
new file mode 100644
index 0000000000..bd30f4c563
--- /dev/null
+++ b/packages/subagent/tool-subagent/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-subagent`.
+ * @module @deepseek-ai/dsh-tool-subagent/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-subagent'
+
+/** Cordis companion plugin name. */
+export const name = 'tool-subagent-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+ * relations are owned by the capability seam it calls.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/subagent/tool-subagent/tsconfig.json b/packages/subagent/tool-subagent/tsconfig.json
index 2aa9d4f14e..25780c367f 100644
--- a/packages/subagent/tool-subagent/tsconfig.json
+++ b/packages/subagent/tool-subagent/tsconfig.json
@@ -31,6 +31,9 @@
},
{
"path": "../../tasks/tasks"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/support/acp-snapshot/package.json b/packages/support/acp-snapshot/package.json
index 9cf18e7824..e5e715238a 100644
--- a/packages/support/acp-snapshot/package.json
+++ b/packages/support/acp-snapshot/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -27,9 +32,11 @@
"vitest": "^4.1.8"
},
"peerDependencies": {
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/support/acp-snapshot/src/invariant.ts b/packages/support/acp-snapshot/src/invariant.ts
new file mode 100644
index 0000000000..e94876100e
--- /dev/null
+++ b/packages/support/acp-snapshot/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-acp-snapshot`.
+ * @module @deepseek-ai/dsh-acp-snapshot/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-acp-snapshot'
+
+/** Cordis companion plugin name. */
+export const name = 'acp-snapshot-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event stream or mutable data;
+ * consuming test suites exercise its behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/support/acp-snapshot/tsconfig.json b/packages/support/acp-snapshot/tsconfig.json
index 9120df0ad1..893282ce51 100644
--- a/packages/support/acp-snapshot/tsconfig.json
+++ b/packages/support/acp-snapshot/tsconfig.json
@@ -8,6 +8,11 @@
"src"
],
"references": [
- { "path": "../loader-smoke" }
+ {
+ "path": "../loader-smoke"
+ },
+ {
+ "path": "../../support/invariants"
+ }
]
}
diff --git a/packages/support/agent-loop-testkit/package.json b/packages/support/agent-loop-testkit/package.json
index 423bd3e80d..aa04d85832 100644
--- a/packages/support/agent-loop-testkit/package.json
+++ b/packages/support/agent-loop-testkit/package.json
@@ -11,11 +11,16 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
@@ -23,6 +28,7 @@
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
+ "@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"@deepseek-ai/dsh-system-prompt": "^0.0.1",
@@ -32,6 +38,7 @@
"devDependencies": {
"@deepseek-ai/dsh-agent": "workspace:^",
"@deepseek-ai/dsh-agent-loop": "workspace:^",
+ "@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
"@deepseek-ai/dsh-system-prompt": "workspace:^",
diff --git a/packages/support/agent-loop-testkit/src/invariant.ts b/packages/support/agent-loop-testkit/src/invariant.ts
new file mode 100644
index 0000000000..33ee4474f9
--- /dev/null
+++ b/packages/support/agent-loop-testkit/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-agent-loop-testkit`.
+ * @module @deepseek-ai/dsh-agent-loop-testkit/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-agent-loop-testkit'
+
+/** Cordis companion plugin name. */
+export const name = 'agent-loop-testkit-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: this test-support package owns no production event stream or mutable data;
+ * consuming test suites exercise its behavior.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/support/agent-loop-testkit/tsconfig.json b/packages/support/agent-loop-testkit/tsconfig.json
index 5e5b3c47f2..d24b4dd988 100644
--- a/packages/support/agent-loop-testkit/tsconfig.json
+++ b/packages/support/agent-loop-testkit/tsconfig.json
@@ -28,6 +28,9 @@
},
{
"path": "../../core/tools"
+ },
+ {
+ "path": "../../support/invariants"
}
]
}
diff --git a/packages/support/invariants/README.md b/packages/support/invariants/README.md
index aef85dbb02..e4866212b6 100644
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -1,65 +1,83 @@
# dsh-invariants
-Runtime event-contract assertions intended for development diagnostics. This pure-listener plugin checks relationships among session events, agent states, scoped dispatches, and model requests; it does not own or change product behavior.
+Configurable registry service for package-owned runtime invariant checks. The root plugin registers `ctx.invariants`; it contains no product checks or product-package imports. Every workspace package publishes a `./invariant` companion that registers its exact npm package name.
-The plugin has no environment guard: it is active wherever it is registered. The default [`dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md) bundle mounts it unconditionally; a custom composition can omit it when the runtime cost is undesirable. It doubles as executable documentation of the event taxonomy — the assertions *are* the contract.
+## Service: `InvariantService` (`ctx.invariants`)
-Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The invariants plugin checks the remaining cross-record and cross-seam rules that Session does not own.
+```ts
+interface Config {
+ enabled?: boolean
+ package_allowlist?: string[]
+ package_blocklist?: string[]
+}
+```
-Session-log assertions run during Cordis `internal/dispatch`, while `Session.append()` is resolving the `session/event` callback snapshot but before it pushes the candidate into the log. A valid transition is staged by exact event identity and applied to the live trace only when that same committed event reaches the plugin's contained post-commit listener. A later internal dispatch check can therefore veto without advancing either the log or the invariant trace, while ordinary `session/event` observer failures remain observe-only.
+Defaults are `enabled: true`, `package_allowlist: []`, and `package_blocklist: []`. A package is selected only when the service is enabled, the allowlist is empty or at least one allowlist pattern matches its full npm name, and no blocklist pattern matches. Blocklist matches therefore override allowlist matches.
-## Plugin
+Each entry is a case-sensitive JavaScript regular-expression source compiled with `new RegExp(pattern)`. Matching is unanchored unless the source supplies `^` and `$`; `/pattern/flags` syntax is not parsed. Blank, whitespace-padded, invalid, or duplicate entries within one list fail service startup. A valid pattern may match no currently loaded package so later loading and HMR remain deterministic.
-A functional plugin — register the module namespace (this is what loading by name in `cordis.yml` does):
+`ctx.invariants.register(packageName, installer)` reserves one active registration for the full npm package name, including when filters keep its installer inactive, and returns its disposer. An enabled contribution runs in a dedicated child Cordis fiber. The installer can declare its required service surface through `installer.inject` and receives `fail(message)`, which throws an `InvariantError` bound to the registering package. Synchronous or asynchronous installer completion is joined before registration succeeds; failure disposes the child and releases ownership atomically.
+
+The service owns every registration fiber, while the returned disposer also belongs to the companion fiber. Unloading either side removes listeners, trace state, and the reservation. A companion can therefore reload and register the same package name without retaining its previous state. Session-backed companions rebuild their baseline from durable events; live-only companions observe operations that begin after reload.
+
+`InvariantError` extends `Error`, carries stable `code: 'INVARIANT'`, and exposes the owning `packageName` without adding a product dependency to the service.
+
+Session itself owns immutable, surface-valid log storage in every composition: it takes one lossless JSON snapshot of each candidate, validates complete provenance and positional replacement, restricts `tool/result` replacement to one current result's `content`, deep-freezes the accepted record, and exposes the log through immutable array snapshots. The `dsh-session` invariant companion checks the remaining cross-record rules that Session does not own.
+
+## Package companions
+
+Publication and registration are exhaustive; runtime assertions are deliberately not synthetic. A companion installs a check only when its package owns an observable event relationship or relevant mutable-data relationship. Confirming a required method, plugin name, injection, effect, or fixed pure-function result is a type, load, or unit-test concern rather than a runtime invariant.
+
+When no plausible runtime relationship exists, the companion uses an empty installer with a package-specific leading `No runtime invariant:` comment explaining why. This is common for pure utilities, thin implementations whose behavior is already observed through their seam, composition-only packages, binaries, persistence adapters whose contracts require crash/round-trip tests, and test-support packages. The explanation must be revisited when the owner gains mutable state or an event protocol.
+
+The current executable companions protect these relationships:
+
+| Companion | Checks |
+|---|---|
+| `dsh-session`, `dsh-agent`, `dsh-scope`, `dsh-agent-loop` | Session enclosure and call/result trace, agent-status transitions, scoped subjects, and model-request reconstruction. |
+| `dsh-llm`, `dsh-llm-retry`, `dsh-tools`, `dsh-system-prompt` | Stream grammar, durable retry position and bounds, tool-pipeline stages and frozen results, and authoritative prompt-assembly data. |
+| `dsh-compact`, `dsh-hook-protocol`, `dsh-sandbox-policy` | Durable compaction and hook pairing, compaction metadata, and sandbox-mode vocabulary. |
+| `dsh-fs`, `dsh-subagent`, `dsh-workflow` | Filesystem event identity, provider/child pairing, and workflow/agent lifecycle identity. |
+| `dsh-goal`, `dsh-goal-session` | Durable goal source/content agreement, revision and lifecycle transitions, timestamps, sequential admitted rounds, and reconstructed continuation prompts. |
+| `dsh-permission`, `dsh-user-approval` | Active-preset references and approval asked/decided audit pairing. |
+| `dsh-tasks`, `dsh-tool-todo` | Task snapshot lifecycle/ownership fields and durable whole-list todo structure. |
+| `dsh-time-context` | Durable clock readings agree with the session's open turn and next pre-step position and elapsed baseline; rendered time parses and does not postdate its event. |
+
+The root entrypoint of each owner remains independent of diagnostics. Loading the service alone installs no product checks, and loading a companion without the service waits on its declared `invariants` injection.
+
+`pnpm run verify-package-invariants` discovers all workspace packages. It rejects generated markers, unexplained empty installers, non-empty installers that omit or ignore the reporter, incorrect registration names, and incomplete export, publication, dependency, TypeScript-reference, or bundle wiring. This source rule is a minimum ownership check; focused tests prove each executable companion's semantics.
+
+## Composition
```ts
import type { Context } from 'cordis'
-import * as Invariants from '@deepseek-ai/dsh-invariants'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+import * as SessionInvariant from '@deepseek-ai/dsh-session/invariant'
declare const ctx: Context
-await ctx.plugin(Invariants)
+ctx.plugin(InvariantService, {
+ enabled: true,
+ package_allowlist: ['^@deepseek-ai/dsh-'],
+ package_blocklist: ['^@deepseek-ai/dsh-agent-loop$'],
+})
+ctx.plugin(SessionInvariant)
```
-`inject`: `['sessions']` — it reads `ctx.sessions.list()` at apply time to rebuild trace state for sessions that already exist, so a hot reload mid-turn does not falsely reject the next event. The oracle listeners are explicitly global so pre-commit staging and post-commit application keep the same audience even if the plugin is mounted under a scoped context; their cleanup still belongs to that mounting fiber. The plugin has no configuration.
+The standard agent spine mounts the service and its four core stateful companions. Custom compositions explicitly add companions for other loaded packages whose contracts they want checked; filters can disable or select registrations without changing package entrypoints.
-## Invariants asserted
-
-Session log (per session):
-
-- **`seq` strictly increases** — the spine of replay equivalence.
-- **turns pair and nest** — `turn/start` opens a turn, `turn/end` closes the matching one; no overlapping turns.
-- **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.
-- **an appended `tool/result` needs a prior `tool/call`** — fresh `surfaceOp: 'append'` results name the open step and consume its pending call. A Session-validated replacement is a turn-enclosed rewrite, not another execution. A `tool/call` may still have no result when the execution pipeline throws.
-
-Agent status (per agent):
-
-- **legal transitions only** — `idle↔running` and `(idle|running)→disposed`. A no-op transition (`setStatus` dedups, so it never fires) and leaving the terminal `disposed` state are violations.
-
-Model requests (on `llm/stream`):
-
-- **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 Agent Note](../../../.agents/notes/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'`).
-
-## Why runtime assertions remain useful
-
-Session enforces the per-record storage boundary at runtime, where a cast cannot bypass it. Pervasive `DeepReadonly` types would add noise across consumers without expressing relationships such as turn/step nesting, subject-correct scoped dispatch, or equality between a request and its log reconstruction. This plugin checks those relationships wherever it is mounted while `dsh-session` keeps history immutable in every composition. See [source-owned session immutability and dev-mode invariants](../../../.agents/notes/implemented/architecture/2026-06-11-dev-invariants-over-deep-readonly.md).
-
-## Seeded sessions
-
-A seeded or forked session arrives with events already in its log because construction does not emit `session/event` for each seed record. `Session` validates, snapshots, and freezes every seed record before accepting it; on `session/created`, this plugin replays the accepted log only to rebuild and check its relational trace state.
+Every ordinary Vitest topology mounts an explicitly enabled service and the current test package's companion. Focused suites cover valid and invalid observations for executable companions, while one exhaustive topology mounts all companions to prove registration and disposal wiring.
## Model Experience
-None, as this observer only validates events and frozen requests and never rewrites prompts, schemas, messages, or streams.
+None, as the service and companions observe runtime events and mutable snapshots without altering prompts, messages, schemas, streams, or tool results.
#### KV Cache effect
-None; this package neither assembles nor sends a provider request.
+None; invariant checks do not assemble or send provider requests.
## Known Limitations and Deferred Work
-- **The request-reconstructability assertion covers loop-built requests only** — hand-built one-shots (e.g. compaction's summarize call) carry no live `sessionId` marker and are skipped.
-- **Merge-extended event families get no family-specific assertions** — `compact/*` lock pairing and `hook/*` invoked/result pairing are not checked here; only the core turn/step/chunk/tool-result contract is.
+- Request reconstruction covers requests explicitly marked by the loop before freezing; direct one-shot LLM calls remain outside that marker contract even when callers freeze them or attach a session id.
+- Live-only lifecycle companions cannot reconstruct operations that began before their own reload. Standard and test compositions mount them before the corresponding operations begin.
+- Regular-expression filters are fixed for the service lifetime; changing them requires ordinary Cordis plugin reload.
diff --git a/packages/support/invariants/package.json b/packages/support/invariants/package.json
index 9ca1e0aab1..d52dd0a14d 100644
--- a/packages/support/invariants/package.json
+++ b/packages/support/invariants/package.json
@@ -1,6 +1,6 @@
{
"name": "@deepseek-ai/dsh-invariants",
- "description": "Runtime event-contract assertions for DeepSeek Harness development diagnostics",
+ "description": "Registry service for package-owned DeepSeek Harness runtime invariants",
"version": "0.0.1",
"private": true,
"type": "module",
@@ -11,33 +11,28 @@
"types": "./lib/types/index.d.ts",
"default": "./lib/index.js"
},
+ "./invariant": {
+ "types": "./lib/types/invariant.d.ts",
+ "default": "./lib/invariant.js"
+ },
"./src/*": "./src/*",
"./package.json": "./package.json"
},
"files": [
"lib/index.js",
+ "lib/invariant.js",
"lib/types/**/*.d.ts",
"lib/types/**/*.d.ts.map",
"src"
],
"license": "BSD-3-Clause",
"peerDependencies": {
- "@deepseek-ai/dsh-agent": "^0.0.1",
- "@deepseek-ai/dsh-llm": "^0.0.1",
- "@deepseek-ai/dsh-scope": "^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-agent": "workspace:^",
- "@deepseek-ai/dsh-goal": "workspace:^",
- "@deepseek-ai/dsh-llm": "workspace:^",
- "@deepseek-ai/dsh-scope": "workspace:^",
- "@deepseek-ai/dsh-session": "workspace:^",
- "@deepseek-ai/dsh-subagent": "workspace:^",
- "@deepseek-ai/dsh-system-prompt": "workspace:^",
- "@deepseek-ai/dsh-tools": "workspace:^",
- "@deepseek-ai/dsh-user-approval": "workspace:^",
"cordis": "^4.0.0-rc.7"
}
}
diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts
index 91b4da4566..2e6194b59b 100644
--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -1,419 +1,200 @@
/**
- * Runtime listeners that fail loudly when cross-event contracts are broken:
- * turn and step nesting, scoped dispatch, status transitions, and request
- * reconstruction. The plugin has no environment guard and is active wherever
- * mounted, including the default `dsh-agent-spine-demo` bundle; custom compositions
- * may omit it. Sessions own immutable, surface-valid event storage; this plugin
- * checks only relationships that event acceptance cannot express.
+ * Configurable registry for package-owned runtime invariant contributions.
+ * Every workspace package registers checks from a `./invariant` companion;
+ * ordinary package entrypoints stay independent of diagnostics.
+ *
* @module @deepseek-ai/dsh-invariants
*/
-import type { Context } from 'cordis'
-import { carrierKeyOf, isScopeCarrier } from '@deepseek-ai/dsh-scope'
-import { assertNever, HarnessError } from '@deepseek-ai/dsh-llm'
-import type { CallId, GenerateOptions } from '@deepseek-ai/dsh-llm'
-import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
-import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
-import type { SessionEvent } from '@deepseek-ai/dsh-session'
-import { scopedSubjectResolverFor } from './scoped-events.generated.ts'
+import { Context, Service } from 'cordis'
+import type { Inject } from 'cordis'
+import z from 'schemastery'
+import type Schema from 'schemastery'
-export const name = 'invariants'
-export const inject = ['sessions']
-
-/**
- * Thrown when a harness event-contract invariant is violated. Extends
- * {@link HarnessError} (`code: 'INVARIANT'`) so a violation is routable like
- * any other harness failure.
- */
-export class InvariantError extends HarnessError {
- constructor(message: string) {
- super(`invariant violated: ${message}`, 'INVARIANT')
- this.name = 'InvariantError'
- }
+/** Runtime invariant selection configured on the service plugin. */
+export interface Config {
+ /** Global switch; defaults to `true`. */
+ readonly enabled?: boolean
+ /** Case-sensitive JavaScript regex sources that admit package names; empty admits all. */
+ readonly package_allowlist?: string[]
+ /** Case-sensitive JavaScript regex sources that exclude package names after allowlist matching. */
+ readonly package_blocklist?: string[]
}
-/** Per-session bookkeeping for the session-log invariants. */
-interface SessionTrace {
- /** Highest `seq` seen so far (must strictly increase). */
- lastSeq: number
- /** Open turn number, or null between turns. */
- openTurn: number | null
- /** Open step within the current turn, or null between steps. */
- openStep: number | null
- /** The next turn number expected in this session log. */
- nextTurn: number
- /** The next step number expected within the open turn. */
- nextStep: number
+/**
+ * Throw a package-attributed invariant failure.
+ * @param message - violated package contract without the standard prefix.
+ * @returns never because reporting a violation throws.
+ */
+export type InvariantFailure = (message: string) => never
+
+/** Install one package's checks into the registration's child context. */
+export interface InvariantInstaller {
/**
- * Tool-call ids issued in the OPEN step awaiting a result. Cleared at
- * `step/end` — a result must arrive in the same step as its call.
+ * Install the package contribution.
+ * @param ctx - child context owned by this invariant registration.
+ * @param fail - reporter bound to the registering package name.
+ * @returns nothing, or a promise settling after asynchronous checks finish.
*/
- pendingCalls: Set
+ (ctx: Context, fail: InvariantFailure): void | Promise
+ /** Services the child installer fiber may access. */
+ readonly inject?: Inject
}
-/** One accepted event's deferred mutation of a live session trace. */
-interface SessionTraceTransition {
- /** Scalar state after the event commits. */
- scalars: Pick
- /** The event's mutation of the open step's pending call set. */
- pendingCalls:
- | { kind: 'none' }
- | { kind: 'add' | 'delete'; callId: CallId }
- | { kind: 'clear' }
+/** Internal effect shape used to join child startup before a companion loads. */
+interface PendingInvariantRegistration extends PromiseLike<() => void> {
+ (): void | Promise
}
-/** Assert that a step-scoped event names the currently open turn and step. */
-function requireOpenStep(trace: SessionTrace, kind: string, turn: number, step: number): void {
- if (trace.openTurn !== turn || trace.openStep !== step) {
- throw new InvariantError(
- `${kind} names turn ${turn}/step ${step} but open is turn ${trace.openTurn}/step ${trace.openStep}`,
- )
+/** Thrown when a package-owned runtime invariant is violated. */
+export class InvariantError extends Error {
+ /** Stable machine-readable invariant failure code. */
+ readonly code = 'INVARIANT' as const
+ /** Full npm package name that owns the violated invariant. */
+ readonly packageName: string
+
+ /**
+ * Construct a package-attributed invariant failure.
+ * @param packageName - full npm package name that registered the check.
+ * @param message - violated contract, without the standard error prefix.
+ */
+ constructor(packageName: string, message: string) {
+ super(`invariant violated by "${packageName}": ${message}`)
+ this.name = 'InvariantError'
+ this.packageName = packageName
}
}
-/** Validate one candidate event without mutating the committed session trace. */
-function validateEvent(trace: SessionTrace, event: SessionEvent): SessionTraceTransition {
- // seq is strictly monotonic — the spine of replay equivalence. lastSeq
- // starts at -1, so the first event (seq 0) passes.
- if (event.seq <= trace.lastSeq) {
- throw new InvariantError(`seq must strictly increase: saw ${event.seq} after ${trace.lastSeq}`)
- }
- let openTurn = trace.openTurn
- let openStep = trace.openStep
- let nextTurn = trace.nextTurn
- let nextStep = trace.nextStep
- let pendingCalls: SessionTraceTransition['pendingCalls'] = { kind: 'none' }
-
- // Boundary/step-scoped events have explicit cases; every OTHER event type —
- // including plugin-added (merge-extensible) SessionEventMap keys — is caught
- // by the `default` and must be turn-enclosed (the turn-enclosure Agent Note). No assertNever: an
- // unknown variant is valid, not a compile error.
- switch (event.type) {
- case 'turn/start': {
- if (trace.openTurn !== null) {
- throw new InvariantError(`turn/start ${event.data.turn} while turn ${trace.openTurn} is still open`)
- }
- // Current sessions replay full logs, so numbering starts at 1 and remains
- // contiguous. If a future compaction/fork stores a partial log, it must
- // seed `nextTurn` from retained metadata before this check runs.
- if (event.data.turn !== trace.nextTurn) {
- throw new InvariantError(`turn/start expected turn ${trace.nextTurn}, got ${event.data.turn}`)
- }
- openTurn = event.data.turn
- nextStep = 1
- break
- }
- case 'turn/end': {
- if (trace.openTurn !== event.data.turn) {
- throw new InvariantError(`turn/end ${event.data.turn} does not match open turn ${trace.openTurn}`)
- }
- if (trace.openStep !== null) {
- throw new InvariantError(`turn/end ${event.data.turn} while step ${trace.openStep} is still open`)
- }
- openTurn = null
- nextTurn += 1
- break
- }
- case 'step/start': {
- if (trace.openTurn !== event.data.turn) {
- throw new InvariantError(`step/start in turn ${event.data.turn} but open turn is ${trace.openTurn}`)
- }
- if (trace.openStep !== null) {
- throw new InvariantError(`step/start ${event.data.step} while step ${trace.openStep} is still open`)
- }
- // Steps are checked under the same full-log assumption as turns above.
- if (event.data.step !== trace.nextStep) {
- throw new InvariantError(`step/start expected step ${trace.nextStep} in turn ${event.data.turn}, got ${event.data.step}`)
- }
- openStep = event.data.step
- break
- }
- case 'step/end': {
- requireOpenStep(trace, 'step/end', event.data.turn, event.data.step)
- // A result must arrive in the step that issued the call; orphan calls
- // (a step that errored before its result) do not carry to the next step.
- pendingCalls = { kind: 'clear' }
- openStep = null
- nextStep += 1
- break
- }
- case 'assistant/chunk': {
- requireOpenStep(trace, 'assistant/chunk', event.data.turn, event.data.step)
- break
- }
- case 'assistant/message': {
- requireOpenStep(trace, 'assistant/message', event.data.turn, event.data.step)
- break
- }
- case 'tool/call': {
- requireOpenStep(trace, 'tool/call', event.data.turn, event.data.step)
- pendingCalls = { kind: 'add', callId: event.data.callId }
- break
- }
- case 'tool/result': {
- // Session has already validated a provenance-backed content rewrite.
- // It is durable turn work, not a second execution of the original call.
- if (event.surfaceOp !== 'append') {
- if (trace.openTurn === null) {
- throw new InvariantError(
- 'tool/result surface replacement appended outside any open turn',
- )
- }
- break
- }
- requireOpenStep(trace, 'tool/result', event.data.turn, event.data.step)
- // A result needs a prior matching call in the same step. (The converse
- // does NOT hold: a call may have no result — a throwing tool-execution
- // pipeline step ends the turn with no tool/result, which is legal.)
- const syntheticInterrupted = event.data.isError && event.data.error?.code === 'interrupted'
- if (!trace.pendingCalls.has(event.data.callId) && !syntheticInterrupted) {
- throw new InvariantError(`tool/result for ${event.data.callId} with no prior tool/call in this step`)
- }
- pendingCalls = { kind: 'delete', callId: event.data.callId }
- break
- }
- // Turn-enclosure (the turn-enclosure Agent Note): EVERY session event not handled by a boundary
- // case above must sit inside an open turn. The durable session log uses the
- // turn as its commit/replay boundary (the JSONL backend treats anything
- // after the last turn/end as a crash tail), so a bare event between turns is
- // silently dropped on reload. The loop records queued user messages after
- // turn/start, and an idle agent.inject() wraps its context/message in a
- // one-shot turn. A `default`
- // (not an enumerated list) is deliberate: SessionEventMap is
- // merge-extensible, so a PLUGIN-added event type appended while idle must
- // also fail here rather than fall through and be dropped on resume.
- default: {
- if (trace.openTurn === null) {
- throw new InvariantError(`${event.type} appended outside any open turn (every event must be turn-enclosed)`)
- }
- break
- }
- }
- return {
- scalars: { lastSeq: event.seq, openTurn, openStep, nextTurn, nextStep },
- pendingCalls,
+declare module 'cordis' {
+ interface Context {
+ invariants: InvariantService
}
}
-/** Apply one already-validated transition after its event commits. */
-function applyTransition(trace: SessionTrace, transition: SessionTraceTransition): void {
- Object.assign(trace, transition.scalars)
- switch (transition.pendingCalls.kind) {
- case 'none':
- break
- case 'add':
- trace.pendingCalls.add(transition.pendingCalls.callId)
- break
- case 'delete':
- trace.pendingCalls.delete(transition.pendingCalls.callId)
- break
- case 'clear':
- trace.pendingCalls.clear()
- break
- /* v8 ignore next -- validateEvent produces this closed transition union */
- default:
- assertNever(transition.pendingCalls, 'session trace pending-call transition')
- }
+/** Compile and validate one package-filter list. */
+function compilePatterns(field: 'package_allowlist' | 'package_blocklist', values: readonly string[]): RegExp[] {
+ const seen = new Set()
+ return values.map((value) => {
+ if (value.length === 0 || value.trim() !== value) {
+ throw new Error(`invariants: ${field} entries must be non-blank and have no surrounding whitespace`)
+ }
+ if (seen.has(value)) {
+ throw new Error(`invariants: ${field} contains duplicate regex ${JSON.stringify(value)}`)
+ }
+ seen.add(value)
+ try {
+ return new RegExp(value)
+ } catch (cause) {
+ throw new Error(`invariants: ${field} contains invalid regex ${JSON.stringify(value)}`, { cause })
+ }
+ })
}
-/** Validate and apply one event while rebuilding an already-committed log. */
-function replayEvent(trace: SessionTrace, event: SessionEvent): void {
- applyTransition(trace, validateEvent(trace, event))
-}
-
-/** Allow an initial observation, idle/running transitions, and terminal disposal; reject repeats and leaving disposed. */
-function checkTransition(from: AgentStatus | undefined, to: AgentStatus): void {
- if (from === undefined) return
- if (from === to) {
- throw new InvariantError(`agent/status repeated ${to} (no-op transition)`)
- }
- if (from === 'disposed') {
- throw new InvariantError(`agent/status left terminal state disposed → ${to}`)
- }
-}
-
-/**
- * Register the runtime invariants. Contributions are effect-scoped, so
- * disposing the plugin fiber removes all listeners (HMR-safe). On (re-)apply
- * the trace state is rebuilt by replaying each existing session's log, so a
- * hot reload mid-turn does not falsely reject the next event.
- *
- * @param ctx - Cordis context that receives the invariant listeners.
- */
-export function apply(ctx: Context): void {
- const traces = new WeakMap()
- const stagedTransitions = new WeakMap()
- // Agent status has no stored history to replay; the first observation after
- // (re-)apply seeds the baseline, so a reload never produces a false positive.
- const lastStatus = new WeakMap()
-
- const freshTrace = (): SessionTrace => ({
- lastSeq: -1,
- openTurn: null,
- openStep: null,
- nextTurn: 1,
- nextStep: 1,
- pendingCalls: new Set(),
+/** Package-owned invariant registry with global and regex-based selection. */
+export class InvariantService extends Service {
+ static Config: Schema = z.object({
+ enabled: z.boolean().default(true),
+ package_allowlist: z.array(z.string()).default([]),
+ package_blocklist: z.array(z.string()).default([]),
})
- /** Build (or rebuild) a session's trace by replaying its whole log. */
- const seedSession = (session: Session): SessionTrace => {
- const trace = freshTrace()
- traces.set(session, trace)
- for (const event of session.events) {
- replayEvent(trace, event)
- }
- return trace
+ private readonly enabled: boolean
+ private readonly ownerCtx: Context
+ private readonly packageAllowlist: readonly RegExp[]
+ private readonly packageBlocklist: readonly RegExp[]
+ private readonly registrations = new Set()
+
+ /**
+ * Create and install the invariant registry.
+ * @param ctx - Cordis context that owns the service.
+ * @param config - global enablement and package-name regex filters.
+ */
+ constructor(ctx: Context, config: Config = {}) {
+ super(ctx, 'invariants')
+ this.ownerCtx = ctx
+ this.enabled = config.enabled ?? true
+ this.packageAllowlist = compilePatterns('package_allowlist', config.package_allowlist ?? [])
+ this.packageBlocklist = compilePatterns('package_blocklist', config.package_blocklist ?? [])
}
- // Every store-created session (the only kind that emits session/event) is
- // seeded first — via ctx.sessions.list() at apply or session/created — so the
- // fallback is a defensive guard, never hit in practice.
- /* v8 ignore next -- traceFor's fallback: session/event always follows a seed */
- const traceFor = (session: Session): SessionTrace => traces.get(session) ?? seedSession(session)
+ /** Return whether one full package name passes the configured filters. */
+ private selected(packageName: string): boolean {
+ if (!this.enabled) return false
+ if (this.packageAllowlist.length > 0
+ && !this.packageAllowlist.some(pattern => pattern.test(packageName))) return false
+ return !this.packageBlocklist.some(pattern => pattern.test(packageName))
+ }
- // Rebuild state for sessions that already exist at (re-)apply time — HMR
- // reload starts a fresh fiber, and a mid-turn session would otherwise look
- // like it began with a stray chunk/step-end.
- for (const session of ctx.sessions.list()) seedSession(session)
-
- // A newly created session may arrive seeded/forked (the constructor copies
- // the seed WITHOUT emitting session/event), so replay its log here too.
- ctx.on('session/created', (session) => { seedSession(session) }, { global: true })
-
- ctx.on('session/event', (session, event) => {
- // Session resolves dispatch before committing, so internal/dispatch has
- // already staged this exact event. A later dispatch veto skips every
- // session/event callback and therefore leaves the live trace unchanged.
- const staged = stagedTransitions.get(event)
- /* v8 ignore next 2 -- internal/dispatch stages the exact callback arguments */
- if (staged === undefined || staged.session !== session) {
- throw new InvariantError('session/event reached publication without matching pre-commit validation')
+ /**
+ * Register one package's invariant installer. The package name is reserved
+ * even when filtering disables its checks. Enabled installers run in a child
+ * fiber; failure disposes that fiber and releases the reservation.
+ * @param packageName - full npm package name that owns the contribution.
+ * @param installer - listener or startup-check installer for the child context.
+ * @returns an effect-scoped disposer for the registration.
+ */
+ register(packageName: string, installer: InvariantInstaller): () => void {
+ if (packageName.length === 0 || packageName.trim() !== packageName || /\s/.test(packageName)) {
+ throw new Error('invariants: packageName must be non-blank and contain no whitespace')
}
- stagedTransitions.delete(event)
- applyTransition(staged.trace, staged.transition)
- }, { global: true })
-
- ctx.on('agent/status', (agent, status) => {
- checkTransition(lastStatus.get(agent), status)
- lastStatus.set(agent, status)
- }, { global: true })
-
- // --- Scoped-dispatch invariants (the agent-scoping seam) ---------------
- //
- // Every scope-filtered event family must dispatch with a scope carrier
- // (scopeTarget) whose key IS the subject the event's arguments name —
- // a dispatch without one silently reverts that event to global delivery
- // (agent-scoped listeners over-hear foreign agents), and a mis-keyed one
- // delivers to the wrong agent's listeners. `internal/dispatch` fires
- // synchronously before listener delivery, so a violation throws at the
- // dispatching call site. The generated table maps each family to the unique
- // payload path whose Program type matches the real scopeTarget routing key;
- // `null` means the key is external to the payload, so only carrier presence
- // can be asserted.
- ctx.on('internal/dispatch', (_mode, name, args, thisArg) => {
- const subjectOf = scopedSubjectResolverFor(name)
- if (subjectOf === undefined) return
- if (!isScopeCarrier(thisArg)) {
- throw new InvariantError(
- `"${name}" is a scope-filtered event but was dispatched without a scope carrier — `
- + 'pass scopeTarget(base, subject) as the dispatch thisArg (agent events: use agentEvents(ctx, agent))')
- }
- if (subjectOf !== null && carrierKeyOf(thisArg) !== subjectOf(args)) {
- throw new InvariantError(
- `"${name}" was dispatched with a scope carrier keyed to a DIFFERENT subject than its arguments name — `
- + 'the carrier key and the event\'s subject must be the same object (use agentEvents(ctx, agent))')
- }
- if (name === 'session/event') {
- const [session, event] = args as [Session, SessionEvent]
- const trace = traceFor(session)
- const transition = validateEvent(trace, event)
- // The exact event identity reaches the contained post-commit listener.
- // A later internal/dispatch listener may still veto; because validation
- // is pure, abandoning this weakly keyed transition does not advance the
- // committed trace or retain the session.
- stagedTransitions.set(event, { session, trace, transition })
- }
- }, { global: true })
-
- // Request-reconstruction cross-check (the reconstructability Agent Note): a
- // loop-built request — frozen envelope + live sessionId is the marker; a
- // hand-built one-shot (compaction summarize) is unfrozen and skipped — must
- // be EXACTLY what the session log reconstructs:
- //
- // - messages: the folded header's session prefix (messagePrefix — the
- // `agent/session-prefix` product, logged on the header because no
- // session event carries it) followed by the
- // derivation over the log prefix strictly before the in-flight step's
- // `step/start` (the reconstruction boundary). The derivation is compared
- // against a FRESH Session built over that prefix — the same projection
- // code with zero shared state, so the live cache under test cannot vouch
- // for itself. Boundary-correct by construction: content appended after
- // 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
- // dispatch, so the fold already covers this request.
- //
- // Registered with `prepend: true` so a short-circuiting llm/stream listener
- // (the replay adapter returns its chunks without calling next()) cannot
- // silence the check by registering first. Prepend beats APPEND-registered
- // listeners only — two prepended listeners have no defined mutual order
- // (cordis unshift) — which is fine: correctness rests on the seq-bounded
- // fold below, never on listener timing.
- ctx.on('llm/stream', (options: GenerateOptions, next) => {
- if (options.sessionId === undefined || !Object.isFrozen(options)) return next()
- // GenerateOptions types sessionId as Branded<'SessionId'>, which IS
- // SessionId (dsh-llm cannot import it without a cycle) — no cast needed.
- const session = ctx.sessions.get(options.sessionId)
- if (!session) return next()
- if (!Object.isFrozen(options.messages)) {
- throw new InvariantError('a loop-built request must carry a frozen messages array')
+ if (this.registrations.has(packageName)) {
+ throw new Error(`invariants: package "${packageName}" is already registered`)
}
- const events = session.events
- // seq === index (checked above), so the last step/start's seq bounds the
- // prefix directly. The in-flight step's step/start is necessarily the
- // last one: the loop cannot open another step while this call streams.
- let boundary = -1
- for (let i = events.length - 1; i >= 0; i -= 1) {
- if (events[i]?.type === 'step/start') {
- boundary = i
- break
- }
- }
- if (boundary === -1) {
- throw new InvariantError('a loop-built request with no step/start in its session log')
- }
- const header = foldRequestHeader(events)
- if (header === undefined) {
- throw new InvariantError('a loop-built request with no request/header event in its session log')
- }
- const rebuilt = new Session(SessionId(`${String(session.id)}-invariant-rebuild`), structuredClone(events.slice(0, boundary)))
- // The reconstruction equation: the folded header's session prefix, then
- // the boundary derivation — the loop
- // logs the header event BEFORE dispatch, so the fold already covers this
- // request's prefix. JSON equality is sound here: both sides are
- // structuredClones produced by the same projection/build code path, so key
- // insertion order matches when the values do.
- const expected = [...header.messagePrefix ?? [], ...rebuilt.deriveMessages()]
- if (JSON.stringify(options.messages) !== JSON.stringify(expected)) {
- throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the boundary derivation (log-reconstruction desync)`)
- }
+ // Service method tracing binds `this.ctx` to the caller. This explicit
+ // origin keeps registrations and their child fibers owned by the service;
+ // companion disposal is covered independently by the returned disposer.
+ const ctx = this.ownerCtx
+ const registrations = this.registrations
+ registrations.add(packageName)
- const headerMatches = options.model === header.config.model
- && options.system === header.system
- && options.temperature === header.config.temperature
- && options.maxTokens === header.config.maxTokens
- && JSON.stringify(options.stop) === JSON.stringify(header.config.stop)
- && JSON.stringify(options.tools ?? []) === JSON.stringify(header.tools ?? [])
- if (!headerMatches) {
- throw new InvariantError(`llm request for session "${String(session.id)}" diverges from the folded request header`)
+ let registration: PendingInvariantRegistration
+ try {
+ registration = ctx.effect(async () => {
+ if (!this.selected(packageName)) {
+ return () => {
+ registrations.delete(packageName)
+ }
+ }
+
+ const installInvariant = (childCtx: Context) => (
+ installer(childCtx, (message): never => {
+ throw new InvariantError(packageName, message)
+ })
+ )
+ try {
+ const child = ctx.plugin(installer.inject === undefined
+ ? installInvariant
+ : Object.assign(installInvariant, { inject: installer.inject }))
+
+ try {
+ await child
+ } catch (error) {
+ await child.dispose()
+ throw error
+ }
+
+ return async () => {
+ try {
+ await child.dispose()
+ } finally {
+ registrations.delete(packageName)
+ }
+ }
+ } catch (error) {
+ registrations.delete(packageName)
+ throw error
+ }
+ }, `invariants.register(${JSON.stringify(packageName)})`)
+ } catch (error) {
+ registrations.delete(packageName)
+ throw error
}
- return next()
- }, { global: true, prepend: true })
+ // Cordis attaches setup thenability and async teardown to this callable;
+ // the service seam intentionally exposes only the conventional disposer.
+ // eslint-disable-next-line @typescript-eslint/no-misused-promises -- the extra runtime shape stays private.
+ return registration
+ }
}
+
+export default InvariantService
diff --git a/packages/support/invariants/src/invariant.ts b/packages/support/invariants/src/invariant.ts
new file mode 100644
index 0000000000..7780e987f5
--- /dev/null
+++ b/packages/support/invariants/src/invariant.ts
@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-invariants`.
+ * @module @deepseek-ai/dsh-invariants/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from './index.ts'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-invariants'
+
+/** Cordis companion plugin name. */
+export const name = 'invariants-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: registration ownership and child lifecycle are the service's mutation
+ * boundary itself; observing them from the same registry would only duplicate its implementation.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+ Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */
diff --git a/packages/support/invariants/src/scoped-events.generated.ts b/packages/support/invariants/src/scoped-events.generated.ts
deleted file mode 100644
index a007ab4174..0000000000
--- a/packages/support/invariants/src/scoped-events.generated.ts
+++ /dev/null
@@ -1,74 +0,0 @@
-/**
- * Generated scoped-event routing-subject resolvers for dsh-invariants.
- * Do not edit by hand; run `pnpm run gen-scoped-events`.
- *
- * @module @deepseek-ai/dsh-invariants/scoped-events.generated
- */
-
-import type { Events } from 'cordis'
-import type { Scoped } from '@deepseek-ai/dsh-scope'
-import type {} from '@deepseek-ai/dsh-agent'
-import type {} from '@deepseek-ai/dsh-goal'
-import type {} from '@deepseek-ai/dsh-session'
-import type {} from '@deepseek-ai/dsh-subagent'
-import type {} from '@deepseek-ai/dsh-system-prompt'
-import type {} from '@deepseek-ai/dsh-tools'
-import type {} from '@deepseek-ai/dsh-user-approval'
-
-type ScopedEventName = {
- [K in keyof Events]: ThisParameterType extends Scoped