Merge remote-tracking branch 'origin/master' into feat/todo-multi-in-progress
# Conflicts: # examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
This commit is contained in:
Chinesezjc
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-20-canonical-tool-output-contract.md: 8cd7df98758d6d4ac240fea21e7bbe0c89f26d1b
|
||||
2026-07-20-canonical-tool-output-contract.zh.md: 0920e0c2c331a247ecd9a039a05c19c9dd2871bc
|
||||
2026-07-20-canonical-tool-output-contract.md: 6b5cd089fcf206e659c7b67b8a996bfe81d0c333
|
||||
2026-07-20-canonical-tool-output-contract.zh.md: 61b25b14ca6f048b73a51788f112165745ae7106
|
||||
|
||||
@@ -34,7 +34,7 @@ type ToolExecutionResult =
|
||||
|
||||
`tools/post-execute` has two mutually exclusive successful projections. Replacing `content` changes only Native/model presentation and preserves the canonical value and metadata. Replacing `value` revalidates the replacement and recomputes both presentation projections. A block removes the value and becomes a failure. Content replacement is therefore not a confidentiality mechanism: policy that must prevent programmatic access blocks the call or replaces the value.
|
||||
|
||||
Canonical values are execution-local. The agent loop persists `tool/result` with only `content`, `error`, and optional `meta`; Code Mode's `tool/code-dispatch` persists only its bounded summary. Neither event stores the intermediate value, so replay reproduces presentation but cannot reconstruct the programmatic result. When a tool declares `presentationMeta`, it is computed only for a direct surface call; a nested Code dispatch gets no metadata or result card. The outer `run_code` card instead reads final post-policy content and declares no presentation metadata. Generic and tool-owned spill projections similarly skip nested dispatches, whose canonical value never enters model context.
|
||||
Canonical values are execution-local. The agent loop persists `tool/result` with only `content`, `error`, and optional `meta`; Code Mode's `tool/code-dispatch` persists the sub-call's rendered `content` and `isError`. Neither event stores the canonical intermediate value, so replay reproduces presentation but cannot reconstruct the programmatic result. When a tool declares `presentationMeta`, it is computed only for a direct surface call; a nested Code dispatch gets no metadata or result card. The outer `run_code` card instead reads final post-policy content and declares no presentation metadata. Generic and tool-owned spill projections similarly skip nested dispatches, whose canonical value never enters model context.
|
||||
|
||||
The first-party tools preserve their existing Native text while returning domain DTOs:
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@ type ToolExecutionResult =
|
||||
|
||||
`tools/post-execute` 为成功结果提供两种互斥的投影方式。替换 `content` 只改变 Native／模型展示，并保留规范值和元数据。替换 `value` 会重新校验替代值，并重新计算两份展示投影。阻止操作会移除值并转为失败。因此，替换内容并不是保密机制：必须阻止程序化访问的策略，应当阻止调用或替换值。
|
||||
|
||||
规范值仅存在于执行期间。agent loop（智能体循环）持久化的 `tool/result` 只包含 `content`、`error` 和可选的 `meta`；Code Mode 的 `tool/code-dispatch` 只持久化其有界摘要。两个事件都不存储中间值，因此回放可以重现展示，却无法重建程序化结果。当工具声明 `presentationMeta` 时，系统只会为直接的外层调用计算它；嵌套 Code 分发没有元数据或结果卡片。外层 `run_code` 卡片则读取最终的 post-policy 内容，并且不声明展示元数据。通用以及工具自有的输出落盘投影同样跳过嵌套分发，因为它们的规范值永远不会进入模型上下文。
|
||||
规范值仅存在于执行期间。agent loop（智能体循环）持久化的 `tool/result` 只包含 `content`、`error` 和可选的 `meta`；Code Mode 的 `tool/code-dispatch` 持久化子调用渲染后的 `content` 与 `isError`。两个事件都不存储规范中间值，因此回放可以重现展示，却无法重建程序化结果。当工具声明 `presentationMeta` 时，系统只会为直接的外层调用计算它；嵌套 Code 分发没有元数据或结果卡片。外层 `run_code` 卡片则读取最终的 post-policy 内容，并且不声明展示元数据。通用以及工具自有的输出落盘投影同样跳过嵌套分发，因为它们的规范值永远不会进入模型上下文。
|
||||
|
||||
第一方工具在保持现有 Native 文本不变的同时返回领域 DTO：
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-20-code-mode-result-card-completeness.md: 97cd9d722e8252b956e16da03c3b8418451350f3
|
||||
2026-07-20-code-mode-result-card-completeness.zh.md: fea162b073e3473f7a07d4bf054408d28851fea9
|
||||
2026-07-20-code-mode-result-card-completeness.md: 05ff0ed41c94bef7eb41204d8dd81bbda3c06016
|
||||
2026-07-20-code-mode-result-card-completeness.zh.md: a93be4cc42fca87ce4ef11b6ad3a6cbe64bef66f
|
||||
|
||||
@@ -16,7 +16,7 @@ The canonical tool registry pipeline owns the final model-facing outer content.
|
||||
|
||||
`run_code` omits `presentResult`. The established generic result fallback keeps the pending program title and renders the raw final `tool/result.content`; that durable, replayable, post-policy projection is the card's only result-content source. The host API proxy therefore omits a separate result view instead of serializing the same content in both `event.data.content` and `view.view.content`. The redundant logs-only `presentationMeta` projection remains removed.
|
||||
|
||||
Nested dispatch remains unchanged. Calls marked by `exec.parent` emit bounded `tool/code-dispatch` diagnostics but no `tool/call` or `tool/result` surface cards, so one outer `run_code` invocation still produces exactly one card.
|
||||
Nested dispatch remains unchanged. Calls marked by `exec.parent` emit `tool/code-dispatch` events (full rendered content) but no `tool/call` or `tool/result` surface cards, so one outer `run_code` invocation still produces exactly one card.
|
||||
|
||||
## Testing
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ Status: implemented
|
||||
|
||||
`run_code` 不提供 `presentResult`。既有的通用结果回退机制会保留待完成的程序标题，并渲染原始的最终 `tool/result.content`；这一持久、可回放且经过 post-policy 处理的投影是卡片中结果内容的唯一来源。宿主 API 代理因此不提供单独的结果视图，而不会在 `event.data.content` 与 `view.view.content` 中重复序列化同一内容。冗余的仅含日志的 `presentationMeta` 投影继续保持移除状态。
|
||||
|
||||
嵌套分发保持不变。带有 `exec.parent` 标记的调用会发出有界的 `tool/code-dispatch` 诊断，但不会生成与 `tool/call` 或 `tool/result` 对应的界面卡片，因此一次外层 `run_code` 调用仍然只会生成一张卡片。
|
||||
嵌套分发保持不变。带有 `exec.parent` 标记的调用会发出 `tool/code-dispatch` 事件（携带完整渲染内容），但不会生成与 `tool/call` 或 `tool/result` 对应的界面卡片，因此一次外层 `run_code` 调用仍然只会生成一张卡片。
|
||||
|
||||
## 测试
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-06-15-code-mode.md: 8e964eeb36e430b58312427e45cf8e4a99582457
|
||||
2026-06-15-code-mode.zh.md: 3de1adfcf287b69ca8307244bde35f286ce4b99d
|
||||
2026-06-15-code-mode.md: 1170fa4f9fa778fa9176097317477ea336588d32
|
||||
2026-06-15-code-mode.zh.md: 4362efa332d0ed24a6383a4cf75b83c0dba22e7e
|
||||
|
||||
@@ -40,9 +40,9 @@ This note owns Code Mode's presentation, composition, isolation, and settlement
|
||||
|
||||
### The run_code tool and the dispatch bridge
|
||||
|
||||
Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentation transport with one required parameter, `{ code: string }`. It is represented by a normal `ToolDefinition` for dispatch but stays outside the filterable capability layers, so restrictions cannot accidentally remove Code Mode's only entry point. Calls traverse the complete tool pipeline — `tools/pre-execute` → monotonic guards → `tools/execute` around dispatch → `tools/post-execute` → optional definition-owned `finalizeContent` → immutable `tools/result` notification — exactly like native calls; a permission plugin can inspect the program text before it runs, and final-result observers see the normalized outer outcome. Its `execute(args, exec)`:
|
||||
Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentation transport with two required parameters, `{ code: string; description: string }` (the description labels the call in UIs, the bash precedent). It is represented by a normal `ToolDefinition` for dispatch but stays outside the filterable capability layers, so restrictions cannot accidentally remove Code Mode's only entry point. Calls traverse the complete tool pipeline — `tools/pre-execute` → monotonic guards → `tools/execute` around dispatch → `tools/post-execute` → optional definition-owned `finalizeContent` → immutable `tools/result` notification — exactly like native calls; a permission plugin can inspect the program text before it runs, and final-result observers see the normalized outer outcome. Its `execute(args, exec)`:
|
||||
|
||||
1. **Build bindings.** One run-scoped signal follows outer cancellation and is aborted whenever the run settles. Each visible tool binding snapshots lossless-JSON arguments, waits on the serialization queue, executes with a deterministic call id and the outer token as `parent`, defers returned contexts through the outer execution, and logs `tool/code-dispatch`. Success returns the tool's final canonical JSON value; failure becomes the program-visible `ToolCallError`. Every sub-call retains its own immutable execution identity and traverses the full tool pipeline.
|
||||
1. **Build bindings.** One run-scoped signal follows outer cancellation and is aborted whenever the run settles. Each visible tool binding snapshots lossless-JSON arguments, enters the native-contract dispatch pool (the [live-parallel note](2026-07-26-code-mode-live-parallel-dispatch.md) owns the scheduling design), executes with a deterministic call id and the outer token as `parent`, defers returned contexts through the outer execution, and logs the `tool/code-dispatch-start`/`tool/code-dispatch` pair, the settle side carrying the full rendered result content. Success returns the tool's final canonical JSON value; failure becomes the program-visible `ToolCallError`. Every sub-call retains its own immutable execution identity and traverses the full tool pipeline.
|
||||
2. **Runs the program**: `ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`. The runtime receives the run-scoped signal, not only the caller's outer signal, so any way the outer run settles also aborts work inside the runtime.
|
||||
3. **Settle after quiescence.** When the runtime settles, the bridge aborts outstanding work and drains the dispatch queue before returning. Success returns captured logs and the completion value as canonical output; the registry renders that value into durable `tool/result.content`, which the result card reads directly. A runtime failure becomes `CodeRunFailedError`; backend rejection uses the registry's normal error boundary. Both produce structured error results, and no sub-call can append after `run_code` settles.
|
||||
|
||||
@@ -54,7 +54,7 @@ Under `'code'` and `'both'` the registry owns `run_code` as a reserved presentat
|
||||
|
||||
### Observability: `tool/code-dispatch`
|
||||
|
||||
Each sub-dispatch appends a log-only `tool/code-dispatch` event containing parent and child call ids, tool identity, normalized arguments, and result summary. It remains outside model history but available to persistence and UIs. Appends occur inside the open `run_code` turn. Direct executions without an agent still run but cannot log the event.
|
||||
Each sub-dispatch appends a log-only `tool/code-dispatch-start` event at pool entry and a `tool/code-dispatch` settle event containing parent and child call ids, tool identity, normalized arguments, and the complete rendered `content`/`isError` outcome. It remains outside model history but available to persistence and UIs. Appends occur inside the open `run_code` turn. Direct executions without an agent still run but cannot log the event.
|
||||
|
||||
### The code-runtime seam
|
||||
|
||||
|
||||
@@ -40,9 +40,9 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
|
||||
### run_code 工具与分发桥
|
||||
|
||||
在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带一个必需参数 `{ code: string }`。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
|
||||
在 `'code'` 和 `'both'` 下，注册表拥有 `run_code` 作为保留的呈现传输通道，带两个必需参数 `{ code: string; description: string }`（description 为 UI 标注该调用，沿用 bash 的先例）。它由一个正常的 `ToolDefinition` 表示以供分发，但位于可过滤的能力层之外，因此限制规则不会意外移除 Code Mode 的唯一入口。调用遍历完整的工具流水线——`tools/pre-execute` → 单调守卫 → `tools/execute` 包裹分发 → `tools/post-execute` → 由定义拥有的可选 `finalizeContent` → 不可变的 `tools/result` 通知——与原生调用完全一致；权限插件可以在程序运行前检查程序文本，最终结果观察者看到的是规范化的外层结果。其 `execute(args, exec)`：
|
||||
|
||||
1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，等待序列化队列，以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch`。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
|
||||
1. **构建绑定。** 一个 run 级别的 signal 跟随外层取消，并在 run 结算时被 abort。每个可见工具绑定都会对无损 JSON 参数创建快照，进入原生契约的分发池（调度设计由[实时并行 Agent Note](2026-07-26-code-mode-live-parallel-dispatch.md) 负责），以确定性的 call id 和外层 token 作为 `parent` 执行，通过外层 execution 延后返回的上下文，并记录 `tool/code-dispatch-start`/`tool/code-dispatch` 事件对，其中结算侧携带完整渲染后的结果内容。成功时返回工具最终的规范 JSON 值；失败则变为程序可见的 `ToolCallError`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。
|
||||
2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。
|
||||
3. **完全停稳后结算。** 运行时结算后，桥 abort 未完成的工作并排空分发队列后再返回。成功时返回捕获的日志和完成值，将其作为规范输出；注册表再把该值渲染为持久化的 `tool/result.content`，供结果卡片直接读取。运行时失败变为 `CodeRunFailedError`；后端拒绝使用注册表的正常错误边界。两者都产生结构化的错误结果，且 `run_code` 结算后不允许子调用追加。
|
||||
|
||||
@@ -54,7 +54,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
|
||||
|
||||
### 可观测性：`tool/code-dispatch`
|
||||
|
||||
每次子分发追加一个仅日志的 `tool/code-dispatch` 事件，包含父子 call id、工具标识、规范化参数和结果摘要。它不进入模型历史，但可供持久化和 UI 使用。追加发生在开放的 `run_code` 轮次内。没有 agent 的直接执行仍然运行，但无法记录该事件。
|
||||
每次子分发在进入分发池时追加一个仅日志的 `tool/code-dispatch-start` 事件，并以一个 `tool/code-dispatch` 结算事件收尾，后者包含父子 call id、工具标识、规范化参数以及完整渲染后的 `content`/`isError` 结果。它不进入模型历史，但可供持久化和 UI 使用。追加发生在开放的 `run_code` 轮次内。没有 agent 的直接执行仍然运行，但无法记录该事件。
|
||||
|
||||
### code-runtime seam
|
||||
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-20-code-mode-typed-tool-returns.md: 1b5cbb9f4664c371a03cfefd079d5dc531711b51
|
||||
2026-07-20-code-mode-typed-tool-returns.zh.md: 70fd9ee72803c5cd2fa228a1d38ddf7ae47a4814
|
||||
2026-07-20-code-mode-typed-tool-returns.md: 3d8642d66baf521f22dfb1ea0ef3e64683f918d4
|
||||
2026-07-20-code-mode-typed-tool-returns.zh.md: fea1be3e236c0ccba729e449ab9714ed497d900a
|
||||
|
||||
@@ -73,7 +73,7 @@ Dynamic Cordis mounting follows the same rule: `cordis_mount` returns `{ id, plu
|
||||
|
||||
### Persistence, metadata, and spill
|
||||
|
||||
Nested dispatch keeps the existing bounded `tool/code-dispatch.resultSummary` for diagnostics but does not persist canonical values. `tool/result` continues to persist only rendered content, error, and optional metadata. This is deliberately not a session-format change, so `SESSION_FORMAT_VERSION` remains unchanged and replay cannot recreate intermediate program values.
|
||||
Nested dispatch logs the sub-call's full rendered `content`/`isError` on `tool/code-dispatch` but does not persist canonical values. `tool/result` continues to persist only rendered content, error, and optional metadata. `SESSION_FORMAT_VERSION` remains unchanged (pre-release shape churn does not bump it) and replay cannot recreate intermediate canonical program values.
|
||||
|
||||
The opaque `exec.parent` token marks nested calls. Presentation metadata and generic or tool-owned spill projections skip those calls because they have no direct result card and their canonical values never enter context. The outer `run_code` call alone produces one card and may spill its final post-policy presentation; `run_code` intentionally declares neither a result presenter nor presentation metadata, so UI adapters complete the card through their generic raw-content fallback using durable `tool/result.content`.
|
||||
|
||||
|
||||
@@ -73,7 +73,7 @@ Code Mode 通过运行时请求中的 `{ name: "ToolCallError", memberNameProper
|
||||
|
||||
### 持久化、元数据与输出落盘
|
||||
|
||||
嵌套分发会为诊断保留既有的有界 `tool/code-dispatch.resultSummary`，但不会持久化规范值。`tool/result` 继续只持久化渲染后的内容、错误和可选元数据。这并非会话格式变更，因此 `SESSION_FORMAT_VERSION` 保持不变，回放也无法重建程序的中间值。
|
||||
嵌套分发在 `tool/code-dispatch` 上记录子调用完整渲染后的 `content`/`isError`，但不会持久化规范值。`tool/result` 继续只持久化渲染后的内容、错误和可选元数据。`SESSION_FORMAT_VERSION` 保持不变（预发布阶段的形状变动不递增版本号），回放也无法重建程序的规范中间值。
|
||||
|
||||
不透明的 `exec.parent` token 用于标识嵌套调用。由于这些调用没有直接对应的结果卡片，而且其规范值永远不会进入上下文，展示元数据以及通用或工具自有的输出落盘投影都会跳过它们。只有外层 `run_code` 调用会生成一张卡片，并且可能将 post-policy 处理后的最终展示写入落盘文件；`run_code` 有意既不声明结果展示器，也不声明展示元数据，因此 UI 适配器会通过通用的原始内容回退机制，使用持久化的 `tool/result.content` 补全该卡片。
|
||||
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-26-code-dispatch-ui-foundation.md: a1629c77304bc7ef744f7a09241bcdfc81e461ae
|
||||
2026-07-26-code-dispatch-ui-foundation.zh.md: 164b1e8eed343e88b6529e4fedde06ba442d7d51
|
||||
@@ -0,0 +1,31 @@
|
||||
# Agent Note: Code Mode UI foundation — run_code description and native-parity dispatch logging
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-26-code-dispatch-ui-foundation.zh.md)
|
||||
|
||||
> Scope: the host-side contract changes that let a UI render a Code Mode turn with the same fidelity as native tool calls — the first PR of the Code Mode web-UI stack. The [Code Mode foundation](2026-06-15-code-mode.md) owns the transport design; this note owns the model-visible `description` parameter, the full-content `tool/code-dispatch` payload, and the temporary `DSH_TOOLS_MODE` enablement seam for the `dsh` config tree.
|
||||
|
||||
## Problem
|
||||
|
||||
A `run_code` turn was opaque in every product surface. The call card's title was the raw program text — unreadable at row width, and unlike `bash` (whose required `description` labels the card while the command rides the expanded input) there was no model-authored label at all. The `tool/code-dispatch` event carried only a 200-char, cwd-normalized `resultSummary` of each sub-call, so no UI could ever show what a sub-call actually returned: the planned web conversation view renders sub-calls through the exact components that render native `tool/result` cards, and a bounded summary cannot feed a native-parity card. And the `dsh web` composition had no way to enable Code Mode at all — the `tools` row pinned the schema default and the runtime was absent from the tree.
|
||||
|
||||
## Decision
|
||||
|
||||
Three changes, one per obstacle:
|
||||
|
||||
1. **`run_code` gains a required `description` parameter** (bash's exact contract: active voice, 5-10 words, shown in the UI; whitespace-only rejected at execute). `presentCall` now titles the card with the description and moves the program to `rawInput`. The prompt-side cost is a few tokens per call; the return is that every surface — TUI card, ACP title, web row — gets a human-readable label without parsing TypeScript.
|
||||
2. **`tool/code-dispatch` logs the sub-call's complete model-facing outcome** — `content: ContentBlock[]` + `isError`, the `tool/result` vocabulary — replacing `resultSummary` and deleting the summarize/cwd-normalization machinery outright. A UI renders a sub-call through the identical code path as a native result, including error text and non-text blocks. The event stays log-only (`deriveMessages()` ignores it): nothing about model context changes.
|
||||
3. **`DSH_TOOLS_MODE` env var on the `dsh` config tree** (`native`|`code`|`both`; unset keeps the schema default): the `tools` row reads it via `!!js`, and the worker code runtime is mounted unconditionally (Loader metadata is static, so no conditional row exists; a native boot only registers the service — workers spawn per run). This is an explicitly temporary seam: per-session tool-mode selection owned by the web UI is the design goal, and the env var dies when that lands.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Keep a bounded summary (raised cap, or a cap + `truncated` flag).** Rejected: the stack's settled requirement is that sub-call rows and details render *identically* to native calls; any cap forces a second, degraded render path plus truncation UI. The cost accepted instead: a program that reads a large file logs the rendered content verbatim on the dispatch event — uncapped, outside spill policy, growing the session log by the same bytes. Spill integration for the logged copy is deferred to a later PR of this stack (the projection exists; wiring it into the bridge is mechanical once the event shape settles with the start/end pair).
|
||||
|
||||
**A `--tools-mode` CLI flag or profile key.** Deferred, not rejected: the flag grammar suggests permanence, and the profile json is user config — both would harden a seam the per-session design intends to remove. An env var reads as the workaround it is.
|
||||
|
||||
**Log the canonical `value` instead of rendered `content`.** Rejected: `tool/result` persists content, not values (the [canonical output contract](../architecture/2026-07-20-canonical-tool-output-contract.md)), and native parity means matching that exactly; values remain execution-local everywhere.
|
||||
|
||||
## Consequences
|
||||
|
||||
Session format keeps `SESSION_FORMAT_VERSION` 0 (pre-release churn does not bump; old logs with `resultSummary` simply carry an extra unread field and lack `content` — v0 makes no compatibility promise). Existing code-mode snapshot fixtures were re-recorded. Model-visible surface grew: the `run_code` schema (one required parameter) and every code-mode system prompt/tool-schema snapshot changed. The web UI stack (subsequent PRs) builds directly on the new event payload; live per-sub-call running state needs a dispatch start/end pair that will reshape this event again.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Agent Note：Code Mode 的 UI 基础——run_code 的 description 参数，以及与原生同等保真的分发日志
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-26-code-dispatch-ui-foundation.md) | 中文
|
||||
|
||||
> 范围：让 UI 能以与原生工具调用相同的保真度渲染 Code Mode 轮次的宿主侧契约变更，即 Code Mode web UI 堆叠 PR（Pull Request）链的第一个 PR。传输设计归 [Code Mode 基础](2026-06-15-code-mode.md)所有；模型可见的 `description` 参数、携带完整内容的 `tool/code-dispatch` 载荷，以及 `dsh` 配置树上临时的 `DSH_TOOLS_MODE` 启用 seam，归本篇所有。
|
||||
|
||||
## 问题
|
||||
|
||||
`run_code` 轮次过去在每个产品表面上都不透明。调用卡片的标题就是原始程序文本，在行宽内无法阅读；而且不同于 `bash`（其必填的 `description` 用作卡片标签，命令本身放在展开后的输入里），`run_code` 完全没有模型撰写的标签。`tool/code-dispatch` 事件过去只携带每个子调用的 `resultSummary`（上限 200 字符、经 cwd 归一化），因此任何 UI 都无从展示子调用实际返回的内容：规划中的 web 对话视图会用渲染原生 `tool/result` 卡片的同一批组件来渲染子调用，而有界摘要无法支撑一张与原生同等保真的卡片。同时，`dsh web` 组合此前根本无法启用 Code Mode：`tools` 行钉死在 schema 默认值上，配置树里也完全没有该运行时。
|
||||
|
||||
## 决策
|
||||
|
||||
三项变更，每项对应一个障碍：
|
||||
|
||||
1. **`run_code` 新增必填的 `description` 参数**（与 bash 完全相同的契约：主动语态、5-10 个词、展示在 UI 中；仅含空白的取值在执行时被拒绝）。`presentCall` 现在以该 description 作为卡片标题，并把程序文本移入 `rawInput`。提示词侧的成本是每次调用多出几个 token；换来的是每个表面——TUI 卡片、ACP（Agent Client Protocol）标题、web 行——都无需解析 TypeScript 就能获得可供人阅读的标签。
|
||||
2. **`tool/code-dispatch` 记录子调用面向模型的完整结果**（`content: ContentBlock[]` 加 `isError`，即 `tool/result` 的词汇），取代 `resultSummary`，并把摘要与 cwd 归一化机制彻底删除。UI 渲染子调用走的代码路径与渲染原生结果完全相同，包括错误文本和非文本块。该事件保持仅日志（`deriveMessages()` 忽略它）：模型上下文没有任何变化。
|
||||
3. **`dsh` 配置树上的 `DSH_TOOLS_MODE` 环境变量**（`native`|`code`|`both`；未设置时保持 schema 默认值）：`tools` 行通过 `!!js` 读取它，worker 代码运行时则无条件挂载（Loader 元数据是静态的，因此不存在条件行；native 启动只是注册该服务，worker 要到每次运行时才 spawn）。这是一个明确标注为临时的 seam：设计目标是让 web UI 拥有按会话的工具模式选择，该目标落地后，这个环境变量随即退役。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**保留有界摘要（提高上限，或上限加 `truncated` 标志）。** 否决：本堆叠 PR 链已敲定的要求是，子调用的行与详情必须与原生调用渲染得*完全一致*；任何上限都会强制引入第二条降级的渲染路径，外加截断 UI。转而接受的代价是：读取大文件的程序会把渲染后的内容原样记录在分发事件上，不设上限、位于 spill 策略之外，并以同样的字节数增大会话日志。已记录副本的 spill 集成推迟到本链靠后的 PR（投影已经存在；待事件形状随 start/end 事件对一同定形，把它接入桥接层只是机械工作）。
|
||||
|
||||
**一个 `--tools-mode` CLI（命令行界面）标志或 profile 配置键。** 推迟，而非否决：标志语法暗示永久性，profile json 又是用户配置；两者都会固化这个 seam，而按会话选择的设计本就打算移除它。环境变量则如实呈现了它权宜之计的本质。
|
||||
|
||||
**记录规范 `value`，而非渲染后的 `content`。** 否决：`tool/result` 持久化的是内容而非值（见[规范输出契约](../architecture/2026-07-20-canonical-tool-output-contract.md)），与原生同等保真意味着与之精确对齐；值在任何地方都保持执行期本地。
|
||||
|
||||
## 后果
|
||||
|
||||
会话格式保持 `SESSION_FORMAT_VERSION` 为 0（预发布阶段的变动不递增版本号；携带 `resultSummary` 的旧日志只是多出一个不被读取的字段并缺少 `content`；v0 不作任何兼容性承诺）。既有的 code-mode 快照 fixture（测试前置数据）已重新录制。模型可见表面扩大了：`run_code` 的 schema（新增一个必填参数）以及每一份 code-mode 系统提示词／工具 schema 快照都发生了变化。web UI 堆叠 PR 链（后续各 PR）直接构建在新的事件载荷之上；每个子调用的实时运行状态还需要一对分发 start/end 事件，这将再次重塑本事件的形状。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-26-code-mode-chat-subcall-rows.md: 7d666f0a9e4b8bdb9bd6f5d0d0984fee0c4b21e2
|
||||
2026-07-26-code-mode-chat-subcall-rows.zh.md: fb9b0c62bb702cfdb7ba3c8ccce73d8e43f29c1b
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note: Code Mode chat rendering — sub-calls as native rows under the parent
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-26-code-mode-chat-subcall-rows.zh.md)
|
||||
|
||||
> Scope: how the web chat view renders a `run_code` turn — the client-side half of the Code Mode UI stack, built on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) (full-content `tool/code-dispatch`, the required `description` parameter). The [toolview dissolution](../architecture/2026-07-23-toolview-dissolution.md) owns the slot model this rides on.
|
||||
|
||||
## Problem
|
||||
|
||||
With Code Mode enabled, the chat view showed one opaque `run_code` row: raw program text as the summary, sub-calls invisible everywhere. The settled product requirement is the opposite: each sub-call must render *identically* to a native tool call — same row components, same custom registrations, same details panel — while the transcript stays honest about the fact that the model made ONE call.
|
||||
|
||||
## Decision
|
||||
|
||||
**Sub-calls are `ToolResultNode`s indexed off the surface flow, rendered through the same keyed slot as native rows, nested always-visible under their parent.**
|
||||
|
||||
- **Data layer**: `Session.applyEventSideEffects` folds each in-window `tool/code-dispatch` into `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`, where `CodeSubCall` IS `ToolResultNode` (the sub-call id as `callId`, the logged args JSON-stringified into `call.argsRaw`, the full logged `content`/`isError`). Live mux frames and history replay build the identical index (`rebuildDerivedFromWindow` clears and re-derives; copy-on-write per-parent arrays keep snapshot references memo-stable). Sub-calls never join `nodes` — the surface flow remains exactly the model-visible turn structure. The event is narrowed structurally at the wire-consumer boundary (dsh-tools' host types cannot enter the client program — the host/client `Context` merges collide), the same posture as every cross-wire payload.
|
||||
- **Render layer**: `ChatView`'s `CallRow` renders the parent, then — for parents present in the index — a `[data-subcalls]` nest of `SubCallRow`s, each dispatching through the SAME `'conversation.chat.toolview'` keyed hole with `entryKey = sub-tool name` and the same `GenericToolCard` fallback. Identity with native rows holds by construction: a keyed registration (e.g. the bash sample) takes over sub-rows exactly as it takes over top-level rows, with zero registration changes. Running parents (`runningCalls`) nest their so-far dispatches the same way, so sub-rows stream in live during the run (PR1 logs each dispatch as it completes).
|
||||
- **`run_code` presentation**: a new `code` row variant (classifier `run_code → code`, `Code` title, `IconCodeOutline16`) summarizes with the model-authored `description` and expands to the program itself (monospace on the markdown code-block fill) rather than the args JSON envelope.
|
||||
- **Details panel**: `materialFor` falls through nodes → runningCalls → the dispatch index, so a selected sub-callId resolves to full args and complete output through the identical rendering path as a native settled call.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Sub-calls flat in the surface flow (fold them into `nodes`).** Rejected: misrepresents the transcript — the model made one call; nesting under the parent preserves the code↔calls association and keeps the fold's model-visible-order invariant untouched.
|
||||
|
||||
**Hidden until the parent row expands.** Rejected by product decision: the sub-calls ARE the story of a Code Mode turn; hiding them re-creates the opacity this feature removes. The parent's expand toggle reveals only the program.
|
||||
|
||||
**A dedicated sub-call row component.** Rejected: the whole point is identity with native rows; a parallel component would drift. The nest wrapper (indent + left edge) is the only sub-call-specific chrome.
|
||||
|
||||
## Consequences
|
||||
|
||||
Custom toolview registrations apply to sub-calls for free — and deliberately: there is no per-registration opt-out short of the component reading its own context, which no current consumer needs. Selection highlighting reaches nested rows through the same `selectedCallId` channel (group membership tests both levels). Trajectory/waterfall still render `run_code` as a single row — their sub-call spans are deferred to the PR that adds dispatch timing (start/end events), without which a waterfall span would be a lie. Fixture turn 64 (`?fixture`) plus the `code-mode-round` browser e2e (recorded real round, keyless replay) pin the full surface; the jsdom suites pin the slot dispatch, error states, details resolution, and index reference stability.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note：Code Mode 的 chat 渲染——子调用作为父行之下的原生行
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-26-code-mode-chat-subcall-rows.md) | 中文
|
||||
|
||||
> 范围：web chat 视图如何渲染一个 `run_code` 轮次，即 Code Mode UI 堆叠 PR（Pull Request）链的 client 侧一半，构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)之上（携带完整内容的 `tool/code-dispatch`、必填的 `description` 参数）。本篇所依托的 slot 模型归 [toolview 溶解](../architecture/2026-07-23-toolview-dissolution.md)所有。
|
||||
|
||||
## 问题
|
||||
|
||||
启用 Code Mode 后，chat 视图过去只显示一条不透明的 `run_code` 行：摘要就是原始程序文本，子调用则处处不可见。已敲定的产品要求恰恰相反：每个子调用都必须与原生工具调用渲染得*完全一致*——同样的行组件、同样的自定义注册、同样的 details 面板——同时 transcript（文本记录）仍须如实反映模型只发起了一次调用这一事实。
|
||||
|
||||
## 决策
|
||||
|
||||
**子调用是 surface 流之外单独索引的 `ToolResultNode`，经由与原生行相同的 keyed slot 渲染，以始终可见的方式嵌套在父行之下。**
|
||||
|
||||
- **数据层**：`Session.applyEventSideEffects` 把窗口内的每条 `tool/code-dispatch` 折入 `ConversationSnapshot.codeDispatches: ReadonlyMap<parentCallId, readonly CodeSubCall[]>`，其中 `CodeSubCall` 本身就是 `ToolResultNode`（子调用 id 充当 `callId`，已记录的参数经 JSON 字符串化写入 `call.argsRaw`，完整记录的 `content`/`isError` 原样携带）。live mux 帧与历史回放构建出同一份索引（`rebuildDerivedFromWindow` 先清空再重新推导；逐父级的写时复制（copy-on-write）数组保持快照引用 memo 稳定）。子调用永不进入 `nodes`——surface 流始终精确等于模型可见的轮次结构。该事件在 wire 消费方边界作结构性收窄（dsh-tools 的 host 类型进不了 client 程序——host/client 两侧的 `Context` 声明合并会冲突），姿态与所有跨 wire 载荷一致。
|
||||
- **渲染层**：`ChatView` 的 `CallRow` 先渲染父行，随后对索引中出现的父级渲染一组 `[data-subcalls]` 嵌套的 `SubCallRow`，每一行都经由同一个 `'conversation.chat.toolview'` keyed 孔位、以 `entryKey = sub-tool name` 分发，并共用同一个 `GenericToolCard` fallback。与原生行的同一性由构造保证：一个 keyed 注册（例如 bash 样例）接管子行与接管顶层行的方式完全相同，注册本身零改动。运行中的父调用（`runningCalls`）也以同样的方式嵌套目前已产生的分发，因此子行在运行期间实时流入（PR1 在每次分发完成时即记录该分发）。
|
||||
- **`run_code` 的呈现**：新增一种 `code` 行变体（分类器映射 `run_code → code`、标题 `Code`、图标 `IconCodeOutline16`），以模型撰写的 `description` 作摘要，展开后显示程序本身（在 markdown 代码块的填充底色上以等宽字体呈现），而非参数的 JSON 信封。
|
||||
- **details 面板**：`materialFor` 按 nodes → runningCalls → 分发索引的顺序逐级回落，因此被选中的子调用 callId 会经由与已完结的原生调用完全相同的渲染路径，解析出完整参数与完整输出。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**把子调用平铺进 surface 流（折入 `nodes`）。** 否决：这会歪曲 transcript——模型只发起了一次调用；嵌套在父行之下既保住代码↔调用的关联，也让 fold 的模型可见顺序不变式原封不动。
|
||||
|
||||
**隐藏子调用，展开父行后才显示。** 由产品决策否决：子调用正是一个 Code Mode 轮次的核心内容；把它们藏起来，等于重新制造出本功能所要消除的那种不透明。父行的展开开关只用于显示程序本身。
|
||||
|
||||
**专用的子调用行组件。** 否决：本功能的全部要义就在于与原生行保持同一性；一个平行组件必然漂移。嵌套包装层（缩进 + 左侧边线）是子调用唯一的专属 chrome。
|
||||
|
||||
## 后果
|
||||
|
||||
自定义 toolview 注册免费适用于子调用——而且是刻意为之：不存在按注册粒度的 opt-out，唯一的出路是组件自行读取自身上下文，而当前没有任何消费方需要这么做。选中高亮经由同一条 `selectedCallId` 通道到达嵌套行（分组归属判断会同时检验两个层级）。trajectory/waterfall 仍把 `run_code` 渲染为单独一行——它们的子调用 span 推迟到增加分发计时（start/end 事件）的那个 PR；缺少计时，waterfall 上的 span 就是在撒谎。fixture（测试前置数据）的轮次 64（`?fixture`），加上 `code-mode-round` 浏览器 e2e（录制的真实 round、无密钥回放），共同锁定整个表面；jsdom 套件则锁定 slot 分发、错误状态、details 解析与索引引用稳定性。
|
||||
@@ -0,0 +1,6 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write
|
||||
2026-07-26-code-mode-live-parallel-dispatch.md: b4afc21be902d8ed3e5bee2ad1a540413a864f25
|
||||
2026-07-26-code-mode-live-parallel-dispatch.zh.md: 409e4cbf9ea3d1b4d1bbe0cd86b494429ebb8a3d
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note: Code Mode live dispatch lifecycle and native-contract parallelism
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-26-code-mode-live-parallel-dispatch.zh.md)
|
||||
|
||||
> Scope: the third PR of the Code Mode UI stack — the `tool/code-dispatch-start` event, per-sub-call running state in the web chat, and the bridge's scheduler reusing the native concurrency contract. Builds on the [host foundation](2026-07-26-code-dispatch-ui-foundation.md) and [chat sub-call rows](2026-07-26-code-mode-chat-subcall-rows.md); the native contract itself is owned by the [parallel tool-call note](2026-07-10-parallel-tool-call-execution.md).
|
||||
|
||||
## Problem
|
||||
|
||||
Two gaps remained after the first two PRs. Sub-call rows appeared only when each dispatch *settled* — while one ran, the UI showed nothing for it, so a slow sub-call read as a stalled parent. And the bridge serialized every binding call ("even `Promise.all` executes one at a time"), a placeholder from before tools carried concurrency metadata: `isConcurrencySafe` now exists, the loop scheduler already runs native siblings in bounded pools, and a Code Mode program awaiting three independent reads paid 3× the latency the native path would.
|
||||
|
||||
## Decision
|
||||
|
||||
**One lifecycle pair, one scheduling contract, shared with native.**
|
||||
|
||||
- **Event pair**: `tool/code-dispatch-start` (parent/sub ids, name, normalized args) is appended when the scheduler actually starts a call — not at submission, so a queued call abandoned by run settlement logs nothing. The existing `tool/code-dispatch` settles the pair (same `subCallId`); every started call settles exactly once (aborts settle as `isError` outcomes through the pipeline). Timing = the two events' `time` fields. Both stay log-only; model context is untouched; format stays v0.
|
||||
- **Bridge scheduler**: submitted calls are classified at start time via `registry.executionMode` (the SAME fail-closed `isConcurrencySafe` contract the loop uses) and start strictly in submission order. One single-lane driver owns every ORDERED stage — the start append, `prepare` (pre-execute/guards), the head-of-line `finalize`/`finish` commit (post-execute + context deferral + settle append) — so ordered policy stages never overlap each other and only the around-dispatch/body stage runs concurrently, exactly the native loop's sequencing (`fillPool` awaits `startCall` then `commitReady`). Consecutive parallel-classified calls overlap up to `maxParallelSubCalls` (a `Config` field validated by the Loader schema AND re-validated at direct construction, default 10 — the loop scheduler's own default; `1` restores serial dispatch); an exclusive call drains the pool, runs alone, and holds its barrier until its COMMIT completes (post-execute included), like a native exclusive group. Run settlement aborts in-flight dispatches and abandons queued-unstarted ones (binding rejection, no events), then drains to quiescence — including a commit already mid-flight when the program returned — before the outer result closes the turn.
|
||||
- **Client**: `CodeSubCall` widens to `RunningToolCall | ToolResultNode` — a start event lands the running shape in the dispatch index (rows derive the running ring from the shape, exactly as for native in-flight calls), and its settle replaces the entry in place, preserving start order under parallel completion and carrying the start's `time` as `callTime` (duration source). A settle with no observed start (window cut mid-pair, or a pre-start-event log) appends directly, so old logs keep rendering.
|
||||
- **SDK prompt**: the model-facing "calls execute sequentially" sentence is replaced with the true contract (independent safe calls may overlap under `Promise.all`; dependent work sequences with `await`) — a model-visible change, re-recorded across every code-mode snapshot.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**Unrestricted parallelism (let `Promise.all` overlap everything).** Rejected: writes could race; the native scheduler exists precisely because the tool, not the caller, owns the safety claim. One concurrency vocabulary across native and Code Mode was the settled requirement.
|
||||
|
||||
**Emit the start event at submission instead of pool entry.** Rejected: a submission-time start would show queued-but-never-run calls as "running" and would force a third "abandoned" terminal event to reconcile the log. Start-at-entry keeps the invariant *started ⇔ settles exactly once* and needs no third event.
|
||||
|
||||
**Reuse the loop scheduler's implementation directly.** Rejected: the loop schedules a fully-parsed batch with model-order result commitment; the bridge schedules an open-ended stream of submissions whose results return to the program (not the transcript), so only the *contract* (classification, pool, barriers) is shared, not the machinery.
|
||||
|
||||
## Consequences
|
||||
|
||||
Programs get native-grade latency for independent reads with no new model-side API — `Promise.all` simply works better, and prompt guidance changed accordingly. The web UI shows per-sub-call running rings live (fixture emits start/settle pairs; jsdom pins the running shape; the runtime spec pins in-place settlement, out-of-order completion, and callTime pairing). PR6 (trajectory/waterfall spans) can now draw truthful spans from the pair's timing. The spill PR (next) inherits the settle event as its single bounding point.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Agent Note：Code Mode 的实时分发生命周期，以及复用原生契约的并行执行
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-26-code-mode-live-parallel-dispatch.md) | 中文
|
||||
|
||||
> 范围：Code Mode UI 堆叠 PR（Pull Request）链的第三个 PR，涵盖 `tool/code-dispatch-start` 事件、web chat 中每个子调用的运行状态，以及桥接层调度器对原生并发契约的复用。构建在[宿主侧基础](2026-07-26-code-dispatch-ui-foundation.md)与 [chat 子调用行](2026-07-26-code-mode-chat-subcall-rows.md)之上；原生契约本身归[并行工具调用 Agent Note](2026-07-10-parallel-tool-call-execution.md) 所有。
|
||||
|
||||
## 问题
|
||||
|
||||
前两个 PR 之后仍留有两个缺口。子调用行过去只在每次分发*结算*（settle）后才出现：某次分发运行期间，UI 对它毫无展示，于是一个慢的子调用看上去就像父调用卡住了。而桥接层过去把每一次绑定调用都串行化（「即使 `Promise.all` 也一次只执行一个」），这是工具尚未携带并发元数据时留下的占位实现：如今 `isConcurrencySafe` 已经存在，agent loop（智能体循环）调度器早已在有界并发池中运行原生兄弟调用，而一个等待三个独立读取的 Code Mode 程序，付出的延迟却是原生路径的 3 倍。
|
||||
|
||||
## 决策
|
||||
|
||||
**一对生命周期事件，一份调度契约，与原生共用。**
|
||||
|
||||
- **事件对**：`tool/code-dispatch-start`（父/子 id、名称、规范化参数）在调度器真正启动某个调用时才追加，而非在提交时，因此因 run 结算而被放弃的排队调用不会留下任何日志。既有的 `tool/code-dispatch` 结算该事件对（`subCallId` 相同）；每个已启动的调用恰好结算一次（中止也会作为 `isError` 结果经由流水线结算）。计时即这两个事件的 `time` 字段。两个事件都保持仅日志；模型上下文不受影响；格式保持 v0。
|
||||
- **桥接层调度器**：已提交的调用在启动那一刻经 `registry.executionMode` 分类（与 loop 所用完全相同的 fail-closed `isConcurrencySafe` 契约），并严格按提交顺序启动。所有有序阶段——start 事件追加、`prepare`（pre-execute/守卫）、队首 `finalize`/`finish` 提交（post-execute + 上下文延迟提交 + settle 事件追加）——由单一驱动车道独占执行，因此有序策略阶段彼此绝不重叠，只有 around-dispatch/工具体阶段并发运行，与原生 loop 的时序完全一致（`fillPool` 先 await `startCall` 再 `commitReady`）。连续被分类为可并行的调用可以重叠执行，上限为 `maxParallelSubCalls`（`Config` 字段，Loader schema 校验之外直接构造时也重新校验，默认值 10，即 loop 调度器自身的默认值；设为 `1` 即恢复串行分发）；独占调用则先排空池、独自运行，且其屏障保持到自身提交（含 post-execute）完成为止，与原生独占分组一致。run 结算时会中止仍在运行的分发，并放弃已排队未启动的分发（绑定调用被拒绝，不产生事件），随后排空到完全停稳——包括程序返回时已在途的提交——之后外层结果才结束该轮次。
|
||||
- **client 侧**：`CodeSubCall` 拓宽为 `RunningToolCall | ToolResultNode`：start 事件把运行中形状写入分发索引（行组件从该形状推导出运行指示环，与原生运行中的调用处理完全一致），其结算事件则原位替换该条目，即使并行完成也保持启动顺序不变，并把 start 事件的 `time` 作为 `callTime`（时长来源）带入。未观察到对应 start 的结算事件（窗口切在事件对中间，或日志录制于 start 事件引入之前）会直接追加，因此旧日志仍能照常渲染。
|
||||
- **SDK 提示词**：面向模型的「调用按顺序执行」一句替换为真实契约（相互独立的安全调用可以在 `Promise.all` 下重叠执行；相互依赖的工作以 `await` 顺序衔接）；这是模型可见的变更，每一份 code-mode 快照都已重新录制。
|
||||
|
||||
## 曾考虑的替代方案
|
||||
|
||||
**不加限制的并行（让 `Promise.all` 重叠一切）。** 否决：写操作可能产生竞态；原生调度器之所以存在，正是因为安全性声明归工具所有，而不归调用方。原生与 Code Mode 使用同一套并发词汇，是已敲定的要求。
|
||||
|
||||
**在提交时而非入池时发出 start 事件。** 否决：提交即发 start 会把排了队却从未运行的调用显示成「运行中」，还得强行引入第三种「已放弃」终态事件才能使日志自洽。入池才发 start 保住了*已启动 ⇔ 恰好结算一次*这一不变式，且不需要第三种事件。
|
||||
|
||||
**直接复用 loop 调度器的实现。** 否决：loop 调度的是一个完整解析好的批次，并按模型顺序提交结果；桥接层调度的则是一条开放式的提交流，其结果返回给程序，而不是进入 transcript（文本记录）。因此两者共享的只是*契约*（分类、池、屏障），而不是实现机制。
|
||||
|
||||
## 后果
|
||||
|
||||
程序不需要任何新的模型侧 API，独立读取就获得了原生级的延迟：`Promise.all` 直接变得更好用，提示词指引也随之修改。web UI 实时显示每个子调用的运行指示环：fixture（测试前置数据）发出成对的 start/settle 事件；jsdom 锁定运行中形状；运行时 spec 锁定原位结算、乱序完成与 callTime 配对。PR6（trajectory/waterfall 的 span）现在可以依据这对事件的计时绘制如实的 span。spill PR（下一个）则继承结算事件，作为自己唯一施加边界的位置。
|
||||
Reference in New Issue
Block a user