diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml index 7f14684d59..1939ff2f17 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.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 .agents/notes/implemented/architecture/2026-06-18-session-surface.md -2026-06-18-session-surface.md: 93ea55883dedd943fe1ffac67a9842c962ca6dac -2026-06-18-session-surface.zh.md: 54ecb1162bc46007dfcbb7d8cb39075d52171567 +2026-06-18-session-surface.md: 26780d54a1ea12283900572c6fd0e8f740de5524 +2026-06-18-session-surface.zh.md: 328a9ee9f1bed9c52996cfd307549a7745e16d4b 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 93ea55883d..26780d54a1 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.md +++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.md @@ -37,7 +37,7 @@ Delta processing is O(1) when no new events and O(new events) when new events ar ### Persistence -The fields are serialized as top-level JSON properties. JSONL preserves placement and provenance without a separate column mapping. The [V3 canonical-envelope decision](2026-09-06-v3-canonical-session-envelopes.md) owns exact replacement keys and strict-acceptance rationale; the [V2-to-V3 specification](../../../../packages/session/session-format-v2-to-v3/README.md#canonical-envelopes) owns historical conversion. This note retains ordered-projection ownership and replacement rationale. +The fields are serialized as top-level JSON properties. JSONL preserves placement and source-event references without a separate column mapping. The [V3 canonical-envelope decision](2026-09-06-v3-canonical-session-envelopes.md) owns exact replacement keys and strict-acceptance rationale; the [V2-to-V3 specification](../../../../packages/session/session-format-v2-to-v3/README.md#canonical-envelopes) owns historical conversion. This note retains ordered-projection ownership and replacement rationale. ### Crash recovery diff --git a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md index 54ecb1162b..328a9ee9f1 100644 --- a/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md +++ b/.agents/notes/implemented/architecture/2026-06-18-session-surface.zh.md @@ -37,7 +37,7 @@ surface 元数据仅属于四种 surface 事件类型(`system/message`、`user ### 持久化 -这些字段作为顶层 JSON 属性序列化。JSONL 无需单独列映射即可保留位置与来源。[V3 规范信封决策](2026-09-06-v3-canonical-session-envelopes.zh.md)负责精确替换键与严格准入依据;[V2 到 V3 规范](../../../../packages/session/session-format-v2-to-v3/README.zh.md#canonical-envelopes)负责历史转换。本文继续负责有序投影的所有权与替换依据。 +这些字段作为顶层 JSON 属性序列化。JSONL 无需单独列映射即可保留位置与源事件引用。[V3 规范信封决策](2026-09-06-v3-canonical-session-envelopes.zh.md)负责精确替换键与严格准入依据;[V2 到 V3 规范](../../../../packages/session/session-format-v2-to-v3/README.zh.md#canonical-envelopes)负责历史转换。本文继续负责有序投影的所有权与替换依据。 ### 崩溃恢复 diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml index 9f08a92826..ac7f2acd4e 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.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 .agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md -2026-07-05-reconstructable-requests.md: 2f88675a75a72e7fbf105dfbf4f337a4dd80948a -2026-07-05-reconstructable-requests.zh.md: 90008502a6651e38c142b7fb88052c05d46dea76 +2026-07-05-reconstructable-requests.md: f47d0938b91edf6c9b544223ac44925f02dd8c1f +2026-07-05-reconstructable-requests.zh.md: d2499a6264a3e6bebf31944d8eb056265e082c68 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 2f88675a75..f47d0938b9 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.md @@ -22,9 +22,9 @@ Prefix-cache stability is corollary #1, not the headline: an append-only log pro **Messages.** `Session.deriveMessages()` is cached: each surface entry is projected exactly once, when first seen, through the public per-event function `deriveEventMessage(event)`; a surface rewrite (a compaction `replace` — `SurfaceManager.replaceGeneration`) rebuilds. Callers get a fresh array per call over shared, deep-frozen messages: mutating logged history through a projection is unrepresentable (it throws), replacing the old clone-per-call isolation. External reconstructors fold the same public function over a log prefix, so no two paths can disagree. -`EpochHeader` records the request's non-history state: call config and tool schemas. Writers omit `tools: []` and `adapterDefaults: {}`; current acceptance rejects those fields and any `header.system`, rather than repairing them. Whitespace-only system-message content, `config.stop: []`, and nested extensions remain intact. The [V3 canonical-envelope decision](2026-09-06-v3-canonical-session-envelopes.md) owns historical conversion. The rendered system prompt is derived history — the `system/message` event at surface node 0, per the [surface-node Agent Note](2026-09-02-system-prompt-as-surface-node.md) — so a prompt change is a surface replacement rather than a header change. Adapter-supplied effort and token defaults retain their `adapterDefaults` provenance; a Web model selection restored from the log omits an adapter-owned effort so the next resolution cannot reclassify the same effective config as an explicit selection and a false change. `request/header` always writes a full snapshot: the first loop instance uses reason `initial`, later instances use `resume`, an in-instance change uses `change`, and an unchanged envelope beginning an explicitly declared message series or following a surface replacement uses `series`. A `change` snapshot carries `startsSeries: true` when the changed request also starts a series, preserving the two independent facts without a duplicate header. Ordinary append-only later Turns, further same-series Steps, and retries inherit the latest snapshot. `foldRequestHeader` selects the latest snapshot. Legacy `request/header-delta` events and the removed `fallback` reason are rejected when appended or loaded. +`EpochHeader` records the request's non-history state: call config and tool schemas. Writers omit `tools: []` and `adapterDefaults: {}`; current acceptance rejects those fields and any `header.system`, rather than repairing them. Whitespace-only system-message content, `config.stop: []`, and nested extensions remain intact. The [V3 canonical-envelope decision](2026-09-06-v3-canonical-session-envelopes.md) owns historical conversion. The rendered system prompt is derived history — the `system/message` event at surface node 0, per the [surface-node Agent Note](2026-09-02-system-prompt-as-surface-node.md) — so a prompt change is a surface replacement rather than a header change. Adapter-supplied effort and token defaults retain their `adapterDefaults` ownership; a Web model selection restored from the log omits an adapter-owned effort so the next resolution cannot reclassify the same effective config as an explicit selection and a false change. `request/header` always writes a full snapshot: the first loop instance uses reason `initial`, later instances use `resume`, an in-instance change uses `change`, and an unchanged envelope beginning an explicitly declared message series or following a surface replacement uses `series`. A `change` snapshot carries `startsSeries: true` when the changed request also starts a series, preserving the two independent facts without a duplicate header. Ordinary append-only later Turns, further same-series Steps, and retries inherit the latest snapshot. `foldRequestHeader` selects the latest snapshot. Legacy `request/header-delta` events and the removed `fallback` reason are rejected when appended or loaded. -Each proposed step first claims its inbox batch, assembles the system prompt and tools, projects the rendered prompt against the surviving `system/message` node, and runs `agent/pre-step`. Rejection opens no step; enter opens `step/start`, commits a changed prompt as the `system/message` append or node-0 replacement, records the final message batch as `user/message` events, and may use `startsRequestSeries: true` to declare a distinct series. `agent/request` may replace only the frozen call-config seed. The loop records the owed initial, resume, change, or series full snapshot, builds `GenerateOptions` from derived messages (system message first) and that header with no `system` field, and freezes it while leaving `AbortSignal` live. The [request-freeze provenance decision](../simplification/2026-09-06-agent-request-freeze-provenance.md) owns reuse of completed message freezes and per-request local header freezing. The first call config starts from explicit `AgentOptions`, preserving fork overrides and resume reconfiguration; later calls start from the folded header. +Each proposed step first claims its inbox batch, assembles the system prompt and tools, projects the rendered prompt against the surviving `system/message` node, and runs `agent/pre-step`. Rejection opens no step; enter opens `step/start`, commits a changed prompt as the `system/message` append or node-0 replacement, records the final message batch as `user/message` events, and may use `startsRequestSeries: true` to declare a distinct series. `agent/request` may replace only the frozen call-config seed. The loop records the owed initial, resume, change, or series full snapshot, builds `GenerateOptions` from derived messages (system message first) and that header with no `system` field, and freezes it while leaving `AbortSignal` live. The [request-freeze evidence decision](../simplification/2026-09-06-agent-request-freeze-evidence.md) owns reuse of completed message freezes and per-request local header freezing. The first call config starts from explicit `AgentOptions`, preserving fork overrides and resume reconfiguration; later calls start from the folded header. **The open step is the reconstruction boundary.** Its entered `user/message` batch and any newly written `request/header` precede request dispatch. Injection after the atomic claim joins a later request, while a listener that must affect this request returns messages through `agent/pre-step`. Header reconstruction selects the step's `request/header`, or carries the prior snapshot when no new header is written. diff --git a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md index 90008502a6..d2499a6264 100644 --- a/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md +++ b/.agents/notes/implemented/architecture/2026-07-05-reconstructable-requests.zh.md @@ -24,7 +24,7 @@ Status: implemented `EpochHeader` 记录请求的非历史状态:调用配置和工具 schema。写入方省略 `tools: []` 与 `adapterDefaults: {}`;当前接纳拒绝这些字段以及任何 `header.system`,而不修复它们。仅含空白的系统消息内容、`config.stop: []` 与嵌套扩展保持原样。[V3 规范信封决策](2026-09-06-v3-canonical-session-envelopes.zh.md)负责历史转换。渲染后的系统提示词是派生历史——surface 第 0 号节点上的 `system/message` 事件,见[surface 节点 Agent Note](2026-09-02-system-prompt-as-surface-node.zh.md)——因此提示词变更是 surface 替换而不是 header 变更。适配器提供的推理强度与 token 默认值会保留其 `adapterDefaults` 来源信息;Web 从日志恢复模型选择时会省略适配器持有的推理强度,因此下一次解析不会把相同的有效配置重新归类为显式选择并产生虚假变更。`request/header` 始终写入完整快照:首个循环实例使用 reason `initial`,后续实例使用 `resume`,实例内变更使用 `change`,内容未变的封装显式开启消息序列或跟随表层替换时使用 `series`。如果发生变化的请求同时开启序列,`change` 快照会携带 `startsSeries: true`,无需重复 header 即可保留这两个独立事实。普通的仅追加后续 Turn、同一序列内后续的 Step 与重试沿用最新快照。`foldRequestHeader` 选择最新快照。旧的 `request/header-delta` 事件和已移除的 `fallback` reason 在追加或加载时都会被拒绝。 -每个拟议步骤先领取其 inbox 批次,组装系统提示词与工具,把渲染后的提示词与存活的 `system/message` 节点比对投影,再运行 `agent/pre-step`。reject 不打开步骤;enter 打开 `step/start`,把变化的提示词作为 `system/message` 追加或第 0 号节点替换提交,把最终消息批次记录为 `user/message` 事件,并可使用 `startsRequestSeries: true` 声明独立序列。`agent/request` 只能替换冻结的调用配置种子。循环记录所需的 initial、resume、change 或 series 完整快照,从派生消息(系统消息在先)与该不含 `system` 字段的 header 构建 `GenerateOptions`,冻结请求但保持 `AbortSignal` 活跃。[请求冻结来源证明决策](../simplification/2026-09-06-agent-request-freeze-provenance.zh.md)拥有消息完整冻结的复用规则和每次请求的本地 header 冻结规则。首次调用配置从显式的 `AgentOptions` 出发,保留 fork 覆盖和恢复重配置;后续调用从折叠后的 header 出发。 +每个拟议步骤先领取其 inbox 批次,组装系统提示词与工具,把渲染后的提示词与存活的 `system/message` 节点比对投影,再运行 `agent/pre-step`。reject 不打开步骤;enter 打开 `step/start`,把变化的提示词作为 `system/message` 追加或第 0 号节点替换提交,把最终消息批次记录为 `user/message` 事件,并可使用 `startsRequestSeries: true` 声明独立序列。`agent/request` 只能替换冻结的调用配置种子。循环记录所需的 initial、resume、change 或 series 完整快照,从派生消息(系统消息在先)与该不含 `system` 字段的 header 构建 `GenerateOptions`,冻结请求但保持 `AbortSignal` 活跃。[请求冻结证据决策](../simplification/2026-09-06-agent-request-freeze-evidence.zh.md)拥有消息完整冻结的复用规则和每次请求的本地 header 冻结规则。首次调用配置从显式的 `AgentOptions` 出发,保留 fork 覆盖和恢复重配置;后续调用从折叠后的 header 出发。 **已打开步骤是重建边界。** 进入步骤的 `user/message` 批次与任何新写入的 `request/header` 都位于请求分派之前。原子领取后发生的注入加入后续请求;必须影响本次请求的监听器则通过 `agent/pre-step` 返回消息。header 重建选择该步骤的 `request/header`,或在无新 header 写入时沿用前一个快照。 diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml index 2522b59d89..072caec450 100644 --- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.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 .agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md -2026-07-08-tool-output-spill-files.md: a80b6cdcb0e731a687d511d38ea288a68a298173 +2026-07-08-tool-output-spill-files.md: fa6697aad63c97b0ef580fe1ca46e50541e3d682 2026-07-08-tool-output-spill-files.zh.md: a995eafc7878b342a2164c5116da1f43ada791a5 diff --git a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md index a80b6cdcb0..fa6697aad6 100644 --- a/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md +++ b/.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md @@ -22,7 +22,7 @@ A thin spill storage seam plus a default spill policy plugin, in a new `packages | `@deepseek-ai/dsh-spill-local` | Local backend: private, session-scoped file storage on the host filesystem. | | `@deepseek-ai/dsh-spill-policy` | Tool-result policy plugin: wraps final text results after dispatch and replaces oversized results with a retained preview plus a spill locator. | -The tool-result Consumer is `dsh-spill-policy`, which consumes final tool results through the `tools/post-execute` waterfall. The model follows the backend-supplied retrieval hint for the returned locator. [Session-reference spill reuse](../bug-fix/2026-09-05-session-reference-spill-reuse.md) adds a direct storage consumer with separate preview, provenance, and failure semantics; it does not change the tool-result policy. +The tool-result Consumer is `dsh-spill-policy`, which consumes final tool results through the `tools/post-execute` waterfall. The model follows the backend-supplied retrieval hint for the returned locator. [Session-reference spill reuse](../bug-fix/2026-09-05-session-reference-spill-reuse.md) adds a direct storage consumer with separate preview, source-description, and failure semantics; it does not change the tool-result policy. ### Spill seam diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml index f7987d80d7..003214c467 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.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 .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md -2026-07-10-single-file-executable-sdk-runtime-distribution.md: 8c55c142137f0ab24869bd57ffed3835b7b0516a +2026-07-10-single-file-executable-sdk-runtime-distribution.md: e8c38a7b96cbff9feae2271fcd9a5c41087c62c4 2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: 52ca2e13901d9469e2f9663936acb766a934e8f7 diff --git a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md index 8c55c14213..e8c38a7b96 100644 --- a/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md +++ b/.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md @@ -46,7 +46,7 @@ The deploy root includes `@deepseek-ai/dsh-mcp-client` as an explicitly supporte [`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-python-runtime-closure deploy --legacy --prod --config.allow-unused-patches=true --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/`, including [`python/sdk-runtime/runtime-bootstrap.mjs`](../../../../python/sdk-runtime/runtime-bootstrap.mjs) as the carrier-root `runtime-bootstrap.mjs` → restore direct workspace packages omitted by legacy deploy and reject any remaining manifest gap → replace staged dependency symlinks with their target bytes, remove package-manager `.bin` links, and fail if any symlink remains → verify the deployed bootstrap and inject pkg configuration with that bin plus assets covering dynamic profile, bundle, frontend, preset, native-library, and configuration reads → stage the target `node-pty` addon → invoke `pkg --sea` once per target → write `deepseek-harness-sdk-runtime--` under `dist-exe/` and copy it into the runtime directory. The Python runtime owns that bootstrap. It calls the public CLI export for ordinary launches and dispatches a provider-private selection to the same `@deepseek-ai/dsh-subprocess-local/runner` core without changing CLI grammar or adding another executable; the [native-containment decision](2026-08-28-subprocess-native-containment.md) owns that private path. Linux CI rebuilds `pty.node` inside the matching manylinux 2.28 container because legacy deploy omits that install side effect. Every target copies its native `@vscode/ripgrep` binary beside the executable as the required `-rg` sidecar; pkg runtimes select that sidecar through `process.pkg`, while ordinary Node execution uses `@vscode/ripgrep` directly. macOS uses its target prebuild and also emits the required `-spawn-helper`. The deploy flags preserve the measured runtime layout: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry. Production deployment permits unused workspace patches because development-only tools can be absent from its closure; included-package patch failures still fail deployment. Workspace installs retain strict unused-patch validation. -CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) runs [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) on Linux/Windows x64 for pull requests and Linux ARM64 plus both macOS architectures for master pushes. The [public publication workflow](../../archived/process/2026-08-11-python-publication-workflow.md) calls it for all five targets; `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / macos-x64 (`macos-15-intel`) / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, proves their package and executable provenance, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests and master pushes additionally run a real DeepSeek two-turn tool smoke on their selected targets; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS checks the runtime, ripgrep, and PTY helper architectures and verifies that all three deployment targets fit the wheel tag. A full five-target run retains six artifacts, each containing one release file: the platform-independent SDK wheel and five native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and five native runtime wheels, then a single serialized job checks and publishes all six to the project PyPI registry. The [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows target and the explicit exclusion of Windows arm64. +CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml) runs [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md) on Linux/Windows x64 for pull requests and Linux ARM64 plus both macOS architectures for master pushes. The [public publication workflow](../../archived/process/2026-08-11-python-publication-workflow.md) calls it for all five targets; `workflow_dispatch` can still select a subset. Native builds run on linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64 / macos-x64 (`macos-15-intel`) / win-x64 (`windows-2025`), with `~/.pkg-cache` cached where applicable, and pkg handles macOS ad-hoc signing. Each leg installs the release-shaped SDK and runtime wheels into a clean venv outside the checkout, verifies their package and executable origin, then drives the complete keyless scenario set through the public SDK and direct NDJSON JSON-RPC. Trusted pull requests and master pushes additionally run a real DeepSeek two-turn tool smoke on their selected targets; fork and Dependabot heads receive no key. Linux inspects the executable and native addon's GLIBC requirements and runs an additional manylinux 2.28 smoke, while macOS checks the runtime, ripgrep, and PTY helper architectures and verifies that all three deployment targets fit the wheel tag. A full five-target run retains six artifacts, each containing one release file: the platform-independent SDK wheel and five native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts `python-v` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and five native runtime wheels, then a single serialized job checks and publishes all six to the project PyPI registry. The [`python/sdk-runtime` README](../../../../python/sdk-runtime/README.md) owns the Windows target and the explicit exclusion of Windows arm64. ### Python SDK distribution: two carriers, exe for production, node for development diff --git a/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.i18n.yaml index 0642d7aaad..4830f124d8 100644 --- a/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.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 .agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md -2026-08-19-session-projection-mandatory-seam.md: 371faa254809649e93685a8f3ada3e640d5f391e +2026-08-19-session-projection-mandatory-seam.md: e1c6835311228fcaf7a22140f1db8da748603186 2026-08-19-session-projection-mandatory-seam.zh.md: 5d6a5169a556febae3f5c960b2d519c324d99863 diff --git a/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md b/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md index 371faa2548..e1c6835311 100644 --- a/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md +++ b/.agents/notes/implemented/architecture/2026-08-19-session-projection-mandatory-seam.md @@ -25,7 +25,7 @@ The registry provides `stateOf(session, key)` for one typed host state and keeps - **Default missing projected state.** This preserves more partial compositions but makes missing host state indistinguishable from a valid empty value. Rejected because official profiles mount the registry and configuration errors must fail explicitly. - **Require every contributor at activation.** This makes the key set uniform but unnecessarily couples contribution lifecycle to service activation. Explicit first-access failure preserves the optional registration form without allowing silent degradation. - **Use `snapshot()` for every read.** This keeps one method but computes unrelated wire views and encourages consumers to depend on batch transport data for host logic. Rejected in favor of typed single-key state reads. -- **Send full host values to clients.** This avoids separate view types but exposes provenance and policy knobs that no client consumes. Rejected in favor of explicit cropped views. +- **Send full host values to clients.** This avoids separate view types but exposes producer identities and policy knobs that no client consumes. Rejected in favor of explicit cropped views. - **Broadcast registry additions and removals across Host and mux streams.** The streams have no shared ordering, so clients need tombstones, buffered frames, and baseline retries to reconcile them. Rejected because plugin-key churn does not justify a second synchronization protocol. ## Consequences diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml index 13c4e2fb9b..2be979e55d 100644 --- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.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 .agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md -2026-08-21-deepseek-llm-api-request-extensions.md: eadbe2a5f17de446c345120f9a6aeeeb531c43b4 -2026-08-21-deepseek-llm-api-request-extensions.zh.md: f45210adbc075c30484754ce7f8c2b65b515be6c +2026-08-21-deepseek-llm-api-request-extensions.md: a0e38c1da5af32b0ba5e07df632ac4e25148419e +2026-08-21-deepseek-llm-api-request-extensions.zh.md: 763f418c7bd6029c08027cd5f4705bffd984b9ee diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md index eadbe2a5f1..a0e38c1da5 100644 --- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md +++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.md @@ -30,7 +30,7 @@ The `events` array contains complete canonical `SessionEvent` objects directly. `@deepseek-ai/dsh-plugin-package-inventory-deepseek` owns the default-on `dsh_plugin_packages` field from the `llm` package family. It reads active non-group entries from the host Loader tree and, for a live requesting Agent, its standing preset tree. Node package resolution locates the owning manifest without requiring a `./package.json` export. Ordinary entries resolve from their owning tree, while a standing preset root mirrors its Loader's intentional harness-base override and nested includes retain their own bases. An anonymous nearest manifest marks a loose module; a named manifest must carry a version. Exact name/version pairs are deduplicated with deterministic ordering; simultaneously active versions remain separate. -Disabled, pending, failed, unloading, disposed, structural, loose non-package, ordinary dependency, programmatic child-fiber, and in-memory dynamic-plugin entries are outside this package inventory. This definition reports package-backed composition facts the runtime can prove instead of inventing provenance for arbitrary callbacks. +Disabled, pending, failed, unloading, disposed, structural, loose non-package, ordinary dependency, programmatic child-fiber, and in-memory dynamic-plugin entries are outside this package inventory. This definition reports package-backed composition facts the runtime can prove instead of inventing package identity for arbitrary callbacks. ## Deferred inventory caching @@ -73,11 +73,11 @@ The receiver would also need to traverse the tagged tree, resolve paths into the ### Why not omit assistant chunks or overlapping event data? -About 98% of the measured v1 real-session events were `assistant/chunk`. Omitting them after reference encoding reduced the complete identity JSON by another 84.79% for late enable and 6.49% for steady state, but prevented lossless reconstruction and left message provenance dangling. V2 embeds compact streams in attempt settlements; `dsh_session_log` still sends every current canonical event whole and does not omit those embedded records. Fuzzy or normalized substitutions have the same reconstruction defect. +About 98% of the measured v1 real-session events were `assistant/chunk`. Omitting them after reference encoding reduced the complete identity JSON by another 84.79% for late enable and 6.49% for steady state, but prevented lossless reconstruction and left message source-event references dangling. V2 embeds compact streams in attempt settlements; `dsh_session_log` still sends every current canonical event whole and does not omit those embedded records. Fuzzy or normalized substitutions have the same reconstruction defect. **Keep the upload cursor only in memory.** Rejected because a normal process restart would resend the entire Session. A canonical acceptance event makes restart recovery best-effort durable without another storage backend; the remaining crash window produces allowed duplicates. -**Inventory every live Cordis fiber.** Rejected because programmatic and in-memory fibers have no authoritative npm package provenance. Loader-backed host and preset entries provide exact resolvable package identity. +**Inventory every live Cordis fiber.** Rejected because programmatic and in-memory fibers have no authoritative npm package identity. Loader-backed host and preset entries provide exact resolvable package identity. **Cache one process-global list or expire it on a TTL.** Rejected because one immutable list is incorrect for Loader lifecycle and per-Session presets, while a TTL permits stale metadata between expiry boundaries. The deferred epoch design invalidates on the authoritative active-state transition instead. diff --git a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md index f45210adbc..763f418c7b 100644 --- a/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-21-deepseek-llm-api-request-extensions.zh.md @@ -73,7 +73,7 @@ Status: implemented ### 为什么不省略 assistant 分片或重叠事件数据? -实测 v1 真实 Session event 中约 98% 为 `assistant/chunk`。在引用编码后省略它们,会让完整 identity JSON 在延迟启用场景进一步减少 84.79%,在稳态场景进一步减少 6.49%,但会阻止无损重建并让 message provenance 悬空。V2 把紧凑 stream 嵌入 attempt settlement;`dsh_session_log` 仍会完整发送每个当前规范 event,且不会省略这些嵌入式 record。模糊或规范化替换也有相同重建缺陷。 +实测 v1 真实 Session event 中约 98% 为 `assistant/chunk`。在引用编码后省略它们,会让完整 identity JSON 在延迟启用场景进一步减少 84.79%,在稳态场景进一步减少 6.49%,但会阻止无损重建并让 message source-event reference 悬空。V2 把紧凑 stream 嵌入 attempt settlement;`dsh_session_log` 仍会完整发送每个当前规范 event,且不会省略这些嵌入式 record。模糊或规范化替换也有相同重建缺陷。 **只在内存中保留上传游标。** 已否决,因为普通进程重启会重发完整会话。权威接受事件让重启恢复获得尽力而为的持久性,无需另一存储后端;剩余崩溃窗口只会产生允许的重复。 diff --git a/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.i18n.yaml index a75186206d..bc7d37ce4c 100644 --- a/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.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 .agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md -2026-08-27-adjacent-agent-steer-messaging.md: 7bd97d5c992acac240a28d61d27e35e1f1058ae3 +2026-08-27-adjacent-agent-steer-messaging.md: 47d9bd05c24871a14f78ebfa0afb8c13a6c2754d 2026-08-27-adjacent-agent-steer-messaging.zh.md: 1fd0fc39b937287ac34a2862c7cb9cde90256c09 diff --git a/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md b/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md index 7bd97d5c99..47d9bd05c2 100644 --- a/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md +++ b/.agents/notes/implemented/architecture/2026-08-27-adjacent-agent-steer-messaging.md @@ -6,7 +6,7 @@ English | [中文](2026-08-27-adjacent-agent-steer-messaging.zh.md) ## Problem -Continuable Agents originally used direction-specific model controls. A parent called `send_message({ subagent_id, message })`, which delegated to a FIFO `followup` service operation. A child instead received a child-scoped `report({ output })` tool, a `tool:report` system-prompt section, and deployment-selected quiet or waking delivery. The tools described one adjacent-Agent operation through different schemas, service paths, provenance, and scheduling. +Continuable Agents originally used direction-specific model controls. A parent called `send_message({ subagent_id, message })`, which delegated to a FIFO `followup` service operation. A child instead received a child-scoped `report({ output })` tool, a `tool:report` system-prompt section, and deployment-selected quiet or waking delivery. The tools described one adjacent-Agent operation through different schemas, service paths, source attribution, and scheduling. A continuable child owns its own Session, so its parent does not automatically receive the child's transcript, tool output, or reasoning. The return path must therefore remain explicit and repeatable: a child may send progress before it finishes, remain available after sending, or fail before it can cooperate. Turning every final assistant message into an implicit result would conflate turn completion with model-selected communication and would not cover abnormal endings. diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml index 9fbfab3698..7fd3cc3676 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.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 .agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md -2026-09-01-v2-embedded-assistant-streams.md: 98207749028e2182c5e60073fc07985688ecfa30 -2026-09-01-v2-embedded-assistant-streams.zh.md: 90dff5a385cf83071ec52a2fc2b57a893107b861 +2026-09-01-v2-embedded-assistant-streams.md: 219879600f8435a6ecc9593661dd3f463ed1158c +2026-09-01-v2-embedded-assistant-streams.zh.md: d38c180b1f1de689620f2e0533d2b02f4a71e466 diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md index 9820774902..219879600f 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md +++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md @@ -23,7 +23,7 @@ Session format v2 has no top-level `assistant/chunk` event. Each model attempt c `AssistantStreamAccumulator` snapshots each chunk once. Consecutive text, reasoning, or tool-argument deltas for the same block become one compact run with its first timestamp, exact timestamp gaps, and one array member per original delta. Every other chunk remains a timestamped raw record. `expandAssistantStream()` strictly validates and reconstructs the exact timed sequence; compaction never joins delta boundaries. -The migration publication verifier and frozen v2 fixture validator require the embedded stream to reproduce a non-empty `assistant/message`'s content, usage, and replay state. An empty stream remains valid for a migrated legacy message that had no source chunks. Ordinary Session restoration validates the settlement fields needed by the runtime without expanding every historical stream; consumers that expand a compact stream validate its records when they read it. `assistant/message` cannot carry obsolete chunk `sourceEventSeqs`; ordinary user and tool surface provenance remains available. +The migration publication verifier and frozen v2 fixture validator require the embedded stream to reproduce a non-empty `assistant/message`'s content, usage, and replay state. An empty stream remains valid for a migrated legacy message that had no source chunks. Ordinary Session restoration validates the settlement fields needed by the runtime without expanding every historical stream; consumers that expand a compact stream validate its records when they read it. `assistant/message` cannot carry obsolete chunk `sourceEventSeqs`; ordinary user and tool source-event references remain available. ### Live presentation and durable replay @@ -35,9 +35,9 @@ The Client event source passes durable settlements through unchanged. The Chat a ### Released v1 to v2 migration -The adjacent migration validates the complete frozen v1 artifact, groups chunks by turn, step, terminal boundary, and exact message provenance, and then substitutes one settlement per attempt. A successful group's chunks move into its message. An unclaimed group becomes `assistant/attempt` at the last consumed chunk's position. Unrelated interleaved events retain their relative order, and survivors receive dense v2 sequence numbers. The edge compacts embedded streams through the runtime `AssistantStreamAccumulator` from `dsh-llm` instead of a frozen copy, because that package owns the v2 stream encoding. The isolated publication verifier expands and re-assembles the written stream through `expandAssistantStream()` and `BlockAssembler`, then checks each migrated `assistant/message` against it before publication. A later format that changes the stream encoding must freeze copies of these helpers into this edge. +The adjacent migration validates the complete frozen v1 artifact, groups chunks by turn, step, terminal boundary, and exact message chunk references, and then substitutes one settlement per attempt. A successful group's chunks move into its message. An unclaimed group becomes `assistant/attempt` at the last consumed chunk's position. Unrelated interleaved events retain their relative order, and survivors receive dense v2 sequence numbers. The edge compacts embedded streams through the runtime `AssistantStreamAccumulator` from `dsh-llm` instead of a frozen copy, because that package owns the v2 stream encoding. The isolated publication verifier expands and re-assembles the written stream through `expandAssistantStream()` and `BlockAssembler`, then checks each migrated `assistant/message` against it before publication. A later format that changes the stream encoding must freeze copies of these helpers into this edge. -The edge remaps the finite declared reference inventory: envelope provenance, surface replacement endpoints, command source events, compaction ranges and shadowed lists, and title message lists. The model-visible text of a validated `session/title-llm-request` remains byte-identical in the source sequence namespace while its `messageSeqs` field moves to the v2 namespace; target validation therefore does not reconstruct that text from remapped sequences. A reference to a consumed chunk refuses migration; it is never redirected to a settlement with different meaning. The edge also refuses an inherited cut that splits an attempt. +The edge remaps the finite declared reference inventory: envelope source-event references, surface replacement endpoints, command source events, compaction ranges and shadowed lists, and title message lists. The model-visible text of a validated `session/title-llm-request` remains byte-identical in the source sequence namespace while its `messageSeqs` field moves to the v2 namespace; target validation therefore does not reconstruct that text from remapped sequences. A reference to a consumed chunk refuses migration; it is never redirected to a settlement with different meaning. The edge also refuses an inherited cut that splits an attempt. The v2 physical header requires `isSeeded` and stores no numeric cut. A seeded artifact marks its exact cut with `session/end-seed { inherited: true }`; decoding derives the cut from the last tagged marker. The v2 codec writes one durable event per physical row, range-encodes only `sourceEventSeqs`, and validates physical envelopes without freezing ordinary event vocabulary or payload additions. The v1-to-v2 target validator separately freezes the released-v2 inventory, while current restoration uses the installed Session vocabulary. Frozen v0 and v1 codecs retain packed-row decoding for their immutable historical generations. @@ -49,7 +49,7 @@ Generation selection and publication follow the [released Session migration deci ## Verification -The compact-stream tests pin exact accumulation and expansion for text, reasoning, tool arguments, raw chunks, timestamp gaps, malformed records, and detached snapshots. The v1-to-v2 tests cover successful and failed attempts, interleaving, dense sequence and reference remapping, source-sequence title framing, seed-cut insertion and split refusal, strict source and target validation, one-row v2 encoding, backend-compatible provenance ranges, raw and Zstandard publication, and no-write current reads. +The compact-stream tests pin exact accumulation and expansion for text, reasoning, tool arguments, raw chunks, timestamp gaps, malformed records, and detached snapshots. The v1-to-v2 tests cover successful and failed attempts, interleaving, dense sequence and reference remapping, source-sequence title framing, seed-cut insertion and split refusal, strict source and target validation, one-row v2 encoding, backend-compatible source-event ranges, raw and Zstandard publication, and no-write current reads. The pre-merge performance acceptance measured static catalog-routing overhead against direct released-v2 restoration of the same already parsed physical rows across three runs, 100 warmup pairs, and 600 measured pairs; it did not compare v1 with v2 or time backend I/O. Every pooled median and p95 regression stayed within the 5% budget, with a worst p95 regression of 3.150%. diff --git a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md index 90dff5a385..d38c180b1f 100644 --- a/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md +++ b/.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md @@ -23,7 +23,7 @@ Session format v2 没有顶层 `assistant/chunk` 事件。每个模型 attempt `AssistantStreamAccumulator` 对每个 chunk 只快照一次。同一 block 的连续 text、reasoning 或 tool argument delta 会变成一个紧凑 run,包含首个时间戳、精确时间戳间隔和每个原始 delta 对应的一个数组成员。其他 chunk 保留为带时间戳的 raw record。`expandAssistantStream()` 会严格校验并重建精确的带时间序列;压缩绝不会合并 delta 边界。 -Migration publication verifier 与冻结的 v2 fixture validator 要求嵌入式 stream 能复现非空 `assistant/message` 的 content、usage 与 replay state。对于没有源 chunk 的已迁移旧 message,空 stream 仍然有效。普通 Session restore 只校验 runtime 直接依赖的 settlement 字段,不展开全部历史 stream;需要展开 compact stream 的 consumer 会在读取时校验 record。`assistant/message` 不能携带已停用的 chunk `sourceEventSeqs`;普通 user 与 tool surface provenance 保持可用。 +Migration publication verifier 与冻结的 v2 fixture validator 要求嵌入式 stream 能复现非空 `assistant/message` 的 content、usage 与 replay state。对于没有源 chunk 的已迁移旧 message,空 stream 仍然有效。普通 Session restore 只校验 runtime 直接依赖的 settlement 字段,不展开全部历史 stream;需要展开 compact stream 的 consumer 会在读取时校验 record。`assistant/message` 不能携带已停用的 chunk `sourceEventSeqs`;普通 user 与 tool source-event reference 保持可用。 ### 实时呈现与持久回放 @@ -35,9 +35,9 @@ Client event source 原样传递持久 settlement。Chat 与 Trajectory 的 Assi ### 已发布 v1 到 v2 迁移 -相邻迁移会校验完整的冻结 v1 产物,按 turn、step、terminal boundary 与精确 message provenance 对 chunk 分组,再为每个 attempt 替换一个 settlement。成功分组的 chunk 移入其 message。未被认领的分组会在最后一个被消费 chunk 的位置变成 `assistant/attempt`。无关的交错事件保持相对顺序,存活事件获得密集 v2 序号。该迁移边通过 `dsh-llm` 运行时的 `AssistantStreamAccumulator` 压缩嵌入 stream,而不持有冻结副本,因为该包拥有 v2 stream 编码。隔离的 publication verifier 通过 `expandAssistantStream()` 与 `BlockAssembler` 展开并重组写入后的 stream,并在发布前检查每个迁移后的 `assistant/message` 是否与其一致。日后若某个格式改变 stream 编码,必须把这些 helper 的冻结副本纳入本迁移边。 +相邻迁移会校验完整的冻结 v1 产物,按 turn、step、terminal boundary 与精确 message chunk reference 对 chunk 分组,再为每个 attempt 替换一个 settlement。成功分组的 chunk 移入其 message。未被认领的分组会在最后一个被消费 chunk 的位置变成 `assistant/attempt`。无关的交错事件保持相对顺序,存活事件获得密集 v2 序号。该迁移边通过 `dsh-llm` 运行时的 `AssistantStreamAccumulator` 压缩嵌入 stream,而不持有冻结副本,因为该包拥有 v2 stream 编码。隔离的 publication verifier 通过 `expandAssistantStream()` 与 `BlockAssembler` 展开并重组写入后的 stream,并在发布前检查每个迁移后的 `assistant/message` 是否与其一致。日后若某个格式改变 stream 编码,必须把这些 helper 的冻结副本纳入本迁移边。 -该迁移边会重映射有限的已声明引用清单:信封 provenance、surface replacement 端点、command source event、compaction range 与 shadowed list,以及 title message list。经过校验的 `session/title-llm-request` 模型可见文本会在源序号命名空间中保持逐字节不变,而它的 `messageSeqs` 字段会迁移到 v2 命名空间;因此目标校验不会根据重映射后的序号重建该文本。指向被消费 chunk 的引用会使迁移失败;它绝不会被重定向到含义不同的 settlement。该迁移边也会拒绝切开 attempt 的继承切点。 +该迁移边会重映射有限的已声明引用清单:信封 source-event reference、surface replacement 端点、command source event、compaction range 与 shadowed list,以及 title message list。经过校验的 `session/title-llm-request` 模型可见文本会在源序号命名空间中保持逐字节不变,而它的 `messageSeqs` 字段会迁移到 v2 命名空间;因此目标校验不会根据重映射后的序号重建该文本。指向被消费 chunk 的引用会使迁移失败;它绝不会被重定向到含义不同的 settlement。该迁移边也会拒绝切开 attempt 的继承切点。 v2 物理 header 要求 `isSeeded`,且不存储数值切点。带 seed 的产物用 `session/end-seed { inherited: true }` 标记其精确切点;解码从最后一个 tagged marker 推导切点。v2 编解码器为每个持久事件写一条物理行,只对 `sourceEventSeqs` 做范围编码,并在不冻结普通事件词汇或 payload 新增项的前提下校验物理 envelope。v1-to-v2 target validator 会另行冻结 released-v2 清单,current restoration 则使用 installed Session 词汇。冻结的 v0 与 v1 编解码器继续为不可变历史 generation 解码 packed row。 @@ -49,7 +49,7 @@ Generation 选择与发布遵循[已发布 Session 迁移决策](2026-08-31-rele ## 验证 -紧凑 stream 测试固定 text、reasoning、tool argument、raw chunk、时间戳间隔、格式错误 record 与分离 snapshot 的精确累积和展开。v1 到 v2 测试覆盖成功与失败 attempt、交错、密集序号与引用重映射、源序号 title framing、seed 切点插入与切分拒绝、严格源与目标校验、每行一个事件的 v2 编码、与 backend 兼容的 provenance range、原始与 Zstandard 发布,以及无写入的当前读取。 +紧凑 stream 测试固定 text、reasoning、tool argument、raw chunk、时间戳间隔、格式错误 record 与分离 snapshot 的精确累积和展开。v1 到 v2 测试覆盖成功与失败 attempt、交错、密集序号与引用重映射、源序号 title framing、seed 切点插入与切分拒绝、严格源与目标校验、每行一个事件的 v2 编码、与 backend 兼容的 source-event range、原始与 Zstandard 发布,以及无写入的当前读取。 合并前的 performance acceptance 在三轮、100 组 warmup pair 与 600 组 measured pair 下,针对同一批已经解析的物理 row,把静态 catalog routing 与直接 released-v2 restoration 比较;它不比较 v1 与 v2,也不计入 backend I/O。每个 pooled median 与 p95 regression 都保持在 5% 预算以内,最差 p95 regression 为 3.150%。 diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.i18n.yaml index 6333d7947a..caf0d668d6 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.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 .agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.md -2026-09-05-nested-terminal-cards.md: b369aef20b0b5fbb338e40affd5fd2800b525bcb +2026-09-05-nested-terminal-cards.md: 03b80382a00c2302d25d2b572c3b06aedff0e1b3 2026-09-05-nested-terminal-cards.zh.md: bf97fffa2a8d92562e982d498d17b830e1e25f48 diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.md b/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.md index b369aef20b..03b80382a0 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.md +++ b/.agents/notes/implemented/bug-fix/2026-09-05-nested-terminal-cards.md @@ -28,7 +28,7 @@ Shell output ending in a recognized spill-policy notice uses generic output: exp ## Consequences -Rows and Details share terminal derivation for nested calls without a second renderer or presentation hint. Generic fallback and settled-persistent behavior remain separate from terminal-card eligibility. The parent-child relationship still controls tree placement, not terminal rendering. Text recognition cannot authenticate output: a tool can print the same notice. A match selects conservative generic presentation, not proof of spill provenance or process status. +Rows and Details share terminal derivation for nested calls without a second renderer or presentation hint. Generic fallback and settled-persistent behavior remain separate from terminal-card eligibility. The parent-child relationship still controls tree placement, not terminal rendering. Text recognition cannot authenticate output: a tool can print the same notice. A match selects conservative generic presentation, not proof of spill source or process status. ## Verification diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.i18n.yaml index 27ac99b5da..2653e7d928 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.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 .agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.md -2026-09-05-patch-plugin-file-urls.md: 48112483b4a3eef1fefcb774c2d19a2c901ccbdb +2026-09-05-patch-plugin-file-urls.md: bad63355ce74b520b5e49b94deeefb2d648b71f4 2026-09-05-patch-plugin-file-urls.zh.md: 775a576324dd2856f490cf3ce3ba907965737fc2 diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.md b/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.md index 48112483b4..bad63355ce 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.md +++ b/.agents/notes/implemented/bug-fix/2026-09-05-patch-plugin-file-urls.md @@ -18,7 +18,7 @@ The optional `HostResolvedRootInclude` import override separately converts absol **Convert only the Python fixture with `Path.as_uri()`.** This avoids one failure but leaves user-authored profile and overlay patches exposed. -**Change the shared Loader base.** This loses per-patch provenance and changes bare-package resolution. File URLs preserve the selected local file without changing the resolver base. +**Change the shared Loader base.** This loses each patch's file source and changes bare-package resolution. File URLs preserve the selected local file without changing the resolver base. ## Consequences diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.i18n.yaml index caf13e2fa5..e188205736 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.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 .agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.md -2026-09-05-pi-ai-upgrade-compatibility.md: ed400ab62d221e1b58025617f05500590bfed5e7 +2026-09-05-pi-ai-upgrade-compatibility.md: e28d911facae33fcf278a6824376f889e3416d77 2026-09-05-pi-ai-upgrade-compatibility.zh.md: 408669ddc963a505254529acaab4c19e9774c6b1 diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.md b/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.md index ed400ab62d..e28d911fac 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.md +++ b/.agents/notes/implemented/bug-fix/2026-09-05-pi-ai-upgrade-compatibility.md @@ -12,7 +12,7 @@ The pi-ai adapter classifies upstream compatibility fields explicitly and persis The adapter follows [pi-ai 0.85.1](https://github.com/earendil-works/pi/blob/v0.85.1/packages/ai/CHANGELOG.md). `thinkingTokenBudgetField`, `vllmPriority`, and `supportsMaxOutputTokens` are opt-in gateway controls; `thinking.budget` joins the existing template placeholders. The SDK owns budget resolution and serialization. `supportsMidConvoEffort` and `allowedFallbackModels` remain catalog-owned because their correctness depends on exact Anthropic transports, model capabilities, and fallback pricing. -Optional `providerThinkingLevel` remains in the adapter replay-v2 response metadata so Anthropic history retains its provider-native effort. Absence remains valid; neither the replay version nor the released Session format changes. Replay provenance retains the requested model while `responseModel` retains an Anthropic alias resolution or fallback. Reconstruction restores that native model so pi-ai still applies its cross-model signature rules. The provider-neutral LLM API stays unchanged; the [provider-routed replay ownership rules](../architecture/2026-07-14-provider-routed-llm-adapters.md) still apply. The 0.84.2 Anthropic adapter [initializes `model` from the request](https://github.com/earendil-works/pi/blob/v0.84.2/packages/ai/src/api/anthropic-messages.ts#L510-L515) and [records only response id and usage at message start](https://github.com/earendil-works/pi/blob/v0.84.2/packages/ai/src/api/anthropic-messages.ts#L589-L605). It never writes `responseModel`, so its replay records retain the requested model without native-model metadata. +Optional `providerThinkingLevel` remains in the adapter replay-v2 response metadata so Anthropic history retains its provider-native effort. Absence remains valid; neither the replay version nor the released Session format changes. Replay metadata retains the requested model while `responseModel` retains an Anthropic alias resolution or fallback. Reconstruction restores that native model so pi-ai still applies its cross-model signature rules. The provider-neutral LLM API stays unchanged; the [provider-routed replay ownership rules](../architecture/2026-07-14-provider-routed-llm-adapters.md) still apply. The 0.84.2 Anthropic adapter [initializes `model` from the request](https://github.com/earendil-works/pi/blob/v0.84.2/packages/ai/src/api/anthropic-messages.ts#L510-L515) and [records only response id and usage at message start](https://github.com/earendil-works/pi/blob/v0.84.2/packages/ai/src/api/anthropic-messages.ts#L589-L605). It never writes `responseModel`, so its replay records retain the requested model without native-model metadata. ## Alternatives considered diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.i18n.yaml index a97e6873d0..577e94fdc8 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.i18n.yaml +++ b/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.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 .agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.md -2026-09-05-session-reference-spill-reuse.md: d9f9e3702075417a9b5c742831737e412e75bd00 +2026-09-05-session-reference-spill-reuse.md: 2a24e3adf28c70df8feb726700376df6f06dee87 2026-09-05-session-reference-spill-reuse.zh.md: 346ed1a39ee65a560cf9e74e519ae45c2ce133e1 diff --git a/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.md b/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.md index d9f9e37020..2a24e3adf2 100644 --- a/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.md +++ b/.agents/notes/implemented/bug-fix/2026-09-05-session-reference-spill-reuse.md @@ -26,7 +26,7 @@ Cancellation after an asynchronous save prevents context publication, even if st **Put omission and retrieval data inside the bounded preview JSON.** Rejected because that spends the conversation budget on metadata and can hide the notice precisely when the budget is smallest. Separate durable model-visible text preserves both obligations. -**Use tool provenance for every spill.** Rejected because a session reference has no model-issued tool call. Invented tool ids would misattribute the artifact rather than describe its producer. +**Use a tool source for every spill.** Rejected because a session reference has no model-issued tool call. Invented tool ids would misattribute the artifact rather than describe its producer. ## Consequences diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml index fc2a00aa26..332515c11d 100644 --- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.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 .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md -2026-07-28-continuable-subagent-conversations.md: 8c3f2e1da593157f17528f13fc8842012aad0284 +2026-07-28-continuable-subagent-conversations.md: af4382a764a59a2d7c02f3cd5feffb32022441f8 2026-07-28-continuable-subagent-conversations.zh.md: 886e31fa3d88b78f875d51058bb2ec8c525837fe diff --git a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md index 8c3f2e1da5..af4382a764 100644 --- a/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md +++ b/.agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.md @@ -44,7 +44,7 @@ Cold resume does not dispatch through a subagent provider. The continuation mana `SubagentProvider.start()` and `SubagentRun` remain exclusively on the unchanged one-shot path. A continuable Activation directly owns its `AgentHandle` and never creates, wraps, or retains a `SubagentRun`; `SubagentRun.steer?()` is therefore absent. -`ctx.subagents.sendMessage(sender, targetId, content, { signal })` is the sole model-authored continuation-message operation. The exact live sender authorizes delivery to its direct parent or direct continuable child; cold resume checks direct-child authority before reconstruction and every path checks again in the final no-await inbox-admission span, so an Agent unregistered or replaced during materialization cannot authorize delivery. The service derives durable `agent-message` provenance from that sender. The model-facing `send_message` tool keeps only `agent_id` and `message` and uses fixed Steer scheduling. Both start and send return the accepted `MessageId`, and neither reports how the manager materialized the Activation. +`ctx.subagents.sendMessage(sender, targetId, content, { signal })` is the sole model-authored continuation-message operation. The exact live sender authorizes delivery to its direct parent or direct continuable child; cold resume checks direct-child authority before reconstruction and every path checks again in the final no-await inbox-admission span, so an Agent unregistered or replaced during materialization cannot authorize delivery. The service derives a durable `agent-message` source from that sender. The model-facing `send_message` tool keeps only `agent_id` and `message` and uses fixed Steer scheduling. Both start and send return the accepted `MessageId`, and neither reports how the manager materialized the Activation. For start and follow-up, the caller signal owns lookup, materialization, and admission only until inbox acceptance. After the operation returns its `MessageId`, the manager owns the Activation independently; later caller cancellation does not cancel the accepted turn or dispose the child. @@ -117,7 +117,7 @@ The shared `sendMessage(sender, targetId, content, options)` service operation a ### Agent and human scheduling -Every accepted Agent message uses `Agent.steer()`. A running target claims it at the nearest step boundary; an idle or cold-resumed target starts a turn. Browser-authored human input separately carries `delivery: 'queue' | 'steer'` through `subagent.prompt`: Queue opens a later FIFO turn, while Steer uses the same best-effort nearest-step scheduling without changing the message's human provenance. The public service exposes no caller-selectable scheduling mode for Agent messages. +Every accepted Agent message uses `Agent.steer()`. A running target claims it at the nearest step boundary; an idle or cold-resumed target starts a turn. Browser-authored human input separately carries `delivery: 'queue' | 'steer'` through `subagent.prompt`: Queue opens a later FIFO turn, while Steer uses the same best-effort nearest-step scheduling without changing the message's human source. The public service exposes no caller-selectable scheduling mode for Agent messages. ### Authority and recorded sender identity diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml index ae2bffad1a..96dfe450a7 100644 --- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.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 .agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md -2026-08-06-manager-owned-subagent-settlement-delivery.md: f223571dc91300d085b7fcf0a9e3196daa48b760 +2026-08-06-manager-owned-subagent-settlement-delivery.md: 9d14d4af775809a974349c753a7b4b593a145489 2026-08-06-manager-owned-subagent-settlement-delivery.zh.md: 4bbee373aa2b50902af5319f9398a89da9cc3143 diff --git a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md index f223571dc9..9d14d4af77 100644 --- a/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md +++ b/.agents/notes/implemented/feature/2026-08-06-manager-owned-subagent-settlement-delivery.md @@ -18,7 +18,7 @@ The continuation manager delivers the account itself, from inside the disposal t When a resident Activation settles, `notifySettlement()` resolves the child's durable direct parent and sends it one user-role message: the epoch's outcome as a sentence the parent can act on, then the child's final assistant content, or a statement that it produced none. Delivery is unconditional for every child whose id a caller actually received. It does not consult whether the child reported, and it keeps no bookkeeping that could make the promise conditional — that unconditionality is what lets `tool-subagent` promise a runtime notice containing the outcome and any final assistant message. A materialization rolled back before its first accepted message stays silent, because the caller was told that child was not established. -### Provenance +### Runtime source The notice carries `{ kind: 'subagent-settled', form: 'notice', summary, senderSessionId }`. It is deliberately not the `agent-message` kind used by `send_message`. An Agent message is content the child chose; this is the runtime stating what became of the child. Merging them would credit the child with words it never wrote, and would make a durable log unable to distinguish "the child said it was done" from "the harness observed that it stopped". The `notice` form also gives a UI the collapsed one-line presentation this message wants, where `relay` presents Agent correspondence. diff --git a/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.i18n.yaml b/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.i18n.yaml index 03918f3585..3877584618 100644 --- a/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.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 .agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md -2026-08-22-fire-and-forget-webhook-sessions.md: 976bccd8b460de7cb696ee45ea8963710cc4c738 +2026-08-22-fire-and-forget-webhook-sessions.md: 08f718b8063c7ca0d78e93f547c0e0c33c183d07 2026-08-22-fire-and-forget-webhook-sessions.zh.md: f015d993e61864bbc21d9d55fc331c25118fbde3 diff --git a/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md b/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md index 976bccd8b4..08f718b806 100644 --- a/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md +++ b/.agents/notes/implemented/feature/2026-08-22-fire-and-forget-webhook-sessions.md @@ -28,7 +28,7 @@ Patch loading anchors relative plugin names in inserted rows to the patch file. A rule result names a local Workspace path, title, text prompt, agent preset, permission preset, and optional explicit provider/model route with an output cap. Without that route, the runtime snapshots the complete live default, including reasoning effort, until the first request records its durable header. It validates presets before mutation, resolves or creates the canonical Workspace, creates the Agent with that path as Session cwd, mounts the preset before publication, and attaches the Session before admitting the prompt. -The initial follow-up is an ordinary durable user-role message with webhook provider, source, delivery, and rule provenance. Its inbox insertion is the webhook operation's last boundary. Ordinary Session persistence and Agent lifecycle own later work; the runtime neither flushes specially nor waits for a turn. +The initial follow-up is an ordinary durable user-role message whose source records the webhook provider, source, delivery, and rule identifiers. Its inbox insertion is the webhook operation's last boundary. Ordinary Session persistence and Agent lifecycle own later work; the runtime neither flushes specially nor waits for a turn. ## Alternatives considered @@ -40,13 +40,13 @@ The initial follow-up is an ordinary durable user-role message with webhook prov **Restrict rules to a declarative predicate language.** Rejected because programmatic rules explicitly need arbitrary external calls. Trusted Cordis plugins already provide the required authority and lifecycle. -**Let each adapter create Sessions directly.** Rejected because Workspace, preset, permission, title, rollback, and provenance logic would spread across provider packages. +**Let each adapter create Sessions directly.** Rejected because Workspace, preset, permission, title, rollback, and message-source logic would spread across provider packages. ## Verification Package tests pin independent callback execution, fire-and-forget HTTP timing, cancellation and quiescent disposal, request validation, Workspace attachment before prompt admission, rollback, GitHub HMAC and body limits, credential rotation, and exact Loader composition. The assembled Web example sends a signed ready-for-review delivery to an isolated second listener and records the resulting ordinary Workspace conversation. -A real-API e2e test starts the built `dsh web` CLI with the webhook overlay and isolated listener, synthesizes only the signed inbound GitHub delivery, observes Workspace attachment and durable provenance through the public Web API, and waits for the real DeepSeek response. No DSH service, model adapter, or provider call is replaced by a test double. +A real-API e2e test starts the built `dsh web` CLI with the webhook overlay and isolated listener, synthesizes only the signed inbound GitHub delivery, observes Workspace attachment and the durable message source through the public Web API, and waits for the real DeepSeek response. No DSH service, model adapter, or provider call is replaced by a test double. Source audits keep execution records, retry timers, dedupe maps, completion events, and Agent-status listeners absent. diff --git a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.i18n.yaml b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.i18n.yaml index e8f658dfe7..25749576f7 100644 --- a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.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 .agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md -2026-08-27-continuable-subagent-human-inbox-control.md: cf5dfd070dfd600fb64bc529b4a1476a258c1181 +2026-08-27-continuable-subagent-human-inbox-control.md: 6bf8ceb2b8eab7138a1e617bb97e475d5cfa8172 2026-08-27-continuable-subagent-human-inbox-control.zh.md: 081fb84f75afcc94339ae3bf627480081bc56d89 diff --git a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md index cf5dfd070d..6bf8ceb2b8 100644 --- a/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md +++ b/.agents/notes/implemented/feature/2026-08-27-continuable-subagent-human-inbox-control.md @@ -20,7 +20,7 @@ The browser gives a continuable child the ordinary busy Enter/Cmd+Enter Queue/St The existing `session.updateQueue(itemId, action)` resolves the exact live Agent and admits a subagent-owned Session only when its current projected identity is continuable and the descriptor sequence belongs to the child's own non-seed suffix. A live one-shot Agent and a missing, inherited-only, or invalid identity retain the ownership failure. An absent Agent returns `queue-item-not-found` and does not cold-resume the child. The target Session id is sufficient human authority for a live inbox occurrence mutation; a parent address is not required. Edit and Remove retain their complete existing `nextTurn` and `nextStep` semantics, including plugin-injected context, while Steer requires a queued occurrence and an Agent that reports running when the command begins. -The continuation manager keeps no second message-reservation state. One private `SubagentInbox` delegates Queue and Steer to the Agent inbox and owns the Activation's existing closing promise. Natural settlement waits for `Agent.whenIdle()`, an empty child Inbox, and disposal of every owned child. The manager confirms the Inbox, owned-child set, and wake generation under the child lock, then flushes final Session state while admission remains open. The final child-lock decision revalidates the Session sequence and the same residency facts, then synchronously starts an `Agent.runMaintenance()` task whose entry claims the idle phase and closes the wrapper in the same JavaScript turn. Every pending Inbox occurrence retains the Activation regardless of its delivery mode or provenance. Manager-owned deliveries, Inbox claims or discards, and owned-child release renew the wake generation. Direct Agent work accepted during the flush either changes the final Session or residency observation, remains active and prevents the final maintenance task from starting, or completes before revalidation. +The continuation manager keeps no second message-reservation state. One private `SubagentInbox` delegates Queue and Steer to the Agent inbox and owns the Activation's existing closing promise. Natural settlement waits for `Agent.whenIdle()`, an empty child Inbox, and disposal of every owned child. The manager confirms the Inbox, owned-child set, and wake generation under the child lock, then flushes final Session state while admission remains open. The final child-lock decision revalidates the Session sequence and the same residency facts, then synchronously starts an `Agent.runMaintenance()` task whose entry claims the idle phase and closes the wrapper in the same JavaScript turn. Every pending Inbox occurrence retains the Activation regardless of its delivery mode or source. Manager-owned deliveries, Inbox claims or discards, and owned-child release renew the wake generation. Direct Agent work accepted during the flush either changes the final Session or residency observation, remains active and prevents the final maintenance task from starting, or completes before revalidation. QueueDock Steer uses the Agent's best-effort delivery after the command admits a running queued occurrence. If the queued occurrence was claimed first, `queue-item-not-found` leaves its ordinary Queue delivery underway. If active cancellation wins during the synchronous transfer, Agent steering appends the message to `nextTurn`, latches a wake, and the Session command still succeeds. The selected message moves behind the remaining Queue in that fallback case. Newly composed Steer uses the same fallback and remains deliverable when it misses the nearest step. @@ -46,6 +46,6 @@ Continuable child conversations and ordinary Sessions share one human inbox inte The generic Session command has one narrow ownership-fence exception for a live subagent-owned Agent with a valid own-suffix continuable identity. Because the operation addresses either inbox destination, a caller that knows a pending `MessageId` can edit or remove plugin-supplied next-step input, exactly as on an ordinary Session. QueueDock renders only `queued`-placement rows, so no browser gesture reaches that input; an edit there also keeps the original producer's `MessageSource`, which would attribute human text to that producer. -Inbox notifications retain their occurrence semantics and do not carry continuation residency. Claim and discard notifications only wake settlement after pending work changes; `whenIdle()`, the final idle-phase maintenance task, `Inbox.hasPending`, the owned-child set, the Activation generation, and the Session sequence decide whether disposal is safe without depending on scheduler ordering, message identity, or provenance. The final flush precedes the closing cutoff, so a detached hook, job completion, or direct Agent delivery accepted during that await invalidates the observation instead of being stopped by the resulting disposal. Maintenance that remains active prevents the final task from claiming the idle phase; maintenance that starts and finishes during the flush has completed before disposal. A child left holding only injected context remains resident even though no driver is obliged to claim it; without a later waking delivery, queue removal, or manager teardown, that child and its live ancestors can remain resident for the process lifetime. A replayed Inbox follows the same conservative rule without reconstructing how each pending message was delivered. +Inbox notifications retain their occurrence semantics and do not carry continuation residency. Claim and discard notifications only wake settlement after pending work changes; `whenIdle()`, the final idle-phase maintenance task, `Inbox.hasPending`, the owned-child set, the Activation generation, and the Session sequence decide whether disposal is safe without depending on scheduler ordering, message identity, or source. The final flush precedes the closing cutoff, so a detached hook, job completion, or direct Agent delivery accepted during that await invalidates the observation instead of being stopped by the resulting disposal. Maintenance that remains active prevents the final task from claiming the idle phase; maintenance that starts and finishes during the flush has completed before disposal. A child left holding only injected context remains resident even though no driver is obliged to claim it; without a later waking delivery, queue removal, or manager teardown, that child and its live ancestors can remain resident for the process lifetime. A replayed Inbox follows the same conservative rule without reconstructing how each pending message was delivered. Model-side scheduling remains fixed rather than caller-selectable. The adjacent-Agent `send_message` tool always uses Steer, while only the browser human path chooses Queue or Steer. diff --git a/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.i18n.yaml b/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.i18n.yaml index ffb1560ce8..0c14aed1d7 100644 --- a/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.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 .agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md -2026-09-02-in-history-system-prompt-replacement.md: 8e5fa65ec4649537889cefc75459d2a4958165e5 +2026-09-02-in-history-system-prompt-replacement.md: aaaf44d6388e6daf98acf8b1a93a61f1d7c55703 2026-09-02-in-history-system-prompt-replacement.zh.md: 73003b04de82f45154f9c673654cc492eb62a4fd diff --git a/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md b/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md index 8e5fa65ec4..aaaf44d638 100644 --- a/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md +++ b/.agents/notes/implemented/feature/2026-09-02-in-history-system-prompt-replacement.md @@ -47,7 +47,7 @@ Web presents an appended in-history node at its own position. `SystemPromptNode` Trajectory chooses the newer of the preceding real header and the preceding synthetic system header as the comparison state. A real header owns configuration and tools; an appended prompt can advance that state without another real header. Comparing only real headers would report A rather than B as the previous prompt for an A → B → C sequence. -Chat and Trajectory interpret the effective prompt through the pure `uiConversation.inspectSystemPrompt` operation. Each target keeps immutable prefix states for system events and positional replacements, with only surviving system nodes and a map of surviving replacement sequences to inherited surface positions. Each replacement copies that map and removes shadowed entries; historical prefix maps remain immutable. Ordinary appends and streaming updates require no prompt fold. Surface order, rather than event order or provenance citations, determines which nodes survive: a compaction can restore an older prompt without another system event, and a head rewrite can have a greater sequence than a later active prompt. Empty nodes remain addressable but do not override a nonempty prompt. An endpoint older than the earliest relevant loaded event has unknown order unless its replacement position is indexed. The interpreter withholds all subsequent prompt text after such an endpoint until prepend replay resolves the missing prefix; numeric event order cannot establish surface order. Historical cards keep their own prefix state rather than reading the final surface. +Chat and Trajectory interpret the effective prompt through the pure `uiConversation.inspectSystemPrompt` operation. Each target keeps immutable prefix states for system events and positional replacements, with only surviving system nodes and a map of surviving replacement sequences to inherited surface positions. Each replacement copies that map and removes shadowed entries; historical prefix maps remain immutable. Ordinary appends and streaming updates require no prompt fold. Surface order, rather than event order or source-event citations, determines which nodes survive: a compaction can restore an older prompt without another system event, and a head rewrite can have a greater sequence than a later active prompt. Empty nodes remain addressable but do not override a nonempty prompt. An endpoint older than the earliest relevant loaded event has unknown order unless its replacement position is indexed. The interpreter withholds all subsequent prompt text after such an endpoint until prepend replay resolves the missing prefix; numeric event order cannot establish surface order. Historical cards keep their own prefix state rather than reading the final surface. ### Compaction @@ -91,7 +91,7 @@ Lifecycle verification requires no event for an unchanged prompt and an appended - `packages/core/agent-loop/tests/system-prompt-projection.spec.ts` pins the append on a continuing series, the re-baseline at a series start with or without surviving later nodes and with changed or unchanged effective text, the empty-prompt clearing of all active versions, and the replace-only behaviour without the capability. - `packages/core/agent-loop/tests/request-reconstruction.spec.ts` pins the appended node under an inherited header with `request/context` carrying `systemPromptUpdate`, the series-start fold into node 0, the compaction-driven re-baseline, and the tool-schema change re-baseline under a `change` header that starts a series. - `packages/llm/llm/tests/service.spec.ts`, `packages/llm/llm-deepseek/tests/adapter.spec.ts`, and `packages/test-support/llm-replay/tests/llm-replay.spec.ts` pin the declared mode on resolved model info and the load-time rejection of any other value. -- `packages/llm/token-meter/tests/context-breakdown-projection.spec.ts` pins newest/middle prompt removal, exact heuristic totals, surface ordering after head rewrites, extra provenance citations, dormant empties and fallback clears, immutable transitions, compact retained checkpoints, late registration, replay, and version invalidation. +- `packages/llm/token-meter/tests/context-breakdown-projection.spec.ts` pins newest/middle prompt removal, exact heuristic totals, surface ordering after head rewrites, extra source-event citations, dormant empties and fallback clears, immutable transitions, compact retained checkpoints, late registration, replay, and version invalidation. - `packages/client/ui-conversation`, `ui-chat`, and `ui-trajectory` client specs pin the update card, the same-step header dedupe, the absent system change after an update, and the synthetic trajectory header. - The keyless authored snapshot `snapshots/session/system-prompt-in-history/` declares the capability on the replay route, changes the prompt after the first tool call through a fixture section, and pins the appended `system/message`, the untouched node 0, the single `request/header`, and the `request/context` mode. - `packages/llm/llm-deepseek/tests/adapter.e2e.ts` runs a two-step prompt change against the model named by `DEEPSEEK_IN_HISTORY_MODEL`, asserts that the reply follows the appended prompt, and asserts that the appended request reads more cached tokens than the same conversation with a rewritten leading prompt; it skips when the variable is unset. diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml index 5892d118ec..4326e893cf 100644 --- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.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 .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md -2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: 887a3666501a97e0930fe7eb4282603f537c17e8 -2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 0202be5c22c75ff4feec225cdff12b772d64d1cf +2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: 91f7913ff0cabafdd1c089e618d7864b9a085147 +2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 315850711adb234fa2bd9a92d9bd69fea5077230 diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md index 887a366650..91f7913ff0 100644 --- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md +++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md @@ -24,6 +24,8 @@ Before using `contract`, `boundary`, or `shape`, writers check whether the sente This decision complements the [documentation tiers and budgets](2026-07-04-doc-tiers-and-budgets.md) decision, which continues to own placement, document form, and word budgets. +The [blocked ambiguous origin label](2026-08-26-ban-ambiguous-origin-label.md) decision partially supersedes the sentence-level policy for one term after that term spread across unrelated contracts. + ## Alternatives considered **Ban a fixed list of words.** Rejected because a word may be an exact identifier or the clearest term in another contract. For example, caller/callee invariants are real contracts, and process or wire boundaries identify real divisions. Sentence-level review catches ambiguity without rejecting valid names. diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md index 0202be5c22..315850711a 100644 --- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md +++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md @@ -24,6 +24,8 @@ Status: implemented 该决策补充了[文档层级与字数预算](2026-07-04-doc-tiers-and-budgets.zh.md)决策;后者继续规定内容位置、文档形式和字数预算。 +[禁止有歧义来源名称](2026-08-26-ban-ambiguous-origin-label.zh.md)决策对其中一个术语部分取代了逐句判断规则,因为该术语已经扩散到互不相关的约定中。 + ## 曾考虑的替代方案 **禁止一份固定词表中的所有词。** 不予采纳:某个词可能是确切的标识符,也可能是另一项约定中最清楚的用词。例如,调用方与被调用方依赖的不变量属于真实的约定,进程边界或协议边界也表示真实分界。逐句审查可以找出歧义,且不会拒绝有效名称。 diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml index aec7f94a6a..ae1929ecc7 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.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 .agents/notes/implemented/process/2026-08-10-npm-release-sequences.md -2026-08-10-npm-release-sequences.md: 19e8d8db8550816f542111a9b831a3694a080de5 -2026-08-10-npm-release-sequences.zh.md: d057d77adbf35c20fc260203d3ef0db92e30f6b7 +2026-08-10-npm-release-sequences.md: 3a52c01494921cacd5df3053fb515461831d6007 +2026-08-10-npm-release-sequences.zh.md: f973b442f2bbf6400ef0b75650392744a489ace3 diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md index 19e8d8db85..3a52c01494 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md @@ -178,7 +178,7 @@ What this costs: - **The change judgement depends on visible tags.** A shallow clone, or a checkout without tags, degrades the vendored judgement to "publish everything for the first time". `fetch-depth: 0` is a precondition, not an optimization. - **The protocol rewrite touched 1504 dependency declarations.** It does not change local resolution — pnpm already resolves from the workspace — but it changes the ranges that go out. - **Private packages need credentials to install.** Every consumer — CI, sandbox e2e, outside users — needs scope credentials, including for the Landlock packages, which have never been published and so cut off no existing anonymous path. -- **`repository` names a different organization than the one running the workflows.** Token-based publication is unaffected; npm provenance (OIDC) requires the two to agree, so adopting it means either repointing `repository` or publishing from the organization it names. +- **`repository` names a different organization than the one running the workflows.** Token-based publication is unaffected; npm's OIDC attestation requires the two to agree, so adopting it means either repointing `repository` or publishing from the organization it names. - **Byte reproducibility is assumed, not measured.** The skip-on-identical-integrity state rests on packing the same commit twice producing the same bytes. Nothing measures that yet: if the build embeds absolute paths or timestamps, a re-run reports a false failure. Measure it before the first publication a re-run might follow, and fall back to comparing per-file content hashes if it does not hold. - **Re-running publish over an older artifact can move `latest` backwards.** Publication is decided per version, so an older set republished after a newer one takes the stable dist-tag again. The rehearsals run from a prerelease version, which never takes `latest`. - **The first publication is one large step.** Nine vendored packages and the whole dsh set publish at once, so any payload defect surfaces in a single release, which is why a prerelease version drives the complete path first. diff --git a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md index d057d77adb..f973b442f2 100644 --- a/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md +++ b/.agents/notes/implemented/process/2026-08-10-npm-release-sequences.zh.md @@ -178,7 +178,7 @@ dsh 的验证会一并安装 vendored 族的 pack 产物。harness 的包把 ven - **变更判据依赖 tag 可见。** shallow clone 或未拉 tag 会把 vendored 族的判据退化成「全部首发」。`fetch-depth: 0` 是前提,不是优化。 - **协议改写触及 1504 处依赖声明。** 它不改变本机解析(pnpm 本来就从 workspace 解析),但改变了发布出去的范围写法。 - **私有包需要凭据才能安装。** 任何消费方——CI、沙箱 e2e、外部使用者——都要持有 scope 凭据,Landlock 三包也在其中;它们从未发布过,所以没有切断既有的匿名安装路径。 -- **`repository` 指向的组织与运行 workflow 的组织不同。** 用 token 发布不受影响;npm provenance(OIDC)要求二者一致,届时要么把 `repository` 改指过去,要么从它指向的组织发布。 +- **`repository` 指向的组织与运行 workflow 的组织不同。** 用 token 发布不受影响;npm 的 OIDC attestation 要求二者一致,届时要么把 `repository` 改指过去,要么从它指向的组织发布。 - **字节可复现性是假定的,没有实测。** 「integrity 相同则跳过」这一态建立在「同一 commit 两次 pack 得到相同字节」之上。目前没有任何东西测量过它:若构建嵌入了绝对路径或时间,重跑会误报失败。在第一次可能被重跑的发布之前实测,若不成立就退到比对 tarball 内逐文件内容哈希。 - **用较旧的 artifact 重跑 publish 会把 `latest` 拉回旧版。** 发布是按版本决定的,所以在较新版本之后重发较旧的一批,会让稳定 dist-tag 再次指向旧版。排练用的是预发布版本,它永远不占 `latest`。 - **首发是一次大步。** 九个 vendored 包与整个 dsh 集一次发出,任何 payload 缺陷都会集中在同一次发布里暴露——这正是先用预发布版本把完整链路走一遍的理由。 diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.i18n.yaml b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.i18n.yaml similarity index 55% rename from .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.i18n.yaml rename to .agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.i18n.yaml index 70e7a16248..5221fa234d 100644 --- a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.i18n.yaml +++ b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.i18n.yaml @@ -1,6 +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 .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md -2026-09-06-agent-request-freeze-provenance.md: 1235a87ea549c6bbd9c53620017cb1d96f8e7cf7 -2026-09-06-agent-request-freeze-provenance.zh.md: 357b25b0f252a9423c485b2cc119f1226ec16687 +# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md +2026-08-26-ban-ambiguous-origin-label.md: fe06cf5d2dd43a09a2699a4dc48ff5791cffa65e +2026-08-26-ban-ambiguous-origin-label.zh.md: 1389d13992f5566d5b6091740e20433b06dd6e31 diff --git a/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md new file mode 100644 index 0000000000..fe06cf5d2d --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md @@ -0,0 +1,37 @@ +# Agent Note: Ban an ambiguous origin label + +Status: implemented + +English | [中文](2026-08-26-ban-ambiguous-origin-label.zh.md) + +## Problem + +The case-insensitive ten-letter ASCII token formed by `prove` followed by `nance` had accumulated unrelated meanings across the repository. It named source-event references, provider and model metadata, context producers, installed artifact identity, configuration origins, browser-recording evidence, and release attestations. A reader could not determine the recorded fact from the label alone. + +The existing [concrete prose decision](2026-08-09-concrete-prose-names-actors-and-recorded-facts.md) required sentence-level classification and normally preserved identifiers. That policy improved individual sentences but allowed the same ambiguous label to remain in APIs, durable compatibility fixtures, filenames, generated catalogs, and new prose. + +## Decision + +Maintained tracked paths and text must not contain that token in any case variant. Each use is replaced with the exact local concept, such as source-event references, provider metadata, model identity, context producer, configuration source, artifact identity, or recorded evidence. + +The rule applies to source, tests, documentation, active Agent Notes, prompts, snapshots, workflow files, scripts, identifiers, fields, exported types, and filenames. Because the repository is pre-release, coordinated public symbol and current durable-field renames are preferred over aliases. A compatibility reader may reconstruct the retired durable key at runtime without embedding the token in maintained text. + +`verify-concrete-terms` scans tracked filenames, symlink targets, and text case-insensitively after NFKC normalization. It runs as a quick leaf of `doc-sync`, and its tests prove rejection in prose, identifiers, and paths. Vendored sources and frozen archived Agent Notes remain excluded because their repository policies prohibit direct edits. + +This decision partially supersedes the earlier decision's rejection of fixed word bans and identifier renames for this one token. The earlier decision remains active for all other abstract language and for choosing each replacement according to its local meaning. + +## Alternatives considered + +**Continue semantic review without a mechanical ban.** Rejected because the label had already spread through unrelated contracts, and sentence-level review could not prevent recurrence in identifiers, fixtures, or filenames. + +**Replace every occurrence with one umbrella term such as `origin` or `source`.** Rejected because one new broad label would preserve the ambiguity between event references, model metadata, build identity, and recorded evidence. + +**Exempt identifiers, durable fields, and generated files.** Rejected because callers and generated reference material would continue teaching the retired label. The pre-release policy permits coordinated renames, while the legacy parser can retain read compatibility without retaining the literal token. + +**Scan vendored and archived sources.** Rejected because vendored content is updated through its synchronization procedure and archived Agent Notes are frozen records. Their explicit exclusions keep this policy consistent with those ownership rules. + +## Consequences + +Callers use more specific public names, and current recordings use provider metadata instead of the retired assistant field. Generated catalogs and recorded snapshots must be refreshed when an owning symbol changes. Compatibility code remains responsible for reading the retired durable field. + +Future uses fail `doc-sync` with the matching path or line. Reviews still classify the intended meaning before choosing a replacement; passing the gate proves absence of the token, not that the replacement is precise. diff --git a/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.zh.md b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.zh.md new file mode 100644 index 0000000000..1389d13992 --- /dev/null +++ b/.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.zh.md @@ -0,0 +1,37 @@ +# Agent Note: 禁止有歧义的来源名称 + +Status: implemented + +[English](2026-08-26-ban-ambiguous-origin-label.md) | 中文 + +## 问题 + +由 `prove` 与 `nance` 拼成的十个 ASCII 字母术语不区分大小写时,在仓库中已经承载了互不相关的含义。它曾表示来源事件引用、提供方与模型元数据、上下文生产方、已安装产物身份、配置来源、浏览器录制证据和发布证明。读者无法仅凭该名称判断实际记录的事实。 + +现有的[具体表述决策](2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md)要求逐句分类,且通常保留标识符。该规则改善了各个句子,却仍允许同一个有歧义名称留在 API、持久化兼容 fixture、文件名、生成目录和新行文中。 + +## 决策 + +仓库维护的已跟踪路径和文本不得包含该术语的任何大小写变体。每处使用都改为当前语境中的确切概念,例如来源事件引用、提供方元数据、模型身份、上下文生产方、配置来源、产物身份或已记录证据。 + +该规则适用于源码、测试、文档、活跃 Agent Note、提示词、快照、工作流文件、脚本、标识符、字段、导出类型和文件名。由于仓库尚未正式发布,公开符号与当前持久字段应协调重命名,而不是保留别名。兼容读取器可以在运行时构造已退役的持久键,无需在维护文本中嵌入该术语。 + +`verify-concrete-terms` 会在 NFKC 规范化后,不区分大小写地扫描已跟踪文件名、符号链接目标和文本。它作为 `doc-sync` 的快速叶子门禁运行;对应测试证明行文、标识符和路径中的违规都会被拒绝。vendored 源码与冻结的 archived Agent Note 仍被排除,因为各自的仓库规则禁止直接编辑这些内容。 + +本决策针对这一个术语,部分取代了旧决策中不采用固定禁词和标识符重命名的选择。旧决策仍适用于其他抽象语言,也仍负责要求根据每处使用的具体含义选择替代名称。 + +## 曾考虑的替代方案 + +**继续只做语义审查,不设置机械禁令。** 不予采纳:该名称已经扩散到互不相关的约定中,逐句审查无法防止它在标识符、fixture 或文件名中再次出现。 + +**用 `origin` 或 `source` 等单一总括术语替换所有位置。** 不予采纳:新的宽泛名称仍会混淆事件引用、模型元数据、构建身份和已记录证据。 + +**豁免标识符、持久字段和生成文件。** 不予采纳:调用方和生成的参考资料会继续传播已退役名称。预发布政策允许协调重命名,而旧格式解析器可以在不保留字面术语的情况下继续提供读取兼容性。 + +**扫描 vendored 与 archived 内容。** 不予采纳:vendored 内容通过同步流程更新,而 archived Agent Note 是冻结记录。明确排除两者,可以使本政策与对应的归属规则保持一致。 + +## 后果 + +调用方使用更具体的公开名称;当前录制使用提供方元数据,而不再使用已退役的 assistant 字段。归属符号变化后,生成目录和录制快照必须刷新。兼容代码仍负责读取已退役的持久字段。 + +以后新增的匹配项会使 `doc-sync` 失败,并报告对应路径或行号。审查仍需先判断预期含义再选择替代名称;通过门禁只能证明该术语不存在,不能证明替代名称足够精确。 diff --git a/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.i18n.yaml b/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.i18n.yaml index 6006f0447a..a331c0727e 100644 --- a/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.i18n.yaml +++ b/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.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 .agents/notes/implemented/process/2026-09-06-master-only-platform-ci.md -2026-09-06-master-only-platform-ci.md: d32864a4eafa81433c6d4fd0e47892b4d17091b1 +2026-09-06-master-only-platform-ci.md: fcdc413d644c1129635a7f33fe80bdec1b4a0b7a 2026-09-06-master-only-platform-ci.zh.md: 4fb55d5e95f8fe75e6d1efb8b57295b8e8469e8d diff --git a/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.md b/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.md index d32864a4ea..fcdc413d64 100644 --- a/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.md +++ b/.agents/notes/implemented/process/2026-09-06-master-only-platform-ci.md @@ -16,7 +16,7 @@ Wine runs once as an independent hosted Ubuntu master job. Its existing image-ke The [superseded-CI cancellation policy](2026-09-09-cancel-superseded-ci.md) applies to the parent and reusable runtime workflows: newer master pushes or manual runs cancel older validation in the same workflow/ref group, while release-owned builds remain protected. A master push schedules all three selected carriers but does not guarantee every intermediate commit reaches a result. -This decision partially supersedes scheduling in the [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md), [native Windows CI](2026-08-08-native-windows-pull-request-ci.md), [serial references](2026-07-21-serial-cross-platform-ci-reference.md), and [failover runbook](2026-07-26-ci-failover-runbook.md). Those notes remain active for artifact provenance, platform fidelity, serial completeness, and trust rules. +This decision partially supersedes scheduling in the [installed-wheel validation](../testing/2026-08-23-installed-python-wheel-black-box-ci.md), [native Windows CI](2026-08-08-native-windows-pull-request-ci.md), [serial references](2026-07-21-serial-cross-platform-ci-reference.md), and [failover runbook](2026-07-26-ci-failover-runbook.md). Those notes remain active for artifact origin, platform fidelity, serial completeness, and trust rules. ## Alternatives considered diff --git a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.i18n.yaml index 713c7e676b..11c416587f 100644 --- a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.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 .agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md -2026-08-09-explicit-schedule-time-zone.md: fd8a09df4c6f8b0003e6e01f48510ecb28d7e568 -2026-08-09-explicit-schedule-time-zone.zh.md: 3a840edda83edf70e65d6acf6a8874d1d47b09b5 +2026-08-09-explicit-schedule-time-zone.md: 2f23394e65d37f9eb714c2e55b0556cdf0bc967e +2026-08-09-explicit-schedule-time-zone.zh.md: aafa5d56853339e51b9a4265a32fca1a24e7b1dd diff --git a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md index fd8a09df4c..2f23394e65 100644 --- a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md +++ b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.md @@ -6,17 +6,17 @@ English | [中文](2026-08-09-explicit-schedule-time-zone.zh.md) ## Problem -Implicit local `at` input made a browser fact into shared product state. Capturing a default zone on Session creation required new Session headers, create/resume/fork conflict rules, JSONL metadata, a SQLite migration, client creation plumbing, Host comparisons, and Schedule logic coupled to time-context markers. Travel, concurrent tabs, missing provenance, and old Sessions then needed a confirmation protocol merely to decide whether an omitted field was safe. +Implicit local `at` input made a browser fact into shared product state. Capturing a default zone on Session creation required new Session headers, create/resume/fork conflict rules, JSONL metadata, a SQLite migration, client creation plumbing, Host comparisons, and Schedule logic coupled to time-context markers. Travel, concurrent tabs, missing browser-zone records, and old Sessions then needed a confirmation protocol merely to decide whether an omitted field was safe. Most of that complexity sat outside Schedule. The model already interprets natural language before it calls the tool, so a durable Session default duplicated an assumption instead of strengthening the absolute-time boundary. ## Decision -Browser zone is request-local provenance. The Web client samples `Intl.DateTimeFormat().resolvedOptions().timeZone` for every prompt. The Host accepts an optional `clientTimeZone`, validates and canonicalizes `UTC` or an IANA Area/Location at the RPC boundary, and logs it on that exact `user-rpc` message. Invalid values reject prompt admission. Non-browser clients may omit it. +The browser zone is request-local source data. The Web client samples `Intl.DateTimeFormat().resolvedOptions().timeZone` for every prompt. The Host accepts an optional `clientTimeZone`, validates and canonicalizes `UTC` or an IANA Area/Location at the RPC boundary, and logs it on that exact `user-rpc` message. Invalid values reject prompt admission. Non-browser clients may omit it. -Time-context derives unique, mixed, or missing browser facts from original user-rpc messages in the open turn. A unique zone formats the clock and tells the model to interpret otherwise-unqualified dates and times in that zone. Mixed or missing provenance tells the model to ask the user. The configured or process zone is only a display fallback and is never presented as user authority. +Time-context derives unique, mixed, or missing browser facts from original user-rpc messages in the open turn. A unique zone formats the clock and tells the model to interpret otherwise-unqualified dates and times in that zone. Mixed or missing browser-zone records tell the model to ask the user. The configured or process zone is only a display fallback and is never presented as user authority. -Schedule accepts no implicit local zone. `at` is either a strict offset-bearing RFC 3339 string or exact `{ date, time, time_zone }`. The structured form requires its zone even when time-context just showed the model a browser zone. Schedule does not import time-context, inspect user-message provenance, read a Session header, or produce a confirmation error. Its parser validates the explicit value, rejects daylight-saving gaps, chooses the first instant in overlaps, and stores only canonical UTC `scheduledAt`. +Schedule accepts no implicit local zone. `at` is either a strict offset-bearing RFC 3339 string or exact `{ date, time, time_zone }`. The structured form requires its zone even when time-context just showed the model a browser zone. Schedule does not import time-context, inspect user-message sources, read a Session header, or produce a confirmation error. Its parser validates the explicit value, rejects daylight-saving gaps, chooses the first instant in overlaps, and stores only canonical UTC `scheduledAt`. No Session time-zone field, create/resume/fork zone conflict, JSONL header field, SQLite column or migration, connection default, or Schedule-specific Host/client presentation remains. The browser assumption crosses into Schedule only through the model's explicit tool arguments. @@ -26,11 +26,11 @@ No Session time-zone field, create/resume/fork zone conflict, JSONL header field **Use the most recent browser zone as mutable Session state.** This reduces confirmation prompts but lets one tab silently change another tab's interpretation and makes replay depend on update ordering. -**Let Schedule inspect the latest time-context message.** A prose snapshot is model-visible evidence, not a typed package seam. Consuming it would couple Schedule to AgentLoop history and duplicate validation against original provenance. +**Let Schedule inspect the latest time-context message.** A prose snapshot is model-visible evidence, not a typed package seam. Consuming it would couple Schedule to AgentLoop history and duplicate validation against the original user-message sources. **Let the Host inject `time_zone` into tool calls.** The Host cannot know which natural-language expression the model interpreted or whether the user named another zone. Rewriting model arguments hides meaning at the wrong boundary. -**Require the model to ask on every unqualified time.** This is safe but unnecessarily interrupts the common browser-local case. The request-local instruction provides the intended assumption while mixed or missing provenance still asks. +**Require the model to ask on every unqualified time.** This is safe but unnecessarily interrupts the common browser-local case. The request-local instruction provides the intended assumption while mixed or missing browser-zone records still ask. ## Verification @@ -42,6 +42,6 @@ Source audits reject `SessionHeader.timeZone`, persistence `time_zone` columns, - Browser-local natural language works without a persisted Session-zone subsystem. - Schedule has one explicit, independently testable absolute-time boundary. -- Travel and concurrent tabs affect only their own prompts; a turn with mixed provenance asks instead of mutating shared state. +- Travel and concurrent tabs affect only their own prompts; a turn with mixed browser-zone records asks instead of mutating shared state. - Non-browser clients remain valid but must provide enough natural-language context or explicit tool arguments. - The model may still make an interpretation error; the tool guarantees only that the explicit calendar value is valid and deterministic. diff --git a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.zh.md b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.zh.md index 3a840edda8..aafa5d5685 100644 --- a/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.zh.md +++ b/.agents/notes/implemented/simplification/2026-08-09-explicit-schedule-time-zone.zh.md @@ -6,17 +6,17 @@ Status: implemented ## 问题 -隐式本地 `at` 输入把浏览器事实变成了共享产品状态。在 Session 创建时捕获默认时区,需要增加新的 Session header、create/resume/fork 冲突规则、JSONL metadata、SQLite migration、client 创建 plumbing、Host 比较,以及与 time-context 标记耦合的 Schedule 逻辑。随后,旅行、并发 tab、缺失 provenance 和旧 Session 都需要一套确认协议,仅仅为了判断省略字段是否安全。 +隐式本地 `at` 输入把浏览器事实变成了共享产品状态。在 Session 创建时捕获默认时区,需要增加新的 Session header、create/resume/fork 冲突规则、JSONL metadata、SQLite migration、client 创建 plumbing、Host 比较,以及与 time-context 标记耦合的 Schedule 逻辑。随后,旅行、并发 tab、缺失浏览器时区记录和旧 Session 都需要一套确认协议,仅仅为了判断省略字段是否安全。 大部分复杂度都位于 Schedule 之外。模型在调用工具前已经解释自然语言,因此持久 Session 默认值只是重复了一个假设,并没有强化绝对时间边界。 ## 决策 -浏览器时区是请求本地的 provenance。Web client 会为每条提示词采样 `Intl.DateTimeFormat().resolvedOptions().timeZone`。Host 接受可选的 `clientTimeZone`,在 RPC 边界校验并规范化 `UTC` 或 IANA Area/Location,再将其记录在确切的那条 `user-rpc` 消息上。无效值会使提示词准入被拒绝。非浏览器 client 可以省略它。 +浏览器时区是请求本地的来源数据。Web client 会为每条提示词采样 `Intl.DateTimeFormat().resolvedOptions().timeZone`。Host 接受可选的 `clientTimeZone`,在 RPC 边界校验并规范化 `UTC` 或 IANA Area/Location,再将其记录在确切的那条 `user-rpc` 消息上。无效值会使提示词准入被拒绝。非浏览器 client 可以省略它。 -Time-context 从 open turn 中的原始 user-rpc 消息派生唯一、混合或缺失的浏览器事实。唯一时区会用于格式化时钟,并告诉模型把未明确限定时区的日期和时间解释为该时区。provenance 混合或缺失时,模型会被告知询问用户。配置或进程时区只作为显示 fallback,绝不会被呈现为用户权威。 +Time-context 从 open turn 中的原始 user-rpc 消息派生唯一、混合或缺失的浏览器事实。唯一时区会用于格式化时钟,并告诉模型把未明确限定时区的日期和时间解释为该时区。浏览器时区记录混合或缺失时,模型会被告知询问用户。配置或进程时区只作为显示 fallback,绝不会被呈现为用户权威。 -Schedule 不接受隐式本地时区。`at` 要么是带显式偏移量且严格符合 RFC 3339 的字符串,要么是精确的 `{ date, time, time_zone }`。即使 time-context 刚向模型展示了浏览器时区,结构化形式仍要求自己的时区。Schedule 不导入 time-context、不检查 user message provenance、不读取 Session header,也不产生确认错误。它的 parser 会校验显式值、拒绝夏令时缺口、在重叠时选择第一个时点,并且只存储规范化后的 UTC `scheduledAt`。 +Schedule 不接受隐式本地时区。`at` 要么是带显式偏移量且严格符合 RFC 3339 的字符串,要么是精确的 `{ date, time, time_zone }`。即使 time-context 刚向模型展示了浏览器时区,结构化形式仍要求自己的时区。Schedule 不导入 time-context、不检查 user message 来源、不读取 Session header,也不产生确认错误。它的 parser 会校验显式值、拒绝夏令时缺口、在重叠时选择第一个时点,并且只存储规范化后的 UTC `scheduledAt`。 不再保留 Session 时区字段、create/resume/fork 时区冲突、JSONL header 字段、SQLite column 或 migration、连接默认值,也不再保留 Schedule 专属的 Host/client 呈现。浏览器假设只会通过模型的显式工具参数跨入 Schedule。 @@ -26,11 +26,11 @@ Schedule 不接受隐式本地时区。`at` 要么是带显式偏移量且严格 **把最近的浏览器时区用作可变 Session 状态。** 这会减少确认提示,却允许一个 tab 悄然改变另一个 tab 的解释,并使回放依赖更新顺序。 -**让 Schedule 检查最新的 time-context 消息。** prose snapshot(文本快照)是模型可见证据,而不是有类型的包 seam。消费它会使 Schedule 与 AgentLoop history 耦合,并针对原始 provenance 重复校验。 +**让 Schedule 检查最新的 time-context 消息。** prose snapshot(文本快照)是模型可见证据,而不是有类型的包 seam。消费它会使 Schedule 与 AgentLoop history 耦合,并针对原始 user message 来源重复校验。 **让 Host 向工具调用注入 `time_zone`。** Host 无法知道模型解释的是哪个自然语言表达式,也无法知道用户是否指定了另一个时区。重写模型参数会在错误的边界隐藏含义。 -**要求模型对每个未限定时区的时间都询问用户。** 这样做是安全的,却会不必要地打断常见的浏览器本地场景。请求本地指令提供预期假设,而 provenance 混合或缺失时仍会询问用户。 +**要求模型对每个未限定时区的时间都询问用户。** 这样做是安全的,却会不必要地打断常见的浏览器本地场景。请求本地指令提供预期假设,而浏览器时区记录混合或缺失时仍会询问用户。 ## 验证 @@ -42,6 +42,6 @@ Host 测试固定别名的规范化、可省略行为和进入 Agent(智能体 - 无需持久 Session 时区子系统,浏览器本地自然语言也能工作。 - Schedule 具有一个显式且可独立测试的绝对时间边界。 -- 旅行与并发 tab 只影响各自的提示词;provenance 混合的 turn 会询问用户,而不是改变共享状态。 +- 旅行与并发 tab 只影响各自的提示词;浏览器时区记录混合的 turn 会询问用户,而不是改变共享状态。 - 非浏览器 client 仍然有效,但必须提供足够的自然语言上下文或显式工具参数。 - 模型仍可能产生解释错误;工具只保证显式日历值有效且具有确定性。 diff --git a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.i18n.yaml index d848027401..57d6fb3b1f 100644 --- a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.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 .agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md -2026-08-28-omit-unneeded-invariant-companions.md: d4ab138d62a67c2c6666ae7998028fedb3a53580 -2026-08-28-omit-unneeded-invariant-companions.zh.md: 609bacd6b631bef3f77d373475107c1c677acb26 +2026-08-28-omit-unneeded-invariant-companions.md: 82d421677cb2f2a425c92e203766527aac7ce860 +2026-08-28-omit-unneeded-invariant-companions.zh.md: d0fda9154675d038c1f304609313654fc4e51f23 diff --git a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md index d4ab138d62..82d421677c 100644 --- a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md +++ b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.md @@ -18,7 +18,7 @@ A package publishes `./invariant` only when it can compare observations that may Service or method presence, plugin metadata or effects, fixed pure examples, and probes that call the same mutation they claim to verify remain type, load, unit, or integration-test concerns. Parser and config input, model or tool JSON, durable files, worker and process messages, and wire input remain validated at their owning input operation. -The `dsh-time-context` companion remains published. Its check compares the plugin-produced context message with independently owned current-turn user-message provenance and durable event time, so attribution, turn position, and elapsed-time relations can diverge even when the formatter itself is correct. +The `dsh-time-context` companion remains published. Its check compares the plugin-produced context message with independently owned current-turn user-message source and durable event time, so attribution, turn position, and elapsed-time relations can diverge even when the formatter itself is correct. ### Omission is explicit in the package README @@ -36,7 +36,7 @@ Existing package behavior tests remain responsible for omitted relationships, in - **Keep explained empty companions.** Rejected because a source file, public subpath, dependency edges, build output, and tests are disproportionate machinery for saying that no check exists; the package README records that conclusion directly. - **Keep the webserver probe as a teardown sentinel.** Rejected because it mutates a reserved route on unrelated lifecycle events and verifies only the service method it invokes. Real routing and HMR tests exercise the behavior without production diagnostic effects. -- **Treat every producer-format parser as self-validation.** Rejected because a parser can compare independent provenance, timing, or durable history even when one producer owns the text. `dsh-time-context` qualifies because its message is checked against current-turn user messages and durable event time; a same-writer payload round trip alone would not qualify. +- **Treat every producer-format parser as self-validation.** Rejected because a parser can compare independent source identity, timing, or durable history even when one producer owns the text. `dsh-time-context` qualifies because its message is checked against current-turn user messages and durable event time; a same-writer payload round trip alone would not qualify. - **Require every package with mutable private state to publish a companion.** Rejected because private state without an independent event or second data source cannot be checked without duplicating the implementation or exposing new API solely for diagnostics. ## Consequences diff --git a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.zh.md b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.zh.md index 609bacd6b6..d0fda91546 100644 --- a/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.zh.md +++ b/.agents/notes/implemented/simplification/2026-08-28-omit-unneeded-invariant-companions.zh.md @@ -18,7 +18,7 @@ Status: implemented 服务或方法是否存在、插件 metadata 或 effect、固定纯函数示例,以及调用同一变更操作来验证该操作的探针,仍属于类型、加载、单元或集成测试。parser 与 config 输入、模型或工具 JSON、持久文件、worker 与进程消息和 wire 输入,仍在拥有其输入的操作处校验。 -`dsh-time-context` 伴生入口继续发布。它把插件产生的 context message 与独立拥有的当前轮用户消息 provenance 和持久事件时间进行对照,因此即使 formatter 本身正确,attribution、轮次位置与 elapsed-time 关系仍可能产生分歧。 +`dsh-time-context` 伴生入口继续发布。它把插件产生的 context message 与独立拥有的当前轮用户消息 source 和持久事件时间进行对照,因此即使 formatter 本身正确,attribution、轮次位置与 elapsed-time 关系仍可能产生分歧。 ### 在包 README 中明确省略 @@ -36,7 +36,7 @@ Status: implemented - **保留带说明的空伴生入口。** 不采用:源文件、公共子路径、依赖边、构建输出和测试是一套过于繁重的机制,不应只用来表达不存在检查;包 README 可以直接记录该结论。 - **把 webserver 探针保留为清理 sentinel。** 不采用:它会在无关生命周期事件上修改保留路由,并且只验证自己调用的服务方法。真实路由与 HMR 测试可以在没有生产诊断 effect 的情况下覆盖该行为。 -- **把每个生产方格式 parser 都视为自校验。** 不采用:即使文本只有一个生产方,parser 仍可能对照独立 provenance、时间或持久历史。`dsh-time-context` 符合条件,因为其消息会与当前轮用户消息和持久事件时间对照;只对同一写入方的 payload 做往返检查不符合条件。 +- **把每个生产方格式 parser 都视为自校验。** 不采用:即使文本只有一个生产方,parser 仍可能对照独立 source identity、时间或持久历史。`dsh-time-context` 符合条件,因为其消息会与当前轮用户消息和持久事件时间对照;只对同一写入方的 payload 做往返检查不符合条件。 - **要求每个拥有私有可变状态的包都发布伴生入口。** 不采用:没有独立事件或第二数据源的私有状态只能通过重复实现来检查,或者需要专门为诊断暴露新 API。 ## 后果 diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.i18n.yaml new file mode 100644 index 0000000000..d2c8b4ead2 --- /dev/null +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.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 .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md +2026-09-06-agent-request-freeze-evidence.md: e597ba64ca31da5e6a9be0c32b922737c9a1c074 +2026-09-06-agent-request-freeze-evidence.zh.md: b56b14ca0d69261eddd46507deffba9fa945004c diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md similarity index 94% rename from .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md rename to .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md index 1235a87ea5..e597ba64ca 100644 --- a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md @@ -2,7 +2,7 @@ Status: implemented -English | [中文](2026-09-06-agent-request-freeze-provenance.zh.md) +English | [中文](2026-09-06-agent-request-freeze-evidence.zh.md) ## Problem @@ -28,7 +28,7 @@ Apple M4 Pro, macOS arm64, Node 24.19.0; independent worktree dependencies and b The same 800-turn, four-tools-per-historical-turn history and 40 live requests complete in every sample: 13,923 events, no live tool calls. The repeat median is 72.9% below the isolated original. The historical 70 ms M4 expectation rounds above both optimized medians; applying the shared 2× CI scale and 1.25× headroom produced the 175 ms budget used in the table. These remain local reference measurements, not hosted-runner expectations. The explicit hosted calibration below owns the enforced request-history budget; no other case or memory budget changes here. -The first optimized slot also measures cold tool continuation: totals 185.839958, 185.235583, 185.865917, 189.213459, 185.279417; median 185.839958 ms. Every sample completes 40 requests and 160 tool calls with 14,143 events. Retained heap samples are 22.591591, 22.590355, 22.594795, 22.591743, 22.594681 MiB, below the unchanged 28.75 MiB budget. The earlier baseline's approximately 22.295 MiB highlights the small provenance-table cost; weak keys prevent the table itself retaining replaced messages. +The first optimized slot also measures cold tool continuation: totals 185.839958, 185.235583, 185.865917, 189.213459, 185.279417; median 185.839958 ms. Every sample completes 40 requests and 160 tool calls with 14,143 events. Retained heap samples are 22.591591, 22.590355, 22.594795, 22.591743, 22.594681 MiB, below the unchanged 28.75 MiB budget. The earlier baseline's approximately 22.295 MiB highlights the small freeze-evidence table cost; weak keys prevent the table itself retaining replaced messages. The same slot's shipped SDK profile completes 100 turns, 200 requests, and 800 real reads per sample. Totals are 1428.555292, 1160.396333, 1139.843500, 1135.834750, 1155.890334 ms; median 1155.890334 ms. The first sample includes 461.829250 ms boot time versus 164–169 ms for the others and is retained, not discarded. Provider serialization, network time, and browser rendering remain excluded as specified by the baseline owner. @@ -70,7 +70,7 @@ Deterministic controls call the timed case's `assertRequestHistoryBudget`. They Request construction still scans message identities and allocates a fresh array; it avoids recursively traversing already-proven history. Each loop pays one complete traversal for restored history. Local headers remain a per-request cost. Message values, request markers, previous request snapshots, cancellation, and serialized SDK outputs keep their existing behavior. -The [focused tests](../../../../packages/core/agent-loop/tests/request-freeze.spec.ts) exercise shallow-frozen restored roots with mutable descendants, wrapper identity and mutability, successful-only provenance, repeated requests, same-id compaction replacements, a fresh loop, nested tool schemas, adapter and `NO_ADAPTER` stop arrays, held requests, and live cancellation. Reconstruction and cancellation suites cover adjacent loop semantics. Performance measurements use the unchanged [continuation workload](../../../../benchmarks/agent-continuation/workload.ts), not a smaller synthetic microbenchmark. +The [focused tests](../../../../packages/core/agent-loop/tests/request-freeze.spec.ts) exercise shallow-frozen restored roots with mutable descendants, wrapper identity and mutability, successful-only freeze evidence, repeated requests, same-id compaction replacements, a fresh loop, nested tool schemas, adapter and `NO_ADAPTER` stop arrays, held requests, and live cancellation. Reconstruction and cancellation suites cover adjacent loop semantics. Performance measurements use the unchanged [continuation workload](../../../../benchmarks/agent-continuation/workload.ts), not a smaller synthetic microbenchmark. Validation runs 646 Agent-loop and LLM tests with 100% statement, branch, function, and line coverage of agent.ts. Keyless TypeScript SDK bash-tool and multi-turn snapshots pass against rebuilt libraries. Python sdk-minimal and sdk-snapshot checks pass against an independently packaged node24-macos-arm64 executable. Neither SDK requires an expected-output change. The packaging deploy temporarily removes workspace dependency links; a frozen-lockfile install restores them before source checks, without a tracked dependency change. diff --git a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.zh.md similarity index 99% rename from .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md rename to .agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.zh.md index 357b25b0f2..b56b14ca0d 100644 --- a/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md +++ b/.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.zh.md @@ -2,7 +2,7 @@ Status: implemented -[English](2026-09-06-agent-request-freeze-provenance.md) | 中文 +[English](2026-09-06-agent-request-freeze-evidence.md) | 中文 ## 问题 diff --git a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.i18n.yaml b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.i18n.yaml index a27a7a3c2e..c7d4cb6a88 100644 --- a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.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 .agents/notes/implemented/simplification/2026-09-07-file-content-scan.md -2026-09-07-file-content-scan.md: 5c52a6346fb934a4c10be305dfc6393f87b43f6a -2026-09-07-file-content-scan.zh.md: 87463ba340f68820e49fd2194d0295a53b93eb3c +2026-09-07-file-content-scan.md: 5a539f0b9c4e00545d9894647599aed713285014 +2026-09-07-file-content-scan.zh.md: 9a8fe390b8b430baf7975bfc1391ccd09ae1db6e diff --git a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md index 5c52a6346f..5a539f0b9c 100644 --- a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md +++ b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md @@ -6,11 +6,11 @@ English | [中文](2026-09-07-file-content-scan.zh.md) ## Problem -Every model dispatch checks complete message content for files, including nested tool results. A request-history CPU profile attributes 23.540 ms of self time to `contentHasFile` and 5.584 ms to its callback. This traversal remains necessary even after [loop-owned freeze provenance](2026-09-06-agent-request-freeze-provenance.md) removes repeated request freezing. The hot LLM source is identical at master `bd5917`, master `112a5`, and the measured `f834b002826453e7918eeb558d052b2c24c56a76`; these observations do not establish PR causality. +Every model dispatch checks complete message content for files, including nested tool results. A request-history CPU profile attributes 23.540 ms of self time to `contentHasFile` and 5.584 ms to its callback. This traversal remains necessary even after [loop-owned freeze evidence](2026-09-06-agent-request-freeze-evidence.md) removes repeated request freezing. The hot LLM source is identical at master `bd5917`, master `112a5`, and the measured `f834b002826453e7918eeb558d052b2c24c56a76`; these observations do not establish PR causality. ## Decision -[`contentHasFile`](../../../../packages/llm/llm/src/content.ts) uses direct iteration instead of recursive `Array.some` callbacks. It preserves early exit, nested tool-result traversal, and false results for other block kinds. It stores no identities, validation results, or freeze proofs. Image detection, file projection, and request construction keep their existing behavior. The [request-freeze calibration](2026-09-06-agent-request-freeze-provenance.md) owns the request-history budget. +[`contentHasFile`](../../../../packages/llm/llm/src/content.ts) uses direct iteration instead of recursive `Array.some` callbacks. It preserves early exit, nested tool-result traversal, and false results for other block kinds. It stores no identities, validation results, or freeze proofs. Image detection, file projection, and request construction keep their existing behavior. The [request-freeze evidence](2026-09-06-agent-request-freeze-evidence.md) owns the request-history budget. ## Measurement evidence @@ -29,4 +29,4 @@ A weak negative-result cache needs proof that every relevant descendant is immut ## Consequences -The scan remains linear in visited blocks and rereads mutable nested content on each call. [Content tests](../../../../packages/llm/llm/tests/content.spec.ts) cover empty, frozen, nested, and subsequently mutated arrays; service tests preserve file-handle projection, and request-freeze, reconstruction, and resume tests preserve native-history semantics. No model-visible text or Session format changes. The freeze-provenance and [backend-baseline](../testing/2026-09-06-backend-continuation-performance.md) notes retain independent ownership; neither is superseded. +The scan remains linear in visited blocks and rereads mutable nested content on each call. [Content tests](../../../../packages/llm/llm/tests/content.spec.ts) cover empty, frozen, nested, and subsequently mutated arrays; service tests preserve file-handle projection, and request-freeze, reconstruction, and resume tests preserve native-history semantics. No model-visible text or Session format changes. The freeze-evidence and [backend-baseline](../testing/2026-09-06-backend-continuation-performance.md) notes retain independent ownership; neither is superseded. diff --git a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md index 87463ba340..9a8fe390b8 100644 --- a/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md +++ b/.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md @@ -6,11 +6,11 @@ Status: implemented ## Problem -每次模型分发都检查完整消息内容中的文件,包括嵌套工具结果。请求历史 CPU profile 将 23.540 ms 自身时间归于 `contentHasFile`,将 5.584 ms 归于其回调。即使[循环自有冻结来源证明](2026-09-06-agent-request-freeze-provenance.zh.md)消除了重复请求冻结,这次遍历仍然必需。master `bd5917`、master `112a5` 与实测的 `f834b002826453e7918eeb558d052b2c24c56a76` 的 LLM 热点源码完全相同;这些观察不能证明 PR 因果关系。 +每次模型分发都检查完整消息内容中的文件,包括嵌套工具结果。请求历史 CPU profile 将 23.540 ms 自身时间归于 `contentHasFile`,将 5.584 ms 归于其回调。即使[循环自有冻结证据](2026-09-06-agent-request-freeze-evidence.zh.md)消除了重复请求冻结,这次遍历仍然必需。master `bd5917`、master `112a5` 与实测的 `f834b002826453e7918eeb558d052b2c24c56a76` 的 LLM 热点源码完全相同;这些观察不能证明 PR 因果关系。 ## Decision -[`contentHasFile`](../../../../packages/llm/llm/src/content.ts) 使用直接迭代,替代递归的 `Array.some` 回调。它保留提前退出、嵌套工具结果遍历,以及其他块类型返回 false 的行为。它不存储身份、校验结果或冻结证明。图片检测、文件投影和请求构建保持既有行为。[请求冻结校准](2026-09-06-agent-request-freeze-provenance.zh.md)拥有请求历史预算。 +[`contentHasFile`](../../../../packages/llm/llm/src/content.ts) 使用直接迭代,替代递归的 `Array.some` 回调。它保留提前退出、嵌套工具结果遍历,以及其他块类型返回 false 的行为。它不存储身份、校验结果或冻结证明。图片检测、文件投影和请求构建保持既有行为。[请求冻结证据](2026-09-06-agent-request-freeze-evidence.zh.md)拥有请求历史预算。 ## Measurement evidence @@ -29,4 +29,4 @@ Apple M4 Pro、Node 24.19.0:九组交替原始/候选配对在全新的普通 ## Consequences -扫描仍与访问块数呈线性关系,每次调用都重新读取可变的嵌套内容。[内容测试](../../../../packages/llm/llm/tests/content.spec.ts)覆盖空数组、冻结数组、嵌套数组与后续变更的数组;服务测试保留文件 handle 投影,请求冻结、重建与恢复测试保留原生历史语义。模型可见文本与 Session 格式均不改变。冻结来源证明与[后端基线](../testing/2026-09-06-backend-continuation-performance.zh.md)记录仍各自拥有独立决策;两者均未被取代。 +扫描仍与访问块数呈线性关系,每次调用都重新读取可变的嵌套内容。[内容测试](../../../../packages/llm/llm/tests/content.spec.ts)覆盖空数组、冻结数组、嵌套数组与后续变更的数组;服务测试保留文件 handle 投影,请求冻结、重建与恢复测试保留原生历史语义。模型可见文本与 Session 格式均不改变。冻结证据与[后端基线](../testing/2026-09-06-backend-continuation-performance.zh.md)记录仍各自拥有独立决策;两者均未被取代。 diff --git a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml index 6593e72d9c..753fc7fdcd 100644 --- a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.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 .agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md -2026-08-23-installed-python-wheel-black-box-ci.md: 8821b93d0d1c5a32c7dbd97f67d78f7559769791 +2026-08-23-installed-python-wheel-black-box-ci.md: 8dfc6d7e344837b9663c1dbe5cff940731f53166 2026-08-23-installed-python-wheel-black-box-ci.zh.md: 05972560816193ff0b93323e6dcbea3ad5020215 diff --git a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md index 8821b93d0d..8dfc6d7e34 100644 --- a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md +++ b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md @@ -14,7 +14,7 @@ The Python SDK unit suite drives fake peers, while the packaged-runtime workflow The required Python runtime workflow builds the pure SDK wheel and each platform runtime wheel before behavior tests. Every native target installs those two local files into a new Python 3.10 virtual environment, changes to a temporary directory outside the repository, unsets `PYTHONPATH` and `DSH_RUNTIME_MODE`, and invokes only the public Python modules plus the packaged executable. -The black-box harness rejects a non-venv process, repository-relative working directory, source or editable import, unequal distribution versions, an SDK dependency that does not exactly pin the runtime version, an executable outside the installed runtime package, or an executable absent from the runtime distribution record. This provenance check runs before the first agent request, so a behavior pass cannot conceal that the wrong code ran. +The black-box harness rejects a non-venv process, repository-relative working directory, source or editable import, unequal distribution versions, an SDK dependency that does not exactly pin the runtime version, an executable outside the installed runtime package, or an executable absent from the runtime distribution record. This installed-artifact identity check runs before the first agent request, so a behavior pass cannot conceal that the wrong code ran. ### Keyless behavior diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.i18n.yaml index cd3854e92a..9105d8e0e9 100644 --- a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.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 .agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md -2026-09-06-backend-continuation-performance.md: 94e9192df473515d39014c8be9e82e0413df47bc -2026-09-06-backend-continuation-performance.zh.md: 92556ad8e3434a3219ea585503bec9b17bbf576a +2026-09-06-backend-continuation-performance.md: d72e3145d9bfe0ffabab2822c8a3313785fdd44f +2026-09-06-backend-continuation-performance.zh.md: 66085e1310fbfb92cb384875015d3baa648650c5 diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md index 94e9192df4..d72e3145d9 100644 --- a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.md @@ -39,7 +39,7 @@ The implementation reference is `925e012340f033f0521e802ba8569ce6dd7ef1ac` on Ap | Tool continuation | 358.953, 324.790, 318.861, 320.119, 322.896 | 324.280, 321.952, 340.409, 325.470, 324.312 | 322.896 / 324.312 | 340 | 850 | | Child catalog | 318.730, 309.006, 311.404, 308.565, 310.105 | 308.670, 310.030, 280.086, 303.084, 284.829 | 310.105 / 303.084 | 320 | 800 | -Continuation retains approximately 22.295 MiB; its source expectation is 23 MiB and its budget is 28.75 MiB. SDK time expectations use the existing [calibration helper](../../../../benchmarks/support/calibration.ts): 2× shared CI time scale and 1.25× variance headroom. Request history uses the direct hosted expectation in the [request-freeze calibration](../simplification/2026-09-06-agent-request-freeze-provenance.md), without the 2× scale. Memory uses only 1.25× headroom. The scale is inherited from the existing lane's calibration, not a new Linux measurement of these cases; CI evidence remains necessary when runner characteristics change. Baseline budgets protect the measured implementation; tighter budgets belong with a measured behavior-preserving fix. +Continuation retains approximately 22.295 MiB; its source expectation is 23 MiB and its budget is 28.75 MiB. SDK time expectations use the existing [calibration helper](../../../../benchmarks/support/calibration.ts): 2× shared CI time scale and 1.25× variance headroom. Request history uses the direct hosted expectation in the [request-freeze calibration](../simplification/2026-09-06-agent-request-freeze-evidence.md), without the 2× scale. Memory uses only 1.25× headroom. The scale is inherited from the existing lane's calibration, not a new Linux measurement of these cases; CI evidence remains necessary when runner characteristics change. Baseline budgets protect the measured implementation; tighter budgets belong with a measured behavior-preserving fix. A separate plain-Node request-history CPU profile attributes 132.876 ms of sampled self time to deepFreeze called by buildRequest during a 211.300 ms operation. This identifies repeated traversal of already-frozen history as a focused investigation target, not a proven optimization result. Catalog first/repeat timings remain separate because a second listing still reads body-bearing seeded children after observations are released. diff --git a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md index 92556ad8e3..66085e1310 100644 --- a/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md +++ b/.agents/notes/implemented/testing/2026-09-06-backend-continuation-performance.zh.md @@ -39,7 +39,7 @@ SDK fixture 通过 profile patch 显式插入 `fs-local` 和 `str_replace_editor | 工具续聊 | 358.953, 324.790, 318.861, 320.119, 322.896 | 324.280, 321.952, 340.409, 325.470, 324.312 | 322.896 / 324.312 | 340 | 850 | | 子会话目录 | 318.730, 309.006, 311.404, 308.565, 310.105 | 308.670, 310.030, 280.086, 303.084, 284.829 | 310.105 / 303.084 | 320 | 800 | -续聊保留约 22.295 MiB;源码期望值为 23 MiB,预算为 28.75 MiB。SDK 时间期望值使用现有[校准辅助函数](../../../../benchmarks/support/calibration.ts):2× 共享 CI 时间比例和 1.25× 波动余量。请求历史使用[请求冻结校准](../simplification/2026-09-06-agent-request-freeze-provenance.zh.md)中的直接托管期望值,不乘以 2× 比例。内存只使用 1.25× 余量。比例继承现有通道的校准,并非这些用例的新 Linux 实测值;runner 特征变化时仍需 CI 证据。基线预算保护实测实现;更紧预算属于有测量依据且保持行为的修复。 +续聊保留约 22.295 MiB;源码期望值为 23 MiB,预算为 28.75 MiB。SDK 时间期望值使用现有[校准辅助函数](../../../../benchmarks/support/calibration.ts):2× 共享 CI 时间比例和 1.25× 波动余量。请求历史使用[请求冻结校准](../simplification/2026-09-06-agent-request-freeze-evidence.zh.md)中的直接托管期望值,不乘以 2× 比例。内存只使用 1.25× 余量。比例继承现有通道的校准,并非这些用例的新 Linux 实测值;runner 特征变化时仍需 CI 证据。基线预算保护实测实现;更紧预算属于有测量依据且保持行为的修复。 独立的纯 Node 请求历史 CPU profile 在一次 211.300 ms 操作中,将 132.876 ms 采样自身时间归因于 buildRequest 调用的 deepFreeze。这把重复遍历已冻结历史定位为聚焦调查目标,不是已证实的优化结果。目录首次/重复时间分别保留,因为观察释放后第二次列举仍读取带种子子会话的正文。 diff --git a/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.i18n.yaml b/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.i18n.yaml index f9f26d4043..834bf27d4b 100644 --- a/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.i18n.yaml +++ b/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.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 .agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.md -2026-09-06-python-runtime-install-retry.md: c52e87c2d18393113c0e884d7e6d1e56cc6e6145 +2026-09-06-python-runtime-install-retry.md: 639fe2814ae1b3beadcd47d3b9eac15408c585cc 2026-09-06-python-runtime-install-retry.zh.md: 7a7943f43fcec536542c5aef0e608e177f64907f diff --git a/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.md b/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.md index c52e87c2d1..639fe2814a 100644 --- a/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.md +++ b/.agents/notes/implemented/testing/2026-09-06-python-runtime-install-retry.md @@ -10,7 +10,7 @@ The Python runtime lane's `Install (immutable)` step runs `pnpm install` on ever ## Decision -The install step retries `pnpm install --frozen-lockfile` up to three attempts total with a ten-second pause between failures, running under `bash` on every platform (Git Bash is on the hosted Windows images). Success on any attempt ends the step immediately; a file-lock check or native-build error that would fail every attempt still fails the step after the bounded budget. This mirrors the Wine lane's documented bounded-transfer policy without pulling in a mirror, because these installs also resolve native addons whose second-download provenance matters. +The install step retries `pnpm install --frozen-lockfile` up to three attempts total with a ten-second pause between failures, running under `bash` on every platform (Git Bash is on the hosted Windows images). Success on any attempt ends the step immediately; a file-lock check or native-build error that would fail every attempt still fails the step after the bounded budget. This mirrors the Wine lane's documented bounded-transfer policy without pulling in a mirror, because these installs also resolve native addons whose second-download source matters. ## Alternatives considered diff --git a/.agents/skills/dsh-trim-cot-leakage/SKILL.md b/.agents/skills/dsh-trim-cot-leakage/SKILL.md index fb49a23b7f..cd26b03891 100644 --- a/.agents/skills/dsh-trim-cot-leakage/SKILL.md +++ b/.agents/skills/dsh-trim-cot-leakage/SKILL.md @@ -30,7 +30,7 @@ Unaided citation passes fail in both directions by deleting durable references a - **Merged-PR and issue citations inside Agent Notes and postmortems** — sanctioned evidence per the [documentation standard](../../../docs/AGENTS.md)'s change-story routing. - **Suppression justifications** — `oxlint-disable … -- reason`, coverage-ignore reasons, empty-catch explanations are required prose; fix a false reason, never delete it. - **Counterfactual-present regression pins** — "without X, Y happens", "a naive X would…". -- **Measured bounds** — "(measured: 512 nests ≈ 0.15s)" calibrating a constant; the provenance word "measured" is load-bearing. +- **Measured bounds** — "(measured: 512 nests ≈ 0.15s)" calibrating a constant; the evidence word "measured" is load-bearing. - **Runtime old/new states** — "the old connection drains before the new one accepts" is runtime lifecycle, not change history. - **Historical stage names inside a note's change-story sections** — "the first cut shipped X" is current-state-safe there; indexical stamps ("this cut") stay banned everywhere. - **External references that resolve outside the repo by design** — standards sections (RFC 9110 §10.1.5), Figma frame names; the §-ban covers uncommitted internal drafts, not external standards or committed docs that own their §-numbering. @@ -41,5 +41,5 @@ Unaided citation passes fail in both directions by deleting durable references a 1. Scope and exclusions per [dsh-prose-standard](../dsh-prose-standard/SKILL.md): require an explicit scope; never touch `vendor/` or `.agents/notes/archived/`. Recorded fixtures and snapshots are derivatives, not prose targets: change the owning source or scenario and regenerate them only when an authorized behavior change requires new evidence. 2. Audit read-only first: run the [recall batteries](references/recall-batteries.md) (with `--hidden` so `.agents/` is searched), calibrating each probe against a known positive and a near-miss negative before trusting its output, then judge every hit semantically. The batteries are probes, not the definition — each review round of the original purge found cases the batteries missed, so also read the densest prose in scope (module JSDoc, READMEs, Agent Notes) without a pattern in hand. 3. Fix owner-first per surface: generated catalogs → trace every consumer, fix the source JSDoc or generator template, then regenerate all derivatives; type-equivalence fences → fix the source JSDoc, then re-paste both bilingual pages (`verify-type-equiv` pins them); bilingual prose → update the counterpart minimally and re-record it through the [lightweight routine](../../../docs/AGENTS.md#writing-rules); bilingual fences → copy the corrected verbatim block byte-for-byte into both sides per [dsh-doc](../dsh-doc/SKILL.md), then re-record the pair; model- or user-visible strings → route through [dsh-prose-standard](../dsh-prose-standard/SKILL.md) and change only with owning behavior evidence, otherwise leave unchanged and report the deferral. -4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop provenance. +4. Before deleting anything, enumerate the passage's propositions (prose-standard) and check the [overcorrection traps](references/examples.md#overcorrection-traps): trims that flip an obligation into an endorsement, promote a hypothetical to a shipped feature, delete a true fact, or drop the evidence source. 5. Verify: re-run the batteries expecting only sanctioned keeps, this skill's own directory, and the owning note's quoted evidence; confirm every remaining citation resolves at HEAD; run the gates for touched surfaces (`doc-sync` for docs, `verify-type-equiv`, `verify-translation-pairing`). diff --git a/.agents/skills/dsh-trim-cot-leakage/references/examples.md b/.agents/skills/dsh-trim-cot-leakage/references/examples.md index a0db4fbb26..1d67019c66 100644 --- a/.agents/skills/dsh-trim-cot-leakage/references/examples.md +++ b/.agents/skills/dsh-trim-cot-leakage/references/examples.md @@ -174,7 +174,7 @@ Replace the hedge with the actual bound and the failure behavior when it is exce **Fixed:** "The renderer runs on the client side; spacing follows the Figma frame `widget-badges`." -Working-language fragments and session separators are transcription residue. The Figma frame name stays: external provenance that resolves outside the repo by design. +Working-language fragments and session separators are transcription residue. The Figma frame name stays: an external source that resolves outside the repo by design. ### Authoring-language slip inside a paired fence @@ -216,7 +216,7 @@ The justification clause is required prose. When the stated reason is false (the **Keep:** "Depth cap (measured: 512 nests ≈ 0.15s synchronous; 4096 blocks the loop)." -The measurement pins the constant against uninformed retuning, and "measured" is the provenance that distinguishes data from a guess. +The measurement pins the constant against uninformed retuning, and "measured" identifies data rather than a guess. ### Runtime old/new is not change history @@ -264,7 +264,7 @@ Deleting the future-marker alone turns a design illustration into a claim that t Half the sentence was narration; the other half was a load-bearing coupling. Delete clauses, not sentences, when propositions share a line. -### Dropping provenance while keeping the number +### Dropping the measurement source while keeping the number **Original:** "The 4 MiB ceiling is measured: the largest generated `py-types` module is 3.1 MiB." diff --git a/.agents/skills/record-browser-gif/SKILL.md b/.agents/skills/record-browser-gif/SKILL.md index 9222144902..b425b35b6f 100644 --- a/.agents/skills/record-browser-gif/SKILL.md +++ b/.agents/skills/record-browser-gif/SKILL.md @@ -33,9 +33,9 @@ A GIF for a specific pull request demonstrates that pull request's tree, so stag ## Record the flow -Follow the available browser-control workflow's setup, interaction, and cleanup instructions. When it exposes `recordVideo`, enable video on the same controlled context to capture more intermediate frames. Otherwise use [screenshot capture](#screenshot-capture) within that workflow; video availability does not determine which browser-control workflow to use. Existing user browser state remains an explicit provenance exception. +Follow the available browser-control workflow's setup, interaction, and cleanup instructions. When it exposes `recordVideo`, enable video on the same controlled context to capture more intermediate frames. Otherwise use [screenshot capture](#screenshot-capture) within that workflow; video availability does not determine which browser-control workflow to use. Existing user browser state remains an explicit isolation exception. -Only when browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser and state that fallback in the provenance. In this repository it resolves from `apps/web/package.json`; do not install another driver or open the user's browser. +Only when browser control is unavailable, use the repository-declared Playwright dependency in an isolated headless browser and state that fallback in the capture notes. In this repository it resolves from `apps/web/package.json`; do not install another driver or open the user's browser. Before recording, identify the origin, built or development server, transport, and any mode overrides. When a production default opens a native surface that automation cannot drive, select an official browser-operable production backend through normal application configuration and disclose the override. diff --git a/.github/workflows/python-release.yml b/.github/workflows/python-release.yml index f3d9ab44c3..b756f5bf38 100644 --- a/.github/workflows/python-release.yml +++ b/.github/workflows/python-release.yml @@ -211,7 +211,7 @@ jobs: with: packages-dir: dist/runtime/ # Public attestations reveal the private publisher repository. OIDC - # authentication remains enabled without uploading that provenance. + # authentication remains enabled without uploading that repository identity. attestations: false # Keep the SDK in a dependent job. If its upload fails after the immutable diff --git a/AGENTS.md b/AGENTS.md index b5b8d0295c..3c02822625 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -119,8 +119,9 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, - **Trust TypeScript at typed same-process boundaries.** Do not add runtime validation, fallback behavior, or hostile-input tests solely for values the static interface requires; validate at parser/config, queued, model/tool JSON, durable/file, worker, process, and wire boundaries. - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)). - **Keep compiler faces explicit.** A package with both Host and Client programs exposes face-specific leaf configs and a solution-only root; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)). -- **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement. -- **Keep comments local.** Do not restate code, explain distant behavior unless locally required, or expand unrelated comments ([rationale](.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). +- **An empty `catch` names the swallowed error** and why; keep its `try` to one statement. +- **Keep comments local.** Do not restate code, expand unrelated comments, or explain distant behavior without local need ([rationale](.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). +- **Ban `prove` + `nance`** ([rule](.agents/notes/implemented/process/2026-08-26-ban-ambiguous-origin-label.md)). - **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction. - **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR. - **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)). diff --git a/apps/cli/src/profile-boot.ts b/apps/cli/src/profile-boot.ts index 1c50e1b581..2de773c5d8 100644 --- a/apps/cli/src/profile-boot.ts +++ b/apps/cli/src/profile-boot.ts @@ -336,7 +336,7 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => { app.current = hostCtx // Before any config-tree entry mounts, so plugins resolve all launch-time - // environment values from the same immutable provenance snapshot. + // environment values from the same immutable launch snapshot. hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, options.environment) // The command line and bounded exit request are launcher facts available // to every app plugin that injects the argument snapshot. diff --git a/apps/cli/tests/github-webhook-real.e2e.ts b/apps/cli/tests/github-webhook-real.e2e.ts index f6583c79fa..45e4330ca8 100644 --- a/apps/cli/tests/github-webhook-real.e2e.ts +++ b/apps/cli/tests/github-webhook-real.e2e.ts @@ -412,7 +412,7 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('GitHub webhook through the real const admitted = await eventually( child, observation.text, - 'webhook provenance, title, and permission events', + 'webhook source, title, and permission events', async () => await history(baseUrl, sessionId), (page) => { const events = historyEvents(page) diff --git a/benchmarks/agent-continuation/README.i18n.yaml b/benchmarks/agent-continuation/README.i18n.yaml index c13ad6f35d..3e8b5a92e3 100644 --- a/benchmarks/agent-continuation/README.i18n.yaml +++ b/benchmarks/agent-continuation/README.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 benchmarks/agent-continuation/README.md -README.md: 489939499af8d98922df2cbbdd6be793bf6e3796 -README.zh.md: e51fac2d0df005de9d609cb634778f30b537ae41 +README.md: 98a8f837b9021ee7efbf40c2275362185a215ca9 +README.zh.md: 1b7d0d3efd9b8ee4be8f4acf48fc97af11d3fd3e diff --git a/benchmarks/agent-continuation/README.md b/benchmarks/agent-continuation/README.md index 489939499a..98a8f837b9 100644 --- a/benchmarks/agent-continuation/README.md +++ b/benchmarks/agent-continuation/README.md @@ -18,7 +18,7 @@ Measure long-history request processing, cold tool-heavy continuation, and repea From the repository root, build the libraries and workers with `pnpm run build:bench`, then run `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/agent-continuation/agent-continuation.bench.ts`. Do not overlap timing runs with builds or other benchmarks. -The test reports all five fresh-process samples, CPU models, available parallelism, platform/architecture, and Node/V8 versions, and enforces reviewed median budgets. Catalog and tool continuation each use a 900 ms standard hosted CI expectation with 1.25× headroom (1,125 ms); request history uses a separately reviewed 297 ms hosted limit ([calibration](../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md)), and SDK continuation uses reference-machine scaling. A failed worker reports its exit, signal, timeout, and stderr; temporary roots are removed even on failure. The required benchmark lane discovers this file automatically. +The test reports all five fresh-process samples, CPU models, available parallelism, platform/architecture, and Node/V8 versions, and enforces reviewed median budgets. Catalog and tool continuation each use a 900 ms standard hosted CI expectation with 1.25× headroom (1,125 ms); request history uses a separately reviewed 297 ms hosted limit ([evidence](../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md)), and SDK continuation uses reference-machine scaling. A failed worker reports its exit, signal, timeout, and stderr; temporary roots are removed even on failure. The required benchmark lane discovers this file automatically. diff --git a/benchmarks/agent-continuation/README.zh.md b/benchmarks/agent-continuation/README.zh.md index e51fac2d0d..1b7d0d3efd 100644 --- a/benchmarks/agent-continuation/README.zh.md +++ b/benchmarks/agent-continuation/README.zh.md @@ -18,7 +18,7 @@ 在仓库根目录使用 `pnpm run build:bench` 构建库和 worker,然后运行 `pnpm exec vitest run --config vitest.bench.config.ts benchmarks/agent-continuation/agent-continuation.bench.ts`。不要让计时运行与构建或其他基准重叠。 -测试报告全部五个新进程样本、CPU 型号、可用并行度、平台/架构和 Node/V8 版本,并约束经审查的中位数预算。目录和工具续聊用例均使用标准托管 CI 的 900 ms 期望值与 1.25× 余量(1,125 ms);请求历史使用单独审查的 297 ms 托管上限([校准依据](../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md)),SDK 续聊使用参考机器缩放。worker 失败时报告退出状态、信号、超时和 stderr;失败时也会删除临时根目录。必需基准通道自动发现此文件。 +测试报告全部五个新进程样本、CPU 型号、可用并行度、平台/架构和 Node/V8 版本,并约束经审查的中位数预算。目录和工具续聊用例均使用标准托管 CI 的 900 ms 期望值与 1.25× 余量(1,125 ms);请求历史使用单独审查的 297 ms 托管上限([证据](../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.zh.md)),SDK 续聊使用参考机器缩放。worker 失败时报告退出状态、信号、超时和 stderr;失败时也会删除临时根目录。必需基准通道自动发现此文件。 diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml index e71254886c..799699d836 100644 --- a/docs/architecture.i18n.yaml +++ b/docs/architecture.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 docs/architecture.md -architecture.md: 2a3c291c5acb7e94bd1f666609af901e928671bc +architecture.md: 4c8b78554cd744838a26da9bde39a405b275b739 architecture.zh.md: 0eea56b18ae79b297178dfb831ce78e5aed66699 diff --git a/docs/architecture.md b/docs/architecture.md index 2a3c291c5a..4c8b78554c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -108,7 +108,7 @@ Input reaches the driver through one inbox. Some messages wake it immediately; i `agent/pre-step` decides the accepted input. Listeners may rewrite or reject claimed messages; a rejected or empty first claim closes a durable turn without a step. An enter decision may set `startsRequestSeries`: the loop logs a fresh `request/header` (reason `series`, or `change` with `startsSeries: true` when the envelope also changed). Wrapping listeners preserve that declaration with `{ ...decision, messages }`. After assembly and `step/start`, `agent/request` and `prepareCall()` resolve the actual route before the system prompt and accepted users are committed; cancellation during either async phase commits neither. The prepared call capability governs prompt admission, not the preceding `request/context`. Every attempt synchronously reconciles the same rendered assembly, appends users only on the first attempt, logs header/context as needed, and derives and freezes the request before streaming the bound call. Retries do not repeat assembly or `agent/pre-step`. Surface replacements after attachment start a new request series, including during the first resumed pre-step; unchanged resume continues the series. The first admitted step reserves the system head before user messages even for an empty prompt (no wire message). The prompt travels only as `system/message` history: an empty rendering clears all active system nodes, leaving no old prompt model-visible; capable routes can append non-empty updates after the cached prefix; incapable routes and new request series consolidate non-empty prompt text at the first system node, with logged empty replacements for non-empty later system nodes ([decision](../.agents/notes/implemented/architecture/2026-09-02-system-prompt-as-surface-node.md); [decision rule](../packages/core/agent-loop/README.md#understand-the-implementation)). -The loop sends immutable requests while keeping cancellation live. It reuses message-freeze provenance only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction rules. +The loop sends immutable requests while keeping cancellation live. It reuses message-freeze evidence only for identities it has fully frozen; [agent-loop](../packages/core/agent-loop/README.md) owns the request construction rules. Details: the [sequence diagram](agent-lifecycle.md), the [tool pipeline](tool-execution-pipeline.md), and [cancellation and error recovery](subsystems/core.md#the-agent-handle). diff --git a/docs/deepseek-llm-api-wire-extensions.i18n.yaml b/docs/deepseek-llm-api-wire-extensions.i18n.yaml index e0b7be4a17..f73024d8f0 100644 --- a/docs/deepseek-llm-api-wire-extensions.i18n.yaml +++ b/docs/deepseek-llm-api-wire-extensions.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 docs/deepseek-llm-api-wire-extensions.md -deepseek-llm-api-wire-extensions.md: a6689c97670260a7b673fc73d455726e357fd022 +deepseek-llm-api-wire-extensions.md: 28a320fc277f82dcc69b7f335cd94d02a562e282 deepseek-llm-api-wire-extensions.zh.md: 9f54d78609186055d3ac5e3b9b4f4272c7304e83 diff --git a/docs/deepseek-llm-api-wire-extensions.md b/docs/deepseek-llm-api-wire-extensions.md index a6689c9767..28a320fc27 100644 --- a/docs/deepseek-llm-api-wire-extensions.md +++ b/docs/deepseek-llm-api-wire-extensions.md @@ -67,7 +67,7 @@ Every request re-reads active non-group Loader entries from the host tree and, w The sender deduplicates exact `(name, version)` pairs and sorts first by `name`, then by `version`, with a locale-independent text comparison. Simultaneously active versions of one package remain separate entries. Receivers must not collapse the array by package name or infer package activation from array order. -Disabled, pending, failed, unloading, disposed, and structural Loader entries are absent. Ordinary dependencies, loose modules without a named owning package, programmatically mounted child fibers, and in-memory dynamic plugins are also absent because they have no authoritative Loader package provenance. +Disabled, pending, failed, unloading, disposed, and structural Loader entries are absent. Ordinary dependencies, loose modules without a named owning package, programmatically mounted child fibers, and in-memory dynamic plugins are also absent because they have no authoritative Loader-backed package identity. An enabled inventory with no qualifying entries sends `packages: []`; disabling the contributor omits the entire `dsh_plugin_packages` field. Package identities are provider metadata and never enter model input. diff --git a/docs/subsystems/llm-streaming.i18n.yaml b/docs/subsystems/llm-streaming.i18n.yaml index d543a5f4e7..26ddf5d641 100644 --- a/docs/subsystems/llm-streaming.i18n.yaml +++ b/docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md -llm-streaming.md: 28492b46435e3288609129b0dfc5cb40dd5f7296 -llm-streaming.zh.md: fe02e2ebe5b558162e849e26ff05b8d633c07ba0 +llm-streaming.md: e42d5f0c4a4e5273926ca8a58b3f060637da43dc +llm-streaming.zh.md: 727b327e31421477891955383bebbbe1a9e1b5fb diff --git a/docs/subsystems/llm-streaming.md b/docs/subsystems/llm-streaming.md index 28492b4643..e42d5f0c4a 100644 --- a/docs/subsystems/llm-streaming.md +++ b/docs/subsystems/llm-streaming.md @@ -49,7 +49,7 @@ A `Message` is one identified, immutable role/source/content value. Model-produc ```ts type-equiv /** Provider/model identity and adapter-private replay data for an assistant message. */ -interface AssistantProvenance { +interface AssistantProviderMetadata { /** Provider route that produced the message. */ provider: string /** Provider model id that produced the message. */ @@ -97,7 +97,7 @@ Producer identity and presentation form are independent. `kind` answers *who pro ```ts type-equiv /** * The kind of information in producer-supplied context, declared by the - * producer beside its provenance. + * producer in the same `MessageSource`. * * `MessageSource.kind` answers *who produced this*; `form` answers *what kind * of thing it is*, and the two axes are deliberately independent — several diff --git a/docs/subsystems/llm-streaming.zh.md b/docs/subsystems/llm-streaming.zh.md index fe02e2ebe5..727b327e31 100644 --- a/docs/subsystems/llm-streaming.zh.md +++ b/docs/subsystems/llm-streaming.zh.md @@ -49,7 +49,7 @@ interface ImageAttachmentAccess { ```ts type-equiv /** Provider/model identity and adapter-private replay data for an assistant message. */ -interface AssistantProvenance { +interface AssistantProviderMetadata { /** Provider route that produced the message. */ provider: string /** Provider model id that produced the message. */ @@ -97,7 +97,7 @@ interface MessageSourceMap { ```ts type-equiv /** * The kind of information in producer-supplied context, declared by the - * producer beside its provenance. + * producer in the same `MessageSource`. * * `MessageSource.kind` answers *who produced this*; `form` answers *what kind * of thing it is*, and the two axes are deliberately independent — several diff --git a/docs/subsystems/schedule.i18n.yaml b/docs/subsystems/schedule.i18n.yaml index 3e13e79724..58c4a9363b 100644 --- a/docs/subsystems/schedule.i18n.yaml +++ b/docs/subsystems/schedule.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 docs/subsystems/schedule.md -schedule.md: 82d221260ec4ca1411ab981801d89226753703b2 -schedule.zh.md: f60edcc53d610aa29afed36fce10b100c401e27c +schedule.md: b92b81c6f24773b8cbafea5fccd7ac16df07ccd3 +schedule.zh.md: a3e6a4e5f82223526f0ec84e60e5c752e6f65f9a diff --git a/docs/subsystems/schedule.md b/docs/subsystems/schedule.md index 82d221260e..b92b81c6f2 100644 --- a/docs/subsystems/schedule.md +++ b/docs/subsystems/schedule.md @@ -85,7 +85,7 @@ interface LocalAtInput { type AtInput = string | LocalAtInput ``` -The official Web overlay samples the browser's IANA zone for every prompt. Time-context tells the model to interpret otherwise-unqualified natural-language dates and times in that request-local zone when the open turn has one unambiguous browser zone; mixed or missing provenance tells the model to ask. That guidance is not a durable Session default: the model must still pass an offset in the string form or `time_zone` in the local form, and Schedule never reads browser, Session, process, or model context. +The official Web overlay samples the browser's IANA zone for every prompt. Time-context tells the model to interpret otherwise-unqualified natural-language dates and times in that request-local zone when the open turn has one unambiguous browser zone; mixed or missing browser-zone records tell the model to ask. That guidance is not a durable Session default: the model must still pass an offset in the string form or `time_zone` in the local form, and Schedule never reads browser, Session, process, or model context. Schedule rejects invalid offsets and zones, offset-free strings, non-future targets, and local times inside daylight-saving gaps. A daylight-saving overlap chooses its first, earlier instant. Successful creation stores only canonical UTC `scheduledAt`, so replay never depends on ambient time-zone state. diff --git a/docs/subsystems/schedule.zh.md b/docs/subsystems/schedule.zh.md index f60edcc53d..a3e6a4e5f8 100644 --- a/docs/subsystems/schedule.zh.md +++ b/docs/subsystems/schedule.zh.md @@ -85,7 +85,7 @@ interface LocalAtInput { type AtInput = string | LocalAtInput ``` -官方 Web overlay 会为每条提示词采样浏览器的 IANA 时区。当 open turn 只有一个无歧义的浏览器时区时,Time-context 会告诉模型按该请求本地时区解释未明确限定时区的自然语言日期和时间;provenance 混合或缺失时,则告诉模型询问用户。该指引不是持久 Session 默认值:模型仍必须在字符串形式中传入偏移量,或在本地形式中传入 `time_zone`;Schedule 绝不会读取浏览器、Session、进程或模型上下文。 +官方 Web overlay 会为每条提示词采样浏览器的 IANA 时区。当 open turn 只有一个无歧义的浏览器时区时,Time-context 会告诉模型按该请求本地时区解释未明确限定时区的自然语言日期和时间;浏览器时区记录混合或缺失时,则告诉模型询问用户。该指引不是持久 Session 默认值:模型仍必须在字符串形式中传入偏移量,或在本地形式中传入 `time_zone`;Schedule 绝不会读取浏览器、Session、进程或模型上下文。 Schedule 会拒绝无效偏移量与时区、不带偏移量的字符串、非未来目标,以及落在夏令时缺口内的本地时间。遇到夏令时重叠时,会选择第一次出现的较早时点。创建成功后只存储规范化后的 UTC `scheduledAt`,因此回放绝不依赖环境时区状态。 diff --git a/docs/subsystems/session-title.i18n.yaml b/docs/subsystems/session-title.i18n.yaml index 63292c20f0..623eaac62f 100644 --- a/docs/subsystems/session-title.i18n.yaml +++ b/docs/subsystems/session-title.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 docs/subsystems/session-title.md -session-title.md: 20ed32b4a08127e7193433673d22f0dea3a90c46 -session-title.zh.md: c01d5d4bf177169069bbe0a39ef533ada0f7c36a +session-title.md: 75e17f06d73e6d51db51961327f8f34f0d5e5dd5 +session-title.zh.md: 187dad8f3a8cdaef14b450635f1f308fb2b429be diff --git a/docs/subsystems/session-title.md b/docs/subsystems/session-title.md index 20ed32b4a0..75e17f06d7 100644 --- a/docs/subsystems/session-title.md +++ b/docs/subsystems/session-title.md @@ -17,7 +17,7 @@ type SessionTitleProviderId = Branded<'SessionTitleProviderId'> ```ts type-equiv /** Exact auxiliary model route that produced a title. */ -interface SessionTitleModelProvenance { +interface SessionTitleModelIdentity { /** Registered LLM provider route. */ readonly provider: string /** Provider model id. */ @@ -32,7 +32,7 @@ type SessionTitleSource = | { readonly kind: 'provider' readonly provider: SessionTitleProviderId - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } | { /** Explicit user rename: pins the title — automatic generation stops scheduling. */ @@ -74,7 +74,7 @@ interface SessionTitleLlmRequestEventData { /** Exact human `user/message` seqs represented in `messages`. */ readonly messageSeqs: SessionSeq[] /** Exact auxiliary LLM route. */ - readonly route: SessionTitleModelProvenance + readonly route: SessionTitleModelIdentity /** Exact auxiliary system prompt. */ readonly system: string /** Exact auxiliary message list. */ @@ -111,7 +111,7 @@ interface SessionTitleProviderRequest { /** All eligible human messages through this generation revision. */ readonly messages: readonly SessionTitleUserMessage[] /** Exact current logged main-request route, when one has been recorded. */ - readonly route?: SessionTitleModelProvenance + readonly route?: SessionTitleModelIdentity /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */ readonly signal: AbortSignal } @@ -125,7 +125,7 @@ interface SessionTitleProviderResult { /** Exact seqs from `request.messages` used by this result. */ readonly messageSeqs: readonly SessionSeq[] /** Auxiliary LLM route, when generation used a model. */ - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } ``` diff --git a/docs/subsystems/session-title.zh.md b/docs/subsystems/session-title.zh.md index c01d5d4bf1..187dad8f3a 100644 --- a/docs/subsystems/session-title.zh.md +++ b/docs/subsystems/session-title.zh.md @@ -17,7 +17,7 @@ type SessionTitleProviderId = Branded<'SessionTitleProviderId'> ```ts type-equiv /** Exact auxiliary model route that produced a title. */ -interface SessionTitleModelProvenance { +interface SessionTitleModelIdentity { /** Registered LLM provider route. */ readonly provider: string /** Provider model id. */ @@ -32,7 +32,7 @@ type SessionTitleSource = | { readonly kind: 'provider' readonly provider: SessionTitleProviderId - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } | { /** Explicit user rename: pins the title — automatic generation stops scheduling. */ @@ -74,7 +74,7 @@ interface SessionTitleLlmRequestEventData { /** Exact human `user/message` seqs represented in `messages`. */ readonly messageSeqs: SessionSeq[] /** Exact auxiliary LLM route. */ - readonly route: SessionTitleModelProvenance + readonly route: SessionTitleModelIdentity /** Exact auxiliary system prompt. */ readonly system: string /** Exact auxiliary message list. */ @@ -111,7 +111,7 @@ interface SessionTitleProviderRequest { /** All eligible human messages through this generation revision. */ readonly messages: readonly SessionTitleUserMessage[] /** Exact current logged main-request route, when one has been recorded. */ - readonly route?: SessionTitleModelProvenance + readonly route?: SessionTitleModelIdentity /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */ readonly signal: AbortSignal } @@ -125,7 +125,7 @@ interface SessionTitleProviderResult { /** Exact seqs from `request.messages` used by this result. */ readonly messageSeqs: readonly SessionSeq[] /** Auxiliary LLM route, when generation used a model. */ - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } ``` diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 594dcfee20..124374407d 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/docs/subsystems/session.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 docs/subsystems/session.md -session.md: 7157dfd403d005112a75d0bbb46f99ad385b68df -session.zh.md: 6cb157a8016f236f52d4f8963e6efe070f0b89e3 +session.md: 1dd8db699784c70eedea80c42025cfac6a4747da +session.zh.md: 5e8d4d160192af57d3454393aa44f87e5ffff10d diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index 7157dfd403..1dd8db6997 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -272,7 +272,7 @@ type SessionEvent = { `SessionEventType = keyof SessionEventMap`. Because `SessionEventMap` is merge-extensible, switches over `SessionEvent` must NOT use `assertNever` — a plugin-added variant is a valid unknown value; handle the known cases and fall through `default`. -Every surface event requires `surfaceOp`; known log-only events forbid both surface metadata fields. Native unknown or obsolete ignorable envelopes remain opaque. `assistant/message` embeds its provider stream and forbids `sourceEventSeqs`. System, user, and tool surface events may cite a complete non-empty set of unique earlier events when their provenance or replacement operation requires it. A `tool/result` may carry `data.error` only when its tool-result block has `isError: true`; failure identity remains optional for failed results. +Every surface event requires `surfaceOp`; known log-only events forbid both surface metadata fields. Native unknown or obsolete ignorable envelopes remain opaque. `assistant/message` embeds its provider stream and forbids `sourceEventSeqs`. System, user, and tool surface events may cite a complete non-empty set of unique earlier events when source attribution or replacement coverage requires it. A `tool/result` may carry `data.error` only when its tool-result block has `isError: true`; failure identity remains optional for failed results. ## Surface types diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index 6cb157a801..5e8d4d1601 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -272,7 +272,7 @@ type SessionEvent = { `SessionEventType = keyof SessionEventMap`。由于 `SessionEventMap` 可通过合并扩展,对 `SessionEvent` 的 switch 语句禁止使用 `assertNever`:插件添加的变体是合法的未知值;处理已知 case 后在 `default` 中放行。 -每个 surface 事件都要求 `surfaceOp`;已知仅日志事件禁止两个 surface 元数据字段。原生未知或已退役的可忽略信封保持不透明。`assistant/message` 嵌入其提供方 stream,并禁止 `sourceEventSeqs`。System、user 与 tool surface 事件可以在来源或替换操作需要时引用完整、非空且唯一的较早事件集合。`tool/result` 仅在工具结果块带有 `isError: true` 时可以携带 `data.error`;失败结果的失败身份仍可省略。 +每个 surface 事件都要求 `surfaceOp`;已知仅日志事件禁止两个 surface 元数据字段。原生未知或已退役的可忽略信封保持不透明。`assistant/message` 嵌入其提供方 stream,并禁止 `sourceEventSeqs`。System、user 与 tool surface 事件可以在来源归属或替换覆盖需要时引用完整、非空且唯一的较早事件集合。`tool/result` 仅在工具结果块带有 `isError: true` 时可以携带 `data.error`;失败结果的失败身份仍可省略。 diff --git a/docs/subsystems/spill.i18n.yaml b/docs/subsystems/spill.i18n.yaml index ac302150e2..644a193f9c 100644 --- a/docs/subsystems/spill.i18n.yaml +++ b/docs/subsystems/spill.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 docs/subsystems/spill.md -spill.md: 05e48361ae1bdd815ee88ea5233ccbbac23ddf7d -spill.zh.md: 39e49f17564644c6a554440a80b46b79d837c79f +spill.md: 577f3ff14bade2b0c03a0aeaa975d12ae96803b8 +spill.zh.md: 1bc238b8cdc0ef81e966bc5ec9c11b2dd31b24da diff --git a/docs/subsystems/spill.md b/docs/subsystems/spill.md index 05e48361ae..577f3ff14b 100644 --- a/docs/subsystems/spill.md +++ b/docs/subsystems/spill.md @@ -8,7 +8,7 @@ Source: [`packages/spill/spill/src/types.ts`](../../packages/spill/spill/src/typ ## The save request -`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), descriptive producer provenance (`source`, never access control), and a `suggestedName` the backend may use as a naming hint, not a path. Tool provenance identifies the actual tool call; session-reference provenance identifies the captured source session, while its owner is the target session receiving the context. +`saveText` is the sole service operation: persist `content` verbatim, return an opaque locator, a backend-supplied retrieval hint, and the exact byte count. The request carries the save-time storage namespace (`owner`), descriptive producer details (`source`, never access control), and a `suggestedName` the backend may use as a naming hint, not a path. A tool source identifies the actual tool call; a session-reference source identifies the captured source session, while its owner is the target session receiving the context. ```ts type-equiv /** One request to persist text to a spill artifact. */ @@ -44,7 +44,7 @@ A retention-period cleanup may expire old locators with other old session artifa /** * Producer of a spilled artifact. Tool results carry their model-issued call id; * session references identify the captured source session instead. Descriptive - * provenance only, never access control. + * source description only, never access control. */ type SpillSource = { kind: 'tool' diff --git a/docs/subsystems/spill.zh.md b/docs/subsystems/spill.zh.md index 39e49f1756..1bc238b8cd 100644 --- a/docs/subsystems/spill.zh.md +++ b/docs/subsystems/spill.zh.md @@ -44,7 +44,7 @@ interface SpillOwner { /** * Producer of a spilled artifact. Tool results carry their model-issued call id; * session references identify the captured source session instead. Descriptive - * provenance only, never access control. + * source description only, never access control. */ type SpillSource = { kind: 'tool' diff --git a/docs/subsystems/subagent.i18n.yaml b/docs/subsystems/subagent.i18n.yaml index 4750a413d5..68df33bd6a 100644 --- a/docs/subsystems/subagent.i18n.yaml +++ b/docs/subsystems/subagent.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 docs/subsystems/subagent.md -subagent.md: 5f927f4c0bef57c0fda0bcb39280a5ac2012343e +subagent.md: cd311634c36f7168e7bffc71fe54eeb4f5eddba9 subagent.zh.md: ce827f154989404825e322682c4af6ba83182253 diff --git a/docs/subsystems/subagent.md b/docs/subsystems/subagent.md index 5f927f4c0b..cd311634c3 100644 --- a/docs/subsystems/subagent.md +++ b/docs/subsystems/subagent.md @@ -147,7 +147,7 @@ persisted Session The Agent inbox is the only queue. Every Agent message uses `Agent.steer()`: an idle target starts a turn, while a running target claims it at the nearest step boundary. The browser `subagent.prompt` Remote separately carries `delivery: 'queue' | 'steer'` through the same internal admission path; Queue opens a later FIFO turn, while Steer retains the Agent loop's best-effort nearest-step behavior and the message's human source. Successful delivery returns the accepted `MessageId`; the existing `agent/inbox/inserted`, `agent/inbox/claimed`, and `agent/inbox/discarded` events remain the message-lifecycle observations, and the continuation layer defines no second queue. -Authority comes from the exact live sender. Parent-to-child delivery requires the target's `SessionHeader.parentSession` to name the sender; child-to-parent delivery requires the sender's resident Activation to name the target. Siblings, ancestors beyond one edge, self-targets, stale Agent objects, and one-shot children are rejected. Each accepted message is framed as `Agent sent a message:` and records `AgentMessageSource`; provenance records the sender but grants no authority. +Authority comes from the exact live sender. Parent-to-child delivery requires the target's `SessionHeader.parentSession` to name the sender; child-to-parent delivery requires the sender's resident Activation to name the target. Siblings, ancestors beyond one edge, self-targets, stale Agent objects, and one-shot children are rejected. Each accepted message is framed as `Agent sent a message:` and records `AgentMessageSource`; the source records the sender but grants no authority. For `startContinuable()`, `sendMessage()`, and browser prompt delivery, the caller signal owns lookup, materialization, and admission only until inbox acceptance. Afterwards the manager owns the Activation independently: later caller cancellation neither cancels the accepted turn nor disposes the child. The public subagent service exposes no caller-selected Agent-message scheduling; browser human Queue and Steer remain internal adapter choices. @@ -199,7 +199,7 @@ interface ContinuableStart { } ``` -When a resident Activation settles, the manager delivers one notice to the child's durable direct parent describing how that epoch ended and carrying its final assistant content. That delivery is unconditional for every child whose id a caller received, happens before the ownership release that would let the parent be judged settled, and reaches a resident parent through the same waking Agent delivery as an Agent message. A parent whose own lineage is already tearing down receives it without a wake, because waking an idle Agent starts a turn rather than queueing work. Its provenance is a distinct kind so a transcript never presents a runtime account as something the child wrote. +When a resident Activation settles, the manager delivers one notice to the child's durable direct parent describing how that epoch ended and carrying its final assistant content. That delivery is unconditional for every child whose id a caller received, happens before the ownership release that would let the parent be judged settled, and reaches a resident parent through the same waking Agent delivery as an Agent message. A parent whose own lineage is already tearing down receives it without a wake, because waking an idle Agent starts a turn rather than queueing work. Its source has a distinct kind so a transcript never presents a runtime account as something the child wrote. ```ts type-equiv /** diff --git a/docs/subsystems/webhook.i18n.yaml b/docs/subsystems/webhook.i18n.yaml index c27aa424bb..4d91c674b9 100644 --- a/docs/subsystems/webhook.i18n.yaml +++ b/docs/subsystems/webhook.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 docs/subsystems/webhook.md -webhook.md: 5f04c99141c5630add46db3b55c3af78e2df2bdf +webhook.md: 5ca2b722e1e0201aa5fb618cdaae6e0dfb5783dd webhook.zh.md: 2eadf03aa5f32ae6f384e6b32a95e67bc0fdab7e diff --git a/docs/subsystems/webhook.md b/docs/subsystems/webhook.md index 5f04c99141..5ca2b722e1 100644 --- a/docs/subsystems/webhook.md +++ b/docs/subsystems/webhook.md @@ -6,7 +6,7 @@ The Webhook subsystem turns authenticated external deliveries into optional ordi ## Shared values -`WebhookRuleId`, `WebhookSourceId`, and `WebhookDeliveryId` are opaque strings. A delivery id is provenance only: the runtime neither stores nor deduplicates it. +`WebhookRuleId`, `WebhookSourceId`, and `WebhookDeliveryId` are opaque strings. A delivery id records the provider's identifier only: the runtime neither stores nor deduplicates it. `WebhookEventMap` is merge-extensible by provider kind. `WebhookEventOf` selects a known provider event and otherwise admits generic lossless JSON, allowing an out-of-tree adapter without changing the runtime package. @@ -26,7 +26,7 @@ The runtime has no queue, retry, deduplication, execution status, crash replay, A non-null result is snapshotted before asynchronous preflight. The runtime validates permission and agent presets, resolves or creates the canonical Workspace, creates an Agent whose Session cwd equals the Workspace path, mounts the selected agent preset before publication, and durably attaches the Session before applying permission, title, and the initial follow-up. -The follow-up is a normal durable user-role message with `source.kind: "webhook"` and provider/source/delivery/rule provenance. Its accepted inbox insertion commits the webhook operation. The runtime does not specially flush or wait for the turn; ordinary Session persistence and Agent lifecycle apply afterward. +The follow-up is a normal durable user-role message with `source.kind: "webhook"` and the provider, source, delivery, and rule identifiers. Its accepted inbox insertion commits the webhook operation. The runtime does not specially flush or wait for the turn; ordinary Session persistence and Agent lifecycle apply afterward. Failed attachment disposes the new Agent before a prompt exists. A failure between attachment and prompt admission attempts Workspace detach and Agent disposal without replacing the original error. A Workspace automatically created during preflight remains because another concurrent caller may already use it. diff --git a/package.json b/package.json index 01e7b245e0..bdb721cfb4 100644 --- a/package.json +++ b/package.json @@ -96,6 +96,7 @@ "verify-md-links": "tsx scripts/verify-md-links.ts", "verify-doc-site-fragments": "tsx scripts/verify-doc-site-fragments.ts", "verify-public-repository-links": "tsx scripts/verify-public-repository-links.ts", + "verify-concrete-terms": "tsx scripts/verify-concrete-terms.ts", "verify-doc-refs": "tsx scripts/verify-doc-refs.ts", "verify-subsystem-pages": "tsx scripts/verify-subsystem-pages.ts", "verify-package-paths": "tsx scripts/verify-package-paths.ts", diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index 418425f098..2e81443d71 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.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 packages/api/session-controller/README.md -README.md: 15f16200d66949163ac8c1e5dbb2994756598dfc -README.zh.md: 63641025575b61a38d1e06485dc5ea546101f5b6 +README.md: 9b2cdeed600cd597ecfab076fe98a3a334533ba8 +README.zh.md: 04ed7808dc7ea581b489921f88349479d46d8037 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index 15f16200d6..9b2cdeed60 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -26,7 +26,7 @@ English | [中文](README.zh.md) History pages and follow opening snapshots carry one `{ type: 'event', event: SessionWireEvent }` record per durable Session event. The Client retains each accepted record as one durable `SessionEventLikeEntry`; Assistant token boundaries remain inside the compact stream on `assistant/message` or `assistant/attempt`. Tool arguments, result content, failures, and `tool/result.data.meta` pass through unchanged; the controller does not resolve a Tool definition, run a presenter, or attach UI data. -The Client journal validates exact V3 event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provenance, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host. +The Client journal validates exact V3 event envelopes before publishing follow snapshots, live entries, or history pages. It reuses the browser-safe Session validators for required surface markers, exact replacement endpoints, earlier unique source seqs, embedded Assistant provider metadata, request-header omissions, and tool-error consistency. Invalid records fail without field stripping or normalization; range membership and source existence remain durable-log checks on the Host. Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Queue mutation and cancellation require live state; model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the default application. diff --git a/packages/api/session-controller/README.zh.md b/packages/api/session-controller/README.zh.md index 6364102557..04ed7808dc 100644 --- a/packages/api/session-controller/README.zh.md +++ b/packages/api/session-controller/README.zh.md @@ -26,7 +26,7 @@ kind: "package-reference" 历史页与 follow opening 快照为每个持久 Session 事件携带一条 `{ type: 'event', event: SessionWireEvent }` record。Client 把每条已接受 record 保留为一个持久 `SessionEventLikeEntry`;Assistant token 边界保留在 `assistant/message` 或 `assistant/attempt` 的紧凑流内。工具参数、结果内容、失败信息和 `tool/result.data.meta` 原样通过;控制器不解析工具定义、不运行展示转换器,也不附加 UI 数据。 -Client journal 在发布 follow 快照、live entry 或历史页之前验证精确的 V3 事件 envelope。它复用浏览器安全的 Session validator,检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 来源、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败,不删除字段或归一化;范围成员与来源存在性仍由 Host 的持久日志检查。 +Client journal 在发布 follow 快照、live entry 或历史页之前验证精确的 V3 事件 envelope。它复用浏览器安全的 Session validator,检查必需的 surface marker、精确的 replacement endpoint、更早且唯一的 source seq、内嵌 Assistant 提供方元数据、request header 可选字段的省略规则以及工具错误一致性。无效 record 直接失败,不删除字段或归一化;范围成员与来源存在性仍由 Host 的持久日志检查。 每个 endpoint 都声明自己的激活策略。列表只读取持久化 header 与 projection cache row,绝不调用逐 Session stat 或打开冷 Session body。当前格式 cache identity 可以提供全部列表 hint;生命周期匹配的 predecessor cache 只能提供版本兼容的 title,作为可能过时的展示事实,绝不能作为权威 fold seed。搜索、附件、历史页、日志跟随、skill 发现和工作区路径打开可以在不激活 Agent 的情况下检查 persistence;`canOpenWorkspacePath()` 无需指定 Session 即可报告原生打开能力。queue 变更与取消要求 live 状态;模型、重命名、prompt 和文件引用操作可以解析或恢复普通 Session。提示词会在解析 Agent 或追加 Session 事件前,拒绝既没有非空白文本也没有附件的 content;queue edit 只接受非空文本 content。prompt 准入从注入的 [`fileUploads`](../../client/file-upload/README.zh.md) Host 服务取得不透明凭证,在把完整有序内容列表交给 `ctx.attachments` 前解析每个属于同一 Agent 的凭证。`requestId` 已进入 queue 或日志时,prompt 重试直接返回原来的接受结果,不会重复插入消息。只有 create 与 fork 会直接创建新 Agent。该服务把同一套感知 preset 的恢复策略和 subagent ownership fence 同时用于自身方法,以及其他 Remote namespace 使用的 Typert Agent 与 Session lookup。Queue 变更只有一个狭窄例外:当前 projection identity 为 continuable 且来自自身非 seed suffix 的在线 child,可以在两个 inbox 目标上使用普通 Edit、Remove 与 QueueDock Steer action。One-shot、缺失、未知、损坏、仅含 seed identity 或冷 child 继续被拒绝,且不会恢复。skill 目录优先使用已有 live Agent,否则使用所记录 preset 的常驻 scope,因此列表查询绝不会启动 Agent。经过鉴权的文件交付路由通过 `workspaceDesktop()` 获取提供服务的 Host 名称和文件管理器行为。`openWorkspacePath({ path, action: "reveal" })` 将文件管理器导航委托给原生适配器;省略 `action` 时打开默认应用。 diff --git a/packages/api/session-controller/src/client/time-zone.ts b/packages/api/session-controller/src/client/time-zone.ts index 9c2ddc4ea2..f4ba8207ff 100644 --- a/packages/api/session-controller/src/client/time-zone.ts +++ b/packages/api/session-controller/src/client/time-zone.ts @@ -1,4 +1,4 @@ -/** Browser-owned time-zone sampling for prompt RPC provenance. */ +/** Browser-owned time-zone sampling for one prompt RPC. */ /** * Resolve the current browser IANA zone for one outbound operation. diff --git a/packages/api/session-controller/tests/transport.host.spec.ts b/packages/api/session-controller/tests/transport.host.spec.ts index ebc731769e..bac8a541d4 100644 --- a/packages/api/session-controller/tests/transport.host.spec.ts +++ b/packages/api/session-controller/tests/transport.host.spec.ts @@ -697,7 +697,7 @@ describe('SessionHistoryController', () => { expect(childSnapshot).toHaveBeenCalledWith(childSession) }) - it('keeps message-aligned pagination contiguous across replacement provenance', async () => { + it('keeps message-aligned pagination contiguous across replacement source-event references', async () => { const { ctx, transport } = await setup() const session = ctx.sessions.create(SessionId('pagination'), { meta: { cwd: '/workspace' } }) session.append('turn/start', { turn: 1 }) diff --git a/packages/boot/app-boot/README.i18n.yaml b/packages/boot/app-boot/README.i18n.yaml index ad93250809..f9371c44cc 100644 --- a/packages/boot/app-boot/README.i18n.yaml +++ b/packages/boot/app-boot/README.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 packages/boot/app-boot/README.md -README.md: 10d582289707c87bd84b0eb32267ac4f5addf884 +README.md: 91ad6b67357172a0f6dea18c03deee73de391c0b README.zh.md: c8bb61e28e8ad758c757fe11a5b55135e1daf319 diff --git a/packages/boot/app-boot/README.md b/packages/boot/app-boot/README.md index 10d5822897..91ad6b6735 100644 --- a/packages/boot/app-boot/README.md +++ b/packages/boot/app-boot/README.md @@ -173,6 +173,6 @@ This Dev Note is working context for maintainers: open design questions and dire #### Open: config dump stability -`renderConfigDump` output is a loadable YAML document whose `# ==` provenance comments and `!!js`-verbatim rendering serve the `--dump-config` diagnostic. Nothing promises byte stability across package versions; decide whether the dump becomes a serialization contract before anything consumes it programmatically. +`renderConfigDump` output is a loadable YAML document whose `# ==` source comments and `!!js`-verbatim rendering serve the `--dump-config` diagnostic. Nothing promises byte stability across package versions; decide whether the dump becomes a serialization contract before anything consumes it programmatically. diff --git a/packages/boot/app-boot/src/index.ts b/packages/boot/app-boot/src/index.ts index cebe39888b..b8c96db202 100644 --- a/packages/boot/app-boot/src/index.ts +++ b/packages/boot/app-boot/src/index.ts @@ -454,7 +454,7 @@ export function renderConfigDump( } let previous = base let previousWarnings: string[] = [] - const provenance: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] })) + const entryOrigins: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] })) let composed = base for (let count = 1; count <= layers.length; count += 1) { const layer = layers[count - 1] @@ -467,19 +467,19 @@ export function renderConfigDump( } const before = previous.map(entry => JSON.stringify(entry)) for (let index = 0; index < composed.length; index += 1) { - if (index >= before.length) provenance.push({ origin: layer.label, patchedBy: [] }) - else if (JSON.stringify(composed[index]) !== before[index]) provenance[index]?.patchedBy.push(layer.label) + if (index >= before.length) entryOrigins.push({ origin: layer.label, patchedBy: [] }) + else if (JSON.stringify(composed[index]) !== before[index]) entryOrigins[index]?.patchedBy.push(layer.label) } previous = composed previousWarnings = warnings } - return groupedDump(composed, provenance) + return groupedDump(composed, entryOrigins) } /** Render the composed rows grouped under one source-and-patches comment per contiguous run. */ function groupedDump( composed: readonly unknown[], - provenance: readonly { origin: string; patchedBy: string[] }[], + entryOrigins: readonly { origin: string; patchedBy: string[] }[], ): string { const lines: string[] = [] let currentLabel: string | undefined @@ -491,7 +491,7 @@ function groupedDump( group = [] } for (let index = 0; index < composed.length; index += 1) { - const record = provenance[index] + const record = entryOrigins[index] /* v8 ignore next -- this array is index-aligned with composed by construction */ if (record === undefined) continue const label = record.patchedBy.length === 0 diff --git a/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx b/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx index 37f08dc2f5..c905035119 100644 --- a/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx +++ b/packages/client/ui-chat/src/client/chat/ContextInjectionRow.tsx @@ -10,7 +10,7 @@ export interface ContextInjectionRowProps { content: ContextMessageNode['content'] source: ContextMessageNode['source'] /** Role and producer name projected from the durable source. */ - provenance: ContextMessageNode['provenance'] + producer: ContextMessageNode['producer'] /** Producer-declared information form; null renders the opaque body. */ form: ContextMessageNode['form'] /** The owning view's locale seat, passed down as a plain prop. */ @@ -28,7 +28,7 @@ export interface ContextInjectionRowProps { * @param props - Durable content, its projected producer role/name and form, and the locale seat. * @returns A collapsed context row with a bounded, form-specific body. */ -export function ContextInjectionRow({ content, source, provenance, form, t }: ContextInjectionRowProps) { +export function ContextInjectionRow({ content, source, producer, form, t }: ContextInjectionRowProps) { const [open, setOpen] = useState(false) // Resolved rather than declared: a form whose fields are unreadable renders // the opaque body, and the marker must say what the row actually shows. @@ -37,18 +37,18 @@ export function ContextInjectionRow({ content, source, provenance, form, t }: Co return ( : } chevronClassName={css.chevron} - title={t(provenance.role === 'recall' ? 'message.contextRecall' : 'message.contextInjection')} - collapsedContent={provenance.label === null ? undefined : ( + title={t(producer.role === 'recall' ? 'message.contextRecall' : 'message.contextInjection')} + collapsedContent={producer.label === null ? undefined : ( /* ToolRow's separator shape: an aria-hidden dot, so the accessible name stays the two readable parts and the two disclosure rows expose one name shape. A source that names no producer drops the dot with it. */ <> - {provenance.label} + {producer.label} {summary !== null && ( <> diff --git a/packages/client/ui-chat/src/client/chat/MessageItem.tsx b/packages/client/ui-chat/src/client/chat/MessageItem.tsx index 0666fe7115..e1875f5ce2 100644 --- a/packages/client/ui-chat/src/client/chat/MessageItem.tsx +++ b/packages/client/ui-chat/src/client/chat/MessageItem.tsx @@ -344,7 +344,7 @@ export const ContextMessageNodeView = memo(function ContextMessageNodeView({ nod diff --git a/packages/client/ui-chat/src/client/contract/snapshot.ts b/packages/client/ui-chat/src/client/contract/snapshot.ts index 0d02198811..80f8654e7c 100644 --- a/packages/client/ui-chat/src/client/contract/snapshot.ts +++ b/packages/client/ui-chat/src/client/contract/snapshot.ts @@ -5,7 +5,7 @@ import type { ChatConversationViewNode } from './chat-nodes.ts' import type { TurnProcessSpec } from './turn-process.ts' export type { - AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig, + AssistantBlock, AssistantMessageNode, AssistantProviderMetadataView, AssistantRequestConfig, AssistantTiming, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode, PartialAssistant, RunningToolCall, SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UnknownSurfaceNode, diff --git a/packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts b/packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts index 1695a467fe..5995638194 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/event-projection.ts @@ -2,7 +2,7 @@ import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types' import type { - AssistantBlock, ContextProvenanceView, KnownContextForm, + AssistantBlock, ContextProducerView, KnownContextForm, } from '@deepseek-ai/dsh-client-ui-conversation/client' /* jscpd:ignore-start -- Chat and Trajectory own independent event-to-view projections. */ @@ -57,7 +57,7 @@ export function contextForm(source: unknown): KnownContextForm | null { * @param source - Logged `user/message` source. * @returns Role and label rendered by Chat. */ -export function contextProvenance(source: unknown): ContextProvenanceView { +export function contextProducer(source: unknown): ContextProducerView { const record = asRecord(source) const kind = record === null ? null : readString(record, 'kind') if (record === null || kind === null) return { role: 'inject', label: null } diff --git a/packages/client/ui-chat/src/client/conversation-nodes/message.ts b/packages/client/ui-chat/src/client/conversation-nodes/message.ts index 3cd6538bd5..823bbe3c93 100644 --- a/packages/client/ui-chat/src/client/conversation-nodes/message.ts +++ b/packages/client/ui-chat/src/client/conversation-nodes/message.ts @@ -5,7 +5,7 @@ import type { import { isAppendSurfaceEvent, isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session/surface' import type { InboxState } from './inbox.ts' import { chatNode } from './common.ts' -import { contextForm, contextProvenance } from './event-projection.ts' +import { contextForm, contextProducer } from './event-projection.ts' interface ReferencedUserMessageNode extends UserMessageNode { /** Labels cited by the immediately following session-reference context. */ @@ -59,7 +59,7 @@ export const messageDefinition: ConversationNodeDefinition = { time: event.time, content: event.data.content, source: event.data.source, - provenance: contextProvenance(event.data.source), + producer: contextProducer(event.data.source), form: contextForm(event.data.source), } } diff --git a/packages/client/ui-chat/src/client/index.ts b/packages/client/ui-chat/src/client/index.ts index 450ce00fce..9c2fe3a5d0 100644 --- a/packages/client/ui-chat/src/client/index.ts +++ b/packages/client/ui-chat/src/client/index.ts @@ -14,7 +14,7 @@ export type {} from './conversation-nodes/turn-process.ts' export type {} from './conversation-nodes/turn-tail.ts' export type { - AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig, + AssistantBlock, AssistantMessageNode, AssistantProviderMetadataView, AssistantRequestConfig, AssistantTiming, ChatLocationNodeIndex, ChatNodeProcessSource, ChatNodeSource, ChatNodeStore, ChatSnapshot, ChatTurnNavigationIndex, ChatTurnProcessPresentation, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, @@ -42,7 +42,7 @@ export type { export type { ChatKey } from './locale.ts' export type { ConversationContext, ConversationContextOriginKind } from './model/conversation-context.ts' export type { - ContextProvenanceView, ContextRole, KnownContextForm, + ContextProducerView, ContextRole, KnownContextForm, } from '@deepseek-ai/dsh-client-ui-conversation/client' export type { ConversationPromptSnapshot, RequestInspectionSnapshot, RequestPromptChange, RequestView, diff --git a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx index d24a0a3446..56ed85a3e9 100644 --- a/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx +++ b/packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx @@ -332,7 +332,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'line one\n\nline two' }], source: { kind: 'plugin', plugin: 'fixture', empty: {}, list: [] }, - provenance: { role: 'inject', label: 'fixture' }, + producer: { role: 'inject', label: 'fixture' }, form: null, } as never} />, @@ -373,7 +373,7 @@ describe('MessageItem arms', () => { { action: 'replace', scope: '.\u0000AGENTS.md', path: 'AGENTS.md' }, ], }, - provenance: { role: 'inject', label: 'AGENTS.md, sub/AGENTS.md' }, + producer: { role: 'inject', label: 'AGENTS.md, sub/AGENTS.md' }, form: 'instructions', } as never} />, @@ -401,7 +401,7 @@ describe('MessageItem arms', () => { { action: 'replace', scope: 'b', path: 'old/AGENTS.md' }, ], }, - provenance: { role: 'inject', label: 'new/AGENTS.md, old/AGENTS.md' }, + producer: { role: 'inject', label: 'new/AGENTS.md, old/AGENTS.md' }, form: 'instructions', } as never} />, @@ -422,7 +422,7 @@ describe('MessageItem arms', () => { { type: 'text', text: 'after' }, ], source: null, - provenance: { role: 'inject', label: null }, + producer: { role: 'inject', label: null }, form: null, } as never} />, @@ -444,7 +444,7 @@ describe('MessageItem arms', () => { form: 'catalog', entries: [{ name: 'a-skill', description: 'Does A' }, { name: 'b-skill', description: 'Does B' }], }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -468,7 +468,7 @@ describe('MessageItem arms', () => { update: true, entries: [{ name: 'a-skill', description: 'Does A' }], }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -490,7 +490,7 @@ describe('MessageItem arms', () => { form: 'catalog', entries: [{ name: 'a-skill', description: 'Does A' }, { name: 'b-skill' }], }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -510,7 +510,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'instruction prose' }], source: { kind: 'agent-instructions', form: 'instructions', changes: [{ action: 'set' }] }, - provenance: { role: 'inject', label: 'agent-instructions' }, + producer: { role: 'inject', label: 'agent-instructions' }, form: 'instructions', } as never} />, @@ -530,7 +530,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'first' }, { type: 'text', text: 'second' }], source: null, - provenance: { role: 'inject', label: null }, + producer: { role: 'inject', label: null }, form: null, } as never} />, @@ -546,7 +546,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'short' }], source: { kind: 'plugin', note: 'y'.repeat(21_000) }, - provenance: { role: 'inject', label: 'plugin' }, + producer: { role: 'inject', label: 'plugin' }, form: null, } as never} />, @@ -565,7 +565,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'catalog prose' }], source: { kind: 'skill-catalog', form: 'catalog', update: true, entries: [] }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -584,7 +584,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'catalog prose' }], source: { kind: 'skill-catalog', form: 'catalog', entries: 'not-a-list' }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -600,7 +600,7 @@ describe('MessageItem arms', () => { , @@ -617,7 +617,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'prose' }, { type: 'future-block', payload: 1 }], source: { kind: 'skill-catalog', form: 'catalog', entries: [{ name: 'a', description: 'b' }] }, - provenance: { role: 'inject', label: 'skill-catalog' }, + producer: { role: 'inject', label: 'skill-catalog' }, form: 'catalog', } as never} />, @@ -635,7 +635,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'instruction prose' }], source: { kind: 'agent-instructions', form: 'instructions', changes: [{ action: 'merge', path: 'A.md' }] }, - provenance: { role: 'inject', label: 'agent-instructions' }, + producer: { role: 'inject', label: 'agent-instructions' }, form: 'instructions', } as never} />, @@ -651,7 +651,7 @@ describe('MessageItem arms', () => { , @@ -673,7 +673,7 @@ describe('MessageItem arms', () => { form: 'snapshot', sections: [{ name: 'sandbox:policy', text: 'workspace-write' }, { name: 'workspace', text: '/repo' }], }, - provenance: { role: 'inject', label: '@deepseek-ai/dsh-system-prompt' }, + producer: { role: 'inject', label: '@deepseek-ai/dsh-system-prompt' }, form: 'snapshot', } as never} />, @@ -691,7 +691,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'background job bash-1 finished.' }], source: { kind: 'plugin', plugin: 'tool-jobs', form: 'notice', summary: 'bash pnpm test [status: completed]' }, - provenance: { role: 'inject', label: 'tool-jobs' }, + producer: { role: 'inject', label: 'tool-jobs' }, form: 'notice', } as never} />, @@ -706,7 +706,7 @@ describe('MessageItem arms', () => { , @@ -729,7 +729,7 @@ describe('MessageItem arms', () => { const view = render( , ) @@ -745,7 +745,7 @@ describe('MessageItem arms', () => { , @@ -762,7 +762,7 @@ describe('MessageItem arms', () => { seq: 3, content: [{ type: 'text', text: 'child report body' }], source: { kind: 'agent-message', form: 'relay', senderSessionId: 'child-7' }, - provenance: { role: 'inject', label: 'agent-message' }, + producer: { role: 'inject', label: 'agent-message' }, form: 'relay', } as never} />, @@ -789,7 +789,7 @@ describe('MessageItem arms', () => { { label: '修 CI', retainedMessages: 3, omittedMessages: 0, truncated: false }, ], }, - provenance: { role: 'recall', label: '重构 loader, 修 CI' }, + producer: { role: 'recall', label: '重构 loader, 修 CI' }, form: 'recall', } as never} />, diff --git a/packages/client/ui-chat/tests/chat-view.client.spec.tsx b/packages/client/ui-chat/tests/chat-view.client.spec.tsx index c724bf7ba6..4f43dccec5 100644 --- a/packages/client/ui-chat/tests/chat-view.client.spec.tsx +++ b/packages/client/ui-chat/tests/chat-view.client.spec.tsx @@ -150,7 +150,7 @@ const reasoningAssistant = (seq: number, text: string, turn = 1, step = 1): Assi }) const context = (seq: number, text: string, turn?: number): ContextMessageNode & { turn?: number } => ({ kind: 'context', seq, time: seq * 1_000, content: [{ type: 'text', text }], source: null, - provenance: { role: 'inject', label: null }, form: null, + producer: { role: 'inject', label: null }, form: null, ...(turn === undefined ? {} : { turn }), }) const steering = (seq: number, text: string, turn: number): SteeringMessageNode & { turn: number } => ({ @@ -1250,7 +1250,7 @@ describe('ChatView', () => { const nextRetry = { ...retry(3), turn: 2, retry: 2 } const context = { kind: 'context', seq: 4, time: 4_000, content: [], source: null, - provenance: { role: 'inject', label: null }, + producer: { role: 'inject', label: null }, form: null, } as const satisfies ConversationNode const h = makeHarness({ nodes: [user(1, 'try'), retryNode] }, { running: true }) diff --git a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts index 85fa2b6eb0..6b8031c406 100644 --- a/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts +++ b/packages/client/ui-chat/tests/conversation-node-definitions.client.spec.ts @@ -1433,7 +1433,7 @@ describe('built-in conversation node Definitions', () => { expect(node(snapshot(value), 'context')?.data).toMatchObject({ kind: 'context', - provenance: { role: 'inject', label: 'demo-skill' }, + producer: { role: 'inject', label: 'demo-skill' }, form: 'instructions', }) }) diff --git a/packages/client/ui-chat/tests/event-projection.client.spec.ts b/packages/client/ui-chat/tests/event-projection.client.spec.ts index aa333c4cba..f1818da09c 100644 Binary files a/packages/client/ui-chat/tests/event-projection.client.spec.ts and b/packages/client/ui-chat/tests/event-projection.client.spec.ts differ diff --git a/packages/client/ui-conversation/src/client/contract/context-provenance.ts b/packages/client/ui-conversation/src/client/contract/context-producer.ts similarity index 96% rename from packages/client/ui-conversation/src/client/contract/context-provenance.ts rename to packages/client/ui-conversation/src/client/contract/context-producer.ts index db732bf59c..567ce167f6 100644 --- a/packages/client/ui-conversation/src/client/contract/context-provenance.ts +++ b/packages/client/ui-conversation/src/client/contract/context-producer.ts @@ -11,7 +11,7 @@ export type ContextRole = 'inject' | 'recall' /** Role and producer name presented for one logged non-user message. */ -export interface ContextProvenanceView { +export interface ContextProducerView { /** The role this context plays in the model-facing conversation. */ role: ContextRole /** diff --git a/packages/client/ui-conversation/src/client/contract/records.ts b/packages/client/ui-conversation/src/client/contract/records.ts index 0e61abe4b0..48b67d54a3 100644 --- a/packages/client/ui-conversation/src/client/contract/records.ts +++ b/packages/client/ui-conversation/src/client/contract/records.ts @@ -8,7 +8,7 @@ import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment' import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types' import type { TodoItem } from '@deepseek-ai/dsh-tool-todo/client' -import type { ContextProvenanceView, KnownContextForm } from './context-provenance.ts' +import type { ContextProducerView, KnownContextForm } from './context-producer.ts' export type { TodoItem } /** Request configuration recorded for one provider call. */ @@ -24,7 +24,7 @@ export interface AssistantRequestConfig { } /** Stable provider/model identity reported for one completed request. */ -export interface AssistantProvenanceView { +export interface AssistantProviderMetadataView { provider: string model: string } @@ -73,7 +73,7 @@ export interface AssistantMessageNode { step: number blocks: readonly AssistantBlock[] usage?: unknown - provenance?: AssistantProvenanceView + providerInfo?: AssistantProviderMetadataView requestConfig?: AssistantRequestConfig /** Timing derived from the recorded step/chunk/message event sequence. */ timing?: AssistantTiming @@ -104,7 +104,7 @@ export interface ContextMessageNode { content: readonly ContentBlock[] source: unknown /** Role and producer name projected from `source` by the target. */ - provenance: ContextProvenanceView + producer: ContextProducerView /** Producer-declared information form supported by the target; null presents as opaque. */ form: KnownContextForm | null } diff --git a/packages/client/ui-conversation/src/client/contract/request-inspection.ts b/packages/client/ui-conversation/src/client/contract/request-inspection.ts index a59b803459..8ff135b657 100644 --- a/packages/client/ui-conversation/src/client/contract/request-inspection.ts +++ b/packages/client/ui-conversation/src/client/contract/request-inspection.ts @@ -1,11 +1,11 @@ import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm/types' import type { SessionEvent } from '@deepseek-ai/dsh-session/types' import type { - AssistantProvenanceView, AssistantRequestConfig, + AssistantProviderMetadataView, AssistantRequestConfig, } from './records.ts' export type { - AssistantProvenanceView, AssistantRequestConfig, + AssistantProviderMetadataView, AssistantRequestConfig, } from './records.ts' /** @@ -133,7 +133,7 @@ interface RequestViewBase { error?: string /** Stable provider code for localized presentation of known failures. */ errorCode?: string - provenance?: AssistantProvenanceView + providerInfo?: AssistantProviderMetadataView requestConfig?: AssistantRequestConfig usage?: unknown /** Assistant message or compaction summary sequence produced by this request. */ diff --git a/packages/client/ui-conversation/src/client/index.ts b/packages/client/ui-conversation/src/client/index.ts index 52c801ae4d..2b94139936 100644 --- a/packages/client/ui-conversation/src/client/index.ts +++ b/packages/client/ui-conversation/src/client/index.ts @@ -21,15 +21,15 @@ export type { ConversationPhase, ConversationSnapshot, } from './contract/snapshot.ts' export type { - AssistantBlock, AssistantMessageNode, AssistantProvenanceView, AssistantRequestConfig, + AssistantBlock, AssistantMessageNode, AssistantProviderMetadataView, AssistantRequestConfig, AssistantTiming, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode, PartialAssistant, RunningToolCall, SteeringMessageNode, TodoItem, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UnknownSurfaceNode, UserMessageNode, } from './contract/records.ts' export type { - ContextProvenanceView, ContextRole, KnownContextForm, -} from './contract/context-provenance.ts' + ContextProducerView, ContextRole, KnownContextForm, +} from './contract/context-producer.ts' export type { ConversationPromptSnapshot, RequestInspectionSnapshot, RequestPromptChange, RequestPromptInspection, RequestPromptInspector, RequestView, SystemPromptNode, diff --git a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml b/packages/client/ui-settings-plugin-inventory/README.i18n.yaml index d437829dd5..c41ba66d5d 100644 --- a/packages/client/ui-settings-plugin-inventory/README.i18n.yaml +++ b/packages/client/ui-settings-plugin-inventory/README.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 packages/client/ui-settings-plugin-inventory/README.md -README.md: d56e7bcd2bc8a1590910045319db5cd3b6307e85 +README.md: 40b7e41cd2d6953fdf3b9155fd6adff9d9d65391 README.zh.md: 45f3444ea4fa56fe4a55517eb5d981913c790b15 diff --git a/packages/client/ui-settings-plugin-inventory/README.md b/packages/client/ui-settings-plugin-inventory/README.md index d56e7bcd2b..40b7e41cd2 100644 --- a/packages/client/ui-settings-plugin-inventory/README.md +++ b/packages/client/ui-settings-plugin-inventory/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -The **Plugin list** tab lets Web users inspect plugins without changing their configuration. It presents agent presets first and collapses the global inventory until needed. Cards retain the package name as the primary title, identify instances by stable entry id, and expose enablement, provenance, runtime status, disabled conditions, and discovery failures; preset-provided global entries name their presets. Search covers both groups and points to matches in other presets. The tab handles loading, empty, no-match, failure, and retry states without exposing transport details, and still shows the global inventory without a preset roster. +The **Plugin list** tab lets Web users inspect plugins without changing their configuration. It presents agent presets first and collapses the global inventory until needed. Cards retain the package name as the primary title, identify instances by stable entry id, and expose enablement, source details, runtime status, disabled conditions, and discovery failures; preset-provided global entries name their presets. Search covers both groups and points to matches in other presets. The tab handles loading, empty, no-match, failure, and retry states without exposing transport details, and still shows the global inventory without a preset roster. ## Table of Contents diff --git a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx index f441987ba1..eeb9d620da 100644 --- a/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx +++ b/packages/client/ui-settings-plugin-inventory/tests/components.client.spec.tsx @@ -114,7 +114,7 @@ describe('PluginInventorySettingsTab', () => { expect(view.container.querySelector('[data-plugin-count]')?.getAttribute('data-plugin-count')).toBe('7') expect(screen.getByText(`1 ${en.failedCountLabel}`)).toBeTruthy() - // A preset row expands into its provenance facts. + // A preset row expands into its source facts. fireEvent.click(screen.getByRole('button', { name: 'pwsh, pwsh, Conditional' })) expect(screen.getByText(en.fromPreset)).toBeTruthy() expect(screen.getByText('标准模式')).toBeTruthy() @@ -213,7 +213,7 @@ describe('PluginInventorySettingsTab', () => { pickPreset('ptc') expect(view.container.querySelector('[data-preset-plugin-count]')?.getAttribute('data-preset-plugin-count')).toBe('3') fireEvent.click(screen.getByRole('button', { name: 'tool-bash, bash, Enabled' })) - // An unnamed preset labels provenance by its id. + // An unnamed preset labels its source by id. expect(screen.getByText(en.fromPreset).nextElementSibling?.textContent).toBe('ptc') pickPreset('坏预设 (failed to load)') diff --git a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx index 4f8bc63d9c..2884d4f52e 100644 --- a/packages/client/ui-trajectory/src/client/TrajectoryView.tsx +++ b/packages/client/ui-trajectory/src/client/TrajectoryView.tsx @@ -250,8 +250,8 @@ export function TrajectoryView({ const turn = request?.turn ?? node?.turn const step = request?.step ?? node?.step if (turn === undefined || step === undefined) continue - const provider = request?.provenance?.provider ?? node?.provenance?.provider - const model = request?.provenance?.model ?? node?.provenance?.model + const provider = request?.providerInfo?.provider ?? node?.providerInfo?.provider + const model = request?.providerInfo?.model ?? node?.providerInfo?.model const requestConfig = request?.requestConfig ?? node?.requestConfig numbered.push({ seq: entry.seq, @@ -292,12 +292,12 @@ export function TrajectoryView({ ...(request.error === undefined ? {} : { error: request.error }), ...(request.errorCode === undefined ? {} : { errorCode: request.errorCode }), resultSeq: request.startSeq, - ...(request.provenance?.provider === undefined + ...(request.providerInfo?.provider === undefined ? {} - : { provider: request.provenance.provider }), - ...(request.provenance?.model === undefined + : { provider: request.providerInfo.provider }), + ...(request.providerInfo?.model === undefined ? {} - : { model: request.provenance.model }), + : { model: request.providerInfo.model }), ...(request.requestConfig === undefined ? {} : { requestConfig: request.requestConfig }), ...(usage === undefined ? {} : { usage }), ...(cumulativeUsage === undefined ? {} : { cumulativeUsage }), diff --git a/packages/client/ui-trajectory/src/client/trajectory-assistant-definition.ts b/packages/client/ui-trajectory/src/client/trajectory-assistant-definition.ts index 2bc68039d6..792eb63bae 100644 --- a/packages/client/ui-trajectory/src/client/trajectory-assistant-definition.ts +++ b/packages/client/ui-trajectory/src/client/trajectory-assistant-definition.ts @@ -252,7 +252,7 @@ function finalNode( step: state.step, blocks: toAssistantBlocks(event.data.message.content), usage: event.data.usage, - provenance: { + providerInfo: { provider: event.data.message.source.provider, model: event.data.message.source.model, }, @@ -309,7 +309,7 @@ function assistantRequest( ? {} : { resultSeq: node.seq, - ...(node.provenance === undefined ? {} : { provenance: node.provenance }), + ...(node.providerInfo === undefined ? {} : { providerInfo: node.providerInfo }), }), ...(state.usage === undefined ? {} : { usage: state.usage }), } diff --git a/packages/client/ui-trajectory/src/client/trajectory-compaction-definition.ts b/packages/client/ui-trajectory/src/client/trajectory-compaction-definition.ts index c5487bbb91..8e45be67a9 100644 --- a/packages/client/ui-trajectory/src/client/trajectory-compaction-definition.ts +++ b/packages/client/ui-trajectory/src/client/trajectory-compaction-definition.ts @@ -64,7 +64,7 @@ function requestFromState( resultSeq: summary.seq, summary: summary.data.summary, ...(summary.data.rawOutput === undefined ? {} : { rawOutput: summary.data.rawOutput }), - provenance: { provider: summary.data.provider, model: summary.data.model }, + providerInfo: { provider: summary.data.provider, model: summary.data.model }, requestConfig: { provider: summary.data.provider, model: summary.data.model, diff --git a/packages/client/ui-trajectory/src/client/trajectory-event-projection.ts b/packages/client/ui-trajectory/src/client/trajectory-event-projection.ts index d97aa40789..c132e88747 100644 --- a/packages/client/ui-trajectory/src/client/trajectory-event-projection.ts +++ b/packages/client/ui-trajectory/src/client/trajectory-event-projection.ts @@ -2,7 +2,7 @@ import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm/types' import type { - AssistantBlock, ContextProvenanceView, KnownContextForm, + AssistantBlock, ContextProducerView, KnownContextForm, } from '@deepseek-ai/dsh-client-ui-conversation/client' /* jscpd:ignore-start -- Chat and Trajectory own independent event-to-view projections. */ @@ -57,7 +57,7 @@ export function contextForm(source: unknown): KnownContextForm | null { * @param source - Logged `user/message` source. * @returns Role and label rendered by Trajectory. */ -export function contextProvenance(source: unknown): ContextProvenanceView { +export function contextProducer(source: unknown): ContextProducerView { const record = asRecord(source) const kind = record === null ? null : readString(record, 'kind') if (record === null || kind === null) return { role: 'inject', label: null } diff --git a/packages/client/ui-trajectory/src/client/trajectory-message-definitions.ts b/packages/client/ui-trajectory/src/client/trajectory-message-definitions.ts index deb4097406..1faaeb3547 100644 --- a/packages/client/ui-trajectory/src/client/trajectory-message-definitions.ts +++ b/packages/client/ui-trajectory/src/client/trajectory-message-definitions.ts @@ -5,7 +5,7 @@ import type { } from '@deepseek-ai/dsh-client-ui-conversation/client' import type {} from '@deepseek-ai/dsh-agent/types' import { trajectoryNode } from './trajectory-definition-common.ts' -import { contextForm, contextProvenance } from './trajectory-event-projection.ts' +import { contextForm, contextProducer } from './trajectory-event-projection.ts' /* jscpd:ignore-start -- Target-owned Definitions intentionally keep their event * state machines independent; see ../../../../../.agents/notes/implemented/ @@ -151,7 +151,7 @@ const trajectoryMessageDefinition: ConversationNodeDefinition = { time: event.time, content: event.data.content, source: event.data.source, - provenance: contextProvenance(event.data.source), + producer: contextProducer(event.data.source), form: contextForm(event.data.source), } } diff --git a/packages/client/ui-trajectory/tests/conversation-definitions.client.spec.ts b/packages/client/ui-trajectory/tests/conversation-definitions.client.spec.ts index abcf09646f..6e2c89e911 100644 --- a/packages/client/ui-trajectory/tests/conversation-definitions.client.spec.ts +++ b/packages/client/ui-trajectory/tests/conversation-definitions.client.spec.ts @@ -397,7 +397,7 @@ describe('Trajectory conversation Definitions', () => { purpose: 'assistant', resultSeq: 3, status: 'error', - provenance: { provider: 'test', model: 'test' }, + providerInfo: { provider: 'test', model: 'test' }, }]) }) diff --git a/packages/client/ui-trajectory/tests/event-projection.client.spec.ts b/packages/client/ui-trajectory/tests/event-projection.client.spec.ts index 9d2d8ff433..0405cd9cc5 100644 --- a/packages/client/ui-trajectory/tests/event-projection.client.spec.ts +++ b/packages/client/ui-trajectory/tests/event-projection.client.spec.ts @@ -1,27 +1,27 @@ import { describe, expect, it } from 'vitest' import type { ContentBlock } from '@deepseek-ai/dsh-llm/types' import { - contextForm, contextProvenance, displayFailure, emptyAssistantBlock, isTokenDelta, + contextForm, contextProducer, displayFailure, emptyAssistantBlock, isTokenDelta, toAssistantBlock, toAssistantBlocks, } from '../src/client/trajectory-event-projection.ts' describe('Trajectory event projection', () => { it('projects known, unknown, and unreadable context sources', () => { - expect(contextProvenance({ kind: 'session-reference', references: [{ label: 'A' }, { label: 'A' }] })) + expect(contextProducer({ kind: 'session-reference', references: [{ label: 'A' }, { label: 'A' }] })) .toEqual({ role: 'recall', label: 'A' }) - expect(contextProvenance({ kind: 'session-reference', references: [] })) + expect(contextProducer({ kind: 'session-reference', references: [] })) .toEqual({ role: 'recall', label: 'session-reference' }) - expect(contextProvenance({ kind: 'agent-instructions', changes: [{ path: 'AGENTS.md' }, null] })) + expect(contextProducer({ kind: 'agent-instructions', changes: [{ path: 'AGENTS.md' }, null] })) .toEqual({ role: 'inject', label: 'AGENTS.md' }) - expect(contextProvenance({ kind: 'agent-instructions', changes: 'bad' }).label) + expect(contextProducer({ kind: 'agent-instructions', changes: 'bad' }).label) .toBe('agent-instructions') - expect(contextProvenance({ kind: 'plugin', plugin: 'p' }).label).toBe('p') - expect(contextProvenance({ kind: 'plugin', plugin: 1 }).label).toBe('plugin') - expect(contextProvenance({ kind: 'skill-invocation', name: 's' }).label).toBe('s') - expect(contextProvenance({ kind: 'future' }).label).toBe('future') - expect(contextProvenance(null)).toEqual({ role: 'inject', label: null }) - expect(contextProvenance([])).toEqual({ role: 'inject', label: null }) - expect(contextProvenance({ kind: '' })).toEqual({ role: 'inject', label: null }) + expect(contextProducer({ kind: 'plugin', plugin: 'p' }).label).toBe('p') + expect(contextProducer({ kind: 'plugin', plugin: 1 }).label).toBe('plugin') + expect(contextProducer({ kind: 'skill-invocation', name: 's' }).label).toBe('s') + expect(contextProducer({ kind: 'future' }).label).toBe('future') + expect(contextProducer(null)).toEqual({ role: 'inject', label: null }) + expect(contextProducer([])).toEqual({ role: 'inject', label: null }) + expect(contextProducer({ kind: '' })).toEqual({ role: 'inject', label: null }) }) it('accepts only forms supported by the target', () => { diff --git a/packages/compaction/command-compact/tests/command-compact.spec.ts b/packages/compaction/command-compact/tests/command-compact.spec.ts index bd312d2a99..cf4fc3eb3a 100644 --- a/packages/compaction/command-compact/tests/command-compact.spec.ts +++ b/packages/compaction/command-compact/tests/command-compact.spec.ts @@ -64,13 +64,13 @@ class StubCompactionEngine extends CompactionEngine { result: CompactionResult, sourceCommandId: Parameters[2], ): CompactionResult { - const provenance = { + const operationIds = { compactionId: result.compactionId, ...sourceCommandId === undefined ? {} : { sourceCommandId }, } - agent.session.append('compaction/start', { ...provenance, turn: null }) + agent.session.append('compaction/start', { ...operationIds, turn: null }) agent.session.append('compaction/summary', { - ...provenance, + ...operationIds, summary: result.summary, shadowedRange: result.shadowedRange, shadowedSeqs: result.shadowedSeqs, @@ -78,8 +78,8 @@ class StubCompactionEngine extends CompactionEngine { provider: 'command-test', model: 'command-test', }) - agent.session.append('compaction/end', { ...provenance, turn: null }) - return { ...result, ...provenance } + agent.session.append('compaction/end', { ...operationIds, turn: null }) + return { ...result, ...operationIds } } } diff --git a/packages/compaction/command-compact/tests/loader-composition.spec.ts b/packages/compaction/command-compact/tests/loader-composition.spec.ts index 57367b2c7b..d37448d5ad 100644 --- a/packages/compaction/command-compact/tests/loader-composition.spec.ts +++ b/packages/compaction/command-compact/tests/loader-composition.spec.ts @@ -50,13 +50,13 @@ class LoaderCompactionEngine extends CompactionEngine { _signal: AbortSignal, sourceCommandId?: Parameters[2], ): Promise { - const provenance = { + const operationIds = { compactionId: RESULT.compactionId, ...sourceCommandId === undefined ? {} : { sourceCommandId }, } - agent.session.append('compaction/start', { ...provenance, turn: null }) + agent.session.append('compaction/start', { ...operationIds, turn: null }) agent.session.append('compaction/summary', { - ...provenance, + ...operationIds, summary: RESULT.summary, shadowedRange: RESULT.shadowedRange, shadowedSeqs: RESULT.shadowedSeqs, @@ -64,8 +64,8 @@ class LoaderCompactionEngine extends CompactionEngine { provider: 'loader-test', model: 'loader-test', }) - agent.session.append('compaction/end', { ...provenance, turn: null }) - return Promise.resolve({ ...RESULT, ...provenance }) + agent.session.append('compaction/end', { ...operationIds, turn: null }) + return Promise.resolve({ ...RESULT, ...operationIds }) } } diff --git a/packages/compaction/compaction-basic/src/region.ts b/packages/compaction/compaction-basic/src/region.ts index e8efef2b12..048c732c8d 100644 --- a/packages/compaction/compaction-basic/src/region.ts +++ b/packages/compaction/compaction-basic/src/region.ts @@ -470,7 +470,7 @@ function commitCompactionBody( usage, checkpointMessage, } = summarized - const callProvenance = summarized.llmStreamCall === true + const callRecord = summarized.llmStreamCall === true ? { rawOutput: summarized.rawOutput, llmStreamCall: true as const } : summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput } const summaryEvent = session.append('compaction/summary', { @@ -479,7 +479,7 @@ function commitCompactionBody( ? {} : { sourceCommandId: startEvent.data.sourceCommandId }, summary, - ...callProvenance, + ...callRecord, shadowedRange: { start, end }, shadowedSeqs: [...shadowedSeqs], shadowedTokenCount, diff --git a/packages/compaction/compaction/src/checkpoint.ts b/packages/compaction/compaction/src/checkpoint.ts index 116ff18aa5..395a70c1f6 100644 --- a/packages/compaction/compaction/src/checkpoint.ts +++ b/packages/compaction/compaction/src/checkpoint.ts @@ -1,5 +1,5 @@ /** - * Compaction checkpoint provenance: the correlated source constructor and type + * Compaction checkpoint source: the correlated constructor and type * every backend uses for its replacement user message, plus the predicate that * recognizes persisted checkpoints. * @@ -18,14 +18,14 @@ import type { CompactionId } from './brand.ts' const COMPACT_CHECKPOINT_MARKER = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const) -/** Message provenance carried by a concrete compaction checkpoint. */ +/** Message source carried by a concrete compaction checkpoint. */ export type CompactionCheckpointSource = typeof COMPACT_CHECKPOINT_MARKER & { readonly compactionId: CompactionId readonly sourceCommandId?: CommandId } /** - * Create checkpoint provenance correlated with one compaction transaction. + * Create a checkpoint source correlated with one compaction transaction. * @param compactionId - owning compaction identity. * @param sourceCommandId - initiating manual command, when present. * @returns immutable checkpoint source. diff --git a/packages/compaction/compaction/tests/invariant.spec.ts b/packages/compaction/compaction/tests/invariant.spec.ts index ff49a3400e..20269e558e 100644 --- a/packages/compaction/compaction/tests/invariant.spec.ts +++ b/packages/compaction/compaction/tests/invariant.spec.ts @@ -334,7 +334,7 @@ describe('compaction invariants', () => { })).toThrow(/compaction checkpoint id .* does not match compaction\/start id/) }) - it('requires checkpoint provenance to name an open transaction', async () => { + it('requires a checkpoint source to name an open transaction', async () => { const ctx = await setup() const withoutStart = ctx.sessions.create() const original = withoutStart.append('user/message', createUserMessage({ diff --git a/packages/context/session-reference/README.i18n.yaml b/packages/context/session-reference/README.i18n.yaml index 2436daf6f1..7bd0b1d5f8 100644 --- a/packages/context/session-reference/README.i18n.yaml +++ b/packages/context/session-reference/README.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 packages/context/session-reference/README.md -README.md: a7da16668c32ae50568e4012221bbaf6b7da7d2d +README.md: 533a1282da920b6daa47ef5be98e49c691a8cb84 README.zh.md: e7b43c9a56cd5b4062770144ccea0bf125153b40 diff --git a/packages/context/session-reference/README.md b/packages/context/session-reference/README.md index a7da16668c..533a1282da 100644 --- a/packages/context/session-reference/README.md +++ b/packages/context/session-reference/README.md @@ -68,7 +68,7 @@ This section explains the design of the service; the observable behavior is cove Preparation reads each referenced session's current surface exactly once, when the target message reaches `agent/pre-step`. Both preview and spill use that same captured projection: direct-user text, assistant text, and user checkpoints carrying the canonical compaction marker; tools, reasoning, and other injected context are excluded. This prevents recursive reference propagation and prevents a later source mutation from changing the saved transcript. Preview JSON escapes every `<` as `\u003c`, so source text cannot spell the `` framing tag. -The resolver discovers optional storage through `ctx.get("spillStore")` and saves only truncated references. Storage ownership is the target session; provenance identifies the referenced source session and label, without a fabricated tool call. Cancellation is checked after the asynchronous save and prevents publication even if an artifact was written. Artifact expiry remains the backend's existing policy. +The resolver discovers optional storage through `ctx.get("spillStore")` and saves only truncated references. Storage ownership is the target session; the source descriptor identifies the referenced session and label, without a fabricated tool call. Cancellation is checked after the asynchronous save and prevents publication even if an artifact was written. Artifact expiry remains the backend's existing policy. The budget uses the provider and model captured after `system-prompt/assemble` completes for the target agent. Direct `prepare` calls before any assembly use agent options; session headers do not select the budget model. Diagnostic assemblies without an agent do not affect captured routes. diff --git a/packages/context/time-context/README.i18n.yaml b/packages/context/time-context/README.i18n.yaml index a1e84a7b81..1368cfe310 100644 --- a/packages/context/time-context/README.i18n.yaml +++ b/packages/context/time-context/README.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 packages/context/time-context/README.md -README.md: 007cfeb69c5b0434603ab8f75a8e989c76583b66 +README.md: ea6f480b51dddc72f2be1a480053b47045a3f60b README.zh.md: 600a8870860ee1558758d2eaf71220dbcabf9588 diff --git a/packages/context/time-context/README.md b/packages/context/time-context/README.md index 007cfeb69c..ea6f480b51 100644 --- a/packages/context/time-context/README.md +++ b/packages/context/time-context/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -`dsh-time-context` gives the model a clock: on eligible steps it appends a durable, source-attributed reading with the current time, the browser zone attached to the open request, and the elapsed time since the preceding model-visible message. It helps the model interpret otherwise-unqualified dates and times in the user's browser zone, and tells it to ask when zone provenance is mixed or missing. The plugin is opt-in: default compositions leave it disabled, and the Schedule Web overlay mounts it. A positive `refreshIntervalMs` reduces how often readings accumulate; omission or `0` injects at every eligible step. +`dsh-time-context` gives the model a clock: on eligible steps it appends a durable, source-attributed reading with the current time, the browser zone attached to the open request, and the elapsed time since the preceding model-visible message. It helps the model interpret otherwise-unqualified dates and times in the user's browser zone, and tells it to ask when current-turn browser zones are mixed or missing. The plugin is opt-in: default compositions leave it disabled, and the Schedule Web overlay mounts it. A positive `refreshIntervalMs` reduces how often readings accumulate; omission or `0` injects at every eligible step. ## Table of Contents @@ -50,7 +50,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a ### Choosing the zone -When the open turn contains exactly one Host-validated browser zone, the timestamp is formatted in that request-local zone. With missing or mixed browser provenance, the configured `timeZone` formats the display; omitting it resolves the Node process zone once at plugin load, and every explicit fallback is validated through `Intl.DateTimeFormat`. The resolved instruction tells the model to interpret unqualified dates and times in the chosen zone, and to ask the user to clarify when provenance is mixed or unavailable. +When the open turn contains exactly one Host-validated browser zone, the timestamp is formatted in that request-local zone. With missing or mixed browser-zone records, the configured `timeZone` formats the display; omitting it resolves the Node process zone once at plugin load, and every explicit fallback is validated through `Intl.DateTimeFormat`. The resolved instruction tells the model to interpret unqualified dates and times in the chosen zone, and to ask the user to clarify when those records are mixed or unavailable. ----- @@ -134,9 +134,9 @@ Append-only; newly visible content follows the reusable request prefix and does These limits define when clock context is a poor fit. They are current package constraints. -- **Prompt provenance only** — browser-zone context guides natural-language interpretation but does not silently supply another tool's required zone field. +- **Prompt guidance only** — browser-zone context guides natural-language interpretation but does not silently supply another tool's required zone field. - **Mixed turns ask** — if one open turn contains prompts from different browser zones, the model is told to clarify rather than guess which one owns an unqualified time. -- **Fallback is not user authority** — the configured or process zone formats the clock when browser provenance is missing or mixed, but the model-facing policy still says to clarify. +- **Fallback is not user authority** — the configured or process zone formats the clock when current-turn browser zones are missing or mixed, but the model-facing policy still says to clarify. - **Whole-second display** — timestamps and durations omit sub-second precision even though durable event times retain milliseconds. - **History cost between compactions** — omission or `0` retains one reading for every eligible attempt; a positive interval reduces but does not eliminate this cost and may leave a later request without fresh browser-zone guidance. diff --git a/packages/context/time-context/tests/invariant.spec.ts b/packages/context/time-context/tests/invariant.spec.ts index 51ebd42629..74ab8b5241 100644 --- a/packages/context/time-context/tests/invariant.spec.ts +++ b/packages/context/time-context/tests/invariant.spec.ts @@ -102,7 +102,7 @@ describe('time-context invariants', () => { }).not.toThrow() }) - it('requires browser-zone policy and timestamp to match current-turn request provenance', async () => { + it('requires browser-zone policy and timestamp to match current-turn request sources', async () => { const ctx = await setup() const policy = 'Browser time zone for this request: Asia/Shanghai. ' + 'Interpret otherwise-unqualified dates and times in this zone.' @@ -150,7 +150,7 @@ describe('time-context invariants', () => { } }) - it('rejects invalid browser provenance loaded across the durable boundary', async () => { + it('rejects invalid browser-zone data loaded across the durable boundary', async () => { const ctx = await setup() const timeZone = 'Not/A_Real_Zone' const policy = `Browser time zone for this request: ${timeZone}. ` @@ -283,7 +283,7 @@ describe('time-context invariants', () => { }).toThrow(message) }) - it('requires exact snapshot provenance without copied request authority', async () => { + it('requires the exact snapshot source without copied request authority', async () => { const ctx = await setup() const base = event(reading()) for (const source of [ diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml index 2936b69d34..cff528aef5 100644 --- a/packages/core/agent-loop/README.i18n.yaml +++ b/packages/core/agent-loop/README.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 packages/core/agent-loop/README.md -README.md: cff0eb77b8464d49908bbd7b0e7a1b0658ed2f3c -README.zh.md: 94fb5406193300abc3077462407fdc8b1dd742a0 +README.md: 780fed31a34113e01d7c98313bd88b5c322a8332 +README.zh.md: 766ff4a2e7287f6987b4443c19f3164d7e2cd2f3 diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md index cff0eb77b8..780fed31a3 100644 --- a/packages/core/agent-loop/README.md +++ b/packages/core/agent-loop/README.md @@ -92,7 +92,7 @@ The package is the one concrete implementation of the public `Agent` contract. I After `agent/request`, `ctx.llm.prepareCall()` validates adapter-owned fields and resolves reasoning-effort and output-token defaults under the active turn signal. The loop retains that exact adapter through resolution, `request/header` logging, and dispatch. It writes a full header for the first request, a changed envelope (config or tools — the prompt is not part of the header), an explicit message-series start, a request after surface replacement (an in-place prompt replacement or compaction), and resume; unchanged steps, retries, and ordinary later turns in the same series inherit the latest header, and an in-history prompt append is not a replacement, so the request that follows it inherits the header too. Beside the header, the loop logs `request/context` — provider, model, `contextWindow`, and the route's `systemPromptUpdate` mode from `prepareCall()` — only when one of those differs from the latest snapshot. Before the next waterfall, the loop removes adapter-default fields so the current route resolves them again, while explicit settings persist. An unhandled route still fails with `NO_ADAPTER`. -The loop deep-freezes each derived message identity on its first request and reuses that proof only within the same agent. Restored messages keep their identity; request construction does not freeze their containing event wrappers. Each request freezes its local canonical header, fresh message array, and envelope while leaving the cancellation signal live. The [request-freeze decision](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.md) explains ownership and measurement. +The loop deep-freezes each derived message identity on its first request and reuses that proof only within the same agent. Restored messages keep their identity; request construction does not freeze their containing event wrappers. Each request freezes its local canonical header, fresh message array, and envelope while leaving the cancellation signal live. The [request-freeze decision](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.md) explains ownership and measurement. ### Source map diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md index 94fb540619..766ff4a2e7 100644 --- a/packages/core/agent-loop/README.zh.md +++ b/packages/core/agent-loop/README.zh.md @@ -92,7 +92,7 @@ const handle = await ctx.agents.create({ `agent/request` 返回后,`ctx.llm.prepareCall()` 会在活跃轮次信号下校验适配器持有的字段,并解析推理强度和输出 token 默认值。循环会在解析、`request/header` 记录与分派期间保留同一个适配器。循环会为首次请求、变化的 envelope(配置或工具——提示词不属于 header)、显式消息序列起点、surface 替换(原地替换提示词或压缩(compaction))后的请求及恢复写入完整 header;同一序列内内容未变的步骤、重试与普通后续轮次继承最新 header,历史内追加提示词不是替换,因此紧随其后的请求同样继承 header。在 header 之外,循环还会记录 `request/context`——提供方、模型、`contextWindow` 以及来自 `prepareCall()` 的路由 `systemPromptUpdate` 模式——且仅在其中任何一项与最新快照不同时记录。下一次 waterfall 分发前,循环移除适配器默认字段,使当前路由重新解析它们;显式设置则保留。未处理的路由仍以 `NO_ADAPTER` 失败。 -循环在每个派生消息对象首次进入请求时执行深冻结,并且仅在同一 agent 内复用该证明。恢复的消息保留对象身份;构造请求不会冻结包含消息的事件包装对象。每个请求都会冻结本地规范化 header、新消息数组和请求封装,同时保留取消信号的可变性。[请求冻结决策](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-provenance.zh.md)解释了所有权与测量依据。 +循环在每个派生消息对象首次进入请求时执行深冻结,并且仅在同一 agent 内复用该证明。恢复的消息保留对象身份;构造请求不会冻结包含消息的事件包装对象。每个请求都会冻结本地规范化 header、新消息数组和请求封装,同时保留取消信号的可变性。[请求冻结决策](../../../.agents/notes/implemented/simplification/2026-09-06-agent-request-freeze-evidence.zh.md)解释了所有权与测量依据。 ### 源码地图 diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index e4ccbdc3ec..c74112c5a6 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/README.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 packages/core/session/README.md -README.md: a18fd0de73a6aa7dc881f1472d991c133f81ad55 +README.md: 2368e20df012b16ed12f35de327db62c71ee3269 README.zh.md: 84cc0aa35da11a5a782e1949e32852785fb681c4 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index a18fd0de73..2368e20df0 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -135,7 +135,7 @@ The package-level contract is enough for most consumers; read these when you nee #### What the model sees -The model receives the complete messages from `system/message`, `user/message`, `assistant/message`, and `tool/result` surface entries verbatim, the system prompt first — identities, roles, sources, and content blocks are the same values established at creation, and projections never mint identities. Direct prompts and injected context remain separate `user/message` events whose sources preserve their provenance. Embedded streams, `assistant/attempt`, boundaries, and other log-only facts add no message. +The model receives the complete messages from `system/message`, `user/message`, `assistant/message`, and `tool/result` surface entries verbatim, the system prompt first — identities, roles, sources, and content blocks are the same values established at creation, and projections never mint identities. Direct prompts and injected context remain separate `user/message` events whose sources preserve their attribution. Embedded streams, `assistant/attempt`, boundaries, and other log-only facts add no message. #### Token effect diff --git a/packages/core/session/src/surface.ts b/packages/core/session/src/surface.ts index 5d8ce74fe2..a702f9618a 100644 --- a/packages/core/session/src/surface.ts +++ b/packages/core/session/src/surface.ts @@ -266,7 +266,7 @@ function surfaceOpOf(event: SessionEvent): SurfaceOp | undefined { } /** Validate cited source-event seqs against prior log entries and the replacement range. */ -function assertProvenance( +function assertSourceEventReferences( event: SessionEvent, shadowedSeqs: readonly SessionSeq[], ): void { @@ -316,7 +316,7 @@ export function validateSurfaceMetadata(event: SessionEvent): SurfaceOp | undefi && (op.startSeq >= event.seq || op.endSeq >= event.seq)) { throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`) } - if (op !== undefined) assertProvenance(event, []) + if (op !== undefined) assertSourceEventReferences(event, []) return op } @@ -434,7 +434,7 @@ function planSurfaceEvent( return { kind: 'append', seq: event.seq } } const range = replacementRange(state, surfaceOp) - assertProvenance(event, range.shadowedSeqs) + assertSourceEventReferences(event, range.shadowedSeqs) assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq) assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq) return { diff --git a/packages/core/session/tests/canonical-envelopes.spec.ts b/packages/core/session/tests/canonical-envelopes.spec.ts index 123852762d..ec78041a8b 100644 --- a/packages/core/session/tests/canonical-envelopes.spec.ts +++ b/packages/core/session/tests/canonical-envelopes.spec.ts @@ -252,7 +252,7 @@ describe('canonical event-local surface metadata', () => { expect(() => accept({ ...userEvent(), surfaceOp } as unknown as SessionEvent)).toThrow(/invalid replace surfaceOp/) }) - it(path + ' requires markers and forbids non-surface and assistant provenance', () => { + it(path + ' requires markers and forbids non-surface and assistant source-event references', () => { const { surfaceOp: _op, ...markerless } = userEvent() expect(() => accept(markerless as SessionEvent)).toThrow(/requires a surfaceOp marker/) expect(() => accept({ type: 'turn/start', seq: SessionSeq(0), time: 1, data: { turn: 1 }, surfaceOp: 'append' } as never)) @@ -293,7 +293,7 @@ describe('canonical event-local surface metadata', () => { } }) - it('requires system placement and preserves system data and provenance on head replacements', () => { + it('requires system placement and preserves system data and source-event references on head replacements', () => { const session = Session.create(id) const data = { turn: 1, step: 1, message: createSystemMessage('head', 'fixture'), extra: { nested: true } } const head = session.append('system/message', data, { surfaceOp: 'append' }) @@ -319,7 +319,7 @@ describe('canonical event-local surface metadata', () => { expect(snapshotSessionEvent(event)).toEqual(event) }) - it('requires surface intent on event variants and forbids assistant provenance in types', () => { + it('requires surface intent on event variants and forbids assistant source-event references in types', () => { expectTypeOf().toEqualTypeOf>() expectTypeOf, 'surfaceOp'>>().not.toExtend>() expectTypeOf<{ surfaceOp: 'append'; sourceEventSeqs: SessionSeq[] }>().not.toExtend>() diff --git a/packages/core/session/tests/seq-ranges.spec.ts b/packages/core/session/tests/seq-ranges.spec.ts index cace9b53c3..89a05dc50a 100644 --- a/packages/core/session/tests/seq-ranges.spec.ts +++ b/packages/core/session/tests/seq-ranges.spec.ts @@ -21,7 +21,7 @@ describe('sourceEventSeqs ranges', () => { expect(encodeSeqRanges(seqs([3, 2]))).toEqual([3, 2]) }) - it('does not impose a persistence-only provenance length limit', () => { + it('does not impose a persistence-only source-event length limit', () => { const values = Array.from({ length: 1_000_001 }, (_, index) => SessionSeq(index)) expect(encodeSeqRanges(values)).toEqual([[0, 1_000_000]]) }) diff --git a/packages/core/session/tests/surface.spec.ts b/packages/core/session/tests/surface.spec.ts index 6d10e22335..c861e17b3b 100644 --- a/packages/core/session/tests/surface.spec.ts +++ b/packages/core/session/tests/surface.spec.ts @@ -64,7 +64,7 @@ function surfaceSession(): Session { return s } -function provenanceEvent(seq: SessionSeq, sourceEventSeqs: unknown): SessionEvent { +function sourceEventReferenceEvent(seq: SessionSeq, sourceEventSeqs: unknown): SessionEvent { return { type: 'user/message', seq, @@ -104,10 +104,10 @@ function toolResultEvent( describe('foldSurface source-event references', () => { it('accepts absent or valid source-event references and complete replacement coverage', () => { const events = [ - provenanceEvent(SessionSeq(0), undefined), - provenanceEvent(SessionSeq(1), undefined), + sourceEventReferenceEvent(SessionSeq(0), undefined), + sourceEventReferenceEvent(SessionSeq(1), undefined), { - ...provenanceEvent(SessionSeq(2), [0, 1]), + ...sourceEventReferenceEvent(SessionSeq(2), [0, 1]), surfaceOp: surfaceOp({ op: 'replace', startSeq: 0, endSeq: 1 }), }, ] as SessionEvent[] @@ -125,7 +125,7 @@ describe('foldSurface source-event references', () => { expect(() => foldSurface([event])).toThrow(/cannot carry sourceEventSeqs/) }) - it('rejects obsolete source-event provenance on an assistant message', () => { + it('rejects obsolete Assistant chunk references on an assistant message', () => { const event = { type: 'assistant/message', seq: SessionSeq(0), @@ -150,19 +150,19 @@ describe('foldSurface source-event references', () => { }) it.each([ - ['a non-array', [{ ...provenanceEvent(SessionSeq(0), undefined), sourceEventSeqs: 'invalid' }], /must be an array/], - ['an empty array', [provenanceEvent(SessionSeq(0), [])], /must not be empty/], - ['duplicates', [provenanceEvent(SessionSeq(0), undefined), provenanceEvent(SessionSeq(1), [0, 0])], /must not contain duplicates/], - ['a sparse array', [provenanceEvent(SessionSeq(0), Array(1))], /densely contain/], - ['a non-number', [{ ...provenanceEvent(SessionSeq(0), undefined), sourceEventSeqs: ['0'] }], /non-negative safe integers/], - ['a fractional number', [provenanceEvent(SessionSeq(0), [0.5])], /non-negative safe integers/], - ['a negative number', [provenanceEvent(SessionSeq(0), [-1])], /non-negative safe integers/], - ['a self reference', [provenanceEvent(SessionSeq(0), [0])], /must reference earlier events/], - ['a non-contiguous event seq', [provenanceEvent(SessionSeq(0), undefined), provenanceEvent(SessionSeq(2), [1])], /seq 2 is not contiguous; expected 1/], + ['a non-array', [{ ...sourceEventReferenceEvent(SessionSeq(0), undefined), sourceEventSeqs: 'invalid' }], /must be an array/], + ['an empty array', [sourceEventReferenceEvent(SessionSeq(0), [])], /must not be empty/], + ['duplicates', [sourceEventReferenceEvent(SessionSeq(0), undefined), sourceEventReferenceEvent(SessionSeq(1), [0, 0])], /must not contain duplicates/], + ['a sparse array', [sourceEventReferenceEvent(SessionSeq(0), Array(1))], /densely contain/], + ['a non-number', [{ ...sourceEventReferenceEvent(SessionSeq(0), undefined), sourceEventSeqs: ['0'] }], /non-negative safe integers/], + ['a fractional number', [sourceEventReferenceEvent(SessionSeq(0), [0.5])], /non-negative safe integers/], + ['a negative number', [sourceEventReferenceEvent(SessionSeq(0), [-1])], /non-negative safe integers/], + ['a self reference', [sourceEventReferenceEvent(SessionSeq(0), [0])], /must reference earlier events/], + ['a non-contiguous event seq', [sourceEventReferenceEvent(SessionSeq(0), undefined), sourceEventReferenceEvent(SessionSeq(2), [1])], /seq 2 is not contiguous; expected 1/], ['incomplete replacement coverage', [ - provenanceEvent(SessionSeq(0), undefined), - provenanceEvent(SessionSeq(1), undefined), - { ...provenanceEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', startSeq: 0, endSeq: 1 } }, + sourceEventReferenceEvent(SessionSeq(0), undefined), + sourceEventReferenceEvent(SessionSeq(1), undefined), + { ...sourceEventReferenceEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', startSeq: 0, endSeq: 1 } }, ], /missing 1/], ] as const)( 'rejects %s', @@ -175,8 +175,8 @@ describe('foldSurface source-event references', () => { describe('foldSurface tool-result rewrites', () => { it('rejects a replacement spanning multiple current nodes', () => { const events = [ - provenanceEvent(SessionSeq(0), undefined), - provenanceEvent(SessionSeq(1), undefined), + sourceEventReferenceEvent(SessionSeq(0), undefined), + sourceEventReferenceEvent(SessionSeq(1), undefined), toolResultEvent(SessionSeq(2), 'rewrite', { op: 'replace', startSeq: 0, endSeq: 1 }, [0, 1]), ] expect(() => foldSurface(events)).toThrow(/must rewrite exactly one current node/) @@ -184,7 +184,7 @@ describe('foldSurface tool-result rewrites', () => { it('rejects a replacement targeting a non-result node', () => { const events = [ - provenanceEvent(SessionSeq(0), undefined), + sourceEventReferenceEvent(SessionSeq(0), undefined), toolResultEvent(SessionSeq(1), 'rewrite', { op: 'replace', startSeq: 0, endSeq: 0 }, [0]), ] expect(() => foldSurface(events)).toThrow(/must target a current tool\/result/) @@ -267,10 +267,10 @@ describe('SurfaceManager', () => { it('folds a contiguous window without materializing earlier event sequences', () => { const baseSeq = 400_000 const events = [ - provenanceEvent(SessionSeq(baseSeq), undefined), - provenanceEvent(SessionSeq(baseSeq + 1), undefined), + sourceEventReferenceEvent(SessionSeq(baseSeq), undefined), + sourceEventReferenceEvent(SessionSeq(baseSeq + 1), undefined), { - ...provenanceEvent(SessionSeq(baseSeq + 2), [baseSeq]), + ...sourceEventReferenceEvent(SessionSeq(baseSeq + 2), [baseSeq]), surfaceOp: surfaceOp({ op: 'replace', startSeq: baseSeq, endSeq: baseSeq }), }, ] as SessionEvent[] @@ -300,9 +300,9 @@ describe('SurfaceManager', () => { it('rejects a replacement that crosses a loaded window head', () => { const baseSeq = 400_000 const events = [ - provenanceEvent(SessionSeq(baseSeq), undefined), + sourceEventReferenceEvent(SessionSeq(baseSeq), undefined), { - ...provenanceEvent(SessionSeq(baseSeq + 1), [baseSeq - 1, baseSeq]), + ...sourceEventReferenceEvent(SessionSeq(baseSeq + 1), [baseSeq - 1, baseSeq]), surfaceOp: surfaceOp({ op: 'replace', startSeq: baseSeq - 1, endSeq: baseSeq }), }, ] as SessionEvent[] @@ -361,9 +361,9 @@ describe('SurfaceManager', () => { it('foldSurface reports the same invalid replacement failures as the incremental manager', () => { const events = [ - provenanceEvent(SessionSeq(0), undefined), + sourceEventReferenceEvent(SessionSeq(0), undefined), { type: 'turn/start', seq: SessionSeq(1), time: 1, data: { turn: 1 } }, - { ...provenanceEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', startSeq: 1, endSeq: 0 } }, + { ...sourceEventReferenceEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', startSeq: 1, endSeq: 0 } }, ] as SessionEvent[] expect(() => foldSurface(events)).toThrow(/start seq 1 not found/) @@ -373,7 +373,7 @@ describe('SurfaceManager', () => { it('rejects negative-zero replacement event sequences', () => { const event = { - ...provenanceEvent(SessionSeq(0), [0]), + ...sourceEventReferenceEvent(SessionSeq(0), [0]), surfaceOp: { op: 'replace', startSeq: -0, endSeq: -0 }, } as SessionEvent diff --git a/packages/extensions/tool-cordis/src/api-catalog.ts b/packages/extensions/tool-cordis/src/api-catalog.ts index 2804caa564..82a15f1920 100644 --- a/packages/extensions/tool-cordis/src/api-catalog.ts +++ b/packages/extensions/tool-cordis/src/api-catalog.ts @@ -3711,8 +3711,8 @@ export const TYPE_API: readonly TypeApiEntry[] = [ declaration: 'export interface AssistantMessage extends Message {\n readonly role: \'assistant\';\n readonly source: ModelMessageSource;\n}', }, { - name: 'AssistantProvenance', - declaration: 'export interface AssistantProvenance {\n provider: string;\n model: string;\n replayState?: unknown;\n}', + name: 'AssistantProviderMetadata', + declaration: 'export interface AssistantProviderMetadata {\n provider: string;\n model: string;\n replayState?: unknown;\n}', }, { name: 'AssistantStreamFrame', @@ -4716,7 +4716,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'ModelMessageSource', - declaration: 'export interface ModelMessageSource extends AssistantProvenance {\n kind: \'model\';\n}', + declaration: 'export interface ModelMessageSource extends AssistantProviderMetadata {\n kind: \'model\';\n}', }, { name: 'ModelModality', @@ -5475,8 +5475,8 @@ export const TYPE_API: readonly TypeApiEntry[] = [ declaration: 'export interface SessionTitleEventData {\n readonly title: string;\n readonly messageSeqs: SessionSeq[];\n readonly source: SessionTitleSource;\n}', }, { - name: 'SessionTitleModelProvenance', - declaration: 'export interface SessionTitleModelProvenance {\n readonly provider: string;\n readonly model: string;\n}', + name: 'SessionTitleModelIdentity', + declaration: 'export interface SessionTitleModelIdentity {\n readonly provider: string;\n readonly model: string;\n}', }, { name: 'SessionTitleObservation', @@ -5492,11 +5492,11 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionTitleProviderRequest', - declaration: 'export interface SessionTitleProviderRequest {\n readonly session: Session;\n readonly messages: readonly SessionTitleUserMessage[];\n readonly route?: SessionTitleModelProvenance;\n readonly signal: AbortSignal;\n}', + declaration: 'export interface SessionTitleProviderRequest {\n readonly session: Session;\n readonly messages: readonly SessionTitleUserMessage[];\n readonly route?: SessionTitleModelIdentity;\n readonly signal: AbortSignal;\n}', }, { name: 'SessionTitleProviderResult', - declaration: 'export interface SessionTitleProviderResult {\n readonly title: string;\n readonly messageSeqs: readonly SessionSeq[];\n readonly model?: SessionTitleModelProvenance;\n}', + declaration: 'export interface SessionTitleProviderResult {\n readonly title: string;\n readonly messageSeqs: readonly SessionSeq[];\n readonly model?: SessionTitleModelIdentity;\n}', }, { name: 'SessionTitleSnapshot', @@ -5504,7 +5504,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [ }, { name: 'SessionTitleSource', - declaration: 'export type SessionTitleSource = {\n readonly kind: \'fallback\';\n} | {\n readonly kind: \'provider\';\n readonly provider: SessionTitleProviderId;\n readonly model?: SessionTitleModelProvenance;\n} | {\n readonly kind: \'user\';\n};', + declaration: 'export type SessionTitleSource = {\n readonly kind: \'fallback\';\n} | {\n readonly kind: \'provider\';\n readonly provider: SessionTitleProviderId;\n readonly model?: SessionTitleModelIdentity;\n} | {\n readonly kind: \'user\';\n};', }, { name: 'SessionTitleUserMessage', diff --git a/packages/host/plugin-inventory/README.i18n.yaml b/packages/host/plugin-inventory/README.i18n.yaml index 4b2a6a19f1..2cb23a1f0d 100644 --- a/packages/host/plugin-inventory/README.i18n.yaml +++ b/packages/host/plugin-inventory/README.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 packages/host/plugin-inventory/README.md -README.md: f4981bfdee614854a214ef27f1c9463f05585d28 +README.md: b64a017df28716cfd0b5c3a41f437b87b8e4f19e README.zh.md: a29bc402537d88fa512675bfb768502753ca7929 diff --git a/packages/host/plugin-inventory/README.md b/packages/host/plugin-inventory/README.md index f4981bfdee..b64a017df2 100644 --- a/packages/host/plugin-inventory/README.md +++ b/packages/host/plugin-inventory/README.md @@ -9,7 +9,7 @@ English | [中文](README.zh.md) ## Summary -Clients can call `pluginInventory/list` to display the host’s current plugins in load order, including each entry’s identifier, module specifier, effective enablement, and live phase. Deployments with an agent-preset roster also report each preset’s metadata, health, and flattened plugin composition; without a roster, preset data is absent. Each response is a point-in-time, read-only snapshot for display and diagnostics: it cannot mutate plugins and provides no history, provenance, or change subscription. +Clients can call `pluginInventory/list` to display the host’s current plugins in load order, including each entry’s identifier, module specifier, effective enablement, and live phase. Deployments with an agent-preset roster also report each preset’s metadata, health, and flattened plugin composition; without a roster, preset data is absent. Each response is a point-in-time, read-only snapshot for display and diagnostics: it cannot mutate plugins and provides no history, introduction source, or change subscription. ## Table of Contents @@ -97,7 +97,7 @@ None; this package neither assembles nor sends a provider request. These limits define what a point-in-time inventory cannot tell a client. They are current package constraints, not a task backlog. - **Point-in-time state only** — the result contains no durable failure history or subscription; a missing root Fiber is reported as `null`, regardless of why no live root exists. -- **No provenance or mutation** — the service does not identify which bundle, profile, or override introduced an entry, and it cannot enable, disable, add, or remove plugins in either plane. +- **No introduction source or mutation** — the service does not identify which bundle, profile, or override introduced an entry, and it cannot enable, disable, add, or remove plugins in either plane. - **Presets appear only with a roster** — a deployment without `dsh-agent-presets` serves Loader entries alone; the `agentPresets` field is absent rather than empty. diff --git a/packages/interaction/permission-presets/src/index.ts b/packages/interaction/permission-presets/src/index.ts index 9e9a6ec91e..2bfd071fb5 100644 --- a/packages/interaction/permission-presets/src/index.ts +++ b/packages/interaction/permission-presets/src/index.ts @@ -38,7 +38,7 @@ declare module '@deepseek-ai/cordis' { declare module '@deepseek-ai/dsh-session-projection/types' { interface SessionProjectionStateMap { - /** Latest logged permission overrides and constructor-seed provenance. */ + /** Latest logged permission overrides and constructor-seed status. */ permissions: PermissionProjectionState } } @@ -89,7 +89,7 @@ export interface KnobState { approval: ApprovalPolicy | null } -/** Projection state for permission overrides and constructor-seed provenance. */ +/** Projection state for permission overrides and constructor-seed status. */ interface PermissionProjectionState extends KnobState { /** Whether the log contains a constructor-seed boundary. */ seeded: boolean diff --git a/packages/llm/llm-deepseek/src/protocols/messages/replay.ts b/packages/llm/llm-deepseek/src/protocols/messages/replay.ts index 378a5caa8e..d6ff95804b 100644 --- a/packages/llm/llm-deepseek/src/protocols/messages/replay.ts +++ b/packages/llm/llm-deepseek/src/protocols/messages/replay.ts @@ -31,7 +31,7 @@ export function replayState(model: string, blocks: ReplayBlock[]): ReplayEnvelop } /** Validate native replay, discarding unusable metadata before serializing durable content. - * @param message - durable assistant content and provenance. + * @param message - durable assistant content and source metadata. * @param model - target model; cross-model signatures are not portable. * @param onDegrade - diagnostic for unusable metadata; receives no message content or signatures. * @returns index-aligned metadata, absent for foreign, cross-model or degraded history. @@ -51,7 +51,7 @@ function validateReplay(message: Message, model: string): ReplayBlock[] | undefi const envelope = object(message.source.replayState, 'INVALID_REPLAY_STATE') const response = object(envelope.response, 'INVALID_REPLAY_STATE') if (response.kind !== 'deepseek-messages' || response.version !== 1) return fail('unsupported kind or version') - if (response.model !== message.source.model) return fail('model does not match assistant provenance') + if (response.model !== message.source.model) return fail('model does not match assistant source model') if (!Array.isArray(envelope.blocks) || envelope.blocks.length !== message.content.length) return fail('block count mismatch') const blocks = envelope.blocks.map((value, index): ReplayBlock => { const block = object(value, 'INVALID_REPLAY_STATE') diff --git a/packages/llm/llm-deepseek/src/protocols/messages/translate.ts b/packages/llm/llm-deepseek/src/protocols/messages/translate.ts index a8dd6282cf..deb901119e 100644 --- a/packages/llm/llm-deepseek/src/protocols/messages/translate.ts +++ b/packages/llm/llm-deepseek/src/protocols/messages/translate.ts @@ -98,7 +98,7 @@ function stopReason(raw: unknown): FinishReason { /** Translate decoded SSE data into the Harness stream protocol. * @param events - framed, decoded provider events in arrival order. - * @param model - requested model id for durable replay provenance. + * @param model - requested model id stored in durable replay state. * @returns blocks, one final usage value, and exactly one terminal finish. */ export async function* translate(events: AsyncIterable>, model: string): AsyncGenerator { diff --git a/packages/llm/llm-pi-ai/src/stream.ts b/packages/llm/llm-pi-ai/src/stream.ts index 9bc2f98c4c..380eec2ced 100644 --- a/packages/llm/llm-pi-ai/src/stream.ts +++ b/packages/llm/llm-pi-ai/src/stream.ts @@ -135,7 +135,7 @@ export function mapStopReason(message: AssistantMessage, contextWindow?: number) * @param contextWindow - resolved catalog capacity for usage-based overflow detection. * @param callerSignal - caller cancellation state; an aborted caller makes any * in-band terminal error an aborted finish. - * @param requestedModel - request model identity for durable replay provenance. + * @param requestedModel - request model identity recorded for durable replay. * @returns the harness chunks, ending with `usage` then `finish`; throws * `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event. */ diff --git a/packages/llm/llm/src/message.ts b/packages/llm/llm/src/message.ts index 6f920fe019..05af6bae3e 100644 --- a/packages/llm/llm/src/message.ts +++ b/packages/llm/llm/src/message.ts @@ -7,7 +7,7 @@ import type { MessageId, ToolCallId } from './brand.ts' import type { ContentBlock, ToolResultBlock } from './types.ts' /** Provider/model identity and adapter-private replay data for an assistant message. */ -export interface AssistantProvenance { +export interface AssistantProviderMetadata { /** Provider route that produced the message. */ provider: string /** Provider model id that produced the message. */ @@ -21,7 +21,7 @@ export interface AssistantProvenance { } /** Required source of an assistant message produced by a routed model. */ -export interface ModelMessageSource extends AssistantProvenance { +export interface ModelMessageSource extends AssistantProviderMetadata { kind: 'model' } @@ -33,7 +33,7 @@ export interface ToolMessageSource { /** * The kind of information in producer-supplied context, declared by the - * producer beside its provenance. + * producer in the same `MessageSource`. * * `MessageSource.kind` answers *who produced this*; `form` answers *what kind * of thing it is*, and the two axes are deliberately independent — several diff --git a/packages/llm/llm/src/types.ts b/packages/llm/llm/src/types.ts index bfddde7fc4..23a56e73a3 100644 --- a/packages/llm/llm/src/types.ts +++ b/packages/llm/llm/src/types.ts @@ -26,7 +26,7 @@ declare module '@deepseek-ai/cordis' { export type { AssistantMessage, - AssistantProvenance, + AssistantProviderMetadata, Message, MessageSource, MessageSourceMap, diff --git a/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml b/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml index 8756b37184..63b0ceb3ac 100644 --- a/packages/llm/plugin-package-inventory-deepseek/README.i18n.yaml +++ b/packages/llm/plugin-package-inventory-deepseek/README.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 packages/llm/plugin-package-inventory-deepseek/README.md -README.md: 8da1b526608348c8c6ec0ff75d7d472921e12aed +README.md: fd574c6526a759ecad7872bc89e3436927c21815 README.zh.md: 5c333cef4b5ba12485bb28db7780b1f19b59bb7f diff --git a/packages/llm/plugin-package-inventory-deepseek/README.md b/packages/llm/plugin-package-inventory-deepseek/README.md index 8da1b52660..fd574c6526 100644 --- a/packages/llm/plugin-package-inventory-deepseek/README.md +++ b/packages/llm/plugin-package-inventory-deepseek/README.md @@ -60,7 +60,7 @@ None; package lifecycle changes do not alter the model-visible prefix. -- **Loader package provenance only** — programmatic child fibers and in-memory dynamic plugins do not have authoritative npm name/version provenance and remain outside this inventory. +- **Loader package identity only** — programmatic child fibers and in-memory dynamic plugins do not have authoritative npm names and versions and remain outside this inventory. - **Loose modules are omitted** — a relative file without a named and versioned owning manifest is a plugin module, not a plugin package. - **In-place package replacement requires restart** — manifest identities are cached for the process lifetime. Loader enable, disable, mount, unmount, and ordinary source HMR still refresh the active entry set, but replacing a mounted package's manifest with another version in the same process is not a supported upgrade path. diff --git a/packages/llm/plugin-package-inventory-deepseek/src/index.ts b/packages/llm/plugin-package-inventory-deepseek/src/index.ts index 83161732b9..b373a76040 100644 --- a/packages/llm/plugin-package-inventory-deepseek/src/index.ts +++ b/packages/llm/plugin-package-inventory-deepseek/src/index.ts @@ -1,7 +1,7 @@ /** * Active Loader-backed plugin package inventory for official DeepSeek requests. * Host entries and the requesting agent's standing preset are resolved at request time; - * installed dependencies and plugin fibers without Loader package provenance are excluded. + * installed dependencies and plugin fibers without Loader-backed package identity are excluded. * @module @deepseek-ai/dsh-plugin-package-inventory-deepseek */ @@ -180,7 +180,7 @@ async function collectActivePluginPackages( /** * Register the complete `dsh_plugin_packages` request contribution when enabled. - * @param ctx - plugin context carrying Loader provenance and the DeepSeek request-extension registry. + * @param ctx - plugin context carrying Loader entry metadata and the DeepSeek request-extension registry. * @param config - validated default-on configuration. */ export function apply(ctx: Context, config: Config): void { diff --git a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts index 769f00e0ec..dc1fcfb19e 100644 --- a/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts +++ b/packages/llm/token-meter/tests/context-breakdown-projection.spec.ts @@ -323,7 +323,7 @@ describe('contextBreakdown session projection', () => { content: [{ type: 'text', text: 'rewritten question' }], source: { kind: 'user' }, }), { surfaceOp: { op: 'replace', startSeq: question, endSeq: question }, sourceEventSeqs: [question] }).seq expect(question).toBeGreaterThan(middle) - // Provenance can cite a surviving prompt outside the replaced span. + // Source-event references can cite a surviving prompt outside the replaced span. session.append('user/message', createUserMessage({ content: [{ type: 'text', text: 'middle summary' }], source: { kind: 'user' }, }), { surfaceOp: { op: 'replace', startSeq: question, endSeq: middle }, sourceEventSeqs: [question, middle, tail] }) diff --git a/packages/session-query/session-query/tests/tracing.spec.ts b/packages/session-query/session-query/tests/tracing.spec.ts index 2b16c4b89e..177edad1d7 100644 --- a/packages/session-query/session-query/tests/tracing.spec.ts +++ b/packages/session-query/session-query/tests/tracing.spec.ts @@ -477,7 +477,7 @@ describe('session event tracing', () => { { ...appendEvent(SessionSeq(2), [0]), surfaceOp: { op: 'replace', startSeq: 1, endSeq: 1 } }, ]], ] as const)('rejects an invalid surface log: %s', async (_name, rawEvents) => { - const durable = header('invalid-provenance') + const durable = header('invalid-source-reference') const events = structuredClone(rawEvents) as unknown as SessionEvent[] TracePersistence.reset([{ meta: durable, events }]) const ctx = await queryContext() diff --git a/packages/session/session-format-v0-to-v1/README.i18n.yaml b/packages/session/session-format-v0-to-v1/README.i18n.yaml index 68272905ba..305aea15b0 100644 --- a/packages/session/session-format-v0-to-v1/README.i18n.yaml +++ b/packages/session/session-format-v0-to-v1/README.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 packages/session/session-format-v0-to-v1/README.md -README.md: 052a416c6c0ba8fa4ba434b1de483748f6c817b5 +README.md: 2ff830f4863a3e207f5c23be45b4765ebcb2a02b README.zh.md: 057109a70a71d6ae4f068e1d2ef194839bc41747 diff --git a/packages/session/session-format-v0-to-v1/README.md b/packages/session/session-format-v0-to-v1/README.md index 052a416c6c..2ff830f486 100644 --- a/packages/session/session-format-v0-to-v1/README.md +++ b/packages/session/session-format-v0-to-v1/README.md @@ -40,7 +40,7 @@ stage.transformEvent(event, migrationContext) const targetInheritedEventCount = stage.finish(migrationContext) ``` -`releasedV0SessionFormatCodec` reads the exact v0 header and physical rows, including packed Assistant deltas and range-encoded provenance. Its decoder emits either a scalar event or a codec-owned compact run through `emitEvent()` and `emitRun()`. `sessionFormatV0ToV1` creates one stateful stage per restore; the static catalog connects that decoder and stage so migration does not retain a physical-row array. `releasedV1SessionFormatCodec` exposes the same row-at-a-time decoder for the v1 physical layout without freezing the ordinary event vocabulary. +`releasedV0SessionFormatCodec` reads the exact v0 header and physical rows, including packed Assistant deltas and range-encoded source-event references. Its decoder emits either a scalar event or a codec-owned compact run through `emitEvent()` and `emitRun()`. `sessionFormatV0ToV1` creates one stateful stage per restore; the static catalog connects that decoder and stage so migration does not retain a physical-row array. `releasedV1SessionFormatCodec` exposes the same row-at-a-time decoder for the v1 physical layout without freezing the ordinary event vocabulary. The alpha edge refuses every event type outside its frozen inventory, including an unknown event marked `ignorable: true`. It also refuses unexpected payload members. `tool/result.meta` and nested PTC `arguments` remain explicit opaque JSON fields and are preserved without Session-sequence interpretation. Unknown content-block `type`, message-source `kind`, assistant finish-reason `kind`, and `turn/end` reason `kind` arms remain owner-opaque JSON while their known arms receive structural validation. @@ -58,7 +58,7 @@ The physical codec validates each packed row atomically, emits it as a compact r | File | Role | |---|---| -| [`src/codec.ts`](src/codec.ts) | Frozen v0/v1 physical headers, packed rows, and provenance ranges | +| [`src/codec.ts`](src/codec.ts) | Frozen v0/v1 physical headers, packed rows, and source-event ranges | | [`src/dispositions.ts`](src/dispositions.ts) | Released-v0 event and payload-member inventory | | [`src/payload-validation.ts`](src/payload-validation.ts) | Frozen nested payload semantics for every released-v0/v1 event type | | [`src/relationships.ts`](src/relationships.ts) | Frozen cross-event pairings: turns, steps, tool starts and results, retries, compaction, titles | diff --git a/packages/session/session-format-v0-to-v1/src/migration.ts b/packages/session/session-format-v0-to-v1/src/migration.ts index 5fce679de8..0a4ead8bcf 100644 --- a/packages/session/session-format-v0-to-v1/src/migration.ts +++ b/packages/session/session-format-v0-to-v1/src/migration.ts @@ -21,6 +21,8 @@ import { } from './validation.ts' import { assertReleasedV0Keys, releasedV0Record } from './validation-helpers.ts' +const LEGACY_ASSISTANT_SOURCE_KEY = ['pro', 'venance'].join('') + /** Identity format edge that promotes released v0 into released v1. */ export const sessionFormatV0ToV1 = defineSessionFormatMigration({ name: '@deepseek-ai/dsh-session-format-v0-to-v1', @@ -363,12 +365,15 @@ function normalizeLegacyMessage( } case 'assistant/message': { if (Object.hasOwn(data, 'message') - || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, 'provenance')) return event - const { content, provenance, ...eventData } = data as typeof data & { - content: SessionFormatJsonValue - provenance: SessionFormatJsonValue - } - const source = releasedV0Record(provenance, `assistant/message ${event.seq} provenance`) + || !Object.hasOwn(data, 'content') || !Object.hasOwn(data, LEGACY_ASSISTANT_SOURCE_KEY)) return event + const content = data['content'] as SessionFormatJsonValue + const eventData = { ...data } + delete eventData['content'] + const source = releasedV0Record( + eventData[LEGACY_ASSISTANT_SOURCE_KEY], + `assistant/message ${event.seq} legacy source`, + ) + Reflect.deleteProperty(eventData, LEGACY_ASSISTANT_SOURCE_KEY) return { ...event, data: { diff --git a/packages/session/session-format-v0-to-v1/src/relationships.ts b/packages/session/session-format-v0-to-v1/src/relationships.ts index 2cd4a432ed..ddd1a4b71d 100644 --- a/packages/session/session-format-v0-to-v1/src/relationships.ts +++ b/packages/session/session-format-v0-to-v1/src/relationships.ts @@ -437,8 +437,8 @@ function assertTitleSources( throw new SessionFormatError(`${event.type} ${event.seq} messageSeqs must cite earlier human user/message events`) } const sourceData = releasedV0Record(source.data, `${source.type} ${seq} data`) - const provenance = releasedV0Record(sourceData['source'], `${source.type} ${seq} source`) - if (provenance['kind'] !== 'user') { + const messageSource = releasedV0Record(sourceData['source'], `${source.type} ${seq} source`) + if (messageSource['kind'] !== 'user') { throw new SessionFormatError(`${event.type} ${event.seq} messageSeqs must cite earlier human user/message events`) } const content = sourceData['content'] as readonly Record[] diff --git a/packages/session/session-format-v0-to-v1/src/validation.ts b/packages/session/session-format-v0-to-v1/src/validation.ts index f61080c7bc..762ed963f7 100644 --- a/packages/session/session-format-v0-to-v1/src/validation.ts +++ b/packages/session/session-format-v0-to-v1/src/validation.ts @@ -145,7 +145,7 @@ export function assertReleasedArtifactCoordinates( * @param record - exact event envelope. * @param seq - event position used for earlier-reference checks. * @param type - surface event type used in diagnostics. - * @param assistantSources - whether this generation admits empty Assistant chunk provenance. + * @param assistantSources - whether this generation admits empty Assistant chunk references. */ export function assertReleasedSurfaceMetadata( record: Record, @@ -155,7 +155,7 @@ export function assertReleasedSurfaceMetadata( ): void { const sources = record['sourceEventSeqs'] if (type === 'assistant/message' && sources !== undefined && assistantSources === 'forbid-assistant') { - throw new SessionFormatError(`assistant/message ${seq} retains obsolete chunk provenance`) + throw new SessionFormatError(`assistant/message ${seq} retains obsolete chunk references`) } if (sources !== undefined) { if (!Array.isArray(sources)) throw new SessionFormatError(`${type} ${seq} sourceEventSeqs must be an array`) diff --git a/packages/session/session-format-v0-to-v1/tests/codec.spec.ts b/packages/session/session-format-v0-to-v1/tests/codec.spec.ts index fd60e4f0e4..5a58b33e66 100644 --- a/packages/session/session-format-v0-to-v1/tests/codec.spec.ts +++ b/packages/session/session-format-v0-to-v1/tests/codec.spec.ts @@ -160,7 +160,7 @@ describe('released v0/v1 physical codecs', () => { ['reversed range', [[2, 1]]], ['range past event', [[0, 3]]], ['overlapping ranges', [[0, 1], [1, 2]]], - ])('refuses malformed stored provenance: %s', (_name, sourceEventSeqs) => { + ])('refuses malformed stored source-event ranges: %s', (_name, sourceEventSeqs) => { const rows = [ { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }, { type: 'user/message', seq: 1, time: 2, data: { @@ -216,9 +216,9 @@ describe('released v0/v1 physical codecs', () => { }) expect(runs).toHaveLength(1) expect([...((runs[0] as SessionFormatEventRun).expand())]).toHaveLength(2) - const provenance = create(header) - decodeRow(provenance, { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }) - const item = decodeRow(provenance, { + const codec = create(header) + decodeRow(codec, { type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }) + const item = decodeRow(codec, { type: 'user/message', seq: 1, time: 2, data: { id: 'm', role: 'user', content: [], source: { kind: 'user' } }, sourceEventSeqs: [0], surfaceOp: 'append', diff --git a/packages/session/session-format-v0-to-v1/tests/legacy.spec.ts b/packages/session/session-format-v0-to-v1/tests/legacy.spec.ts index 3dd1d82c3a..8d303b5d95 100644 --- a/packages/session/session-format-v0-to-v1/tests/legacy.spec.ts +++ b/packages/session/session-format-v0-to-v1/tests/legacy.spec.ts @@ -12,6 +12,7 @@ const header = { createdAt: 1, delegationDepth: 0, } as const +const legacyAssistantSourceKey = ['pro', 'venance'].join('') function migrate(rows: readonly unknown[]) { return restoreV0ToV1(header, rows) @@ -33,7 +34,7 @@ describe('released v0 legacy normalization', () => { turn: 1, step: 1, content: [{ type: 'tool-call', id: 'call-1', name: 'read', arguments: '{}' }], - provenance: { provider: 'mock', model: 'mock' }, + [legacyAssistantSourceKey]: { provider: 'mock', model: 'mock' }, }, surfaceOp: 'append', }, diff --git a/packages/session/session-format-v0-to-v1/tests/migration.spec.ts b/packages/session/session-format-v0-to-v1/tests/migration.spec.ts index c786a49ddf..adfea4a67f 100644 --- a/packages/session/session-format-v0-to-v1/tests/migration.spec.ts +++ b/packages/session/session-format-v0-to-v1/tests/migration.spec.ts @@ -144,10 +144,10 @@ describe('released Session format v0 to v1', () => { ], 'recoverable')).toThrow(/seq gap/) }) - it('requires canonical delegation depth and decodes provenance without mutating source rows', () => { + it('requires canonical delegation depth and decodes source-event ranges without mutating source rows', () => { const incompleteHeader = { type: 'session', version: 0, id: 'old', createdAt: 1 } const header = { ...incompleteHeader, delegationDepth: 0 } - const provenanceRow = { + const sourceEventRow = { type: 'assistant/message', seq: 3, time: 5, @@ -171,7 +171,7 @@ describe('released Session format v0 to v1', () => { type: 'assistant/chunk', seq: 2, time: 4, data: { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'x' } }, }, - provenanceRow, + sourceEventRow, ] const migrated = restoreV0ToV1(header, rows) @@ -179,7 +179,7 @@ describe('released Session format v0 to v1', () => { expect(() => restoreV0ToV1(incompleteHeader, rows)).toThrow(/delegationDepth/) expect(migrated.header.delegationDepth).toBe(0) expect(migrated.events[3]?.sourceEventSeqs).toEqual([0, 1, 2]) - expect(provenanceRow.sourceEventSeqs).toEqual([[0, 2]]) + expect(sourceEventRow.sourceEventSeqs).toEqual([[0, 2]]) expect(migrated.header).toEqual({ version: 1, id: 'old', createdAt: 1, isSeeded: false, delegationDepth: 0, }) diff --git a/packages/session/session-format-v0-to-v1/tests/relationships.spec.ts b/packages/session/session-format-v0-to-v1/tests/relationships.spec.ts index ef6223aa79..148a42447f 100644 --- a/packages/session/session-format-v0-to-v1/tests/relationships.spec.ts +++ b/packages/session/session-format-v0-to-v1/tests/relationships.spec.ts @@ -39,7 +39,7 @@ describe('released v1 whole-artifact relationships', () => { data: { rootCallId: 'root', parentCallId: 'root', subCallId: 'sub', name: 'read', arguments: {} }, }, ]], - ['surface replace without shadow provenance', [ + ['surface replace without source-event references', [ { type: 'user/message', seq: 0, time: 1, data: user('one'), surfaceOp: 'append' }, { type: 'user/message', seq: 1, time: 2, data: user('two'), diff --git a/packages/session/session-format-v0-to-v1/tests/validation.spec.ts b/packages/session/session-format-v0-to-v1/tests/validation.spec.ts index 209576c636..8d5dbd6681 100644 --- a/packages/session/session-format-v0-to-v1/tests/validation.spec.ts +++ b/packages/session/session-format-v0-to-v1/tests/validation.spec.ts @@ -369,7 +369,7 @@ describe('released event and payload inventory', () => { }) }).toThrow(/unknown historical event/) }) - it('permits empty Assistant provenance only under the released-v1 policy', () => { + it('permits empty Assistant source-event references only under the released-v1 policy', () => { const assistant = { type: 'assistant/message', seq: 1, time: 2, data: {}, sourceEventSeqs: [], surfaceOp: 'append', @@ -377,7 +377,7 @@ describe('released event and payload inventory', () => { expect(() => { assertReleasedSurfaceMetadata(assistant, 1, assistant.type, 'allow-empty-assistant') }) .not.toThrow() expect(() => { assertReleasedSurfaceMetadata(assistant, 1, assistant.type, 'forbid-assistant') }) - .toThrow(/obsolete chunk provenance/) + .toThrow(/obsolete chunk references/) }) it('keeps capturedFormatVersion v1-only inside session-reference sources', () => { diff --git a/packages/session/session-format-v1-to-v2/README.i18n.yaml b/packages/session/session-format-v1-to-v2/README.i18n.yaml index 3d8e1f3463..adfada7c15 100644 --- a/packages/session/session-format-v1-to-v2/README.i18n.yaml +++ b/packages/session/session-format-v1-to-v2/README.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 packages/session/session-format-v1-to-v2/README.md -README.md: e2bcd2a2be31fddfd8ce77a1ab5fe3ef8cb22599 -README.zh.md: cf8aa67722b04060ac70f46c6bbe65c9485028d2 +README.md: 9fc2e2b837df65bc3b2df9245c0cc44f84ae1ff2 +README.zh.md: 9bc82a5b1623cee24740ea69f03b03abf1b3ec5b diff --git a/packages/session/session-format-v1-to-v2/README.md b/packages/session/session-format-v1-to-v2/README.md index e2bcd2a2be..9fc2e2b837 100644 --- a/packages/session/session-format-v1-to-v2/README.md +++ b/packages/session/session-format-v1-to-v2/README.md @@ -43,11 +43,11 @@ const eventRecord = releasedV2SessionFormatCodec.encodeEvent(currentEvent) `releasedV1SessionFormatCodec` reads the frozen v1 physical language one row at a time. `sessionFormatV1ToV2` creates the cardinality-changing Stage that the static catalog connects to that decoder without retaining a v1 event array. The catalog remaps declared references and validates the released-v2 envelope, inherited cut, event admission, and relationships. Persistence applies full installed-current validation in its Worker before publication. `releasedV2SessionFormatCodec` creates a released-v2 row decoder and encodes v2 headers and events one record at a time. -A successful v1 `assistant/message` must cite its complete ordered attempt. The migration removes the cited top-level chunks and obsolete message provenance, compacts the chunks without joining token boundaries, and stores the stream on that message. An unclaimed attempt becomes one log-only `assistant/attempt` at its final chunk position. Unrelated interleaved events keep their relative order. +A successful v1 `assistant/message` must cite its complete ordered attempt. The migration removes the cited top-level chunks and obsolete message chunk references, compacts the chunks without joining token boundaries, and stores the stream on that message. An unclaimed attempt becomes one log-only `assistant/attempt` at its final chunk position. Unrelated interleaved events keep their relative order. The edge also closes the bounded legacy restart pattern in which a non-empty `next-turn` inbox insertion is followed by the next `turn/start` without the prior `turn/end`. It records that prior turn as interrupted. A legacy round-zero goal mutation becomes a `goal/change` followed by the original model-visible message with ordinary plugin attribution, so both durable goal state and historical model input survive. -The migration refuses a reference to a consumed chunk instead of redirecting it to a different semantic event. It remaps declared event provenance, surface replacements, command source events, compaction ranges and lists, and title message lists. The already model-visible `session/title-llm-request.messages` text remains byte-identical after source validation, so target validation does not reinterpret the old sequence numbers embedded in that prompt. A seeded source also refuses an inherited cut that splits an Assistant attempt; the target marks the exact cut with `session/end-seed { inherited: true }`. +The migration refuses a reference to a consumed chunk instead of redirecting it to a different semantic event. It remaps declared source-event references, surface replacements, command source events, compaction ranges and lists, and title message lists. The already model-visible `session/title-llm-request.messages` text remains byte-identical after source validation, so target validation does not reinterpret the old sequence numbers embedded in that prompt. A seeded source also refuses an inherited cut that splits an Assistant attempt; the target marks the exact cut with `session/end-seed { inherited: true }`. The v2 physical header requires `isSeeded` and does not store a numeric cut. The codec derives the cut from the last inherited end-seed marker, writes one event per row, range-encodes only `sourceEventSeqs`, and remains neutral to ordinary event vocabulary and payload growth. Released-current restoration admits event types known to the installed Session package plus unknown events carrying `ignorable: true`, and validates event members and relationships. Ordinary Session restoration checks runtime-required settlement fields without replaying embedded streams; persistence publication and the frozen writer-image fixture validator retain full stream verification. @@ -64,7 +64,7 @@ The incremental edge retains one unsettled Assistant attempt, events whose outpu | File | Role | |---|---| | [`src/migration.ts`](src/migration.ts) | Attempt grouping, settlement substitution, dense sequence mapping, and reference rewriting | -| [`src/codec.ts`](src/codec.ts) | Released-v2 header, one-event-per-row encoding, provenance ranges, and recoverable prefix decoding | +| [`src/codec.ts`](src/codec.ts) | Released-v2 header, one-event-per-row encoding, source-event ranges, and recoverable prefix decoding | | [`src/validation.ts`](src/validation.ts) | Physical v2 envelope/cut validation and released-current event admission and relationships | | [`src/dispositions.ts`](src/dispositions.ts) | Frozen released-v2 event and payload-member inventory | diff --git a/packages/session/session-format-v1-to-v2/README.zh.md b/packages/session/session-format-v1-to-v2/README.zh.md index cf8aa67722..9bc82a5b16 100644 --- a/packages/session/session-format-v1-to-v2/README.zh.md +++ b/packages/session/session-format-v1-to-v2/README.zh.md @@ -43,11 +43,11 @@ const eventRecord = releasedV2SessionFormatCodec.encodeEvent(currentEvent) `releasedV1SessionFormatCodec` 逐行读取冻结的 v1 物理语言。`sessionFormatV1ToV2` 创建改变事件基数的 Stage,静态 catalog 把它连接到 decoder,且不保留 v1 事件数组。Catalog 会重映射已声明引用,并校验 released-v2 envelope、inherited cut、事件准入与关系。持久化在发布前通过 Worker 执行完整 installed-current 校验。`releasedV2SessionFormatCodec` 创建已发布 v2 格式的逐行 decoder,并逐条编码 v2 header 与事件。 -成功的 v1 `assistant/message` 必须引用其完整有序 attempt。迁移会移除这些顶层 chunk 和已停用的 message provenance,在不合并 token 边界的前提下压缩 chunk,并把 stream 存到该 message 上。未被 message 认领的 attempt 会在其最后一个 chunk 的位置变成一个仅日志可见的 `assistant/attempt`。无关的交错事件保持相对顺序。 +成功的 v1 `assistant/message` 必须引用其完整有序 attempt。迁移会移除这些顶层 chunk 和已停用的 message chunk reference,在不合并 token 边界的前提下压缩 chunk,并把 stream 存到该 message 上。未被 message 认领的 attempt 会在其最后一个 chunk 的位置变成一个仅日志可见的 `assistant/attempt`。无关的交错事件保持相对顺序。 该 edge 还会闭合一种有限的旧版恢复模式:非空的 `next-turn` inbox 插入后直接出现下一个 `turn/start`,但缺少前一轮的 `turn/end`;迁移将前一轮记录为 interrupted。旧版 round-zero goal mutation 会变成一个 `goal/change`,随后保留原本模型可见的 message 并改用普通 plugin attribution,因此持久 goal 状态与历史模型输入都会保留。 -如果引用指向被消费的 chunk,迁移会失败,而不会把它重定向到语义不同的事件。它会重映射已声明的事件 provenance、surface replacement、command source event、compaction range 与 list,以及 title message list。已经对模型可见的 `session/title-llm-request.messages` 文本会在源校验后保持逐字节不变,因此目标校验不会重新解释该 prompt 中嵌入的旧序号。带 seed 的源若让继承切点切开一个 Assistant attempt,也会迁移失败;目标会用 `session/end-seed { inherited: true }` 标出精确切点。 +如果引用指向被消费的 chunk,迁移会失败,而不会把它重定向到语义不同的事件。它会重映射已声明的 source-event reference、surface replacement、command source event、compaction range 与 list,以及 title message list。已经对模型可见的 `session/title-llm-request.messages` 文本会在源校验后保持逐字节不变,因此目标校验不会重新解释该 prompt 中嵌入的旧序号。带 seed 的源若让继承切点切开一个 Assistant attempt,也会迁移失败;目标会用 `session/end-seed { inherited: true }` 标出精确切点。 v2 物理 header 要求 `isSeeded`,且不存储数值切点。编解码器从最后一个 inherited end-seed marker 推导切点,每行写入一个事件,只对 `sourceEventSeqs` 做范围编码,并对普通事件词汇与 payload 扩展保持中立。Released-current restoration 准入 installed Session package 已知的事件 type,以及携带 `ignorable: true` 的未知事件,并校验事件 member 与关系。普通 Session restore 只检查 runtime 直接依赖的 settlement 字段,不重放嵌入 stream;persistence publication 与冻结的 writer-image fixture validator 保留完整 stream verification。 @@ -64,7 +64,7 @@ v2 物理 header 要求 `isSeeded`,且不存储数值切点。编解码器从 | 文件 | 职责 | |---|---| | [`src/migration.ts`](src/migration.ts) | Attempt 分组、settlement 替换、密集序号映射与引用重写 | -| [`src/codec.ts`](src/codec.ts) | 已发布 v2 header、每行一个事件的编码、provenance 范围与可恢复前缀解码 | +| [`src/codec.ts`](src/codec.ts) | 已发布 v2 header、每行一个事件的编码、source-event 范围与可恢复前缀解码 | | [`src/validation.ts`](src/validation.ts) | v2 物理 envelope/cut 校验,以及 released-current 事件准入与关系校验 | | [`src/dispositions.ts`](src/dispositions.ts) | 冻结的已发布 v2 事件与 payload 成员清单 | diff --git a/packages/session/session-format-v1-to-v2/src/codec.ts b/packages/session/session-format-v1-to-v2/src/codec.ts index 7aad50c1c3..4e461f4274 100644 --- a/packages/session/session-format-v1-to-v2/src/codec.ts +++ b/packages/session/session-format-v1-to-v2/src/codec.ts @@ -34,7 +34,7 @@ export const releasedV2SessionFormatCodec = Object.freeze({ return encodeHeader(header, inheritedEventCount) }, encodeEvent(event: SessionFormatEvent) { - return encodeProvenance(event) + return encodeSourceEventRanges(event) }, } satisfies SessionFormatCodec & SessionFormatCurrentEncoder) @@ -175,7 +175,7 @@ function encodeHeader( } } -function encodeProvenance(event: SessionFormatEvent): SessionFormatJsonObject { +function encodeSourceEventRanges(event: SessionFormatEvent): SessionFormatJsonObject { if (event.sourceEventSeqs === undefined) return event return { ...event, diff --git a/packages/session/session-format-v1-to-v2/src/migration.ts b/packages/session/session-format-v1-to-v2/src/migration.ts index 2e6d13e331..b7a8b94afb 100644 --- a/packages/session/session-format-v1-to-v2/src/migration.ts +++ b/packages/session/session-format-v1-to-v2/src/migration.ts @@ -291,7 +291,7 @@ function transformMessage( } if (pending === undefined || !matchesChunkSources(pending.group, sources)) { - throw refusal(`assistant/message ${event.seq} chunk provenance is not one complete ordered attempt`) + throw refusal(`assistant/message ${event.seq} chunk references are not one complete ordered attempt`) } assertAttemptCut(state, pending.group, event.seq) pending.group.terminal = true diff --git a/packages/session/session-format-v1-to-v2/tests/codec.spec.ts b/packages/session/session-format-v1-to-v2/tests/codec.spec.ts index bb1d37b075..bafce48c37 100644 --- a/packages/session/session-format-v1-to-v2/tests/codec.spec.ts +++ b/packages/session/session-format-v1-to-v2/tests/codec.spec.ts @@ -142,7 +142,7 @@ describe('releasedV2SessionFormatCodec headers', () => { }) describe('releasedV2SessionFormatCodec rows', () => { - it('stores one event per row and compacts scalar, pair, and long-run provenance exactly', () => { + it('stores one event per row and compacts scalar, pair, and long-run source-event references exactly', () => { const source = artifact([ feedback(0), userMessage(1, [0]), @@ -159,7 +159,7 @@ describe('releasedV2SessionFormatCodec rows', () => { expect(decodeV2(encoded.header, encoded.rows)).toStrictEqual(source) }) - it('keeps non-monotonic provenance scalar-only for the current backend reader', () => { + it('keeps non-monotonic source-event references scalar-only for the current backend reader', () => { const sourceEventSeqs = [4, 5, 1, 2, 3] const source = artifact([ feedback(0), feedback(1), feedback(2), feedback(3), feedback(4), feedback(5), @@ -186,7 +186,7 @@ describe('releasedV2SessionFormatCodec rows', () => { expect(decodeV2(encoded.header, encoded.rows)).toStrictEqual(source) }) - it('expands mixed stored ranges and preserves non-provenance rows', () => { + it('expands mixed stored source-event ranges and preserves unrelated rows', () => { const rows: SessionFormatJsonObject[] = [feedback(0), feedback(1), feedback(2), feedback(3), feedback(4), { ...userMessage(5), sourceEventSeqs: [[0, 2], 4], @@ -213,7 +213,7 @@ describe('releasedV2SessionFormatCodec rows', () => { ['duplicate scalars', [0, 0], /unique earlier/], ['overlapping range and scalar', [[0, 1], 1], /unique earlier/], ['non-monotonic range', [3, [0, 2]], /strictly increasing/], - ])('refuses malformed stored provenance: %s', (_name, sourceEventSeqs, message) => { + ])('refuses malformed stored source-event ranges: %s', (_name, sourceEventSeqs, message) => { const rows = [feedback(0), feedback(1), feedback(2), feedback(3), { ...userMessage(4), sourceEventSeqs, }] diff --git a/packages/session/session-format-v1-to-v2/tests/migration.spec.ts b/packages/session/session-format-v1-to-v2/tests/migration.spec.ts index df3b595304..9d516cd555 100644 --- a/packages/session/session-format-v1-to-v2/tests/migration.spec.ts +++ b/packages/session/session-format-v1-to-v2/tests/migration.spec.ts @@ -863,7 +863,7 @@ describe('sessionFormatV1ToV2', () => { }) it.each([undefined, []] as const)( - 'retains a legacy message with provenance %s as an empty embedded stream', + 'retains a legacy message with sourceEventSeqs %s as an empty embedded stream', (sourceEventSeqs) => { const source: SessionFormatArtifact = { header: { @@ -890,10 +890,10 @@ describe('sessionFormatV1ToV2', () => { }, ) - it('refuses missing, partial, or reordered provenance for a present v1 attempt', () => { + it('refuses missing, partial, or reordered source-event references for a present v1 attempt', () => { const build = (sourceEventSeqs: readonly number[] | undefined): SessionFormatArtifact => ({ header: { - version: 1, id: `v1-provenance-${String(sourceEventSeqs)}`, createdAt: 1, + version: 1, id: `v1-source-event-references-${String(sourceEventSeqs)}`, createdAt: 1, isSeeded: false, delegationDepth: 0, }, inheritedEventCount: 0, @@ -1020,7 +1020,7 @@ describe('sessionFormatV1ToV2', () => { expect(() => migrateV1ToV2(source)).toThrow(/cut 4 splits one Assistant attempt/) }) - it('keeps referenced-session generation provenance frozen', () => { + it('keeps referenced-session generation metadata frozen', () => { const reference = { ...userMessage, id: 'reference', diff --git a/packages/session/session-format-v1-to-v2/tests/validation.spec.ts b/packages/session/session-format-v1-to-v2/tests/validation.spec.ts index 0ad2542a6a..5a475c6388 100644 --- a/packages/session/session-format-v1-to-v2/tests/validation.spec.ts +++ b/packages/session/session-format-v1-to-v2/tests/validation.spec.ts @@ -337,30 +337,30 @@ describe('released v2 seed and surface relationships', () => { }) it.each([ - ['assistant chunk provenance', artifact([ + ['assistant chunk references', artifact([ event('user/message', 0, userData(), { surfaceOp: 'append' }), event('assistant/message', 1, assistantData({ content: [], stream: [], usage: null, replayState: null }), { surfaceOp: 'append', sourceEventSeqs: [0], }), - ]), /obsolete chunk provenance/], - ['non-array provenance', artifact([ + ]), /obsolete chunk references/], + ['non-array source-event references', artifact([ event('feedback/record', 0, { text: 'x' }), event('user/message', 1, userData(), { surfaceOp: 'append', sourceEventSeqs: 0 }), ]), /must be an array/], - ['invalid provenance member', artifact([ + ['invalid source-event reference', artifact([ event('feedback/record', 0, { text: 'x' }), event('user/message', 1, userData(), { surfaceOp: 'append', sourceEventSeqs: [-1] }), ]), /sourceEventSeqs member/], - ['current provenance member', artifact([ + ['current source-event reference', artifact([ event('feedback/record', 0, { text: 'x' }), event('user/message', 1, userData(), { surfaceOp: 'append', sourceEventSeqs: [1] }), ]), /unique earlier seqs/], - ['duplicate provenance member', artifact([ + ['duplicate source-event reference', artifact([ event('feedback/record', 0, { text: 'x' }), event('feedback/record', 1, { text: 'y' }), event('user/message', 2, userData(), { surfaceOp: 'append', sourceEventSeqs: [0, 0] }), ]), /unique earlier seqs/], - ['empty provenance', artifact([ + ['empty source-event references', artifact([ event('feedback/record', 0, { text: 'x' }), event('user/message', 1, userData(), { surfaceOp: 'append', sourceEventSeqs: [] }), ]), /must be non-empty/], diff --git a/packages/session/session-format-v2-to-v3/README.i18n.yaml b/packages/session/session-format-v2-to-v3/README.i18n.yaml index 5ae76eaec6..7088b8a0e3 100644 --- a/packages/session/session-format-v2-to-v3/README.i18n.yaml +++ b/packages/session/session-format-v2-to-v3/README.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 packages/session/session-format-v2-to-v3/README.md -README.md: 65e62f6d28f9f4cb0a75127429ae9a7ae610f5b2 -README.zh.md: e319e97cc01b23fe50e09c4a31513da801e54c3c +README.md: 3f3fe7255a0542840db27d7ae605862e5cb97de9 +README.zh.md: 8f26cfcb6854a8b4fd6eec038c411bb1b524a535 diff --git a/packages/session/session-format-v2-to-v3/README.md b/packages/session/session-format-v2-to-v3/README.md index 65e62f6d28..3f3fe7255a 100644 --- a/packages/session/session-format-v2-to-v3/README.md +++ b/packages/session/session-format-v2-to-v3/README.md @@ -69,7 +69,7 @@ The first `step/start` is followed immediately by an empty `system/message` appe At every `request/header`, absent `data.header.system` means the empty prompt; otherwise its string is compared exactly with the current prompt. A change inserts a system message immediately before that request header, replacing exactly the current protected head and citing it in `sourceEventSeqs`. An unchanged prompt inserts nothing. Empty strings and absent fields clear an earlier prompt; whitespace-only strings remain nonempty text. Every request header loses `data.header.system`, regardless of whether a replacement was needed. -Synthetic messages carry the open step's `turn` and `step`, the anchor event's `time`, role `system`, and source `{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }`. Empty prompts use `content: []`; other prompts use one text block containing the exact string. The first append has no provenance; each replacement uses the preceding head's target sequence for both endpoints and its sole source reference. Empty heads retain protection but produce no model message. +Synthetic messages carry the open step's `turn` and `step`, the anchor event's `time`, role `system`, and source `{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }`. Empty prompts use `content: []`; other prompts use one text block containing the exact string. The first append has no source-event reference; each replacement uses the preceding head's target sequence for both endpoints and its sole source reference. Empty heads retain protection but produce no model message. Each synthetic id is `v2-to-v3-system-` followed by the hexadecimal SHA-256 of `JSON.stringify(['session-format-v2-to-v3', sourceHeader.id, anchor.seq, anchor.type])`. The anchor is the source `step/start` for initial creation or the changed `request/header` for replacement. Collisions with generated or source message ids are refused in either encounter order, including ids in inbox insertions and title-request messages. Existing message ids never change. In particular, a `TOOL_NOT_STARTED` repair id retains its canonical historical `interrupted-tool-result--` suffix; that suffix is not a target sequence coordinate. @@ -105,7 +105,7 @@ Similar plugin names, other source kinds, arbitrary text, nested JSON, and histo After structural insertion and reference remapping, canonicalization converts exact envelope replacements `{ op: 'replace', start, end }` to `{ op: 'replace', startSeq, endSeq }` on original and synthetic events. It omits exactly `tools: []` and `adapterDefaults: {}` from `request/header.data.header`. This final operation preserves its input event count, coordinates, timestamps, order, and inherited cut; it neither remaps twice nor normalizes unrelated empty values such as `config.stop: []`. -All four V3 surface types (`system/message`, `user/message`, `assistant/message`, `tool/result`) require `surfaceOp`. Assistant messages alone forbid `sourceEventSeqs`; for the others, a supplied list must be nonempty, unique, and refer only to earlier events. Known log-only events allow neither surface metadata field. Replacements allow no aliases or extra keys. Their endpoints identify an inclusive span in current surface order, not numeric sequence order; restoration checks live membership, endpoint order, and complete provenance coverage. +All four V3 surface types (`system/message`, `user/message`, `assistant/message`, `tool/result`) require `surfaceOp`. Assistant messages alone forbid `sourceEventSeqs`; for the others, a supplied list must be nonempty, unique, and refer only to earlier events. Known log-only events allow neither surface metadata field. Replacements allow no aliases or extra keys. Their endpoints identify an inclusive span in current surface order, not numeric sequence order; restoration checks live membership, endpoint order, and complete source-event coverage. Source surface events already require placement; migration does not invent missing append markers. A `tool/result` with `data.error` requires its single tool-result block to carry `isError: true`. Failed results may omit structured error identity. Contradictory outcomes are refused, never repaired by adding `isError` or deleting diagnostics. Ordinary tool and PTC lifecycle relationships still require validation after these event-local checks. @@ -144,7 +144,7 @@ Input already marked V3 does not run V2-to-V3. Native catalog reads with `valida - Native V3 admits in-history system appends, non-head system replacements, and compaction of non-head system nodes. System messages require valid payloads and matching open-step ownership. The first surface system head can be replaced only by a system message covering exactly that head; ordinary replacements and compaction cannot consume it. Migration itself produces only the initial head and head replacements, not route-dependent in-history updates. - Native V3 rejects every `request/header.data.header.system`, even empty or malformed, and rejects noncanonical replacement spellings and the two empty header optionals. It preserves whitespace content, empty stop lists, and admitted nested header/source/data extensions. That extension admission does not widen the V2 source audit or the exact logical Session header fields. -- Required predecessor PTC tags are refused even if installed. Obsolete or unknown ignorable events remain opaque, including their logical metadata, and cannot satisfy current PTC relationships. Installed ordinary event additions are admitted as log-only envelopes; unknown required types are refused by vocabulary-aware restoration. The physical codec still enforces released framing and provenance encoding. +- Required predecessor PTC tags are refused even if installed. Obsolete or unknown ignorable events remain opaque, including their logical metadata, and cannot satisfy current PTC relationships. Installed ordinary event additions are admitted as log-only envelopes; unknown required types are refused by vocabulary-aware restoration. The physical codec still enforces released framing and source-event range encoding. - V3 event-local checks run before encoding and after decoding. Raw retired-system-header, malformed-system-payload, and required predecessor-PTC refusal run before recoverable suppression, including after corrupt rows. Strict reads reject canonical errors immediately. Recoverable canonical decoding withholds the first invalid event and its suffix; a later `turn/end` establishes a commit and rejects that suffix. Only accepted inherited markers count; a seeded accepted prefix without one is refused. Unclassified event metadata is deferred to vocabulary-aware restoration rather than discarded as canonical corruption, so it cannot hide an unknown required type. ----- diff --git a/packages/session/session-format-v2-to-v3/README.zh.md b/packages/session/session-format-v2-to-v3/README.zh.md index e319e97cc0..8f26cfcb68 100644 --- a/packages/session/session-format-v2-to-v3/README.zh.md +++ b/packages/session/session-format-v2-to-v3/README.zh.md @@ -69,7 +69,7 @@ const targetHeader = sessionFormatV2ToV3.migrateHeader(sourceHeader) 在每条 `request/header` 处,缺失的 `data.header.system` 表示空提示词;否则,其字符串与当前提示词进行精确比较。发生变化时,在该请求头之前立即插入系统消息,恰好替换当前受保护的头节点,并在 `sourceEventSeqs` 中引用它。提示词不变时不插入消息。空字符串和缺失字段会清空先前的提示词;仅含空白的字符串仍为非空文本。每个请求头都会移除 `data.header.system`,无论是否需要替换。 -合成消息携带开放步骤的 `turn` 和 `step`、锚点事件的 `time`、角色 `system`,以及来源 `{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }`。空提示词使用 `content: []`;其他提示词使用包含精确字符串的单个文本块。首次追加没有溯源;每次替换的两个端点及唯一源引用都使用前一头节点的目标序号。空头节点保持受保护,但不产生模型消息。 +合成消息携带开放步骤的 `turn` 和 `step`、锚点事件的 `time`、角色 `system`,以及来源 `{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }`。空提示词使用 `content: []`;其他提示词使用包含精确字符串的单个文本块。首次追加没有源事件引用;每次替换的两个端点及唯一源引用都使用前一头节点的目标序号。空头节点保持受保护,但不产生模型消息。 每个合成标识由 `v2-to-v3-system-` 加上 `JSON.stringify(['session-format-v2-to-v3', sourceHeader.id, anchor.seq, anchor.type])` 的十六进制 SHA-256 构成。首次创建的锚点是源 `step/start`,替换的锚点是提示词变化的 `request/header`。与已生成或源消息标识的冲突均被拒绝,不受遇到顺序影响;检查范围包括收件箱插入消息与标题请求消息中的标识。现有消息标识绝不改变。特别是,`TOOL_NOT_STARTED` 修复标识保留规范的历史 `interrupted-tool-result--` 后缀;该后缀不是目标序列坐标。 @@ -105,7 +105,7 @@ const targetHeader = sessionFormatV2ToV3.migrateHeader(sourceHeader) 结构插入和引用重映射完成后,规范化将原始与合成事件上的精确信封替换对象 `{ op: 'replace', start, end }` 转为 `{ op: 'replace', startSeq, endSeq }`。它仅从 `request/header.data.header` 中省略精确的 `tools: []` 和 `adapterDefaults: {}`。这个最终操作保留其输入事件数、坐标、时间戳、顺序与继承切点;既不重复映射,也不规范化 `config.stop: []` 等无关空值。 -四种 V3 surface 类型(`system/message`、`user/message`、`assistant/message`、`tool/result`)都要求 `surfaceOp`。仅 assistant 消息禁止 `sourceEventSeqs`;其他类型提供的列表必须非空、唯一,且仅引用更早的事件。已知仅日志事件对这两个 surface 元数据字段均不允许。替换不允许别名或额外键。端点按当前 surface 顺序而非数值序号顺序标识闭区间;恢复会检查存活成员、端点顺序与完整溯源覆盖。 +四种 V3 surface 类型(`system/message`、`user/message`、`assistant/message`、`tool/result`)都要求 `surfaceOp`。仅 assistant 消息禁止 `sourceEventSeqs`;其他类型提供的列表必须非空、唯一,且仅引用更早的事件。已知仅日志事件对这两个 surface 元数据字段均不允许。替换不允许别名或额外键。端点按当前 surface 顺序而非数值序号顺序标识闭区间;恢复会检查存活成员、端点顺序与完整源事件覆盖。 源 surface 事件本就要求位置标记;迁移不虚构缺失的追加标记。带有 `data.error` 的 `tool/result` 要求其唯一工具结果块携带 `isError: true`。失败结果可以省略结构化错误身份。矛盾结果会被拒绝,绝不通过添加 `isError` 或删除诊断来修复。普通工具与 PTC 生命周期关系仍须在这些事件本地检查后验证。 @@ -144,7 +144,7 @@ V2 `session-log-deepseek/delivery-accepted` 若携带 `data.sessionFormatVersion - 原生 V3 接纳历史内系统消息追加、非头系统节点替换和非头系统节点压缩。系统消息要求有效载荷及匹配的开放步骤归属。首个 surface 系统头节点只能被恰好覆盖该头节点的系统消息替换;普通替换和压缩不能消耗它。迁移本身只产生初始头节点与头节点替换,不产生依赖路由的历史内更新。 - 原生 V3 拒绝任何 `request/header.data.header.system`,包括空值或格式错误值,并拒绝非规范替换拼写及两个空请求头可选字段。它保留空白内容、空停止列表和已接纳的嵌套 header/source/data 扩展。此扩展准入不会扩大 V2 源审计或精确的逻辑会话头字段范围。 -- 必需的前代 PTC 标签即使已安装也会被拒绝。已退役或未知的可忽略事件(包括其逻辑元数据)保持不透明,且不能满足当前 PTC 关系。已安装的普通事件新增项作为仅日志信封接纳;未知必需类型由识别词汇的恢复阶段拒绝。物理编解码器仍执行已发布的分帧与溯源编码规则。 +- 必需的前代 PTC 标签即使已安装也会被拒绝。已退役或未知的可忽略事件(包括其逻辑元数据)保持不透明,且不能满足当前 PTC 关系。已安装的普通事件新增项作为仅日志信封接纳;未知必需类型由识别词汇的恢复阶段拒绝。物理编解码器仍执行已发布的分帧与源事件区间编码规则。 - V3 事件本地检查在编码前及解码后执行。原始行的已退役系统头字段、畸形系统载荷和必需前代 PTC 的拒绝先于可恢复抑制执行,包括损坏行之后。严格读取立即拒绝规范错误。可恢复的规范解码不产出首个无效事件及其后缀;后续 `turn/end` 建立提交事实并拒绝该后缀。只有已接纳的继承标记计数;有种子的已接纳前缀若没有标记则被拒绝。未分类事件元数据会延迟到识别词汇的恢复阶段,而不是作为规范损坏丢弃,因此不能隐藏未知必需类型。 ----- diff --git a/packages/session/session-format-v2-to-v3/src/codec.ts b/packages/session/session-format-v2-to-v3/src/codec.ts index 4873993eed..aae2c2b762 100644 --- a/packages/session/session-format-v2-to-v3/src/codec.ts +++ b/packages/session/session-format-v2-to-v3/src/codec.ts @@ -11,7 +11,7 @@ import { releasedV2SessionFormatCodec } from '@deepseek-ai/dsh-session-format-v1 import { assertReleasedV3Header, assertV3EventAdmission } from './validation.ts' import { assertV3Event, assertV3StructuralRow } from './payload.ts' -/** V3 codec validates structural rows before recovery and logical envelopes after provenance decoding. */ +/** V3 codec validates structural rows before recovery and logical envelopes after source-event range decoding. */ export const releasedV3SessionFormatCodec = Object.freeze({ version: 3, decodeHeader(value: unknown) { @@ -77,7 +77,7 @@ export const releasedV3SessionFormatCodec = Object.freeze({ /** * Validate owned V3 admission rules before a scanner or codec can discard a recoverable tail. - * This checks only identified structural payloads; physical provenance still belongs to decoding. + * This checks only identified structural payloads; physical source-event ranges still belong to decoding. * @param row - parsed physical row, before envelope or compressed-range decoding. */ export function assertV3RowAdmission(row: unknown): void { diff --git a/packages/session/session-format-v2-to-v3/tests/canonical-envelopes.spec.ts b/packages/session/session-format-v2-to-v3/tests/canonical-envelopes.spec.ts index 7467b38195..bded77922f 100644 --- a/packages/session/session-format-v2-to-v3/tests/canonical-envelopes.spec.ts +++ b/packages/session/session-format-v2-to-v3/tests/canonical-envelopes.spec.ts @@ -84,7 +84,7 @@ function toolLog(isError: boolean, error?: SessionFormatJsonValue): SessionForma } describe('canonical V2 to V3 envelopes', () => { - it('renames replacement keys after structural insertion and remaps provenance', () => { + it('renames replacement keys after structural insertion and remaps source-event references', () => { const first = user(2) const replacement = user(3, { surfaceOp: { op: 'replace', start: 2, end: 2 }, sourceEventSeqs: [2] }) const source = [...opening(), first, replacement] @@ -232,14 +232,14 @@ describe.each(['migration', 'native V3'] as const)('%s event admission', (mode) ] satisfies [string, SessionFormatJsonValue][])('forbids assistant sourceEventSeqs: %s', (_name, sourceEventSeqs) => { const events = toolLog(false) events[2] = { ...events[2]!, sourceEventSeqs } - expect(() => admit(events)).toThrow(mode === 'migration' ? /retains obsolete chunk provenance/ : /cannot carry sourceEventSeqs/) + expect(() => admit(events)).toThrow(mode === 'migration' ? /chunk references/ : /cannot carry sourceEventSeqs/) }) it.each([ ['empty', []], ['scalar', 0], ['null', null], ['negative', [-1]], ['fractional', [0.5]], ['unsafe integer', [Number.MAX_SAFE_INTEGER + 1]], ['current', [3]], ['future', [4]], ['duplicate', [0, 0]], ] satisfies [string, SessionFormatJsonValue][])( - 'refuses invalid provenance: %s', (_name, sourceEventSeqs) => { + 'refuses invalid source-event references: %s', (_name, sourceEventSeqs) => { expect(() => admit([...opening(), user(2), user(3, { surfaceOp: 'append', sourceEventSeqs })])) .toThrow(/sourceEventSeqs/) }, @@ -299,7 +299,7 @@ describe('native V3 opaque event preservation', () => { ) it.each(['external/future', 'tool/code-dispatch-start', 'tool/code-dispatch'])( - 'round-trips ignorable %s with physical provenance and arbitrary data', (type) => { + 'round-trips ignorable %s with physical source-event ranges and arbitrary data', (type) => { for (const data of [null, false, ['opaque'], { nested: { sourceEventSeqs: null } }]) { const source = event(type, 1, data, { ignorable: true, sourceEventSeqs: [0], surfaceOp: { future: ['opaque'] } }) const row = releasedV3SessionFormatCodec.encodeEvent(source) @@ -497,8 +497,8 @@ describe('V3 full artifact relationships', () => { it.each([ ['shadowed endpoint', 2, 4, [2, 4], /range is not on the current surface/], ['reversed surface order', 4, 5, [4, 5], /range is not on the current surface/], - ['missing provenance', 5, 4, undefined, /omit a shadowed surface node/], - ['incomplete provenance', 5, 4, [5], /omit a shadowed surface node/], + ['missing source-event references', 5, 4, undefined, /omit a shadowed surface node/], + ['incomplete source-event references', 5, 4, [5], /omit a shadowed surface node/], ] as const)('retains range and source-coverage validation: %s', (_name, start, end, sources, message) => { const source = [ ...opening(), user(2), user(3), user(4), diff --git a/packages/session/session-log-deepseek/README.i18n.yaml b/packages/session/session-log-deepseek/README.i18n.yaml index 7f75b42d3d..d2c8bc5b03 100644 --- a/packages/session/session-log-deepseek/README.i18n.yaml +++ b/packages/session/session-log-deepseek/README.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 packages/session/session-log-deepseek/README.md -README.md: 38a5ec64cee32c25b11e5b7c0b55b7302f66952a -README.zh.md: 2764b3d14ed5a98e140e43583c94424b527065e0 +README.md: fb243a2b1d4975a5c1f8f9671b6564300af2d888 +README.zh.md: a49eae2b89c7e550c77fdccb63a527fa1d8ddc51 diff --git a/packages/session/session-log-deepseek/README.md b/packages/session/session-log-deepseek/README.md index 38a5ec64ce..fb243a2b1d 100644 --- a/packages/session/session-log-deepseek/README.md +++ b/packages/session/session-log-deepseek/README.md @@ -34,7 +34,7 @@ Shipped profiles mount the plugin so an overlay can enable it, but the default c ## Request field -For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session format generation, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains `sessionFormatVersion`, a raw session header (`seedLength` is present only for a seeded Session), numeric `afterSeq` and `throughSeq`, and every complete canonical event translated to raw-number envelope fields. Forked sessions ignore inherited parent watermarks because both the recorded Session id and format generation must match the request source. Surface events require `surfaceOp`, with numeric `startSeq` and `endSeq` for replacements; only user and tool events may carry `sourceEventSeqs`. Assistant provenance stays in the embedded stream, and log-only events carry neither metadata field. +For a request carrying a live `sessionId`, the plugin folds the greatest accepted watermark for that exact Session format generation, snapshots `Session.events`, and sends the contiguous suffix after the watermark. A process-local fold scans each event once and consumes later appends incrementally; restart and HMR rebuild it from the durable log. The version-1 field contains `sessionFormatVersion`, a raw session header (`seedLength` is present only for a seeded Session), numeric `afterSeq` and `throughSeq`, and every complete canonical event translated to raw-number envelope fields. Forked sessions ignore inherited parent watermarks because both the recorded Session id and format generation must match the request source. Surface events require `surfaceOp`, with numeric `startSeq` and `endSeq` for replacements; only user and tool events may carry `sourceEventSeqs`. Assistant provider metadata stays in the embedded stream, and log-only events carry neither metadata field. ## Acceptance and retry diff --git a/packages/session/session-log-deepseek/README.zh.md b/packages/session/session-log-deepseek/README.zh.md index 2764b3d14e..a49eae2b89 100644 --- a/packages/session/session-log-deepseek/README.zh.md +++ b/packages/session/session-log-deepseek/README.zh.md @@ -34,7 +34,7 @@ kind: "package-reference" ## 请求字段 -对于携带存活 `sessionId` 的请求,插件会折叠该确切会话格式代的最大已接受水位,对 `Session.events` 取快照,并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加;重启与 HMR(热模块替换)会从持久日志重建它。版本 1 字段包含 `sessionFormatVersion`、原始会话 header(仅 seeded Session 携带 `seedLength`)、数值型 `afterSeq` 与 `throughSeq`,以及每个已转换为原始数值 envelope 字段的完整规范事件。只有记录的会话 id 与格式代均匹配请求来源时水位才生效,因此 fork 会话会忽略从父会话继承的水位。表层事件必须携带 `surfaceOp`,替换范围使用数值型 `startSeq` 与 `endSeq`;仅 user 与 tool 事件可以携带 `sourceEventSeqs`。assistant 的来源保留在内嵌流中,只出现在日志中的事件不携带这两个元数据字段。 +对于携带存活 `sessionId` 的请求,插件会折叠该确切会话格式代的最大已接受水位,对 `Session.events` 取快照,并发送水位之后的连续后缀。进程内 fold 会让每条事件只被扫描一次并增量消费后续追加;重启与 HMR(热模块替换)会从持久日志重建它。版本 1 字段包含 `sessionFormatVersion`、原始会话 header(仅 seeded Session 携带 `seedLength`)、数值型 `afterSeq` 与 `throughSeq`,以及每个已转换为原始数值 envelope 字段的完整规范事件。只有记录的会话 id 与格式代均匹配请求来源时水位才生效,因此 fork 会话会忽略从父会话继承的水位。表层事件必须携带 `surfaceOp`,替换范围使用数值型 `startSeq` 与 `endSeq`;仅 user 与 tool 事件可以携带 `sourceEventSeqs`。assistant 的提供方元数据保留在内嵌流中,只出现在日志中的事件不携带这两个元数据字段。 ## 接受与重试 diff --git a/packages/session/session-log-deepseek/src/types.ts b/packages/session/session-log-deepseek/src/types.ts index c2ea6cbdad..4201c51f99 100644 --- a/packages/session/session-log-deepseek/src/types.ts +++ b/packages/session/session-log-deepseek/src/types.ts @@ -25,7 +25,7 @@ export type DeepSeekSessionLogWireSurfaceOp = /** * One canonical event translated to raw JSON primitives for upload. Surface * events require an operation; system, user, and tool events may cite sources. - * Assistant provenance is embedded in its data; log-only events carry neither field. + * Assistant provider metadata is embedded in its data; log-only events carry neither field. */ export type DeepSeekSessionLogWireEvent = { [K in SessionEvent['type']]: { diff --git a/packages/session/session-log-deepseek/tests/upload.spec.ts b/packages/session/session-log-deepseek/tests/upload.spec.ts index e92df32921..7527b8b92a 100644 --- a/packages/session/session-log-deepseek/tests/upload.spec.ts +++ b/packages/session/session-log-deepseek/tests/upload.spec.ts @@ -83,7 +83,7 @@ describe('incremental DeepSeek session-log upload', () => { }>() }) - it('uploads assistant provenance only through its embedded stream', async () => { + it('uploads Assistant provider metadata only through its embedded stream', async () => { const { ctx, session } = await harness('wire-assistant') const assistant = session.append('assistant/message', { turn: 1, @@ -106,7 +106,7 @@ describe('incremental DeepSeek session-log upload', () => { }]) }) - it('uploads system append and replacement placement with unchanged data and provenance', async () => { + it('uploads system append and replacement placement with unchanged data and source-event references', async () => { const { ctx, session } = await harness('wire-system') const headData = { turn: 1, step: 1, message: createSystemMessage('head', 'fixture'), extra: { retained: true } } const head = session.append('system/message', headData, { surfaceOp: 'append' }) diff --git a/packages/session/session-persistence-jsonl/README.i18n.yaml b/packages/session/session-persistence-jsonl/README.i18n.yaml index 16b3376a52..b0af7efebf 100644 --- a/packages/session/session-persistence-jsonl/README.i18n.yaml +++ b/packages/session/session-persistence-jsonl/README.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 packages/session/session-persistence-jsonl/README.md -README.md: 942f8540bde43671d358f979554c89358c3ad1bf +README.md: fc431ff27bcd236c4d44b8d3e7b20d4291b936d4 README.zh.md: 3b265bf43f058d4c0711568df156825febed4d24 diff --git a/packages/session/session-persistence-jsonl/README.md b/packages/session/session-persistence-jsonl/README.md index 942f8540bd..fc431ff27b 100644 --- a/packages/session/session-persistence-jsonl/README.md +++ b/packages/session/session-persistence-jsonl/README.md @@ -53,7 +53,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a ### On-disk layout -Each session gets a session-owned directory under a readable project directory. Every canonical generation starts with a physical header whose version equals its filename. The current format stores one physical row per durable event; the frozen v0 and v1 readers also understand their historical packed Assistant-delta rows. The current format stores `isSeeded` in the header and derives the inherited cut from the last tagged `session/end-seed` marker, while historical codecs translate their numeric `seedLength`. The format catalog completes that translation before a handle exposes current logical values. Current storage records use the lossless provenance representation described below: +Each session gets a session-owned directory under a readable project directory. Every canonical generation starts with a physical header whose version equals its filename. The current format stores one physical row per durable event; the frozen v0 and v1 readers also understand their historical packed Assistant-delta rows. The current format stores `isSeeded` in the header and derives the inherited cut from the last tagged `session/end-seed` marker, while historical codecs translate their numeric `seedLength`. The format catalog completes that translation before a handle exposes current logical values. Current storage records use the lossless source-event representation described below: ```text / diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts index 61224de226..854aa5226b 100644 --- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts +++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts @@ -1998,9 +1998,9 @@ describe('JsonlSessionPersistence: scanLog unit', () => { expect(() => { scanner.write(Buffer.from('null\n')) }).toThrow(/invalid committed event/) }) - it('expands valid stored provenance ranges', () => { + it('expands valid stored source-event ranges', () => { const log = [ - JSON.stringify(toHeaderLine(meta('scanner-provenance'))), + JSON.stringify(toHeaderLine(meta('scanner-source-ranges'))), JSON.stringify({ type: 'turn/start', seq: 0, time: 1, data: { turn: 1 } }), JSON.stringify(oneTurnLog()[1]), JSON.stringify({ diff --git a/packages/session/session-title-llm/src/index.ts b/packages/session/session-title-llm/src/index.ts index c8ccadcde5..d0092ec956 100644 --- a/packages/session/session-title-llm/src/index.ts +++ b/packages/session/session-title-llm/src/index.ts @@ -17,7 +17,7 @@ import { } from '@deepseek-ai/dsh-session-title' import type { SessionTitleAutomaticMode, - SessionTitleModelProvenance, + SessionTitleModelIdentity, SessionTitleProviderRequest, SessionTitleProviderResult, SessionTitleUserMessage, @@ -30,7 +30,7 @@ export interface SessionTitleLlmRequestEventData { /** Exact human `user/message` seqs represented in `messages`. */ readonly messageSeqs: SessionSeq[] /** Exact auxiliary LLM route. */ - readonly route: SessionTitleModelProvenance + readonly route: SessionTitleModelIdentity /** Exact auxiliary system prompt. */ readonly system: string /** Exact auxiliary message list. */ @@ -174,7 +174,7 @@ export function registerSessionTitleLlmProvider( function resolveRoute( config: ResolvedSessionTitleLlmConfig, request: SessionTitleProviderRequest, -): SessionTitleModelProvenance { +): SessionTitleModelIdentity { if (config.provider !== undefined && config.model !== undefined) { return { provider: config.provider, model: config.model } } diff --git a/packages/session/session-title/src/index.ts b/packages/session/session-title/src/index.ts index 014310b529..8d9a550a51 100644 --- a/packages/session/session-title/src/index.ts +++ b/packages/session/session-title/src/index.ts @@ -21,7 +21,7 @@ import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection' import type {} from '@deepseek-ai/dsh-agent' export type { SessionTitleEventData, - SessionTitleModelProvenance, + SessionTitleModelIdentity, SessionTitleSnapshot, SessionTitleSource, SessionTitleUserMessage, @@ -30,7 +30,7 @@ export type { import { fallbackSessionTitle, normalizeSessionTitle } from './normalize.ts' import type { SessionTitleEventData, - SessionTitleModelProvenance, + SessionTitleModelIdentity, SessionTitleSnapshot, SessionTitleSource, SessionTitleUserMessage, @@ -98,7 +98,7 @@ export interface SessionTitleProviderRequest { /** All eligible human messages through this generation revision. */ readonly messages: readonly SessionTitleUserMessage[] /** Exact current logged main-request route, when one has been recorded. */ - readonly route?: SessionTitleModelProvenance + readonly route?: SessionTitleModelIdentity /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */ readonly signal: AbortSignal } @@ -110,7 +110,7 @@ export interface SessionTitleProviderResult { /** Exact seqs from `request.messages` used by this result. */ readonly messageSeqs: readonly SessionSeq[] /** Auxiliary LLM route, when generation used a model. */ - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } /** One optional asynchronous title implementation registered with the service. */ @@ -556,7 +556,7 @@ export class SessionTitleService extends Service { session: Session, state: SessionTitleWorkState, pending: PendingAutomaticWork, - route: SessionTitleModelProvenance, + route: SessionTitleModelIdentity, ): void { delete state.pending this.defer(async () => { @@ -578,7 +578,7 @@ export class SessionTitleService extends Service { private startProvider( session: Session, work: ActiveProviderWork, - route?: SessionTitleModelProvenance, + route?: SessionTitleModelIdentity, ): Promise { const run = Promise.resolve().then(() => this.runProvider(session, work, route)) return this.track(run, work.registration) @@ -588,7 +588,7 @@ export class SessionTitleService extends Service { private async runProvider( session: Session, work: ActiveProviderWork, - route?: SessionTitleModelProvenance, + route?: SessionTitleModelIdentity, ): Promise { try { this.assertCurrent(session, work) @@ -651,7 +651,7 @@ export class SessionTitleService extends Service { previous = index } const modelCandidate = candidate.model - let model: SessionTitleModelProvenance | undefined + let model: SessionTitleModelIdentity | undefined if (modelCandidate !== undefined) { if (modelCandidate === null || typeof modelCandidate !== 'object') { throw new Error('session-title provider result model must contain non-empty provider and model strings') diff --git a/packages/session/session-title/src/types.ts b/packages/session/session-title/src/types.ts index c7d913f9e3..20855445a5 100644 --- a/packages/session/session-title/src/types.ts +++ b/packages/session/session-title/src/types.ts @@ -17,7 +17,7 @@ import type { OptionalSessionSeq, SessionSeq } from '@deepseek-ai/dsh-session/ty export type SessionTitleProviderId = Branded<'SessionTitleProviderId'> /** Exact auxiliary model route that produced a title. */ -export interface SessionTitleModelProvenance { +export interface SessionTitleModelIdentity { /** Registered LLM provider route. */ readonly provider: string /** Provider model id. */ @@ -30,7 +30,7 @@ export type SessionTitleSource = | { readonly kind: 'provider' readonly provider: SessionTitleProviderId - readonly model?: SessionTitleModelProvenance + readonly model?: SessionTitleModelIdentity } | { /** Explicit user rename: pins the title — automatic generation stops scheduling. */ diff --git a/packages/shell/pwsh-sandbox/src/helpers.ts b/packages/shell/pwsh-sandbox/src/helpers.ts index 9c843dcc82..963d769390 100644 --- a/packages/shell/pwsh-sandbox/src/helpers.ts +++ b/packages/shell/pwsh-sandbox/src/helpers.ts @@ -26,7 +26,7 @@ function isUsableWorkdir(path: string): boolean { } /** - * Attribute only Node ENOENT/EACCES failures with positive argv[0] provenance + * Attribute only Node ENOENT/EACCES failures whose path or syscall identifies argv[0] * after independently ruling out the caller-owned cwd. A supplied error path * must exactly identify the runner; without one, the syscall must. With a * usable cwd, these codes describe resolution or execute permission for that diff --git a/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts b/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts index 166e5ed042..6b09a1cf4e 100644 --- a/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts +++ b/packages/shell/pwsh-sandbox/tests/sandbox.spec.ts @@ -87,7 +87,7 @@ describe('helpers (pure)', () => { const bare = 'node' const relative = './sandbox-runner' - it('attributes ENOENT/EACCES with argv[0] provenance and a usable workdir', () => { + it('attributes ENOENT/EACCES when path or syscall identifies argv[0] and the workdir is usable', () => { for (const runnerProgram of [absolute, bare, relative]) { expect(isRunnerSpawnFailure({ code: 'ENOENT', syscall: `spawn ${runnerProgram}`, path: runnerProgram }, runnerProgram, workdir)).toBe(true) expect(isRunnerSpawnFailure({ code: 'EACCES', syscall: `spawn ${runnerProgram}`, path: runnerProgram }, runnerProgram, workdir)).toBe(true) @@ -96,7 +96,7 @@ describe('helpers (pure)', () => { } }) - it('rejects mismatched provenance, foreign codes, unusable workdirs, and non-object errors', () => { + it('rejects mismatched runner evidence, foreign codes, unusable workdirs, and non-object errors', () => { expect(isRunnerSpawnFailure({ code: 'ENOENT', syscall: 'spawn', path: 'other' }, 'node', workdir)).toBe(false) expect(isRunnerSpawnFailure({ code: 'ENOENT', syscall: 'spawn other', path: 'node' }, 'node', workdir)).toBe(false) expect(isRunnerSpawnFailure({ code: 'EMFILE', syscall: 'spawn', path: 'node' }, 'node', workdir)).toBe(false) @@ -300,7 +300,7 @@ describe.skipIf(!pwshAvailable())('SandboxPwshExecutor', () => { expect(denied.sandbox).toEqual({ mode: 'read-only', denied: true, enforcement: 'full' }) }, 30_000) - it('background provider rejections with runner provenance settle as runnerFailed facts', async () => { + it('background provider rejections with runner identity settle as runnerFailed facts', async () => { const { executor } = await setup(() => ({ argv: ['definitely-not-a-real-runner', '--', 'pwsh'], enforcement: 'full', diff --git a/packages/spill/spill-policy/src/notice.ts b/packages/spill/spill-policy/src/notice.ts index 80a19c93b6..94d8b7b87a 100644 --- a/packages/spill/spill-policy/src/notice.ts +++ b/packages/spill/spill-policy/src/notice.ts @@ -31,7 +31,7 @@ function isOmission(text: string): boolean { /** * Recognize a final spill-policy notice in persisted text, including notice-only output. - * This identifies the text convention, not authenticated provenance of tool output. + * This identifies the text convention, not authenticated tool-output origin. * @param text - complete recorded text result. * @returns whether a complete notice occupies the end of the result. */ diff --git a/packages/spill/spill/README.i18n.yaml b/packages/spill/spill/README.i18n.yaml index b266c0af25..d79c75ad97 100644 --- a/packages/spill/spill/README.i18n.yaml +++ b/packages/spill/spill/README.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 packages/spill/spill/README.md -README.md: e05dad3f5ea8ed6956b426500f938ad7eba871e4 +README.md: f951a0d689b66aab641b917e43009038bceae153 README.zh.md: a8178e0942ef5798ac41634ffc2fcaa428d133c4 diff --git a/packages/spill/spill/README.md b/packages/spill/spill/README.md index e05dad3f5e..f951a0d689 100644 --- a/packages/spill/spill/README.md +++ b/packages/spill/spill/README.md @@ -93,7 +93,7 @@ The package is built on one separation and a deliberate minimum: ### Data model -`SaveTextSpill` separates storage ownership from descriptive provenance. `SpillSource` accepts either the tool source `{ kind: "tool", toolName, callId, label }` or `{ kind: "session-reference", sessionId, label }`, whose id names the captured source session. Session references never fabricate tool call ids. Neither provenance nor the owner namespace grants read access. Consumers treat the returned locator as opaque and present it with its retrieval hint. +`SaveTextSpill` separates storage ownership from its source description. `SpillSource` accepts either the tool source `{ kind: "tool", toolName, callId, label }` or `{ kind: "session-reference", sessionId, label }`, whose id names the captured source session. Session references never fabricate tool call ids. Neither the source descriptor nor the owner namespace grants read access. Consumers treat the returned locator as opaque and present it with its retrieval hint. ### Lifecycle diff --git a/packages/spill/spill/src/types.ts b/packages/spill/spill/src/types.ts index a45369e6dc..7128b685e8 100644 --- a/packages/spill/spill/src/types.ts +++ b/packages/spill/spill/src/types.ts @@ -41,7 +41,7 @@ export interface SpillOwner { /** * Producer of a spilled artifact. Tool results carry their model-issued call id; * session references identify the captured source session instead. Descriptive - * provenance only, never access control. + * source description only, never access control. */ export type SpillSource = { kind: 'tool' diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts index 8a91e06e56..de908ad0c4 100644 --- a/packages/subagent/subagent/src/index.ts +++ b/packages/subagent/subagent/src/index.ts @@ -254,12 +254,12 @@ export class SubagentRuntime extends TypertRemoteService { /** * Deliver one host-protocol message to a direct continuable child. - * Symbol-keyed so host adapters can preserve their own provenance without + * Symbol-keyed so host adapters can preserve their own source descriptors without * widening the public Service Definition or impersonating an Agent sender. * @param parent - exact live direct parent authorizing delivery. * @param childId - durable direct-child session id. * @param content - host-authored content to deliver. - * @param source - durable host-protocol provenance. + * @param source - durable host-protocol source descriptor. * @param signal - caller cancellation before inbox acceptance. * @param delivery - Queue as a distinct turn or Steer at the nearest step. * @returns the accepted message's inbox id. diff --git a/packages/subagent/subagent/src/internal.ts b/packages/subagent/subagent/src/internal.ts index 642cf98943..95a88749f9 100644 --- a/packages/subagent/subagent/src/internal.ts +++ b/packages/subagent/subagent/src/internal.ts @@ -59,7 +59,7 @@ export interface HostPromptDeliverer { * @param parent - exact live direct parent authorizing delivery. * @param childId - durable direct-child session id. * @param content - host-authored content to deliver. - * @param source - durable host-protocol provenance. + * @param source - durable host-protocol source descriptor. * @param signal - caller cancellation before inbox acceptance. * @returns the accepted message's inbox id. */ @@ -87,7 +87,7 @@ export function queueHostSubagentPrompt( * @param parent - exact live direct parent authorizing delivery. * @param childId - durable direct-child session id. * @param content - host-authored content to deliver. - * @param source - durable host-protocol provenance. + * @param source - durable host-protocol source descriptor. * @param signal - caller cancellation before inbox acceptance. * @returns the accepted message's inbox id. */ diff --git a/packages/test-support/llm-replay/tests/llm-replay.spec.ts b/packages/test-support/llm-replay/tests/llm-replay.spec.ts index 7f192ea598..4e97358b94 100644 --- a/packages/test-support/llm-replay/tests/llm-replay.spec.ts +++ b/packages/test-support/llm-replay/tests/llm-replay.spec.ts @@ -433,7 +433,7 @@ describe('parseSessionLog', () => { expect(parseSessionLog(`${header}\n\n${JSON.stringify(ev)}\n\n`)).toEqual([ev]) }) - it('expands range-encoded source provenance', () => { + it('expands range-encoded sourceEventSeqs', () => { const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0 }) const events = [ { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, @@ -451,7 +451,7 @@ describe('parseSessionLog', () => { expect(parsed[7]).toEqual({ ...events[6], seq: 7, sourceEventSeqs: [3, 4, 5, 6] }) }) - it('reports malformed range provenance with its source line', () => { + it('reports a malformed sourceEventSeqs range with its source line', () => { const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0 }) const events = [ { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, @@ -469,7 +469,7 @@ describe('parseSessionLog', () => { .toThrow(/session snapshot line 8: sourceEventSeqs range/) }) - it('locates malformed range provenance with a materialized v0 seedLength header', () => { + it('locates malformed source-event ranges with a materialized v0 seedLength header', () => { const header = JSON.stringify({ type: 'session', version: 0, id: 's1', createdAt: 0, seedLength: 0 }) const events = [ { type: 'turn/start', seq: 0, time: 0, data: { turn: 1 } }, @@ -740,7 +740,7 @@ describe('parseSessionLog', () => { turn: 1, step: 1, content: [{ type: 'text', text: 'migrated' }], - provenance: { provider: 'mock', model: 'mock' }, + [['pro', 'venance'].join('')]: { provider: 'mock', model: 'mock' }, }, surfaceOp: 'append', }), @@ -777,7 +777,7 @@ describe('parseSessionLog', () => { turn: 1, step: 1, content: [{ type: 'text', text: 'legacy-only' }], - provenance: { provider: 'mock', model: 'mock' }, + [['pro', 'venance'].join('')]: { provider: 'mock', model: 'mock' }, }, surfaceOp: 'append', }), diff --git a/packages/test-support/session-snapshot/README.i18n.yaml b/packages/test-support/session-snapshot/README.i18n.yaml index 2308a1742b..9c31a25c34 100644 --- a/packages/test-support/session-snapshot/README.i18n.yaml +++ b/packages/test-support/session-snapshot/README.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 packages/test-support/session-snapshot/README.md -README.md: a73ea265516f965bec8d11c41d6eb5bb028c7ac6 +README.md: 51aaff9af7dfce83ed032b42ce0bb471aa384002 README.zh.md: ad136b19a75170c130bbb872ba02bb88e010bb02 diff --git a/packages/test-support/session-snapshot/README.md b/packages/test-support/session-snapshot/README.md index a73ea26551..51aaff9af7 100644 --- a/packages/test-support/session-snapshot/README.md +++ b/packages/test-support/session-snapshot/README.md @@ -107,7 +107,7 @@ This section explains the design of the kit; the observable behavior is fully co ### Design -The shared core owns manifests, generation-qualified role selection, workspace setup/comparison, typed identity mapping, normalizers, and fixture invariants. The ACP adapter adds four composable layers: launcher, scenario harness, normalizers, and suite factory. `launchAcpTestAgent` boots a source profile under tsx or a built `lib` profile under plain Node, connects the SDK client over a raw-byte stdout tee, collects Session updates and stderr, fails closed on unhandled permission requests, and owns shutdown. `runScenario` drives ACP JSON-RPC stdio and harvests the numerically highest persisted raw JSONL generation for every Session directory. The pure normalizers replace cwd paths and typed identities with stable tokens, zero times, expand physical provenance ranges, and scrub system-prompt text and tool-schema bulk. `defineAcpSnapshotSuite` registers comparisons, generation-qualified fixture write-back, and the live uniformity guard. +The shared core owns manifests, generation-qualified role selection, workspace setup/comparison, typed identity mapping, normalizers, and fixture invariants. The ACP adapter adds four composable layers: launcher, scenario harness, normalizers, and suite factory. `launchAcpTestAgent` boots a source profile under tsx or a built `lib` profile under plain Node, connects the SDK client over a raw-byte stdout tee, collects Session updates and stderr, fails closed on unhandled permission requests, and owns shutdown. `runScenario` drives ACP JSON-RPC stdio and harvests the numerically highest persisted raw JSONL generation for every Session directory. The pure normalizers replace cwd paths and typed identities with stable tokens, zero times, expand physical source-event ranges, and scrub system-prompt text and tool-schema bulk. `defineAcpSnapshotSuite` registers comparisons, generation-qualified fixture write-back, and the live uniformity guard. ### Source map diff --git a/packages/test-support/session-snapshot/src/index.ts b/packages/test-support/session-snapshot/src/index.ts index 1b53cccfe2..04a9ccd5d7 100644 --- a/packages/test-support/session-snapshot/src/index.ts +++ b/packages/test-support/session-snapshot/src/index.ts @@ -39,7 +39,7 @@ export { } from './launcher.ts' export { extractSnapshotSpillPaths, - normalizeSessionFormatProvenance, + normalizeSessionFormatMetadata, normalizeSessionLog, normalizeSessionSnapshot, normalizeSessionSnapshots, diff --git a/packages/test-support/session-snapshot/src/launcher.ts b/packages/test-support/session-snapshot/src/launcher.ts index b988d944a7..821c4e3e6e 100644 --- a/packages/test-support/session-snapshot/src/launcher.ts +++ b/packages/test-support/session-snapshot/src/launcher.ts @@ -387,7 +387,7 @@ function packageDirFromPatch(source: string, packageName: string): string | unde /** * Install an authored patch's resolvable bare package into the temporary * profile fallback. This mirrors `dsh plugin` while retaining the bare entry - * name and package provenance used by request metadata. + * name and package identity used by request metadata. */ function linkProfilePackage(source: string, cwd: string, packageName: string): void { const packageDir = packageDirFromPatch(source, packageName) diff --git a/packages/test-support/session-snapshot/src/normalize.ts b/packages/test-support/session-snapshot/src/normalize.ts index bb1a507453..0201030f6d 100644 --- a/packages/test-support/session-snapshot/src/normalize.ts +++ b/packages/test-support/session-snapshot/src/normalize.ts @@ -445,7 +445,7 @@ export function normalizeSessionSnapshots( const currentLogs = rawLogs.map(log => hasSessionFormatVersion(log) ? prepareSessionSnapshotFixtureForComparison(log) : log) - const comparableLogs = currentLogs.map(normalizeSessionFormatProvenance) + const comparableLogs = currentLogs.map(normalizeSessionFormatMetadata) return redactSessionSnapshotIds(comparableLogs).map(log => projectSessionSnapshot( scrubSessionSnapshot(normalizeSessionLog( log, @@ -461,7 +461,7 @@ export function normalizeSessionSnapshots( * @param rawLog - Session records or events as compact JSON lines. * @returns the same records with only the Session header version omitted. */ -export function normalizeSessionFormatProvenance(rawLog: string): string { +export function normalizeSessionFormatMetadata(rawLog: string): string { return rawLog.split('\n').map((line) => { if (line.trim().length === 0) return line const record = JSON.parse(line) as Record diff --git a/packages/test-support/session-snapshot/tests/normalize.spec.ts b/packages/test-support/session-snapshot/tests/normalize.spec.ts index 62321e5759..be8bcb7ff4 100644 --- a/packages/test-support/session-snapshot/tests/normalize.spec.ts +++ b/packages/test-support/session-snapshot/tests/normalize.spec.ts @@ -3,7 +3,7 @@ import { type NormalizeContext, extractSnapshotSpillPaths, normalizeSessionLog, - normalizeSessionFormatProvenance, + normalizeSessionFormatMetadata, normalizeSessionSnapshot, normalizeSessionSnapshots, normalizeStdout, @@ -758,8 +758,8 @@ describe('normalizeSessionSnapshot', () => { type: 'session-log-deepseek/delivery-accepted', data: { sessionId: 's', throughSeq: 4, sessionFormatVersion: version }, }) - expect(normalizeSessionFormatProvenance(event(0))).toBe(event(0)) - expect(normalizeSessionFormatProvenance(event(3))).not.toBe(normalizeSessionFormatProvenance(event(0))) + expect(normalizeSessionFormatMetadata(event(0))).toBe(event(0)) + expect(normalizeSessionFormatMetadata(event(3))).not.toBe(normalizeSessionFormatMetadata(event(0))) }) it('preserves opaque generation qualifiers and their lookalikes', () => { @@ -841,7 +841,7 @@ describe('normalizeSessionSnapshot', () => { type: 'user/message', data: { source: { kind: 'session-reference', form: 'recall', version: 1, references: {} } }, }) - expect(normalizeSessionFormatProvenance(raw)).toBe(raw) + expect(normalizeSessionFormatMetadata(raw)).toBe(raw) }) it('keeps session-reference lookalikes outside Message source positions unchanged', () => { @@ -862,12 +862,12 @@ describe('normalizeSessionSnapshot', () => { '', ].join('\n') - const normalized = normalizeSessionFormatProvenance(lookalike).split('\n') + const normalized = normalizeSessionFormatMetadata(lookalike).split('\n') expect(JSON.parse(normalized[0] as string)).not.toHaveProperty('version') expect(normalized[1]).toBe(lookalike.split('\n')[1]) }) - it('projects persisted provenance ranges back to logical seq arrays', () => { + it('projects persisted source-event ranges back to logical seq arrays', () => { const raw = [ JSON.stringify({ type: 'session', version: 0 }), JSON.stringify({ diff --git a/packages/webhook/webhook/README.i18n.yaml b/packages/webhook/webhook/README.i18n.yaml index 76ac38dae5..a4c53cdbf7 100644 --- a/packages/webhook/webhook/README.i18n.yaml +++ b/packages/webhook/webhook/README.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 packages/webhook/webhook/README.md -README.md: e19bb7edc26857312c9249294bcfab23942075c1 +README.md: 685bf3befa1aee3af336452d771c40c01d42c70d README.zh.md: db0801fcbd4aa81a8f24bd706673d1ee4629ed1f diff --git a/packages/webhook/webhook/README.md b/packages/webhook/webhook/README.md index e19bb7edc2..685bf3befa 100644 --- a/packages/webhook/webhook/README.md +++ b/packages/webhook/webhook/README.md @@ -27,7 +27,7 @@ English | [中文](README.zh.md) `WebhookRule` has a branded unique `id`, a provider `kind`, and `run(delivery, signal)`. A callback may execute arbitrary trusted code and returns either `null` or one `WebhookSessionRequest`. Rules of the same kind start independently, and one throw or rejection is logged without starving siblings. -`VerifiedWebhookDelivery` carries provider kind, configured source id, provider delivery id, normalized lossless JSON, and receipt time. The runtime snapshots and freezes the complete value before sharing it. `deliveryId` is provenance only; repeated delivery runs the rules again. +`VerifiedWebhookDelivery` carries provider kind, configured source id, provider delivery id, normalized lossless JSON, and receipt time. The runtime snapshots and freezes the complete value before sharing it. `deliveryId` records the provider's identifier only; repeated delivery runs the rules again. Registration is an effect. Its awaitable disposer first hides the rule, then aborts and drains active callbacks. Callbacks must observe the supplied signal; same-process code that ignores cancellation cannot be forcibly stopped safely. @@ -38,7 +38,7 @@ Registration is an effect. Its awaitable disposer first hides the rule, then abo The runtime validates presets before mutation, resolves or creates the canonical Workspace, creates an Agent with that Workspace path as `SessionHeader.cwd`, mounts the agent preset before publication, and attaches the Session before applying permissions, title, and prompt. Failed attachment disposes the unpublished action. A later pre-prompt failure detaches the Workspace and disposes the Agent on a best-effort rollback. -Successful `Agent.followup()` is the webhook operation's commit point. The message uses `source.kind: "webhook"` with provider, source, delivery, and rule provenance. The runtime does not wait for idle, flush specially, inspect the reply, or publish completion state; ordinary Agent and Session behavior owns everything afterward. +Successful `Agent.followup()` is the webhook operation's commit point. The message uses `source.kind: "webhook"` and records the provider, source, delivery, and rule identifiers. The runtime does not wait for idle, flush specially, inspect the reply, or publish completion state; ordinary Agent and Session behavior owns everything afterward. ## Composition diff --git a/packages/webhook/webhook/src/brand.ts b/packages/webhook/webhook/src/brand.ts index 695177232f..a63488fe88 100644 --- a/packages/webhook/webhook/src/brand.ts +++ b/packages/webhook/webhook/src/brand.ts @@ -1,4 +1,4 @@ -/** Opaque webhook identities shared by adapters, rules, and Session provenance. */ +/** Opaque webhook identities shared by adapters, rules, and Session message sources. */ import type { Branded } from '@deepseek-ai/dsh-brand' diff --git a/packages/webhook/webhook/src/session.ts b/packages/webhook/webhook/src/session.ts index 76c5a1be5e..384832f92a 100644 --- a/packages/webhook/webhook/src/session.ts +++ b/packages/webhook/webhook/src/session.ts @@ -109,7 +109,7 @@ function installInitialModelSelection(agentCtx: Context, selection: ModelSelecti * Agent remains lifecycle-owned by `ctx` and follows normal Session behavior. * * @param ctx - untraced runtime context that owns the resulting Agent. - * @param delivery - exact verified provider delivery used for provenance. + * @param delivery - exact verified provider delivery recorded in the message source. * @param ruleId - rule that returned the request. * @param request - same-process rule result. * @param signal - registration lifetime cancellation through publication. diff --git a/packages/webhook/webhook/src/types.ts b/packages/webhook/webhook/src/types.ts index 3b1d1d1db1..b8bcfc130d 100644 --- a/packages/webhook/webhook/src/types.ts +++ b/packages/webhook/webhook/src/types.ts @@ -16,7 +16,7 @@ export interface VerifiedWebhookDelivery { readonly kind: K /** Configured adapter instance such as `primary-github`. */ readonly source: WebhookSourceId - /** Provider identity exposed as provenance, never as built-in deduplication state. */ + /** Provider delivery identifier exposed in message sources, never as built-in deduplication state. */ readonly deliveryId: WebhookDeliveryId /** Provider-normalized lossless JSON. */ readonly event: WebhookEventOf diff --git a/python/sdk-runtime/README.i18n.yaml b/python/sdk-runtime/README.i18n.yaml index a479d3b412..dd883770cc 100644 --- a/python/sdk-runtime/README.i18n.yaml +++ b/python/sdk-runtime/README.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 python/sdk-runtime/README.md -README.md: ce733b8f293e974ec051e600c187e0741117ab46 +README.md: 8ab226427f89d2746d6da13bcd8bd254731f2460 README.zh.md: 23a042006c38425a83347322fa63f0fafb319d0d diff --git a/python/sdk-runtime/README.md b/python/sdk-runtime/README.md index ce733b8f29..8ab226427f 100644 --- a/python/sdk-runtime/README.md +++ b/python/sdk-runtime/README.md @@ -35,4 +35,4 @@ Production deployment permits unused workspace patches for packages outside the From the repository root, `pnpm exec tsx scripts/build-exe-for-python-sdk.ts` verifies the closure, builds packages, deploys a symlink-free tree, packages the selected target, and syncs the executable and sidecars into this module. `scripts/build-python-release.py` stages release-shaped wheels at the root repository version and pins `deepseek-harness-sdk` to the exact runtime version. -The installed-wheel smoke creates a clean virtual environment outside the checkout, proves distribution and executable provenance, then exercises default and customized SDK profiles, external plugins, MCP, native tools, direct JSON-RPC, committed snapshots, and the real provider on trusted runs. See the [Python contributor workflow](../development.md) and [installed-wheel testing decision](../../.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md). +The installed-wheel smoke creates a clean virtual environment outside the checkout, proves the installed distribution and executable identities, then exercises default and customized SDK profiles, external plugins, MCP, native tools, direct JSON-RPC, committed snapshots, and the real provider on trusted runs. See the [Python contributor workflow](../development.md) and [installed-wheel testing decision](../../.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md). diff --git a/python/sdk/tests/test_smoke_model.py b/python/sdk/tests/test_smoke_model.py index 5b950f98e3..3216b662c1 100644 --- a/python/sdk/tests/test_smoke_model.py +++ b/python/sdk/tests/test_smoke_model.py @@ -244,7 +244,7 @@ def test_advanced_snapshot_normalizes_catalog_child_creation_time() -> None: ) == {"type": "fixture/event", "data": {"childCreatedAt": 1788246207176}} -def test_snapshot_comparison_preserves_opaque_generation_provenance() -> None: +def test_snapshot_comparison_preserves_opaque_generation_qualifiers() -> None: normalize = SMOKE["normalize_session_format_comparison"] expected = { "header": {"type": "session", "version": 0, "otherVersion": 7}, diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts index 9d78884475..312a4c2c87 100644 --- a/scripts/gen-persistence-catalog.ts +++ b/scripts/gen-persistence-catalog.ts @@ -49,7 +49,7 @@ const LINK_MAP: Record = { TurnEndReason: 'subsystems/session.md', SessionTitleEventData: 'subsystems/session-title.md', SessionTitleLlmRequestEventData: 'subsystems/session-title.md', - SessionTitleModelProvenance: 'subsystems/session-title.md', + SessionTitleModelIdentity: 'subsystems/session-title.md', SessionTitleProviderId: 'subsystems/session-title.md', SessionTitleSource: 'subsystems/session-title.md', TeamId: 'subsystems/agent-team.md', diff --git a/scripts/run-gates.spec.ts b/scripts/run-gates.spec.ts index cd26963bab..e449c1e529 100644 --- a/scripts/run-gates.spec.ts +++ b/scripts/run-gates.spec.ts @@ -188,6 +188,12 @@ describe('gate graph validation', () => { expect(ids).toContain('public-repository-links') }) + it('keeps the concrete terminology policy in the documentation gate', () => { + const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id)) + + expect(ids).toContain('concrete-terms') + }) + it('keeps package-group subsystem ownership in the documentation gate', () => { const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id)) diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts index 9105d246e5..3bdb0e3ae2 100644 --- a/scripts/run-gates.ts +++ b/scripts/run-gates.ts @@ -743,6 +743,7 @@ function docSyncLeafGates(options: { pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }), pnpmScript('session-format-catalog', 'verify-session-format-catalog', { label: 'Session format catalog' }), pnpmScript('public-repository-links', 'verify-public-repository-links', { label: 'public repository links', quick: true }), + pnpmScript('concrete-terms', 'verify-concrete-terms', { label: 'concrete terms', quick: true }), pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs', quick: true }), pnpmScript('subsystem-pages', 'verify-subsystem-pages', { label: 'subsystem pages' }), pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }), diff --git a/scripts/session-fixture-layout.spec.ts b/scripts/session-fixture-layout.spec.ts index 069bcc2a97..37908f4dda 100644 --- a/scripts/session-fixture-layout.spec.ts +++ b/scripts/session-fixture-layout.spec.ts @@ -143,7 +143,7 @@ describe('canonicalSessionFixture', () => { expect(canonicalSessionFixture(content)).toBe(content) }) - it.each([0, 1, 2])('rejects v%i sequence gaps and invalid provenance ranges with source line diagnostics', (version) => { + it.each([0, 1, 2])('rejects v%i sequence gaps and invalid source-event ranges with source line diagnostics', (version) => { const header = JSON.stringify({ type: 'session', version, id: 'historical', createdAt: 1, delegationDepth: 0, ...(version === 2 ? { isSeeded: false } : {}) }) expect(() => canonicalSessionFixture(`${header}\n{"type":"feedback/record","seq":3,"data":{"text":"gap"}}\n`, 'gap.jsonl')) .toThrow(/gap\.jsonl: session snapshot line 2:.*seq/) diff --git a/scripts/session-fixture-layout.ts b/scripts/session-fixture-layout.ts index d220a30b77..9feac22ba5 100644 --- a/scripts/session-fixture-layout.ts +++ b/scripts/session-fixture-layout.ts @@ -128,7 +128,7 @@ function parseFixtureRows(content: string, headerValue: unknown): SessionEvent[] // Versionless protocol fixtures and current projected snapshots use scalar // event rows. Current snapshots may contain owner-restored scrub tokens such // as `{{tools}}`; semantic replay restores those sidecars, while this layout - // gate owns only envelopes, provenance ranges, and one-event-per-row form. + // gate owns only envelopes, source-event ranges, and one-event-per-row form. const projectedCurrent = headerValue !== null && typeof headerValue === 'object' && !Array.isArray(headerValue) diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 139be0f756..5b5496c96d 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -2204,7 +2204,7 @@ def project_session_snapshot(records: list[dict[str, object]]) -> list[dict[str, return projected -SESSION_FORMAT_PROVENANCE = "{{sessionFormatVersion}}" +SESSION_FORMAT_TOKEN = "{{sessionFormatVersion}}" def expand_snapshot_stream_member(member: object) -> list[dict[str, object]]: @@ -2293,7 +2293,7 @@ def normalize_session_format_comparison( value: object, source_session_version: int | None = None, ) -> object: - """Canonicalize only generation provenance that differs across immutable Session files.""" + """Canonicalize only generation metadata that differs across immutable Session files.""" if isinstance(value, list): return [ normalize_session_format_comparison(expanded, source_session_version) @@ -2308,7 +2308,7 @@ def normalize_session_format_comparison( for key, item in value.items() } if normalized.get("type") == "session" and "version" in normalized: - normalized["version"] = SESSION_FORMAT_PROVENANCE + normalized["version"] = SESSION_FORMAT_TOKEN normalized.setdefault("isSeeded", False) ordered_header = { key: normalized[key] @@ -2328,7 +2328,7 @@ def normalize_session_format_comparison( def normalize_snapshot_comparison_text(name: str, content: str) -> str: - """Normalize Session generation provenance only while comparing committed expected outputs.""" + """Normalize Session generation metadata only while comparing committed expected outputs.""" if name.startswith("session") and name.endswith(".jsonl"): parsed = [json.loads(line) for line in content.splitlines() if line] header = parsed[0] if parsed else None diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json index 86aba302e1..90191674e2 100644 --- a/scripts/type-equiv.manifest.json +++ b/scripts/type-equiv.manifest.json @@ -8,7 +8,7 @@ }, { "doc": "docs/subsystems/llm-streaming.md", - "symbol": "AssistantProvenance", + "symbol": "AssistantProviderMetadata", "source": "packages/llm/llm/src/message.ts" }, { @@ -688,7 +688,7 @@ }, { "doc": "docs/subsystems/session-title.md", - "symbol": "SessionTitleModelProvenance", + "symbol": "SessionTitleModelIdentity", "source": "packages/session/session-title/src/types.ts" }, { diff --git a/scripts/verify-concrete-terms.spec.ts b/scripts/verify-concrete-terms.spec.ts new file mode 100644 index 0000000000..6f7b6fa500 --- /dev/null +++ b/scripts/verify-concrete-terms.spec.ts @@ -0,0 +1,42 @@ +import { describe, expect, it } from 'vitest' +import { findConcreteTermViolations } from './verify-concrete-terms.ts' + +const blockedTerm = 'prove' + 'nance' + +describe('concrete terminology policy', () => { + it('rejects case variants in paths, prose, and identifiers', () => { + expect(findConcreteTermViolations(`docs/${blockedTerm}-notes.md`, [ + 'origin metadata', + blockedTerm.toUpperCase(), + `Assistant${blockedTerm[0]?.toUpperCase()}${blockedTerm.slice(1)}`, + ].join('\n'))).toEqual([ + { file: `docs/${blockedTerm}-notes.md`, line: null }, + { file: `docs/${blockedTerm}-notes.md`, line: 2 }, + { file: `docs/${blockedTerm}-notes.md`, line: 3 }, + ]) + }) + + it('scans text that contains an embedded NUL', () => { + expect(findConcreteTermViolations('packages/example/src/source.ts', `scope\0${blockedTerm}`)) + .toEqual([{ file: 'packages/example/src/source.ts', line: 1 }]) + }) + + it('accepts exact replacement terms', () => { + expect(findConcreteTermViolations( + 'packages/example/src/origin.ts', + 'provider metadata; source-event references; artifact identity; browser-zone evidence', + )).toEqual([]) + }) + + it('excludes vendored sources and frozen Agent Notes', () => { + expect(findConcreteTermViolations(`vendor/example/${blockedTerm}.ts`, blockedTerm)).toEqual([]) + expect(findConcreteTermViolations( + `.agents/notes/archived/process/${blockedTerm}.md`, + blockedTerm, + )).toEqual([]) + expect(findConcreteTermViolations( + '.agents/notes/implemented/process/current.md', + blockedTerm, + )).toEqual([{ file: '.agents/notes/implemented/process/current.md', line: 1 }]) + }) +}) diff --git a/scripts/verify-concrete-terms.ts b/scripts/verify-concrete-terms.ts new file mode 100644 index 0000000000..4f16c79c86 --- /dev/null +++ b/scripts/verify-concrete-terms.ts @@ -0,0 +1,91 @@ +/** Reject one ambiguous origin label from maintained tracked files. */ + +import { execFileSync } from 'node:child_process' +import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs' +import { resolve } from 'node:path' +import { pathToFileURL } from 'node:url' + +const root = resolve(import.meta.dirname, '..') +const blockedTerm = 'prove' + 'nance' +const excludedPrefixes = ['vendor/', '.agents/notes/archived/'] as const + +/** One blocked term occurrence in a tracked path or text line. */ +export interface ConcreteTermViolation { + /** Repository-relative tracked path. */ + file: string + /** One-based source line, or null when the path contains the term. */ + line: number | null +} + +function isExcluded(file: string): boolean { + return excludedPrefixes.some(prefix => file.startsWith(prefix)) +} + +function containsBlockedTerm(value: string): boolean { + return value.normalize('NFKC').toLowerCase().includes(blockedTerm) +} + +/** + * Find the blocked term in one maintained tracked file. + * @param file - repository-relative tracked path. + * @param source - text contents or symlink target. + * @returns path and line violations; vendored sources and frozen Agent Notes are excluded. + */ +export function findConcreteTermViolations(file: string, source: string): ConcreteTermViolation[] { + if (isExcluded(file)) return [] + const violations: ConcreteTermViolation[] = [] + if (containsBlockedTerm(file)) violations.push({ file, line: null }) + for (const [index, line] of source.split('\n').entries()) { + if (containsBlockedTerm(line)) violations.push({ file, line: index + 1 }) + } + return violations +} + +function trackedFiles(repoRoot: string): string[] { + const files = execFileSync('git', ['ls-files', '-z'], { cwd: repoRoot, encoding: 'utf8' }) + .split('\0') + .filter(file => file !== '') + if (!files.includes('AGENTS.md') + || !files.some(file => file.startsWith('packages/')) + || !files.some(file => file.startsWith('docs/')) + || !files.some(file => file.startsWith('vendor/')) + || !files.some(file => file.startsWith('.agents/notes/archived/'))) { + throw new Error('verify-concrete-terms: tracked-file discovery omitted a required repository area') + } + return files +} + +function readTrackedSource(repoRoot: string, file: string): string | undefined { + const path = resolve(repoRoot, file) + if (!existsSync(path)) return undefined + const stat = lstatSync(path) + if (stat.isSymbolicLink()) return readlinkSync(path) + return stat.isFile() ? readFileSync(path, 'utf8') : undefined +} + +function scanRepository(repoRoot: string): ConcreteTermViolation[] { + const violations: ConcreteTermViolation[] = [] + for (const file of trackedFiles(repoRoot)) { + const source = readTrackedSource(repoRoot, file) + if (source === undefined) continue + violations.push(...findConcreteTermViolations(file, source)) + } + return violations +} + +const invokedPath = process.argv[1] +const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href +if (isMain) { + const violations = scanRepository(root) + if (violations.length === 0) { + console.log(`verify-concrete-terms: maintained tracked files contain no ${blockedTerm}.`) + } else { + console.error(`verify-concrete-terms: ${blockedTerm} is forbidden; name the exact source, field, identity, or evidence:`) + for (const violation of violations) { + console.error(violation.line === null + ? ` ${violation.file} (path)` + : ` ${violation.file}:${String(violation.line)}`) + } + process.exitCode = 1 + } +} diff --git a/snapshots/sdk/sdk.snapshot.ts b/snapshots/sdk/sdk.snapshot.ts index cd62c0e4b7..e14673b7d9 100644 --- a/snapshots/sdk/sdk.snapshot.ts +++ b/snapshots/sdk/sdk.snapshot.ts @@ -20,7 +20,7 @@ import { assertSessionFixtureVersion, captureExpectedWorkspaceSnapshot, captureWorkspaceSnapshot, - normalizeSessionFormatProvenance, + normalizeSessionFormatMetadata, normalizeSessionLog, normalizeSessionSnapshots, normalizeStdout, @@ -364,7 +364,7 @@ function normalizeNotifications(notifications: readonly HarnessNotification[], c const normalizedEvents = events.length === 0 ? [] : scrubModelRequestBulk(normalizeSessionLog( - normalizeSessionFormatProvenance(typedLog), + normalizeSessionFormatMetadata(typedLog), ctx, typedFeedback ? { identityMode: 'preserve' } : {}, )).trimEnd().split('\n').map(line => JSON.parse(line) as Record) diff --git a/snapshots/session/compaction-recovery/session.v2.jsonl b/snapshots/session/compaction-recovery/session.v2.jsonl index 5c18237d46..13416ce1d8 100644 --- a/snapshots/session/compaction-recovery/session.v2.jsonl +++ b/snapshots/session/compaction-recovery/session.v2.jsonl @@ -2,11 +2,11 @@ {"type":"permission/preset","data":{"preset":"danger-full-access"}} {"type":"sandbox/mode","data":{"mode":"danger-full-access"}} {"type":"approval/policy","data":{"policy":"never"}} -{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary source metadata; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} {"type":"turn/start","data":{"turn":1}} {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":1}} -{"type":"user/message","data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary source metadata; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:2}}"},"surfaceOp":"append"} {"type":"session/title","data":{"title":"Establish a durable compaction premise","messageSeqs":[7],"source":{"kind":"fallback"}}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}} @@ -18,7 +18,7 @@ {"type":"step/start","data":{"turn":1,"step":2}} {"type":"assistant/attempt","data":{"turn":1,"step":2,"stream":[{"type":"chunk","time":1788233487095,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}]}} {"type":"compaction/start","data":{"compactionId":"{{id:1}}","turn":1}} -{"type":"compaction/summary","data":{"compactionId":"{{id:1}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":7,"end":8},"shadowedSeqs":[7,8],"shadowedTokenCount":372,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}} +{"type":"compaction/summary","data":{"compactionId":"{{id:1}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":7,"end":8},"shadowedSeqs":[7,8],"shadowedTokenCount":373,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}} {"type":"user/message","data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":""}],"source":{"kind":"plugin","plugin":"compact","compactionId":"{{id:1}}"},"role":"user","id":"{{message:5}}"},"sourceEventSeqs":[18,19,7,8],"surfaceOp":{"op":"replace","start":7,"end":8}} {"type":"compaction/end","data":{"compactionId":"{{id:1}}","turn":1}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"series"}} diff --git a/snapshots/session/compaction-recovery/session.v3.jsonl b/snapshots/session/compaction-recovery/session.v3.jsonl index f731a05123..14bb80640b 100644 --- a/snapshots/session/compaction-recovery/session.v3.jsonl +++ b/snapshots/session/compaction-recovery/session.v3.jsonl @@ -2,12 +2,12 @@ {"type":"permission/preset","data":{"preset":"danger-full-access"}} {"type":"sandbox/mode","data":{"mode":"danger-full-access"}} {"type":"approval/policy","data":{"policy":"never"}} -{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} +{"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary source metadata; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"}]}} {"type":"turn/start","data":{"turn":1}} {"type":"agent/inbox/spliced","data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}} {"type":"step/start","data":{"turn":1,"step":1}} {"type":"system/message","data":{"turn":1,"step":1,"message":{"role":"system","content":[{"type":"text","text":"{{system}}"}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt"},"id":"{{message:2}}"}},"surfaceOp":"append"} -{"type":"user/message","data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary provenance; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} +{"type":"user/message","data":{"content":[{"type":"text","text":"Establish a durable compaction premise before continuing. Record every part of this historical evidence: the snapshot uses keyless replay; persistence uses JSONL; the assembled headless application loads its real Cordis composition; model-visible inputs remain logged; tool calls and results remain paired and ordered; context overflow retains the original failure while recovery is attempted; compaction opens with compaction/start and closes with compaction/end; a successful auxiliary summary records compaction/summary source metadata; the replacement surface shadows only an older balanced range; the checkpoint remains smaller than the history it replaces; the newest tool result remains verbatim; the retried request sees that checkpoint; the final response proves the same turn continued; deterministic snapshot evidence stays separate from the live-provider smoke; and no external API key is needed. Emit one alpha marker through bash, then finish the task after any required recovery with the exact words COMPACTION RECOVERED."}],"source":{"kind":"user"},"role":"user","id":"{{message:1}}"},"surfaceOp":"append"} {"type":"user/message","data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{message:3}}"},"surfaceOp":"append"} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"initial"}} {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash","contextWindow":128000}} @@ -19,7 +19,7 @@ {"type":"step/start","data":{"turn":1,"step":2}} {"type":"assistant/attempt","data":{"turn":1,"step":2,"stream":[{"type":"chunk","time":1788699353021,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"snapshot request exceeded the model context window","code":"CONTEXT_WINDOW_EXCEEDED"}}}}]}} {"type":"compaction/start","data":{"compactionId":"{{id:1}}","turn":1}} -{"type":"compaction/summary","data":{"compactionId":"{{id:1}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":8,"end":9},"shadowedSeqs":[8,9],"shadowedTokenCount":372,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}} +{"type":"compaction/summary","data":{"compactionId":"{{id:1}}","summary":[{"type":"text","text":"The request established a durable compaction premise."}],"rawOutput":[{"type":"text","text":"The request established a durable compaction premise."}],"llmStreamCall":true,"shadowedRange":{"start":8,"end":9},"shadowedSeqs":[8,9],"shadowedTokenCount":373,"provider":"deepseek-official","model":"deepseek-v4-flash","maxTokens":32,"usage":{"inputTokens":20,"outputTokens":4}}} {"type":"user/message","data":{"content":[{"type":"text","text":"This is an automatically generated checkpoint condensing an earlier span of the conversation to free up context. Treat the captured context as established background and build on it without restating it. Continue the task directly from the messages that follow, without acknowledging this checkpoint.\n\n"},{"type":"text","text":"The request established a durable compaction premise."},{"type":"text","text":""}],"source":{"kind":"plugin","plugin":"compact","compactionId":"{{id:1}}"},"role":"user","id":"{{message:6}}"},"sourceEventSeqs":[19,20,8,9],"surfaceOp":{"op":"replace","startSeq":8,"endSeq":9}} {"type":"compaction/end","data":{"compactionId":"{{id:1}}","turn":1}} {"type":"request/header","data":{"header":{"config":{"provider":"deepseek-official","model":"deepseek-v4-flash"},"tools":"{{tools}}"},"reason":"series"}} diff --git a/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl b/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl index 36188dda08..10638c75d7 100644 --- a/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl +++ b/snapshots/session/cordis-inspect-jsdoc/session.v2.jsonl @@ -13,7 +13,7 @@ {"type":"request/context","data":{"provider":"deepseek-official","model":"deepseek-v4-flash"}} {"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:3}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}} -{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProvenance\",\n \"declaration\": \"export interface AssistantProvenance {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"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}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProvenance {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[13],"surfaceOp":"append"} +{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProviderMetadata\",\n \"declaration\": \"export interface AssistantProviderMetadata {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"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}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProviderMetadata {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:4}}"}},"sourceEventSeqs":[13],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} {"type":"step/start","data":{"turn":1,"step":2}} {"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:5}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":0,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":0,"index":0,"dt":[],"id":"inspect-subprocess-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"]},{"type":"chunk","time":0,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}}},{"type":"chunk","time":0,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":0,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} diff --git a/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl b/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl index 86ad93cc03..ff0e383737 100644 --- a/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl +++ b/snapshots/session/cordis-inspect-jsdoc/session.v3.jsonl @@ -14,7 +14,7 @@ {"type":"session/title","data":{"title":"Inspect the exact tools service","messageSeqs":[8],"source":{"kind":"fallback"}}} {"type":"assistant/message","data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:4}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788778145981,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788778145981,"index":0,"dt":[],"id":"inspect-tools-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"]},{"type":"chunk","time":1788778145981,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}}},{"type":"chunk","time":1788778145981,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788778145981,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} {"type":"tool/call","data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"tools\"}}"}} -{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProvenance\",\n \"declaration\": \"export interface AssistantProvenance {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"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}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProvenance {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"} +{"type":"tool/result","data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"inspect-tools-api"},"content":[{"type":"tool-result","toolCallId":"inspect-tools-api","content":[{"type":"text","text":"{\n \"platform\": \"host\",\n \"provider\": \"Service\",\n \"method\": \"listService\",\n \"data\": {\n \"mode\": \"service\",\n \"service\": {\n \"key\": \"tools\",\n \"description\": \"Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.\",\n \"access\": {\n \"optional\": {\n \"expression\": \"ctx.get(\\\"tools\\\")\",\n \"requiresUndefinedCheck\": true\n },\n \"hardDependency\": {\n \"inject\": [\n \"tools\"\n ],\n \"expression\": \"ctx.tools\"\n }\n },\n \"methods\": [\n {\n \"signature\": \"presentAs(mode: ToolPresentationMode): () => void\",\n \"description\": \"Present the calling scope's tools in `mode` instead of the deployment default. Nearest scope on the chain wins, so a preset's standing declaration covers every agent joined under it.\\n\\nScoped only, and one declaration per scope: this is how an agent preset composes PTC mode agents beside native ones in the same process, and a process-global override would be the `mode` config field instead.\",\n \"parameters\": [\n {\n \"name\": \"mode\",\n \"description\": \"the presentation the covered agents' models see.\"\n }\n ],\n \"returns\": \"the exact disposer that restores the deployment default.\"\n },\n {\n \"signature\": \"register(definition: ToolDefinition): () => void\",\n \"description\": \"Register globally or in the calling agent scope. Scoped tools shadow globals; duplicates within one layer and the reserved `run_code` name fail.\",\n \"parameters\": [\n {\n \"name\": \"definition\",\n \"description\": \"tool schema, execution, and optional finalization/presentation callbacks.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the tool.\"\n },\n {\n \"signature\": \"restrict(filter: ToolRestriction): () => void\",\n \"description\": \"Restrict global tools for the calling agent scope. Empty filters, unknown names, scope-local names, and reserved transport names fail. Restrictions intersect; scoped registrations remain visible.\",\n \"parameters\": [\n {\n \"name\": \"filter\",\n \"description\": \"global-tool mask: `allow` (keep only) and/or `deny` (remove).\"\n }\n ],\n \"returns\": \"the exact disposer that lifts this restriction.\"\n },\n {\n \"signature\": \"guard(guard: ToolGuard): () => void\",\n \"description\": \"Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A plain-context guard applies globally; one registered through `agent.ctx` applies only to that agent. Any matching guard may deny by returning a reason, while no guard can force-allow a call another guard denied. The exact effect disposer is returned for ordered ownership and HMR cleanup.\",\n \"parameters\": [\n {\n \"name\": \"guard\",\n \"description\": \"synchronous check; a returned string denies the execution.\"\n }\n ],\n \"returns\": \"the exact disposer that unregisters the guard.\"\n },\n {\n \"signature\": \"get(name: string, scope?: ScopeKey): ToolDefinition | undefined\",\n \"description\": \"Look up a tool as one scope sees it (scoped shadows global; a restricted-away global reads as absent). Presenters pass the calling agent so the rendered card matches the definition that actually executed.\",\n \"parameters\": [\n {\n \"name\": \"name\",\n \"description\": \"the tool name as registered.\"\n },\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"the definition the scope resolves, or undefined when none is visible.\"\n },\n {\n \"signature\": \"schemas(scope?: ScopeKey): ToolSchema[]\",\n \"description\": \"Project visible definitions onto the allowlisted model-facing schema fields, excluding execution and presentation callbacks.\",\n \"parameters\": [\n {\n \"name\": \"scope\",\n \"description\": \"the viewing scope (the agent); omitted = the global view.\"\n }\n ],\n \"returns\": \"one deep-cloned schema per visible tool.\"\n },\n {\n \"signature\": \"executionMode(exec: ToolExecutionInput): ToolExecutionMode\",\n \"description\": \"Classify a pending call through the caller's visible tool definition. Only an exact `true` is parallel; unknown, hidden, undeclared, invalid, or throwing classifiers are exclusive.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"call name, parsed arguments, and optional agent scope.\"\n }\n ],\n \"returns\": \"the fail-closed scheduling mode.\"\n },\n {\n \"signature\": \"async execute(exec: ToolExecutionInput): Promise\",\n \"description\": \"Execute through pre-policy, guards, around-dispatch, post-policy, definition-owned content finalization, and final notification. Tool and listener failures resolve as materialized error results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is the same lossless, frozen snapshot final observers receive. Cancellation arriving after entry and before final result materialization skips a not-yet-started body with `ABORTED_BEFORE_DISPATCH` or replaces a successful started outcome with `ABORTED`; already-started work is still drained and may retain a tool-owned structured error.\",\n \"parameters\": [\n {\n \"name\": \"exec\",\n \"description\": \"the typed same-process call input. The registry assigns its correlation token before policy begins.\"\n }\n ],\n \"returns\": \"the materialized final result.\"\n }\n ]\n },\n \"referencedTypes\": [\n {\n \"name\": \"Agent\",\n \"declaration\": \"export interface Agent {\\n readonly id: SessionId;\\n}\"\n },\n {\n \"name\": \"AssistantProviderMetadata\",\n \"declaration\": \"export interface AssistantProviderMetadata {\\n provider: string;\\n model: string;\\n replayState?: unknown;\\n}\"\n },\n {\n \"name\": \"Branded\",\n \"declaration\": \"export type Branded = string & {\\n readonly [BRAND]: B;\\n};\"\n },\n {\n \"name\": \"ContextFormed\",\n \"declaration\": \"export type ContextFormed = {\\n readonly form?: never;\\n} | {\\n readonly form: 'instructions';\\n} | {\\n readonly form: 'catalog';\\n} | {\\n readonly form: 'snapshot';\\n readonly sections: readonly ContextSnapshotSection[];\\n} | {\\n readonly form: 'notice';\\n readonly summary: string;\\n} | {\\n readonly form: 'relay';\\n} | {\\n readonly form: 'recall';\\n};\"\n },\n {\n \"name\": \"ContextSnapshotSection\",\n \"declaration\": \"export interface ContextSnapshotSection {\\n readonly name: string;\\n readonly text: string;\\n}\"\n },\n {\n \"name\": \"DiffCallView\",\n \"declaration\": \"export interface DiffCallView {\\n card: 'diff';\\n title: string;\\n diffs: FileDiff[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"DiffResultView\",\n \"declaration\": \"export interface DiffResultView {\\n card: 'diff';\\n title?: string;\\n diffs: FileDiff[];\\n}\"\n },\n {\n \"name\": \"FileDiff\",\n \"declaration\": \"export interface FileDiff {\\n path: string;\\n oldText: string | null;\\n newText: string;\\n}\"\n },\n {\n \"name\": \"FileLocation\",\n \"declaration\": \"export interface FileLocation {\\n path: string;\\n line?: number;\\n}\"\n },\n {\n \"name\": \"GenericCallView\",\n \"declaration\": \"export interface GenericCallView {\\n card: 'generic';\\n title: string;\\n kind?: ToolCallKind;\\n rawInput?: unknown;\\n content?: ContentBlock[];\\n locations?: FileLocation[];\\n}\"\n },\n {\n \"name\": \"GenericResultView\",\n \"declaration\": \"export interface GenericResultView {\\n card: 'generic';\\n title?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"JsonSchemaNode\",\n \"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}\"\n },\n {\n \"name\": \"JsonSchemaScalar\",\n \"declaration\": \"export type JsonSchemaScalar = string | number | boolean | null;\"\n },\n {\n \"name\": \"JsonSchemaType\",\n \"declaration\": \"export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';\"\n },\n {\n \"name\": \"JsonValue\",\n \"declaration\": \"export type JsonValue = null | boolean | number | string | JsonValue[] | {\\n [key: string]: JsonValue;\\n};\"\n },\n {\n \"name\": \"Message\",\n \"declaration\": \"export interface Message {\\n readonly id: MessageId;\\n readonly role: 'system' | 'user' | 'assistant';\\n readonly content: ContentBlock[];\\n readonly source: MessageSource;\\n}\"\n },\n {\n \"name\": \"MessageId\",\n \"declaration\": \"export type MessageId = Branded<'MessageId'>;\"\n },\n {\n \"name\": \"MessageSource\",\n \"declaration\": \"export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\"\n },\n {\n \"name\": \"MessageSourceMap\",\n \"declaration\": \"export interface MessageSourceMap {\\n user: {\\n kind: 'user';\\n };\\n plugin: {\\n kind: 'plugin';\\n plugin: string;\\n } & ContextFormed;\\n model: ModelMessageSource;\\n tool: ToolMessageSource;\\n}\"\n },\n {\n \"name\": \"ModelMessageSource\",\n \"declaration\": \"export interface ModelMessageSource extends AssistantProviderMetadata {\\n kind: 'model';\\n}\"\n },\n {\n \"name\": \"ReadFileLine\",\n \"declaration\": \"export interface ReadFileLine {\\n number: number;\\n text: string;\\n}\"\n },\n {\n \"name\": \"ReadResultView\",\n \"declaration\": \"export interface ReadResultView {\\n card: 'read';\\n title?: string;\\n path: string;\\n offset: number;\\n lines: ReadFileLine[];\\n totalLines: number;\\n lang?: string;\\n content?: ContentBlock[];\\n}\"\n },\n {\n \"name\": \"ScopeKey\",\n \"declaration\": \"export type ScopeKey = object;\"\n },\n {\n \"name\": \"SearchFileMatches\",\n \"declaration\": \"export interface SearchFileMatches {\\n path: string;\\n matches: SearchLineMatch[];\\n}\"\n },\n {\n \"name\": \"SearchLineMatch\",\n \"declaration\": \"export interface SearchLineMatch {\\n lineNumber: number;\\n line: string;\\n}\"\n },\n {\n \"name\": \"SearchMatchesResultView\",\n \"declaration\": \"export interface SearchMatchesResultView {\\n card: 'search';\\n shape: 'matches';\\n title?: string;\\n files: SearchFileMatches[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchPathsResultView\",\n \"declaration\": \"export interface SearchPathsResultView {\\n card: 'search';\\n shape: 'paths';\\n title?: string;\\n paths: string[];\\n truncated: boolean;\\n total: number;\\n}\"\n },\n {\n \"name\": \"SearchResultView\",\n \"declaration\": \"export type SearchResultView = SearchMatchesResultView | SearchPathsResultView;\"\n },\n {\n \"name\": \"SessionId\",\n \"declaration\": \"export type SessionId = Branded<'SessionId'>;\"\n },\n {\n \"name\": \"TerminalCallView\",\n \"declaration\": \"export interface TerminalCallView {\\n card: 'terminal';\\n title: string;\\n description?: string;\\n cwd?: string;\\n}\"\n },\n {\n \"name\": \"TerminalResultView\",\n \"declaration\": \"export interface TerminalResultView {\\n card: 'terminal';\\n title?: string;\\n output?: string;\\n exitCode?: number;\\n signal?: string;\\n}\"\n },\n {\n \"name\": \"ToolCallKind\",\n \"declaration\": \"export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\"\n },\n {\n \"name\": \"ToolCallView\",\n \"declaration\": \"export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\"\n },\n {\n \"name\": \"ToolDefinition\",\n \"declaration\": \"export interface ToolDefinition extends ToolSchema {\\n readonly output: ToolOutputDefinition;\\n execute(args: unknown, exec: ToolRunContext): Promise;\\n finalizeContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined;\\n timeoutMs?: number;\\n isConcurrencySafe?(args: unknown): boolean;\\n presentCall?(args: unknown): ToolCallView | undefined;\\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\\n}\"\n },\n {\n \"name\": \"ToolErrorInfo\",\n \"declaration\": \"export interface ToolErrorInfo {\\n name: string;\\n code: string;\\n}\"\n },\n {\n \"name\": \"ToolExecution\",\n \"declaration\": \"export interface ToolExecution extends ToolExecutionInput {\\n readonly rootCallId: ToolCallId;\\n readonly token: ToolExecutionToken;\\n}\"\n },\n {\n \"name\": \"ToolExecutionFailure\",\n \"declaration\": \"export interface ToolExecutionFailure {\\n readonly isError: true;\\n readonly error: ToolFailure;\\n readonly value?: never;\\n readonly content: ContentBlock[];\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: never;\\n}\"\n },\n {\n \"name\": \"ToolExecutionInput\",\n \"declaration\": \"export interface ToolExecutionInput {\\n readonly callId: ToolCallId;\\n readonly rootCallId?: ToolCallId;\\n readonly name: string;\\n readonly arguments: unknown;\\n readonly agent?: Agent;\\n readonly parent?: ToolExecutionToken;\\n readonly signal: AbortSignal;\\n}\"\n },\n {\n \"name\": \"ToolExecutionMode\",\n \"declaration\": \"export type ToolExecutionMode = {\\n kind: 'parallel';\\n} | {\\n kind: 'exclusive';\\n};\"\n },\n {\n \"name\": \"ToolExecutionResult\",\n \"declaration\": \"export type ToolExecutionResult = ToolExecutionSuccess | ToolExecutionFailure;\"\n },\n {\n \"name\": \"ToolExecutionSuccess\",\n \"declaration\": \"export interface ToolExecutionSuccess {\\n readonly isError: false;\\n readonly value: JsonValue;\\n readonly content: ContentBlock[];\\n readonly error?: never;\\n readonly meta?: JsonValue;\\n readonly additionalContexts?: UserMessage[];\\n readonly concludesTurn?: true;\\n}\"\n },\n {\n \"name\": \"ToolExecutionToken\",\n \"declaration\": \"export type ToolExecutionToken = symbol & {\\n readonly [toolExecutionTokenBrand]: true;\\n};\"\n },\n {\n \"name\": \"ToolFailure\",\n \"declaration\": \"export interface ToolFailure {\\n message: string;\\n info?: ToolErrorInfo;\\n}\"\n },\n {\n \"name\": \"ToolGuard\",\n \"declaration\": \"export type ToolGuard = (execution: Readonly) => string | undefined;\"\n },\n {\n \"name\": \"ToolMessageSource\",\n \"declaration\": \"export interface ToolMessageSource {\\n kind: 'tool';\\n callId: ToolCallId;\\n}\"\n },\n {\n \"name\": \"ToolOutputDefinition\",\n \"declaration\": \"export interface ToolOutputDefinition {\\n readonly schema: JsonSchemaNode;\\n render(args: unknown, value: JsonValue): ContentBlock[];\\n presentationMeta?(args: unknown, value: JsonValue): JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolPresentationMode\",\n \"declaration\": \"export type ToolPresentationMode = 'native' | 'ptc' | 'both';\"\n },\n {\n \"name\": \"ToolRestriction\",\n \"declaration\": \"export interface ToolRestriction {\\n readonly allow?: readonly string[];\\n readonly deny?: readonly string[];\\n}\"\n },\n {\n \"name\": \"ToolResult\",\n \"declaration\": \"export interface ToolResult {\\n content: ContentBlock[];\\n isError: boolean;\\n meta?: JsonValue;\\n}\"\n },\n {\n \"name\": \"ToolResultView\",\n \"declaration\": \"export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView | SearchResultView | ReadResultView | WebResultView;\"\n },\n {\n \"name\": \"ToolRunContext\",\n \"declaration\": \"export interface ToolRunContext extends ToolExecution {\\n deferContext(context: UserMessage): void;\\n concludeTurn(): void;\\n}\"\n },\n {\n \"name\": \"ToolSchema\",\n \"declaration\": \"export interface ToolSchema {\\n name: string;\\n description: string;\\n parameters: Record;\\n}\"\n },\n {\n \"name\": \"UserMessage\",\n \"declaration\": \"export interface UserMessage extends Message {\\n readonly role: 'user';\\n}\"\n },\n {\n \"name\": \"WebFetchResultView\",\n \"declaration\": \"export interface WebFetchResultView {\\n card: 'web';\\n kind: 'fetch';\\n title?: string;\\n url: string;\\n statusCode: number;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebResultView\",\n \"declaration\": \"export type WebResultView = WebSearchResultView | WebFetchResultView;\"\n },\n {\n \"name\": \"WebSearchResultView\",\n \"declaration\": \"export interface WebSearchResultView {\\n card: 'web';\\n kind: 'search';\\n title?: string;\\n sources: WebSource[];\\n answer?: string;\\n truncated: boolean;\\n}\"\n },\n {\n \"name\": \"WebSource\",\n \"declaration\": \"export interface WebSource {\\n url: string;\\n title?: string;\\n snippet?: string;\\n publishedAt?: string;\\n}\"\n }\n ]\n }\n}"}],"isError":false}],"role":"user","id":"{{message:5}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"} {"type":"step/end","data":{"turn":1,"step":1}} {"type":"step/start","data":{"turn":1,"step":2}} {"type":"assistant/message","data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"deepseek-v4-flash"},"id":"{{message:6}}"},"usage":{"inputTokens":3,"outputTokens":3},"stream":[{"type":"chunk","time":1788778146017,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}},{"type":"tool-call-chunks","time0":1788778146017,"index":0,"dt":[],"id":"inspect-subprocess-api","name":"cordis_inspect_query","args":["{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"]},{"type":"chunk","time":1788778146017,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-subprocess-api","name":"cordis_inspect_query","arguments":"{\"platform\":\"host\",\"provider\":\"Service\",\"method\":\"listService\",\"input\":{\"service\":\"subprocess\"}}"}}},{"type":"chunk","time":1788778146017,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}},{"type":"chunk","time":1788778146017,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}]},"surfaceOp":"append"} diff --git a/vitest.config.ts b/vitest.config.ts index 31049baa7e..e11bac9c82 100644 --- a/vitest.config.ts +++ b/vitest.config.ts @@ -243,7 +243,7 @@ export default defineConfig({ 'packages/client/ui-chat/src/client/conversation-nodes/*', 'packages/client/ui-chat/src/client/details/*', 'packages/client/ui-chat/src/client/model/*', - 'packages/client/ui-chat/src/client/contract/context-provenance.ts', + 'packages/client/ui-chat/src/client/contract/context-producer.ts', 'packages/client/ui-chat/src/client/contract/snapshot.ts', 'packages/client/ui-chat/src/client/historical-images.ts', 'packages/client/ui-primitives/src/DisclosureRow.tsx',