From 99a9fa850911580f625932aa272fe7c77c115a91 Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 26 Jul 2026 10:18:53 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20address=20review=20=E2=80=94=20python=20?= =?UTF-8?q?smoke=20caller,=20contract=20prose,=20fixture=20header=20hygien?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ds-review-bot findings: the packaged Python runtime smoke's scripted run_code call gains the required description; the ToolDefinition JSDoc and the Code Mode foundation note (both languages, pair re-recorded) now state both required parameters; the cordis-dynamic-toolchain fixture's request/header line is re-compacted so the header-scrub hygiene guard passes (my earlier patch had re-spaced it). The TUI terminal fixture was already regenerated from keyless replay in the previous commit. --- .../implemented/feature/2026-06-15-code-mode.i18n.yaml | 4 ++-- .agents/notes/implemented/feature/2026-06-15-code-mode.md | 2 +- .../notes/implemented/feature/2026-06-15-code-mode.zh.md | 2 +- packages/core/tools/src/code-mode.ts | 5 +++-- scripts/smoke-python-runtime.py | 6 +++++- 5 files changed, 12 insertions(+), 7 deletions(-) diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml index e04e95c817..b8e6c78b6a 100644 --- a/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml +++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write -2026-06-15-code-mode.md: 33b8dc6a27c1cc12962f75e1211996dba6f81496 -2026-06-15-code-mode.zh.md: db03ca10edbc7fa826ed991df26847aa9271b731 +2026-06-15-code-mode.md: be5e29fdafd72c54d5801cc29597a27f401e4872 +2026-06-15-code-mode.zh.md: 55b47cc93bd953a610b5e2d9167e5d3cba1ed90e diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.md index 33b8dc6a27..be5e29fdaf 100644 --- a/.agents/notes/implemented/feature/2026-06-15-code-mode.md +++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.md @@ -40,7 +40,7 @@ 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` with 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. diff --git a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md index db03ca10ed..55b47cc93b 100644 --- a/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md +++ b/.agents/notes/implemented/feature/2026-06-15-code-mode.zh.md @@ -40,7 +40,7 @@ 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`。每个子调用保留自己不可变的执行标识，并遍历完整的工具流水线。 2. **运行程序**：`ctx.codeRuntime.run({ program: args.code, bindings: [{ global: 'tools', functions }], signal: runController.signal })`。运行时接收的是 run 级别的 signal 而非仅调用方的外层 signal，因此外层 run 以任何方式结算都会同时 abort 运行时内部的工作。 diff --git a/packages/core/tools/src/code-mode.ts b/packages/core/tools/src/code-mode.ts index 7ac2e267a5..afa09a3e32 100644 --- a/packages/core/tools/src/code-mode.ts +++ b/packages/core/tools/src/code-mode.ts @@ -170,8 +170,9 @@ function renderValue(value: JsonValue): string { type RunCodeOutput = { logs: string[]; result?: JsonValue } /** - * Build the `run_code` {@link ToolDefinition}: one required `code` parameter, - * executed through the dispatch bridge described above. The + * Build the `run_code` {@link ToolDefinition}: required `code` and + * `description` parameters, executed through the dispatch bridge described + * above. The * registry reserves it as presentation infrastructure under non-native modes, * outside the filterable global/scoped capability layers. * @param registry - the owning registry (sub-calls go through its `execute`, diff --git a/scripts/smoke-python-runtime.py b/scripts/smoke-python-runtime.py index 6d8890aa2e..d575db8b01 100644 --- a/scripts/smoke-python-runtime.py +++ b/scripts/smoke-python-runtime.py @@ -151,7 +151,11 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]: ) if prompt == CODE_PROMPT: assert_advertised_tool(body, "run_code") - return tool_call_chunks("call-code-worker", "run_code", {"code": "return 6 * 7"}) + return tool_call_chunks( + "call-code-worker", + "run_code", + {"code": "return 6 * 7", "description": "Compute the smoke value"}, + ) if prompt == WORKFLOW_PROMPT: assert_advertised_tool(body, "workflow") return tool_call_chunks(