diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
index 4573f0a33f..e4b4714af1 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.i18n.yaml
@@ -24,8 +24,8 @@
en: 26e4b71366bebd1b
zh: 10598e12b28c586e
/agent-note-cooperative-tool-cancellation-at-the-registry-boundary/verification:
- en: fbd101d4576afa92
- zh: 35f5d3c2f6cad6a8
+ en: 983da6d0c09f5c10
+ zh: ca7c86117a1a4d5f
/agent-note-cooperative-tool-cancellation-at-the-registry-boundary/alternatives-considered:
en: c4d86feb135d2ac4
zh: 67c56c0bc2213949
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
index 967c7285df..8ad0af1d21 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md
@@ -46,7 +46,7 @@ This decision requires cancellation at the tool invocation boundary only. Making
## Verification
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`ptc.spec.ts`](../../../../packages/core/tools/tests/ptc.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) proves the required exact signal types, readonly observer and tool views, mutable-but-required around-dispatch view, and `defineTool()` inference. [`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) covers pre-aborted materialization, phase skipping, policy and wrapper races, body invocation classification, caller-signal fusion, error precedence, context retention, and quiescent drainage. [`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) and [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) cover balanced durable results for undispatched siblings. [`ptc.spec.ts`](../../../../packages/core/tool-executor-ptc/tests/ptc.spec.ts) and first-party integration suites cover explicit forwarding, while [`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) preserves timeout ownership.
No registry test can prove that arbitrary third-party same-process code observes the signal or stops in bounded time. Capability tests continue to prove cancellation and quiescence at the boundary that owns each side effect.
diff --git a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
index 87318c3316..613db6dacd 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md
@@ -46,7 +46,7 @@ Status: implemented
## 验证
-[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`ptc.spec.ts`](../../../../packages/core/tools/tests/ptc.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
+[`execution-signal-types.spec.ts`](../../../../packages/core/tools/tests/execution-signal-types.spec.ts) 证明必填的精确信号类型、观察者与工具的只读视图、环绕调度可替换但不可删除的视图，以及 `defineTool()` 推断。[`tools.spec.ts`](../../../../packages/core/tools/tests/tools.spec.ts) 覆盖进入时已中止的物化与阶段跳过、策略和包装层竞态、工具主体调用分类、调用方信号融合、错误优先级、上下文保留和完全停稳。[`tool-calls.spec.ts`](../../../../packages/core/agent-loop/tests/tool-calls.spec.ts) 与 [`contract-regressions.spec.ts`](../../../../packages/core/agent-loop/tests/contract-regressions.spec.ts) 覆盖为未调度的同批调用补齐持久化结果。[`ptc.spec.ts`](../../../../packages/core/tool-executor-ptc/tests/ptc.spec.ts) 和第一方集成测试覆盖显式转发，[`timeout-policy.spec.ts`](../../../../packages/guard/timeout-policy/tests/timeout-policy.spec.ts) 保持超时归属。
任何注册表测试都无法证明任意第三方同进程代码会观察信号或在有界时间内停止。各能力的测试仍需在拥有相应副作用的边界证明取消与完全停稳。
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 8b2cfb83ab..5d8a09e34d 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -188,6 +188,10 @@ flowchart LR
cfg --> plugin_dsh_base_mcp_resources
plugin_dsh_base_tools["tools
@deepseek-ai/dsh-tools"]
cfg --> plugin_dsh_base_tools
+ plugin_dsh_base_tool_executor_native["tool-executor-native
@deepseek-ai/dsh-tool-executor-native"]
+ cfg --> plugin_dsh_base_tool_executor_native
+ plugin_dsh_base_tool_executor_ptc["tool-executor-ptc
@deepseek-ai/dsh-tool-executor-ptc"]
+ cfg --> plugin_dsh_base_tool_executor_ptc
plugin_dsh_base_system_prompt["system-prompt
@deepseek-ai/dsh-system-prompt"]
cfg --> plugin_dsh_base_system_prompt
plugin_dsh_base_agent_loop["agent-loop
@deepseek-ai/dsh-agent-loop"]
@@ -292,6 +296,8 @@ flowchart LR
| `tool-web` | `@deepseek-ai/dsh-tool-web` |
| `mcp-resources` | `@deepseek-ai/dsh-mcp-resources` |
| `tools` | `@deepseek-ai/dsh-tools` |
+| `tool-executor-native` | `@deepseek-ai/dsh-tool-executor-native` |
+| `tool-executor-ptc` | `@deepseek-ai/dsh-tool-executor-ptc` |
| `system-prompt` | `@deepseek-ai/dsh-system-prompt` |
| `agent-loop` | `@deepseek-ai/dsh-agent-loop` |
| `fs-sandbox` | `@deepseek-ai/dsh-fs-sandbox` |
diff --git a/docs/architecture.i18n.yaml b/docs/architecture.i18n.yaml
index 8206f3e6dc..946d6448a0 100644
--- a/docs/architecture.i18n.yaml
+++ b/docs/architecture.i18n.yaml
@@ -24,8 +24,8 @@
en: e89802f066e4955d
zh: ea2fb4bef94e086d
/deepseek-harness-architecture/turn-flow:
- en: e6402b28c0ed15fa
- zh: 6c07be9047b42056
+ en: 5ba2d921295f4254
+ zh: a09fa21b8882fb25
/deepseek-harness-architecture/session-log:
en: a2e35c43438fec6d
zh: e27bdac8e9feff32
diff --git a/docs/architecture.md b/docs/architecture.md
index 03d88148c7..689f29c75d 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -115,6 +115,8 @@ Failed steps [record missing tool results](../packages/core/agent-loop/README.md
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).
+[`ctx.tools.execute()`](subsystems/tools.md) receives raw batches and concurrency limits.
+
## Session log
The session log is the source of the context the model sees. `deriveMessages()` projects model history from it. Each `assistant/message` embeds the exact compact timed stream that produced its assembled content; `assistant/attempt` retains settled failed, retried, cancelled, and stream-error attempts without adding model history. Fork, resume, transcripts, telemetry, and persistence all derive from these durable settlements, while live UI incrementality comes from `agent/assistant-stream`; a hard process loss before settlement leaves no durable attempt stream ([decision](../.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.md)).
diff --git a/docs/architecture.zh.md b/docs/architecture.zh.md
index 870fa1c996..2abbb78807 100644
--- a/docs/architecture.zh.md
+++ b/docs/architecture.zh.md
@@ -119,6 +119,8 @@ turn/end
详情见[时序图](agent-lifecycle.zh.md)、[工具流水线](tool-execution-pipeline.zh.md)和[取消与错误恢复](subsystems/core.zh.md#the-agent-handle)。
+[`ctx.tools.execute()`](subsystems/tools.zh.md) 接收原始调用批次和并发上限。
+
## 会话日志
会话日志是模型所见上下文的来源。`deriveMessages()` 从中投影出模型历史。每个 `assistant/message` 都嵌入产生其组装内容的精确紧凑带时间 stream；`assistant/attempt` 保留已到达 settlement 的失败、重试、取消与 stream error attempt，且不添加模型历史。fork、恢复、transcript（文本记录）、遥测与持久化都从这些持久 settlement 派生，实时 UI 增量则来自 `agent/assistant-stream`；如果进程在 settlement 前硬中断，则不会留下持久 attempt stream（见[决策](../.agents/notes/implemented/architecture/2026-09-01-v2-embedded-assistant-streams.zh.md)）。
diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml
index 25b949f17a..424c721d6c 100644
--- a/docs/capability-seams.i18n.yaml
+++ b/docs/capability-seams.i18n.yaml
@@ -6,5 +6,5 @@
en: 41d772192075e133
zh: 5ef3da69b4de1d8a
/capability-seams-and-core-services:
- en: 048c8c150734d0dd
- zh: 836dd6c78d4c8278
+ en: 28ab205d66a38193
+ zh: 290cacfdc1cb6eab
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index dce33aa090..3933b5ea6f 100644
--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -162,7 +162,7 @@ flowchart LR
pkg_tools["tools"]
pkg_tool_terminal["tool-terminal"]
pkg_tool_web["tool-web"]
- svc_tools["ctx.tools
Tool registry and guarded execution pipeline"]
+ svc_tools["ctx.tools
Scoped tool registry and executor selection"]
pkg_tool_ask_user["tool-ask-user"]
pkg_tool_cordis["tool-cordis"]
pkg_tool_skill["tool-skill"]
@@ -232,6 +232,7 @@ flowchart LR
svc_ptcRuntime["ctx.ptcRuntime
PTC execution seam"]
pkg_ptc_runtime_node["ptc-runtime-node"]
pkg_experimental_ptc_runtime_python["experimental-ptc-runtime-python"]
+ pkg_tool_executor_ptc["tool-executor-ptc"]
pkg_workflow_ptc["workflow-ptc"]
pkg_fs["fs"]
svc_fs["ctx.fs
Filesystem provider seam"]
@@ -507,7 +508,7 @@ flowchart LR
svc_pluginMarket --> pkg_plugin_market
svc_pluginRegistryProbe --> pkg_client_ui_plugin_manager
svc_profileContext --> pkg_plugin_manager
- svc_ptcRuntime --> pkg_tools
+ svc_ptcRuntime --> pkg_tool_executor_ptc
svc_ptcRuntime --> pkg_workflow_ptc
svc_remoteAccess --> pkg_api_gateway
svc_remoteAccess --> pkg_api_session_controller
@@ -666,7 +667,7 @@ flowchart LR
| `ctx.sessionReferenceResolver` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax. |
| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm), [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | - | - | Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration. |
| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/shell/tool-bash), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities, owns PTC mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/shell/tool-bash), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | Registers capabilities and scoped executors. Native and PTC providers own descriptions and complete raw call batches; their optional shared pipeline handles tool policy and dispatch. |
| `ctx.userQuestions` | `seam` | [`user-questions`](../packages/interaction/user-questions) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI front ends provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
| `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions. |
| `ctx.agentPresets` | `core` | [`agent-preset-registry`](../packages/preset/agent-preset-registry) | - | - | - | Eagerly mounts YAML-declared preset revisions, binds Agents and cold readers to scoped contributions, and retains retired revisions until their last user releases them. |
@@ -688,7 +689,7 @@ flowchart LR
| `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/shell/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots. |
| `ctx.approval` | `seam` | [`user-approval`](../packages/interaction/user-approval) | - | [`tools`](../packages/core/tools), [`tool-bash`](../packages/shell/tool-bash), [`acp`](../packages/acp/acp) | - | One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`. |
| `ctx.permissionPresets` | `core` | [`permission-presets`](../packages/interaction/permission-presets) | - | - | - | User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events. |
-| `ctx.ptcRuntime` | `seam` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime) | [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | [`tools`](../packages/core/tools), [`workflow-ptc`](../packages/workflow/workflow-ptc) | - | Runs programs against host-provided async bindings; tools owns PTC presentation and workflow-ptc owns workflow orchestration. |
+| `ctx.ptcRuntime` | `seam` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime) | [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`workflow-ptc`](../packages/workflow/workflow-ptc) | - | Runs programs against host-provided async bindings; tool-executor-ptc owns PTC presentation and workflow-ptc owns workflow orchestration. |
| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-ssh`](../packages/ssh/fs-ssh) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-observation-policy contributes observed-state checks through the fs/* event gate. |
| `ctx.compaction` | `seam` | [`compaction`](../packages/compaction/compaction) | [`compaction-basic`](../packages/compaction/compaction-basic) | [`compaction-basic`](../packages/compaction/compaction-basic) | - | The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool. |
| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/experimental/tool-ralph) | - | Providers prepare local children or execute external tasks; one activation manager owns both lifecycles. The delegation tool selects a backend, control tools deliver local follow-ups, and workflows await activation results. |
diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md
index 20f165490d..e97dfabc60 100644
--- a/docs/capability-seams.zh.md
+++ b/docs/capability-seams.zh.md
@@ -164,7 +164,7 @@ flowchart LR
pkg_tools["tools"]
pkg_tool_terminal["tool-terminal"]
pkg_tool_web["tool-web"]
- svc_tools["ctx.tools
Tool registry and guarded execution pipeline"]
+ svc_tools["ctx.tools
Scoped tool registry and executor selection"]
pkg_tool_ask_user["tool-ask-user"]
pkg_tool_cordis["tool-cordis"]
pkg_tool_skill["tool-skill"]
@@ -234,6 +234,7 @@ flowchart LR
svc_ptcRuntime["ctx.ptcRuntime
PTC execution seam"]
pkg_ptc_runtime_node["ptc-runtime-node"]
pkg_experimental_ptc_runtime_python["experimental-ptc-runtime-python"]
+ pkg_tool_executor_ptc["tool-executor-ptc"]
pkg_workflow_ptc["workflow-ptc"]
pkg_fs["fs"]
svc_fs["ctx.fs
Filesystem provider seam"]
@@ -509,7 +510,7 @@ flowchart LR
svc_pluginMarket --> pkg_plugin_market
svc_pluginRegistryProbe --> pkg_client_ui_plugin_manager
svc_profileContext --> pkg_plugin_manager
- svc_ptcRuntime --> pkg_tools
+ svc_ptcRuntime --> pkg_tool_executor_ptc
svc_ptcRuntime --> pkg_workflow_ptc
svc_remoteAccess --> pkg_api_gateway
svc_remoteAccess --> pkg_api_session_controller
@@ -668,7 +669,7 @@ flowchart LR
| `ctx.sessionReferenceResolver` | `core` | [`session-reference`](../packages/context/session-reference) | - | - | - | 将当前表层中有界的对话快照投影为持久但不可信的消息上下文；Host 适配器负责提及语法。 |
| `ctx.sessionTitle` | `seam` | [`session-title`](../packages/session/session-title) | [`session-title-first-prompt-llm`](../packages/session/session-title-first-prompt-llm), [`session-title-all-prompts-llm`](../packages/experimental/session-title-all-prompts-llm) | - | - | 负责确定性回退、最新标题折叠区，以及唯一的可选异步提供方注册。 |
| `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-web`](../packages/web/tool-web) | - | 为每个步骤收集提示词各部分和面向模型的工具 schema。 |
-| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/shell/tool-bash), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | 注册能力，负责 PTC mode 传输，并让调用依次经过策略前处理、单调守卫、环绕分派、策略后处理和最终结果观测。 |
+| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/interaction/tool-ask-user), [`tool-bash`](../packages/shell/tool-bash), [`tool-cordis`](../packages/extensions/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-terminal`](../packages/experimental/tool-terminal), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web) | - | 注册能力和作用域执行器。原生与 PTC 提供者负责工具描述及完整原始调用批次；它们可选用共享流水线处理工具策略和分发。 |
| `ctx.userQuestions` | `seam` | [`user-questions`](../packages/interaction/user-questions) | - | [`tool-ask-user`](../packages/interaction/tool-ask-user) | - | UI 前端提供当前生效的人工回答提供方；tool-ask-user 在提供方无关的 ask() promise 上暂停工具调用。 |
| `ctx.planMode` | `core` | [`plan-mode`](../packages/plan/plan-mode) | - | - | - | 折叠已记录的计划／模式状态，在轮次边界刷新用户选择，渲染由部署方拥有的指导信息，注册 /plan，并在状态转换期间保持计划退出 schema 稳定。 |
| `ctx.agentPresets` | `core` | [`agent-preset-registry`](../packages/preset/agent-preset-registry) | - | - | - | 立即挂载 YAML 声明的 preset 版本，把 Agent 和冷读取绑定到作用域内的贡献，并保留已替换的版本，直到最后一个使用者释放它。 |
@@ -690,7 +691,7 @@ flowchart LR
| `ctx.sandboxPolicy` | `core` | [`sandbox-policy`](../packages/sandbox/sandbox-policy) | - | [`bash-sandbox`](../packages/shell/bash-sandbox), [`fs-sandbox`](../packages/fs/fs-sandbox), [`terminal-bash`](../packages/terminal/terminal-bash) | - | 统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取该服务（工具层使用它同时导出的纯 `sandbox/mode` 折叠区）。两类强制执行组件都读取该服务，因此 bash 与 fs 不会限制到不同的根目录。 |
| `ctx.approval` | `seam` | [`user-approval`](../packages/interaction/user-approval) | - | [`tools`](../packages/core/tools), [`tool-bash`](../packages/shell/tool-bash), [`acp`](../packages/acp/acp) | - | 一次性权限决策通过 `approval/request` waterfall（瀑布式事件）分派；回答方是监听器（即 ACP 为自身 agent 提供的桥接），没有回答方时以 `unavailable` 关闭失败。 |
| `ctx.permissionPresets` | `core` | [`permission-presets`](../packages/interaction/permission-presets) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 |
-| `ctx.ptcRuntime` | `seam` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime) | [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | [`tools`](../packages/core/tools), [`workflow-ptc`](../packages/workflow/workflow-ptc) | - | 使用 Host 提供的异步绑定运行程序；tools 负责 PTC 呈现，workflow-ptc 负责工作流编排。 |
+| `ctx.ptcRuntime` | `seam` | [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime) | [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), [`experimental-ptc-runtime-python`](../packages/experimental/ptc-runtime-python) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`workflow-ptc`](../packages/workflow/workflow-ptc) | - | 使用 Host 提供的异步绑定运行程序；tool-executor-ptc 负责 PTC 呈现，workflow-ptc 负责工作流编排。 |
| `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`fs-ssh`](../packages/ssh/fs-ssh) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-observation-policy`](../packages/fs/fs-observation-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-observation-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 |
| `ctx.compaction` | `seam` | [`compaction`](../packages/compaction/compaction) | [`compaction-basic`](../packages/compaction/compaction-basic) | [`compaction-basic`](../packages/compaction/compaction-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 |
| `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn-in-process`](../packages/subagent/subagent-spawn-in-process), [`subagent-fork-in-process`](../packages/subagent/subagent-fork-in-process), [`subagent-acp`](../packages/subagent/subagent-acp), [`subagent-codex`](../packages/subagent/subagent-codex), [`subagent-claude-code`](../packages/subagent/subagent-claude-code), [`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-subagent-control`](../packages/subagent/tool-subagent-control), [`tool-ralph`](../packages/experimental/tool-ralph) | - | 提供方准备本地子级或执行外部任务；一个 activation 管理器持有两类生命周期。委派工具选择后端，控制工具投递本地后续消息，工作流等待 activation 结果。 |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 5240eec77a..d3ca9c0530 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -158,11 +158,13 @@ export interface Config {
## `@deepseek-ai/dsh-agent-tool-presentation`
- `inject`: `tools`
-- `refs`: [`ToolPresentationMode`](subsystems/tools.md)
-- `source`: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts)
+- `source`: [`packages/core/agent-tool-presentation/src/index.ts:26`](../packages/core/agent-tool-presentation/src/index.ts)
```ts config-catalog
-/** Plugin config. */
+/**
+ * Plugin config.
+ * @deprecated Select the native or PTC executor plugin directly instead of configuring a mode.
+ */
export interface Config {
/**
* The form this agent's model sees. `native` sends every visible schema,
@@ -171,7 +173,7 @@ export interface Config {
* without this row already gets, so an omitted value would mean the row was
* composed for nothing.
*/
- mode: ToolPresentationMode
+ mode: 'native' | 'ptc'
}
```
@@ -3173,7 +3175,7 @@ export interface Config {
## `@deepseek-ai/dsh-spill-policy`
- `inject`: `tools`
-- `source`: [`packages/spill/spill-policy/src/index.ts:25`](../packages/spill/spill-policy/src/index.ts)
+- `source`: [`packages/spill/spill-policy/src/index.ts:26`](../packages/spill/spill-policy/src/index.ts)
```ts config-catalog
/** Optional result-retention budget. */
@@ -3541,7 +3543,7 @@ export interface Config {
## `@deepseek-ai/dsh-system-prompt`
-- `source`: [`packages/core/system-prompt/src/index.ts:258`](../packages/core/system-prompt/src/index.ts)
+- `source`: [`packages/core/system-prompt/src/index.ts:260`](../packages/core/system-prompt/src/index.ts)
```ts config-catalog
/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.personaPrefix} for its contract). */
@@ -3752,6 +3754,44 @@ export interface Config {
```
+
+
+
+## `@deepseek-ai/dsh-tool-executor-native`
+
+- `inject`: `tools`
+- `refs`: `Volatile` (`@deepseek-ai/cosmokit`)
+- `source`: [`packages/core/tool-executor-native/src/index.ts:14`](../packages/core/tool-executor-native/src/index.ts)
+
+```ts config-catalog
+/** Native batch concurrency configuration. */
+export interface Config {
+ /** Maximum overlapping concurrency-safe calls in one batch. */
+ maxParallelToolCalls: Volatile
+}
+```
+
+
+
+
+
+## `@deepseek-ai/dsh-tool-executor-ptc`
+
+- `inject`: `tools` · `systemPrompt` · `ptcRuntime`
+- `refs`: `Volatile` (`@deepseek-ai/cosmokit`)
+- `source`: [`packages/core/tool-executor-ptc/src/index.ts:19`](../packages/core/tool-executor-ptc/src/index.ts)
+
+```ts config-catalog
+/** Program execution limits. */
+export interface Config {
+ /** Maximum overlapping concurrency-safe calls in one model batch. */
+ maxParallelToolCalls: Volatile
+ /** Maximum overlapping concurrency-safe program subcalls. */
+ maxParallelSubCalls?: number
+}
+```
+
+
@@ -4214,43 +4254,6 @@ export interface Config {
```
-
-
-
-## `@deepseek-ai/dsh-tools`
-
-- `inject`: `systemPrompt`
-- `source`: [`packages/core/tools/src/index.ts:675`](../packages/core/tools/src/index.ts)
-
-```ts config-catalog
-/** Plugin config: how the registered tools are presented to the model. */
-export interface Config {
- /**
- * Model presentation. `native` (default) sends every visible schema; `ptc`
- * sends only `run_code` plus a generated SDK prompt and collapses the
- * executor to the same surface (a model-direct call may only name
- * `run_code`; `run_code` SDK sub-dispatches keep every visible tool).
- * PTC mode requires a `ctx.ptcRuntime` whose `language`
- * has a registered SDK renderer (TypeScript or Python) and fails prompt
- * assembly when it is absent or has no renderer. Under `ptc`, native names
- * in `toolOrder` are invalid.
- */
- mode?: ToolPresentationMode
- /**
- * Concurrency cap for a `run_code` program's overlapping sub-calls
- * (default 10, the loop scheduler's own default). Sub-calls follow the
- * native scheduling contract — only calls whose tools classify
- * concurrency-safe overlap; exclusive calls form barriers — so `1`
- * restores strictly serial dispatch. Must be a positive integer.
- */
- maxParallelSubCalls?: number
-}
-
-/** How the registry presents its tools to the model (see {@link Config.mode}). */
-export type ToolPresentationMode = 'native' | 'ptc'
-```
-
-
@@ -4664,6 +4667,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
| `@deepseek-ai/dsh-tool-schedule` | `tools` | [`packages/schedule/tool-schedule/src/index.ts`](../packages/schedule/tool-schedule/src/index.ts) |
| `@deepseek-ai/dsh-tool-subagent-control` | `tools` · `subagents` | [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts) |
| `@deepseek-ai/dsh-tool-working-directory` | `tools` · `workingDirectory` | [`packages/session/tool-working-directory/src/index.ts`](../packages/session/tool-working-directory/src/index.ts) |
+| `@deepseek-ai/dsh-tools` | `systemPrompt` | [`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts) |
| `@deepseek-ai/dsh-user-questions` | — | [`packages/interaction/user-questions/src/index.ts`](../packages/interaction/user-questions/src/index.ts) |
| `@deepseek-ai/dsh-webhook` | `agents` · `agentDefaultModel` · `agentPresets` · `permissionPresets` · `sessionTitle` · `workspaceRegistry` | [`packages/experimental/webhook/src/index.ts`](../packages/experimental/webhook/src/index.ts) |
| `@deepseek-ai/dsh-workspace` | `storageDomain` · `sessionPersistence` | [`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts) |
@@ -4759,6 +4763,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
| `@deepseek-ai/dsh-session-title-llm` | — | [`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts) |
| `@deepseek-ai/dsh-ssh-helper-runtime` | — | [`packages/ssh/ssh-helper-runtime/src/index.ts`](../packages/ssh/ssh-helper-runtime/src/index.ts) |
| `@deepseek-ai/dsh-timeout` | — | [`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts) |
+| `@deepseek-ai/dsh-tool-testkit` | — | [`packages/test-support/tool-testkit/src/index.ts`](../packages/test-support/tool-testkit/src/index.ts) |
| `@deepseek-ai/dsh-typert-generator` | — | [`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts) |
| `@deepseek-ai/dsh-typert-protocol` | — | [`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts) |
| `@deepseek-ai/dsh-typert-registry` | — | [`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts) |
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index bf66626c51..92f4cb88fe 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -160,11 +160,13 @@ export interface Config {
## `@deepseek-ai/dsh-agent-tool-presentation`
- `inject`: `tools`
-- `refs`: [`ToolPresentationMode`](subsystems/tools.zh.md)
-- `source`: [`packages/core/agent-tool-presentation/src/index.ts:38`](../packages/core/agent-tool-presentation/src/index.ts)
+- `source`: [`packages/core/agent-tool-presentation/src/index.ts:26`](../packages/core/agent-tool-presentation/src/index.ts)
```ts config-catalog
-/** Plugin config. */
+/**
+ * Plugin config.
+ * @deprecated Select the native or PTC executor plugin directly instead of configuring a mode.
+ */
export interface Config {
/**
* The form this agent's model sees. `native` sends every visible schema,
@@ -173,7 +175,7 @@ export interface Config {
* without this row already gets, so an omitted value would mean the row was
* composed for nothing.
*/
- mode: ToolPresentationMode
+ mode: 'native' | 'ptc'
}
```
@@ -3175,7 +3177,7 @@ export interface Config {
## `@deepseek-ai/dsh-spill-policy`
- `inject`: `tools`
-- `source`: [`packages/spill/spill-policy/src/index.ts:25`](../packages/spill/spill-policy/src/index.ts)
+- `source`: [`packages/spill/spill-policy/src/index.ts:26`](../packages/spill/spill-policy/src/index.ts)
```ts config-catalog
/** Optional result-retention budget. */
@@ -3543,7 +3545,7 @@ export interface Config {
## `@deepseek-ai/dsh-system-prompt`
-- `source`: [`packages/core/system-prompt/src/index.ts:258`](../packages/core/system-prompt/src/index.ts)
+- `source`: [`packages/core/system-prompt/src/index.ts:260`](../packages/core/system-prompt/src/index.ts)
```ts config-catalog
/** Plugin config: the deployment-authored fragment of the system prompt (see {@link Config.personaPrefix} for its contract). */
@@ -3754,6 +3756,44 @@ export interface Config {
```
+
+
+
+## `@deepseek-ai/dsh-tool-executor-native`
+
+- `inject`: `tools`
+- `refs`: `Volatile` (`@deepseek-ai/cosmokit`)
+- `source`: [`packages/core/tool-executor-native/src/index.ts:14`](../packages/core/tool-executor-native/src/index.ts)
+
+```ts config-catalog
+/** Native batch concurrency configuration. */
+export interface Config {
+ /** Maximum overlapping concurrency-safe calls in one batch. */
+ maxParallelToolCalls: Volatile
+}
+```
+
+
+
+
+
+## `@deepseek-ai/dsh-tool-executor-ptc`
+
+- `inject`: `tools` · `systemPrompt` · `ptcRuntime`
+- `refs`: `Volatile` (`@deepseek-ai/cosmokit`)
+- `source`: [`packages/core/tool-executor-ptc/src/index.ts:19`](../packages/core/tool-executor-ptc/src/index.ts)
+
+```ts config-catalog
+/** Program execution limits. */
+export interface Config {
+ /** Maximum overlapping concurrency-safe calls in one model batch. */
+ maxParallelToolCalls: Volatile
+ /** Maximum overlapping concurrency-safe program subcalls. */
+ maxParallelSubCalls?: number
+}
+```
+
+
@@ -4216,43 +4256,6 @@ export interface Config {
```
-
-
-
-## `@deepseek-ai/dsh-tools`
-
-- `inject`: `systemPrompt`
-- `source`: [`packages/core/tools/src/index.ts:675`](../packages/core/tools/src/index.ts)
-
-```ts config-catalog
-/** Plugin config: how the registered tools are presented to the model. */
-export interface Config {
- /**
- * Model presentation. `native` (default) sends every visible schema; `ptc`
- * sends only `run_code` plus a generated SDK prompt and collapses the
- * executor to the same surface (a model-direct call may only name
- * `run_code`; `run_code` SDK sub-dispatches keep every visible tool).
- * PTC mode requires a `ctx.ptcRuntime` whose `language`
- * has a registered SDK renderer (TypeScript or Python) and fails prompt
- * assembly when it is absent or has no renderer. Under `ptc`, native names
- * in `toolOrder` are invalid.
- */
- mode?: ToolPresentationMode
- /**
- * Concurrency cap for a `run_code` program's overlapping sub-calls
- * (default 10, the loop scheduler's own default). Sub-calls follow the
- * native scheduling contract — only calls whose tools classify
- * concurrency-safe overlap; exclusive calls form barriers — so `1`
- * restores strictly serial dispatch. Must be a positive integer.
- */
- maxParallelSubCalls?: number
-}
-
-/** How the registry presents its tools to the model (see {@link Config.mode}). */
-export type ToolPresentationMode = 'native' | 'ptc'
-```
-
-
@@ -4666,6 +4669,7 @@ export interface Config {
| `@deepseek-ai/dsh-tool-schedule` | `tools` | [`packages/schedule/tool-schedule/src/index.ts`](../packages/schedule/tool-schedule/src/index.ts) |
| `@deepseek-ai/dsh-tool-subagent-control` | `tools` · `subagents` | [`packages/subagent/tool-subagent-control/src/index.ts`](../packages/subagent/tool-subagent-control/src/index.ts) |
| `@deepseek-ai/dsh-tool-working-directory` | `tools` · `workingDirectory` | [`packages/session/tool-working-directory/src/index.ts`](../packages/session/tool-working-directory/src/index.ts) |
+| `@deepseek-ai/dsh-tools` | `systemPrompt` | [`packages/core/tools/src/index.ts`](../packages/core/tools/src/index.ts) |
| `@deepseek-ai/dsh-user-questions` | — | [`packages/interaction/user-questions/src/index.ts`](../packages/interaction/user-questions/src/index.ts) |
| `@deepseek-ai/dsh-webhook` | `agents` · `agentDefaultModel` · `agentPresets` · `permissionPresets` · `sessionTitle` · `workspaceRegistry` | [`packages/experimental/webhook/src/index.ts`](../packages/experimental/webhook/src/index.ts) |
| `@deepseek-ai/dsh-workspace` | `storageDomain` · `sessionPersistence` | [`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts) |
@@ -4761,6 +4765,7 @@ export interface Config {
| `@deepseek-ai/dsh-session-title-llm` | — | [`packages/session/session-title-llm/src/index.ts`](../packages/session/session-title-llm/src/index.ts) |
| `@deepseek-ai/dsh-ssh-helper-runtime` | — | [`packages/ssh/ssh-helper-runtime/src/index.ts`](../packages/ssh/ssh-helper-runtime/src/index.ts) |
| `@deepseek-ai/dsh-timeout` | — | [`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts) |
+| `@deepseek-ai/dsh-tool-testkit` | — | [`packages/test-support/tool-testkit/src/index.ts`](../packages/test-support/tool-testkit/src/index.ts) |
| `@deepseek-ai/dsh-typert-generator` | — | [`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts) |
| `@deepseek-ai/dsh-typert-protocol` | — | [`packages/typert/protocol/src/index.ts`](../packages/typert/protocol/src/index.ts) |
| `@deepseek-ai/dsh-typert-registry` | — | [`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts) |
diff --git a/docs/cordis-tutorial/07-into-the-harness.md b/docs/cordis-tutorial/07-into-the-harness.md
index a1285e63ed..f0c07b4741 100644
--- a/docs/cordis-tutorial/07-into-the-harness.md
+++ b/docs/cordis-tutorial/07-into-the-harness.md
@@ -37,12 +37,13 @@ export function apply(ctx: Context) {
// the model. ToolCallId brands the correlation id a provider would issue.
void (async () => {
const result = await ctx.tools.execute({
- callId: brandString('demo-1'),
- name: 'greet',
- arguments: { name: 'Cordis' },
+ calls: [{
+ type: 'tool-call', id: brandString('demo-1'),
+ name: 'greet', arguments: JSON.stringify({ name: 'Cordis' }),
+ }],
signal: new AbortController().signal,
})
- console.log('tool replied:', JSON.stringify(result.content))
+ console.log('tool replied:', JSON.stringify(result.results[0]?.result.content))
})()
}
```
diff --git a/docs/cordis-tutorial/07-into-the-harness.zh.md b/docs/cordis-tutorial/07-into-the-harness.zh.md
index 30c91c8e40..b12aae828a 100644
--- a/docs/cordis-tutorial/07-into-the-harness.zh.md
+++ b/docs/cordis-tutorial/07-into-the-harness.zh.md
@@ -37,12 +37,13 @@ export function apply(ctx: Context) {
// the model. ToolCallId brands the correlation id a provider would issue.
void (async () => {
const result = await ctx.tools.execute({
- callId: brandString('demo-1'),
- name: 'greet',
- arguments: { name: 'Cordis' },
+ calls: [{
+ type: 'tool-call', id: brandString('demo-1'),
+ name: 'greet', arguments: JSON.stringify({ name: 'Cordis' }),
+ }],
signal: new AbortController().signal,
})
- console.log('tool replied:', JSON.stringify(result.content))
+ console.log('tool replied:', JSON.stringify(result.results[0]?.result.content))
})()
}
```
diff --git a/docs/defensive-patterns/package-surface.i18n.yaml b/docs/defensive-patterns/package-surface.i18n.yaml
index 31367ff0de..8d5c9525ed 100644
--- a/docs/defensive-patterns/package-surface.i18n.yaml
+++ b/docs/defensive-patterns/package-surface.i18n.yaml
@@ -12,8 +12,8 @@
en: bf79c6acf35c90a5
zh: 9f2ce6c7f6493b17
/package-surface-rules/package-json-exports-uses-the-standard-key-set:
- en: 3604bf435be1c430
- zh: 169621c8a0c2dc4c
+ en: 8a2a50f2876b6fc9
+ zh: ca693a3bf91e16f9
/package-surface-rules/dependency-declarations-and-version-consistency-are-enforced-by-the-dependency-scan:
en: e68bfcde70f845b4
zh: 73e5c4fb067c4fa1
diff --git a/docs/defensive-patterns/package-surface.md b/docs/defensive-patterns/package-surface.md
index 0ca52f1b03..a01b50aa5d 100644
--- a/docs/defensive-patterns/package-surface.md
+++ b/docs/defensive-patterns/package-surface.md
@@ -76,8 +76,9 @@ A hand-written `external` list — and a `tsconfig.foo.json` invented beside it
A `package.json` `exports` map uses only the standard key set, in which every key already has one meaning across the repository, and a package never opens a key for its own local purpose. A key that only a handful of packages use without a documenting owner is not a precedent: formalizing a key, including one of the undocumented keys below, means changing the owning document and the check in the same change. The small shared key set is what lets a consumer infer a key's purpose from its name and lets a scan judge the export map at all.
-- Standard keys, each with one meaning repo-wide, across `packages/*/*/package.json` and `apps/*/package.json`: `.` (the package entry), `./package.json` (toolchain access, not a semantic export), `./src/*` (source passthrough for tests and tools, whose documented status is still open), `./client` (the browser entry, paired with the `dsh.client` declaration), `./types` (the type entry), `./typert` (the typert type runtime), `./remote` (the `@Remote` call surface), `./locale/*.json` (locale resources), `./cordis.patch.yml` (the bundle patch layer declared by `dsh.bundle`). Counts are not listed here because they rot on the next package; the recompute command below prints them.
+- Standard keys, each with one meaning repo-wide, across `packages/*/*/package.json` and `apps/*/package.json`: `.` (the package entry), `./package.json` (toolchain access, not a semantic export), `./src/*` (source passthrough for tests and tools, whose documented status is still open), `./client` (the browser entry, paired with the `dsh.client` declaration), `./types` (the type entry), `./testing` (shared test fixtures at `lib/testing.js` or `lib/types/testing.js`, with declarations at `lib/types/testing.d.ts`), `./typert` (the typert type runtime), `./remote` (the `@Remote` call surface), `./locale/*.json` (locale resources), `./cordis.patch.yml` (the bundle patch layer declared by `dsh.bundle`). Counts are not listed here because they rot on the next package; the recompute command below prints them.
- Keys outside that set (`./brand` in 5 packages, `./worker` in 4, `./startup`, `./runner`, and `./protocol` in 2 each, plus many one-off keys) have no documented meaning; they are pending review, not a pattern to copy.
+- `dsh-tools` additionally exposes `./pipeline` for reusable invocation stages and batch scheduling. Its main and pipeline bundles share runtime chunks to preserve error-class identity; workspace constraints check the export targets and publication files.
- Judged condition: does a change add an export key outside the standard set?
- Exception: none by default; a new key changes the owning document and the check first, with the domain owner's confirmation.
- Recompute the distribution:
diff --git a/docs/defensive-patterns/package-surface.zh.md b/docs/defensive-patterns/package-surface.zh.md
index 09f861ba9f..362a4a9385 100644
--- a/docs/defensive-patterns/package-surface.zh.md
+++ b/docs/defensive-patterns/package-surface.zh.md
@@ -76,8 +76,9 @@ import { isSurfaceEligibleType } from '../../core/session/src/surface.ts'
`package.json` 的 `exports` 只使用标准键集合，集合中每个键在全仓已经只有一个含义，包不得为自己的局部用途开键。只有少数几个包在用、又没有文档正家的键不构成先例：把某个键正式化（包括下面那些未记录在案的键）意味着在同一次改动里改正家文档与检查。键集合小且共享，消费者才能从键名推断用途，扫描也才有可能判定导出映射。
-- 标准键，每个键在全仓只有一个含义，统计口径是 `packages/*/*/package.json` 与 `apps/*/package.json`：`.`（包主入口）、`./package.json`（工具链访问，不是语义导出）、`./src/*`（测试与工具的源码透传，文档状态仍待定）、`./client`（浏览器入口，与 `dsh.client` 声明配对）、`./types`（类型入口）、`./typert`（typert 类型运行时）、`./remote`（`@Remote` 调用面）、`./locale/*.json`（本地化资源）、`./cordis.patch.yml`（`dsh.bundle` 声明的 bundle 补丁层）。这里不列各键的包数，因为下一个包就会让它过期；下面的复算命令会打印当前数字。
+- 标准键，每个键在全仓只有一个含义，统计口径是 `packages/*/*/package.json` 与 `apps/*/package.json`：`.`（包主入口）、`./package.json`（工具链访问，不是语义导出）、`./src/*`（测试与工具的源码透传，文档状态仍待定）、`./client`（浏览器入口，与 `dsh.client` 声明配对）、`./types`（类型入口）、`./testing`（共享测试 fixture，位于 `lib/testing.js` 或 `lib/types/testing.js`，声明位于 `lib/types/testing.d.ts`）、`./typert`（typert 类型运行时）、`./remote`（`@Remote` 调用面）、`./locale/*.json`（本地化资源）、`./cordis.patch.yml`（`dsh.bundle` 声明的 bundle 补丁层）。这里不列各键的包数，因为下一个包就会让它过期；下面的复算命令会打印当前数字。
- 集合之外的键（`./brand` 5 个包、`./worker` 4 个、`./startup`、`./runner`、`./protocol` 各 2 个，另有大量一次性键）没有文档含义，属待核项，不是可照抄的先例。
+- `dsh-tools` 另行提供 `./pipeline`，用于复用调用阶段与批量调度。主入口与 pipeline bundle 共享运行时 chunk，以保持错误类的身份一致；工作区检查验证导出目标与发布文件。
- 判定条件：改动是否新增了标准集合以外的 export 键？
- 例外：无默认例外；新增键须先改正家文档与检查，并取得对应领域专家确认。
- 复算分布：
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 659b9d53a5..15c5bfcef1 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -64,7 +64,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:44`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
| `session/created` | `emit` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`permission-presets`](../packages/interaction/permission-presets), [`schedule`](../packages/schedule/schedule), `server`, `session-controller`, [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry) |
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:63`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `file-upload`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `agent-team`, `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `agent-team`, `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:82`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) |
| `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:75`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`emit`) | `remotes` |
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:296`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
@@ -74,12 +74,12 @@ This matrix shows which packages dispatch each harness-owned event and which pac
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:158`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) |
| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), `browser-use-runtime`, [`session-reference`](../packages/context/session-reference), [`working-directory`](../packages/session/working-directory) |
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:209`](../packages/core/tools/src/index.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:165`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:177`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:154`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) |
+| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/events.ts:29`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/events.ts:41`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) |
+| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tool-executor-ptc/src/types.ts:46`](../packages/core/tool-executor-ptc/src/types.ts) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) |
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:157`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:39`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules`, `remote-access`, `shortcuts`, `ui-sidebar-documentpreview`, `ui-theme` |
| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index 19d1da2409..b0c5eb6c26 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -66,7 +66,7 @@
| `session-telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:44`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
| `session/created` | `emit` | [`packages/core/session/src/index.ts:54`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`permission-presets`](../packages/interaction/permission-presets), [`schedule`](../packages/schedule/schedule), `server`, `session-controller`, [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry) |
| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:63`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), `agent-team`, `file-upload`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-title`](../packages/session/session-title), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `agent-team`, `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:74`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), [`agent-instructions`](../packages/context/agent-instructions), [`agent-loop`](../packages/core/agent-loop), [`agent-preset-registry`](../packages/preset/agent-preset-registry), `agent-team`, `claude-code-mods`, [`compaction-basic`](../packages/compaction/compaction-basic), [`file-reference-local`](../packages/context/file-reference-local), `file-upload`, [`goal`](../packages/goal/goal), [`goal-round-driver`](../packages/goal/goal-round-driver), [`headless`](../packages/bundle/headless), [`loader-smoke`](../packages/test-support/loader-smoke), `product-analytics`, [`ptc-runtime-node`](../packages/ptc-runtime/ptc-runtime-node), `server`, `session-controller`, [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-projection`](../packages/session/session-projection), [`session-projection-cache`](../packages/session/session-projection-cache), [`session-telemetry`](../packages/session/session-telemetry), [`session-telemetry-otel`](../packages/session/session-telemetry-otel), [`session-title`](../packages/session/session-title), [`subagent`](../packages/subagent/subagent), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`user-questions`](../packages/interaction/user-questions), [`workspace-changes`](../packages/deliverables/workspace-changes) |
| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:82`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence-jsonl`](../packages/session/session-persistence-jsonl), [`session-telemetry`](../packages/session/session-telemetry) |
| `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:75`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`emit`) | `remotes` |
| `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:296`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
@@ -76,12 +76,12 @@
| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:158`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/experimental/hooks-claude-code) |
| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), `browser-use-runtime`, [`session-reference`](../packages/context/session-reference), [`working-directory`](../packages/session/working-directory) |
| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
-| `tools/change` | `emit` | [`packages/core/tools/src/index.ts:209`](../packages/core/tools/src/index.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `tools/execute` | `waterfall` | [`packages/core/tools/src/index.ts:165`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
-| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/index.ts:177`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
-| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/index.ts:154`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) |
-| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:191`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
-| `tools/result` | `emit` | [`packages/core/tools/src/index.ts:199`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) |
+| `tools/change` | `emit` | [`packages/core/tools/src/events.ts:56`](../packages/core/tools/src/events.ts) | [`agent-preset-registry`](../packages/preset/agent-preset-registry) (`emit`), [`tools`](../packages/core/tools) (`emit`) | `browser-use-runtime`, [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `tools/execute` | `waterfall` | [`packages/core/tools/src/events.ts:29`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `browser-use-runtime`, `browser-use-stagehand-native`, `claude-code-mods`, `computer-use-cua-driver-native`, [`session-checkpoint-policy`](../packages/session/session-checkpoint-policy), `timeout-policy` |
+| `tools/post-execute` | `waterfall` | [`packages/core/tools/src/events.ts:41`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `claude-code-mods`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`repeat-tool-reminder`](../packages/guard/repeat-tool-reminder), [`spill-policy`](../packages/spill/spill-policy), [`tool-fs-search`](../packages/fs/tool-fs-search) |
+| `tools/pre-execute` | `waterfall` | [`packages/core/tools/src/events.ts:18`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`waterfall`) | `auto-review`, [`hooks-claude-code`](../packages/experimental/hooks-claude-code), [`hooks-codex`](../packages/experimental/hooks-codex), [`tool-jobs`](../packages/jobs/tool-jobs), [`workspace-changes`](../packages/deliverables/workspace-changes) |
+| `tools/ptc-dispatch-log` | `waterfall` | [`packages/core/tool-executor-ptc/src/types.ts:46`](../packages/core/tool-executor-ptc/src/types.ts) | [`tool-executor-ptc`](../packages/core/tool-executor-ptc) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
+| `tools/result` | `emit` | [`packages/core/tools/src/events.ts:49`](../packages/core/tools/src/events.ts) | [`tools`](../packages/core/tools) (`events.dispatch`) | [`agent-instructions`](../packages/context/agent-instructions), `claude-code-mods`, [`subagent`](../packages/subagent/subagent), [`tool-present`](../packages/deliverables/tool-present) |
| `user-questions/request` | `waterfall` | [`packages/interaction/user-questions/src/types.ts:157`](../packages/interaction/user-questions/src/types.ts) | [`user-questions`](../packages/interaction/user-questions) (`waterfall`) | `remotes` |
| `webserver/index-inject` | `emit` | [`packages/host/webserver/src/index.ts:39`](../packages/host/webserver/src/index.ts) | `webserver` (`emit`) | `connection`, `inspector`, `modules`, `remote-access`, `shortcuts`, `ui-sidebar-documentpreview`, `ui-theme` |
| `workflow/agent-end` | `emit` | [`packages/workflow/workflow/src/index.ts:79`](../packages/workflow/workflow/src/index.ts) | [`workflow`](../packages/workflow/workflow) (`events.dispatch`) | [`tool-workflow`](../packages/workflow/tool-workflow) |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index 00bc4da738..56dea3a1f7 100644
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -46,6 +46,8 @@ flowchart TD
pkg_scope["scope"]
pkg_session["session"]
pkg_system_prompt["system-prompt"]
+ pkg_tool_executor_native["tool-executor-native"]
+ pkg_tool_executor_ptc["tool-executor-ptc"]
pkg_tools["tools"]
end
subgraph group_goal["packages/goal"]
@@ -436,6 +438,7 @@ flowchart TD
pkg_loader_smoke["loader-smoke"]
pkg_remote_mock["remote-mock"]
pkg_session_snapshot["session-snapshot"]
+ pkg_tool_testkit["tool-testkit"]
end
subgraph group_typert["packages/typert"]
pkg_typert_generator["typert-generator"]
@@ -715,14 +718,10 @@ flowchart TD
pkg_llm_deepseek_account --> pkg_timeout
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
- pkg_tools --> pkg_ptc_runtime
- pkg_tools --> pkg_sandbox
- pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
- pkg_tools --> pkg_working_directory
pkg_command_goal --> pkg_commands
pkg_command_goal --> pkg_goal
pkg_command_goal --> pkg_llm
@@ -810,6 +809,19 @@ flowchart TD
pkg_agent_loop --> pkg_system_prompt
pkg_agent_loop --> pkg_tools
pkg_agent_tool_presentation --> pkg_tools
+ pkg_tool_executor_native --> pkg_llm
+ pkg_tool_executor_native --> pkg_scope
+ pkg_tool_executor_native --> pkg_tools
+ pkg_tool_executor_ptc --> pkg_agent
+ pkg_tool_executor_ptc --> pkg_llm
+ pkg_tool_executor_ptc --> pkg_ptc_runtime
+ pkg_tool_executor_ptc --> pkg_sandbox
+ pkg_tool_executor_ptc --> pkg_sandbox_policy
+ pkg_tool_executor_ptc --> pkg_scope
+ pkg_tool_executor_ptc --> pkg_session
+ pkg_tool_executor_ptc --> pkg_tools
+ pkg_tool_executor_ptc --> pkg_user_approval
+ pkg_tool_executor_ptc --> pkg_working_directory
pkg_tool_goal --> pkg_agent
pkg_tool_goal --> pkg_goal
pkg_tool_goal --> pkg_llm
@@ -1033,6 +1045,8 @@ flowchart TD
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
+ pkg_tool_testkit --> pkg_llm
+ pkg_tool_testkit --> pkg_tools
pkg_tool_workflow --> pkg_agent
pkg_tool_workflow --> pkg_jobs
pkg_tool_workflow --> pkg_llm
@@ -1169,6 +1183,7 @@ flowchart TD
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
+ pkg_spill_policy --> pkg_tool_executor_ptc
pkg_spill_policy --> pkg_tools
pkg_session_query_sqlite --> pkg_session
pkg_session_query_sqlite --> pkg_session_persistence
@@ -1647,7 +1662,7 @@ flowchart TD
| [`loader-smoke`](../packages/test-support/loader-smoke) | `test-support` | [`agent`](../packages/core/agent), [`http-proxy`](../packages/util/http-proxy), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`llm-deepseek-account`](../packages/llm/llm-deepseek-account) | `llm` | [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`timeout`](../packages/util/timeout) |
-| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm) |
| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`web`](../packages/web/web) |
@@ -1666,6 +1681,8 @@ flowchart TD
| [`terminal-bash`](../packages/terminal/terminal-bash) | `terminal` | [`agent`](../packages/core/agent), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`terminal`](../packages/terminal/terminal), [`working-directory`](../packages/session/working-directory) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-tool-presentation`](../packages/core/agent-tool-presentation) | `core` | [`tools`](../packages/core/tools) |
+| [`tool-executor-native`](../packages/core/tool-executor-native) | `core` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`tool-executor-ptc`](../packages/core/tool-executor-ptc) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
@@ -1708,6 +1725,7 @@ flowchart TD
| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local), [`util-values`](../packages/util/values) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`tool-testkit`](../packages/test-support/tool-testkit) | `test-support` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`session`](../packages/core/session) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
@@ -1728,7 +1746,7 @@ flowchart TD
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`fs-local`](../packages/fs/fs-local), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
-| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
+| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tools`](../packages/core/tools) |
| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) |
| [`plugin-manager`](../packages/boot/plugin-manager) | `boot` | [`brand`](../packages/util/brand), [`hmr`](../packages/boot/hmr), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
diff --git a/docs/module-graph.zh.md b/docs/module-graph.zh.md
index c452bebf03..2d5e82b606 100644
--- a/docs/module-graph.zh.md
+++ b/docs/module-graph.zh.md
@@ -48,6 +48,8 @@ flowchart TD
pkg_scope["scope"]
pkg_session["session"]
pkg_system_prompt["system-prompt"]
+ pkg_tool_executor_native["tool-executor-native"]
+ pkg_tool_executor_ptc["tool-executor-ptc"]
pkg_tools["tools"]
end
subgraph group_goal["packages/goal"]
@@ -438,6 +440,7 @@ flowchart TD
pkg_loader_smoke["loader-smoke"]
pkg_remote_mock["remote-mock"]
pkg_session_snapshot["session-snapshot"]
+ pkg_tool_testkit["tool-testkit"]
end
subgraph group_typert["packages/typert"]
pkg_typert_generator["typert-generator"]
@@ -717,14 +720,10 @@ flowchart TD
pkg_llm_deepseek_account --> pkg_timeout
pkg_tools --> pkg_agent
pkg_tools --> pkg_llm
- pkg_tools --> pkg_ptc_runtime
- pkg_tools --> pkg_sandbox
- pkg_tools --> pkg_sandbox_policy
pkg_tools --> pkg_scope
pkg_tools --> pkg_session
pkg_tools --> pkg_system_prompt
pkg_tools --> pkg_user_approval
- pkg_tools --> pkg_working_directory
pkg_command_goal --> pkg_commands
pkg_command_goal --> pkg_goal
pkg_command_goal --> pkg_llm
@@ -812,6 +811,19 @@ flowchart TD
pkg_agent_loop --> pkg_system_prompt
pkg_agent_loop --> pkg_tools
pkg_agent_tool_presentation --> pkg_tools
+ pkg_tool_executor_native --> pkg_llm
+ pkg_tool_executor_native --> pkg_scope
+ pkg_tool_executor_native --> pkg_tools
+ pkg_tool_executor_ptc --> pkg_agent
+ pkg_tool_executor_ptc --> pkg_llm
+ pkg_tool_executor_ptc --> pkg_ptc_runtime
+ pkg_tool_executor_ptc --> pkg_sandbox
+ pkg_tool_executor_ptc --> pkg_sandbox_policy
+ pkg_tool_executor_ptc --> pkg_scope
+ pkg_tool_executor_ptc --> pkg_session
+ pkg_tool_executor_ptc --> pkg_tools
+ pkg_tool_executor_ptc --> pkg_user_approval
+ pkg_tool_executor_ptc --> pkg_working_directory
pkg_tool_goal --> pkg_agent
pkg_tool_goal --> pkg_goal
pkg_tool_goal --> pkg_llm
@@ -1035,6 +1047,8 @@ flowchart TD
pkg_llm_replay --> pkg_deepseek_llm_api_extensions
pkg_llm_replay --> pkg_llm
pkg_llm_replay --> pkg_session
+ pkg_tool_testkit --> pkg_llm
+ pkg_tool_testkit --> pkg_tools
pkg_tool_workflow --> pkg_agent
pkg_tool_workflow --> pkg_jobs
pkg_tool_workflow --> pkg_llm
@@ -1171,6 +1185,7 @@ flowchart TD
pkg_spill_policy --> pkg_session
pkg_spill_policy --> pkg_spill
pkg_spill_policy --> pkg_token_meter
+ pkg_spill_policy --> pkg_tool_executor_ptc
pkg_spill_policy --> pkg_tools
pkg_session_query_sqlite --> pkg_session
pkg_session_query_sqlite --> pkg_session_persistence
@@ -1649,7 +1664,7 @@ flowchart TD
| [`loader-smoke`](../packages/test-support/loader-smoke) | `test-support` | [`agent`](../packages/core/agent), [`http-proxy`](../packages/util/http-proxy), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`workflow`](../packages/workflow/workflow) | `workflow` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
| [`llm-deepseek-account`](../packages/llm/llm-deepseek-account) | `llm` | [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`llm`](../packages/llm/llm), [`llm-deepseek`](../packages/llm/llm-deepseek), [`timeout`](../packages/util/timeout) |
-| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
+| [`tools`](../packages/core/tools) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`user-approval`](../packages/interaction/user-approval) |
| [`command-goal`](../packages/goal/command-goal) | `goal` | [`commands`](../packages/interaction/commands), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm) |
| [`fs-sandbox`](../packages/fs/fs-sandbox) | `fs` | [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy) |
| [`web-search-deepseek`](../packages/web/web-search-deepseek) | `web` | [`agent`](../packages/core/agent), [`credentials`](../packages/credentials/credentials), [`deepseek-account`](../packages/credentials/deepseek-account), [`launch-environment`](../packages/util/launch-environment), [`session`](../packages/core/session), [`web`](../packages/web/web) |
@@ -1668,6 +1683,8 @@ flowchart TD
| [`terminal-bash`](../packages/terminal/terminal-bash) | `terminal` | [`agent`](../packages/core/agent), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`terminal`](../packages/terminal/terminal), [`working-directory`](../packages/session/working-directory) |
| [`agent-loop`](../packages/core/agent-loop) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`agent-tool-presentation`](../packages/core/agent-tool-presentation) | `core` | [`tools`](../packages/core/tools) |
+| [`tool-executor-native`](../packages/core/tool-executor-native) | `core` | [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`tools`](../packages/core/tools) |
+| [`tool-executor-ptc`](../packages/core/tool-executor-ptc) | `core` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`ptc-runtime`](../packages/ptc-runtime/ptc-runtime), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-goal`](../packages/goal/tool-goal) | `goal` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools) |
| [`tool-fs`](../packages/fs/tool-fs) | `fs` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`user-approval`](../packages/interaction/user-approval), [`working-directory`](../packages/session/working-directory) |
| [`tool-fs-search`](../packages/fs/tool-fs-search) | `fs` | [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`subprocess`](../packages/subprocess/subprocess), [`system-prompt`](../packages/core/system-prompt), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
@@ -1710,6 +1727,7 @@ flowchart TD
| [`tool-pwsh-persistent`](../packages/shell/tool-pwsh-persistent) | `shell` | [`agent`](../packages/core/agent), [`output-retention`](../packages/util/output-retention), [`terminal`](../packages/terminal/terminal), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`ssh`](../packages/ssh/ssh) | `ssh` | [`brand`](../packages/util/brand), [`fs`](../packages/fs/fs), [`fs-local`](../packages/fs/fs-local), [`fs-sandbox`](../packages/fs/fs-sandbox), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-local`](../packages/sandbox/sandbox-local), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`session-projection`](../packages/session/session-projection), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local), [`util-values`](../packages/util/values) |
| [`llm-replay`](../packages/test-support/llm-replay) | `test-support` | [`compaction`](../packages/compaction/compaction), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
+| [`tool-testkit`](../packages/test-support/tool-testkit) | `test-support` | [`llm`](../packages/llm/llm), [`tools`](../packages/core/tools) |
| [`tool-workflow`](../packages/workflow/tool-workflow) | `workflow` | [`agent`](../packages/core/agent), [`jobs`](../packages/jobs/jobs), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`workflow`](../packages/workflow/workflow) |
| [`plugin-package-inventory-deepseek`](../packages/llm/plugin-package-inventory-deepseek) | `llm` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`deepseek-llm-api-extensions`](../packages/llm/deepseek-llm-api-extensions), [`session`](../packages/core/session) |
| [`token-meter`](../packages/llm/token-meter) | `llm` | [`compaction`](../packages/compaction/compaction), [`compaction-image-offload`](../packages/compaction/compaction-image-offload), [`llm`](../packages/llm/llm), [`llm-retry`](../packages/llm/llm-retry), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
@@ -1730,7 +1748,7 @@ flowchart TD
| [`subprocess-ssh`](../packages/ssh/subprocess-ssh) | `ssh` | [`ssh`](../packages/ssh/ssh), [`subprocess`](../packages/subprocess/subprocess), [`subprocess-local`](../packages/subprocess/subprocess-local) |
| [`agent-loop-testkit`](../packages/test-support/agent-loop-testkit) | `test-support` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`fs-local`](../packages/fs/fs-local), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`working-directory`](../packages/session/working-directory) |
| [`subagent`](../packages/subagent/subagent) | `subagent` | [`agent`](../packages/core/agent), [`agent-preset-registry`](../packages/preset/agent-preset-registry), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`permission-presets`](../packages/interaction/permission-presets), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-projection`](../packages/session/session-projection), [`session-query`](../packages/session-query/session-query), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval), [`util-time`](../packages/util/time), [`working-directory`](../packages/session/working-directory), [`workspace`](../packages/workspace/workspace) |
-| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools) |
+| [`spill-policy`](../packages/spill/spill-policy) | `spill` | [`attachment`](../packages/attachment/attachment), [`fs`](../packages/fs/fs), [`llm`](../packages/llm/llm), [`output-retention`](../packages/util/output-retention), [`session`](../packages/core/session), [`spill`](../packages/spill/spill), [`token-meter`](../packages/llm/token-meter), [`tool-executor-ptc`](../packages/core/tool-executor-ptc), [`tools`](../packages/core/tools) |
| [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | `session-query` | [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-query`](../packages/session-query/session-query) |
| [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`attachment`](../packages/attachment/attachment), [`llm`](../packages/llm/llm), [`mcp-client`](../packages/mcp/mcp-client), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`token-meter`](../packages/llm/token-meter), [`user-approval`](../packages/interaction/user-approval) |
| [`plugin-manager`](../packages/boot/plugin-manager) | `boot` | [`brand`](../packages/util/brand), [`hmr`](../packages/boot/hmr), [`host-plugin-inventory`](../packages/host/plugin-inventory), [`sandbox`](../packages/sandbox/sandbox), [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`subprocess`](../packages/subprocess/subprocess), [`tools`](../packages/core/tools), [`typert-protocol`](../packages/typert/protocol), [`user-approval`](../packages/interaction/user-approval) |
diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml
index 7d6496f3b6..6a6af8dfc4 100644
--- a/docs/persistence-catalog.i18n.yaml
+++ b/docs/persistence-catalog.i18n.yaml
@@ -249,11 +249,11 @@
en: 03f36237cbf9e267
zh: 83fe2e69bbbfd3c1
/session-persistence-event-catalog/events/tool/tool-ptc-dispatch-log-only:
- en: 3d5d72b99e702a8c
- zh: e8c3b82cd5361c4a
+ en: e808d7ba03c24dad
+ zh: c67b9189e60e4986
/session-persistence-event-catalog/events/tool/tool-ptc-dispatch-start-log-only:
- en: de38cf70d81ad7c3
- zh: dd0a2a8be099271d
+ en: 5ae8f1bd938d0cdb
+ zh: 8f3fee21c023a246
/session-persistence-event-catalog/events/tool/tool-result-surface:
en: 283e3cf1fdd57f05
zh: 0bc3a15ae4f47aaf
@@ -1161,14 +1161,14 @@
en: bb11552744e477b8
zh: afb881f3ebf97e68
/session-persistence-event-catalog/resolved-persistence-types/principal:
- en: d1e45e03f161dc7c
- zh: 4f80af59ca4967c5
+ en: 6a590e6880db0242
+ zh: 2078c7e558a4cfad
/session-persistence-event-catalog/resolved-persistence-types/ptcdispatcheventdata:
- en: 81e66c5a07e17dd6
- zh: 0ecf3cfceba14d2b
+ en: cf94e6efcd7b19ba
+ zh: a66d50affd2b6f98
/session-persistence-event-catalog/resolved-persistence-types/ptcdispatchstarteventdata:
- en: fbbf650635960ec8
- zh: 9457953f4cbe07c6
+ en: 4ba5104118842c3f
+ zh: d9b487902f8c4f47
/session-persistence-event-catalog/resolved-persistence-types/reasoningblock:
en: 07e04c3e336f880f
zh: 6f8986ede9994fa1
@@ -1281,11 +1281,11 @@
en: 036b2595215410bb
zh: 41792808ebac1fa3
/session-persistence-event-catalog/resolved-persistence-types/toolremovalblock:
- en: f43a635a14568780
- zh: 8d22226b045122eb
+ en: fdac0df45529e14c
+ zh: c5e38de83a0e0a42
/session-persistence-event-catalog/resolved-persistence-types/toolrestriction:
- en: d7d3c0238d9b373e
- zh: f49d93ee54e7a780
+ en: 9d64c653e33bf2b6
+ zh: 7bb427b48756f30f
/session-persistence-event-catalog/resolved-persistence-types/toolresultmessage:
en: 2258683c3cfa4ce3
zh: 5663aa76c911761b
@@ -1440,8 +1440,8 @@
en: a1f188c9058cf621
zh: eb43c0f045fb9afb
/session-persistence-event-catalog/resolved-persistence-types/code-name-reason:
- en: 404a76066a59f3c6
- zh: ec9d510bdbac9786
+ en: 3f78ce454b333a0a
+ zh: 3c414c1510b59caf
/session-persistence-event-catalog/resolved-persistence-types/commandid-kind-sourceeventseq-text:
en: 87b03e1c73d2a326
zh: d7b9f06863cad891
@@ -1671,8 +1671,8 @@
en: c53129cf7214286c
zh: 8c5183b6dabbf714
/session-persistence-event-catalog/resolved-persistence-types/kind-ptc-mode:
- en: 8de77980e11a0562
- zh: 6de199e70a666a71
+ en: 4ed6a03496090056
+ zh: c040b7247425c57b
/session-persistence-event-catalog/resolved-persistence-types/kind-repeat-tool-reminder:
en: e3a0ef98a197374e
zh: 95e9363529a62cc3
@@ -1827,8 +1827,8 @@
en: 08be4349548406a9
zh: 8e7cf9966198ef78
/session-persistence-event-catalog/resolved-persistence-types/kind-tool-registry:
- en: 809a23c25ded8497
- zh: e9cd23e281f8d31f
+ en: 4fde95c569339141
+ zh: 6fa54e19c24ab7f3
/session-persistence-event-catalog/resolved-persistence-types/kind-user:
en: 9b6318ab4d7eba12
zh: f475439ef40b2681
diff --git a/docs/persistence-catalog.md b/docs/persistence-catalog.md
index ec7e3240da..ce5ec7a369 100644
--- a/docs/persistence-catalog.md
+++ b/docs/persistence-catalog.md
@@ -1116,7 +1116,7 @@ Source: [`packages/core/session/src/types.ts:362`](../packages/core/session/src/
'tool/ptc-dispatch': PtcDispatchEventData
```
-Source: [`packages/core/tools/src/types.ts:61`](../packages/core/tools/src/types.ts)
+Source: [`packages/core/tool-executor-ptc/src/session-types.ts:61`](../packages/core/tool-executor-ptc/src/session-types.ts)
@@ -1139,7 +1139,7 @@ Source: [`packages/core/tools/src/types.ts:61`](../packages/core/tools/src/types
'tool/ptc-dispatch-start': PtcDispatchStartEventData
```
-Source: [`packages/core/tools/src/types.ts:45`](../packages/core/tools/src/types.ts)
+Source: [`packages/core/tool-executor-ptc/src/session-types.ts:45`](../packages/core/tool-executor-ptc/src/session-types.ts)
@@ -4434,7 +4434,7 @@ Sources: [`packages/typert/protocol/src/types.ts:457`](../packages/typert/protoc
-
+
@@ -4442,7 +4442,7 @@ Sources: [`packages/typert/protocol/src/types.ts:457`](../packages/typert/protoc
SHA-256: `cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6`
-Sources: [`packages/core/tools/src/types.ts:21`](../packages/core/tools/src/types.ts)
+Sources: [`packages/core/tool-executor-ptc/src/session-types.ts:21`](../packages/core/tool-executor-ptc/src/session-types.ts)
| Property | Presence | Type |
|---|---|---|
@@ -4458,7 +4458,7 @@ Sources: [`packages/core/tools/src/types.ts:21`](../packages/core/tools/src/type
-
+
@@ -4466,7 +4466,7 @@ Sources: [`packages/core/tools/src/types.ts:21`](../packages/core/tools/src/type
SHA-256: `2fe5026daf14bd4ff2b7bfb7cf9791c302d9cbba06802178b6dfec00b892698f`
-Sources: [`packages/core/tools/src/types.ts:12`](../packages/core/tools/src/types.ts)
+Sources: [`packages/core/tool-executor-ptc/src/session-types.ts:12`](../packages/core/tool-executor-ptc/src/session-types.ts)
| Property | Presence | Type |
|---|---|---|
@@ -5177,7 +5177,7 @@ Sources: [`packages/llm/llm/src/types.ts:127`](../packages/llm/llm/src/types.ts)
-
+
@@ -5185,7 +5185,7 @@ Sources: [`packages/llm/llm/src/types.ts:127`](../packages/llm/llm/src/types.ts)
SHA-256: `3cfc3a56502da1f8c6153c2c56657bab4b749056968634dd0991d325ec1c919f`
-Sources: [`packages/core/tools/src/index.ts:701`](../packages/core/tools/src/index.ts)
+Sources: [`packages/core/tools/src/contracts.ts:326`](../packages/core/tools/src/contracts.ts)
| Property | Presence | Type |
|---|---|---|
@@ -5971,7 +5971,7 @@ SHA-256: `cbbe8377ee744964537dbafd83607219e58ba79a13f6db0d0645c7ad3d5e8a09`
SHA-256: `a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735`
-Sources: [`packages/core/session/src/types.ts:384`](../packages/core/session/src/types.ts) · [`packages/core/tools/src/types.ts:27`](../packages/core/tools/src/types.ts)
+Sources: [`packages/core/session/src/types.ts:384`](../packages/core/session/src/types.ts) · [`packages/core/tool-executor-ptc/src/session-types.ts:27`](../packages/core/tool-executor-ptc/src/session-types.ts)
| Property | Presence | Type |
|---|---|---|
@@ -6952,7 +6952,7 @@ Sources: [`packages/session/session-title/src/types.ts:30`](../packages/session/
SHA-256: `dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd`
-Sources: [`packages/core/tools/src/ptc.ts:15`](../packages/core/tools/src/ptc.ts)
+Sources: [`packages/core/tool-executor-ptc/src/types.ts:53`](../packages/core/tool-executor-ptc/src/types.ts)
| Property | Presence | Type |
|---|---|---|
@@ -7534,7 +7534,7 @@ SHA-256: `c5228b7a55498d84f529591744a0ab26e0b93ade18a70a26db1377a1ecfa6b49`
SHA-256: `8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543`
-Sources: [`packages/core/tools/src/index.ts:35`](../packages/core/tools/src/index.ts)
+Sources: [`packages/core/tools/src/index.ts:17`](../packages/core/tools/src/index.ts)
| Property | Presence | Type |
|---|---|---|
diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md
index 15d1af1d58..1ecbff73d4 100644
--- a/docs/persistence-catalog.zh.md
+++ b/docs/persistence-catalog.zh.md
@@ -1118,7 +1118,7 @@ export type SessionEvent = {
'tool/ptc-dispatch': PtcDispatchEventData
```
-来源：[`packages/core/tools/src/types.ts:61`](../packages/core/tools/src/types.ts)
+来源：[`packages/core/tool-executor-ptc/src/session-types.ts:61`](../packages/core/tool-executor-ptc/src/session-types.ts)
@@ -1141,7 +1141,7 @@ export type SessionEvent = {
'tool/ptc-dispatch-start': PtcDispatchStartEventData
```
-来源：[`packages/core/tools/src/types.ts:45`](../packages/core/tools/src/types.ts)
+来源：[`packages/core/tool-executor-ptc/src/session-types.ts:45`](../packages/core/tool-executor-ptc/src/session-types.ts)
@@ -4436,7 +4436,7 @@ SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5`
-
+
@@ -4444,7 +4444,7 @@ SHA-256: `deebfc7c62177ea840f23c6362b8615bc78ffa93377dd5d243c04e541c413af5`
SHA-256: `cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6`
-来源：[`packages/core/tools/src/types.ts:21`](../packages/core/tools/src/types.ts)
+来源：[`packages/core/tool-executor-ptc/src/session-types.ts:21`](../packages/core/tool-executor-ptc/src/session-types.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -4460,7 +4460,7 @@ SHA-256: `cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6`
-
+
@@ -4468,7 +4468,7 @@ SHA-256: `cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6`
SHA-256: `2fe5026daf14bd4ff2b7bfb7cf9791c302d9cbba06802178b6dfec00b892698f`
-来源：[`packages/core/tools/src/types.ts:12`](../packages/core/tools/src/types.ts)
+来源：[`packages/core/tool-executor-ptc/src/session-types.ts:12`](../packages/core/tool-executor-ptc/src/session-types.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -5179,7 +5179,7 @@ SHA-256: `43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8`
-
+
@@ -5187,7 +5187,7 @@ SHA-256: `43e311235aa537df1bacdd92d144df8a952337a76e9ac892cdf670f1a797bad8`
SHA-256: `3cfc3a56502da1f8c6153c2c56657bab4b749056968634dd0991d325ec1c919f`
-来源：[`packages/core/tools/src/index.ts:701`](../packages/core/tools/src/index.ts)
+来源：[`packages/core/tools/src/contracts.ts:326`](../packages/core/tools/src/contracts.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -5973,7 +5973,7 @@ SHA-256: `cbbe8377ee744964537dbafd83607219e58ba79a13f6db0d0645c7ad3d5e8a09`
SHA-256: `a81059ca06999da1e712414520c2c65e491d052fcf9640fae20aa38f0a5dc735`
-来源：[`packages/core/session/src/types.ts:384`](../packages/core/session/src/types.ts) · [`packages/core/tools/src/types.ts:27`](../packages/core/tools/src/types.ts)
+来源：[`packages/core/session/src/types.ts:384`](../packages/core/session/src/types.ts) · [`packages/core/tool-executor-ptc/src/session-types.ts:27`](../packages/core/tool-executor-ptc/src/session-types.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -6954,7 +6954,7 @@ SHA-256: `b81e9de81a481b24e1e1f9adf038bfc59e57b4f35ce62f8f1e45284186f4f812`
SHA-256: `dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd`
-来源：[`packages/core/tools/src/ptc.ts:15`](../packages/core/tools/src/ptc.ts)
+来源：[`packages/core/tool-executor-ptc/src/types.ts:53`](../packages/core/tool-executor-ptc/src/types.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
@@ -7536,7 +7536,7 @@ SHA-256: `c5228b7a55498d84f529591744a0ab26e0b93ade18a70a26db1377a1ecfa6b49`
SHA-256: `8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543`
-来源：[`packages/core/tools/src/index.ts:35`](../packages/core/tools/src/index.ts)
+来源：[`packages/core/tools/src/index.ts:17`](../packages/core/tools/src/index.ts)
| 属性 | 存在性 | 类型 |
|---|---|---|
diff --git a/docs/persistence-schema.json b/docs/persistence-schema.json
index a77fe9f24b..0a8b98c954 100644
--- a/docs/persistence-schema.json
+++ b/docs/persistence-schema.json
@@ -23126,10 +23126,10 @@
{
"digest": "2fe5026daf14bd4ff2b7bfb7cf9791c302d9cbba06802178b6dfec00b892698f",
"names": [
- "packages/core/tools/src/types.ts#PtcDispatchStartEventData"
+ "packages/core/tool-executor-ptc/src/session-types.ts#PtcDispatchStartEventData"
],
"sources": [
- "packages/core/tools/src/types.ts:12"
+ "packages/core/tool-executor-ptc/src/session-types.ts:12"
]
},
{
@@ -23313,10 +23313,10 @@
{
"digest": "3cfc3a56502da1f8c6153c2c56657bab4b749056968634dd0991d325ec1c919f",
"names": [
- "packages/core/tools/src/index.ts#ToolRestriction"
+ "packages/core/tools/src/contracts.ts#ToolRestriction"
],
"sources": [
- "packages/core/tools/src/index.ts:701"
+ "packages/core/tools/src/contracts.ts:326"
]
},
{
@@ -24571,7 +24571,7 @@
"digest": "8fcb0b44a575e998665c053643d1ab04c82f39253ebd190ac0c975b78e40b543",
"names": [],
"sources": [
- "packages/core/tools/src/index.ts:35"
+ "packages/core/tools/src/index.ts:17"
]
},
{
@@ -24892,7 +24892,7 @@
"names": [],
"sources": [
"packages/core/session/src/types.ts:384",
- "packages/core/tools/src/types.ts:27"
+ "packages/core/tool-executor-ptc/src/session-types.ts:27"
]
},
{
@@ -25472,10 +25472,10 @@
{
"digest": "cef171adf021a1867d244618a3dbbaafc22beb17c7f3df3ee203393271c8c6f6",
"names": [
- "packages/core/tools/src/types.ts#PtcDispatchEventData"
+ "packages/core/tool-executor-ptc/src/session-types.ts#PtcDispatchEventData"
],
"sources": [
- "packages/core/tools/src/types.ts:21"
+ "packages/core/tool-executor-ptc/src/session-types.ts:21"
]
},
{
@@ -25594,7 +25594,7 @@
"digest": "dba54c09c6e7aafc9acbed7792ecc920d99f92d0784aeeed10af55f7fe0bc8cd",
"names": [],
"sources": [
- "packages/core/tools/src/ptc.ts:15"
+ "packages/core/tool-executor-ptc/src/types.ts:53"
]
},
{
diff --git a/docs/subsystems/tools.i18n.yaml b/docs/subsystems/tools.i18n.yaml
index 32a5981c35..b05b723c74 100644
--- a/docs/subsystems/tools.i18n.yaml
+++ b/docs/subsystems/tools.i18n.yaml
@@ -14,9 +14,12 @@
/tools/toolrestriction-one-scope-s-live-filter-over-what-it-inherits:
en: 8c3fc4ca26f7e314
zh: 2e27263cb25243b9
+/tools/executors-and-raw-call-batches:
+ en: 14522295539ea2fb
+ zh: 572c462f2c6b70ad
/tools/execution-extensible-waterfalls-plus-monotonic-policy:
- en: dcac8fa88ef3e719
- zh: aae2f4ce8852d8d8
+ en: 356bf8128685d0fe
+ zh: a28541da29c3deed
/tools/the-enforced-raw-json-schema-subset:
en: 28e354bfa2f9cebb
zh: be1f75abccf8afdf
diff --git a/docs/subsystems/tools.md b/docs/subsystems/tools.md
index 585ce1582a..a43e3f29e0 100644
--- a/docs/subsystems/tools.md
+++ b/docs/subsystems/tools.md
@@ -30,7 +30,7 @@ interface ToolDefinition extends ToolSchema {
/**
* Run one accepted call and return only its canonical lossless-JSON value.
* Async work must observe or forward `exec.signal` and settle only after its
- * owned work reaches quiescence. The registry preserves caller cancellation
+ * owned work reaches quiescence. The executor preserves caller cancellation
* through around-dispatch signal replacement and does not abandon this
* promise, but it cannot hard-kill same-process code.
* @param args - losslessly snapshotted, frozen model arguments.
@@ -49,12 +49,12 @@ interface ToolDefinition extends ToolSchema {
*/
projectContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined
/**
- * Synchronous last-mile transform for model-facing content. The registry
+ * Synchronous last-mile transform for model-facing content. The executor
* snapshots this callback when execution starts and invokes it exactly once
* for every normalized outcome, including pipeline failures that bypass
* `tools/post-execute`, immediately before lossless materialization.
* Returning `undefined` preserves the content; every other result field
- * remains registry-owned. The callback must be total and must not throw.
+ * remains executor-owned. The callback must be total and must not throw.
* @param exec - immutable execution identity and arguments.
* @param result - complete normalized outcome before materialization.
* @returns replacement content, or `undefined` to preserve it.
@@ -177,9 +177,91 @@ interface ToolRestriction {
}
```
+## Executors and raw call batches
+
+`ctx.tools.execute()` delegates a complete raw model-call batch to the nearest scoped executor. The service selects the current provider when each batch starts; prompt assembly returns only model input. `agent` is absent for standalone service calls; `log` is absent for programmatic calls outside a model step, such as initialization hooks. An Agent without `log` still scopes tool access but produces no root call/result events. Tool-owned events may still use its Session.
+
+```ts type-equiv
+/** Model-call schemas produced by an executor. */
+type ToolModelInput = Pick
+```
+
+```ts type-equiv
+/** Raw model calls, with optional Agent ownership and model-step logging. */
+interface ToolBatchInput {
+ readonly calls: readonly ToolCallBlock[]
+ readonly signal: AbortSignal
+ /**
+ * Positive integer overriding the executor's concurrency limit for this batch.
+ * Applies to concurrency-safe root calls; program subcall limits remain separate.
+ * Undefined uses the executor's configured limit.
+ */
+ readonly maxParallelToolCalls?: number
+ /**
+ * Owning Agent supplies scoped tools and execution context, including outside a turn.
+ * Undefined for standalone calls outside an Agent, such as a service invocation.
+ */
+ readonly agent?: Agent
+ /**
+ * Committed model step receiving root call/result events; requires `agent`.
+ * Undefined when `agent` is absent or for calls outside a model response, such
+ * as session initialization hooks. Without `log`, root call/result events are
+ * omitted while `agent`, when provided, still supplies scope and execution context.
+ */
+ readonly log?: {
+ readonly turn: number
+ readonly step: number
+ }
+}
+```
+
+```ts type-equiv
+/** One settled result correlated with its original model call. */
+interface ToolCallResult {
+ readonly callId: ToolCallId
+ readonly result: ToolExecutionResult
+}
+```
+
+```ts type-equiv
+/** Model-ordered outcomes and context accepted for the next step. */
+interface ToolBatchResult {
+ readonly results: readonly ToolCallResult[]
+ readonly additionalContexts: readonly UserMessage[]
+ readonly concluded: boolean
+}
+```
+
+```ts type-equiv
+/** A plugin owns argument parsing, dispatch, scheduling, cancellation, and logging. */
+interface ToolExecutor {
+ /** Guidance registered and disposed with this executor; absent means no executor-owned sections. */
+ readonly sections?: readonly ToolPromptSection[]
+ /**
+ * Describe the model's callable tools.
+ * @param tools - currently visible capability definitions, after scoped restrictions.
+ * @returns schemas and names used to validate tool ordering.
+ */
+ describe(tools: readonly ToolDefinition[]): ToolModelInput
+ /**
+ * Execute a complete batch. With log, commit root call/result events to the
+ * Agent's Session; without log, omit those events. Tool-owned events may still
+ * use the owning Agent's Session. Return
+ * one outcome per input call in input order, including skipped calls on abort.
+ * Never settle while started work is still running. Internal failures reject
+ * with ToolBatchExecutionError after draining, preserving committed outcomes
+ * and context; callers must stop dependent work and repair missing log results.
+ * An explicit maxParallelToolCalls takes precedence over executor configuration.
+ * @param input - original calls, cancellation, optional concurrency override, Agent and logging step.
+ * @returns settled results, deferred context, and whether a success concludes the turn.
+ */
+ execute(input: ToolBatchInput): Promise
+}
+```
+
## Execution: extensible waterfalls plus monotonic policy
-`ctx.tools.execute()` accepts a caller-owned `ToolExecutionInput` with a required readonly `signal`, materializes its parsed JSON arguments once into a pipeline-owned `ToolExecution`, and runs that call through `tools/pre-execute` (the reorderable allow/deny/ask waterfall) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `projectContent` → `tools/post-execute` (inspect/replace the result) → optional definition-owned `finalizeContent` → `tools/result` (the immutable authoritative outcome). Only the `tools/execute` view may replace the required signal. The outcome is a `ToolExecutionResult`.
+Built-in executors pass parsed `ToolExecutionInput` values to the shared `ToolExecutionPipeline`. The pipeline owns argument snapshots, execution identities, policy waterfalls, dispatch, and final-result notification, returning one `ToolExecutionResult` per invocation. Custom executors can implement their own execution; the public `ToolExecutor` requires only descriptions and batch execution.
```ts type-equiv
/** Opaque call identity that permits correlation without exposing mutable execution state. */
@@ -188,8 +270,8 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
```ts type-equiv
/**
- * Caller-supplied description of one tool call. {@link ToolRuntime.execute}
- * adds the registry-owned token to form a pipeline {@link ToolExecution};
+ * Parsed input to the shared invocation pipeline. The pipeline
+ * adds its own token to form a {@link ToolExecution};
* callers do not choose that token.
*/
interface ToolExecutionInput {
@@ -213,7 +295,7 @@ interface ToolExecutionInput {
* The token also marks the call as a transport sub-dispatch rather than a
* model-direct call: under `mode: 'ptc'`, only calls WITH a parent may
* execute a native tool name — a model-direct call (no parent) is denied as
- * `UNKNOWN_TOOL` before the policy pipeline. See {@link ToolRuntime.execute}.
+ * `UNKNOWN_TOOL` before the policy pipeline.
*/
readonly parent?: ToolExecutionToken
/** Required caller-owned cancellation for this invocation. */
@@ -225,7 +307,7 @@ A tool body receives the runtime extension. `deferContext()` attaches context to
```ts type-equiv
/**
- * Runtime context handed to a tool implementation after the registry has
+ * Runtime context handed to a tool implementation after the executor has
* accepted a {@link ToolExecution}. {@link deferContext} attaches context to
* this execution's own result — a composite tool ferries nested-dispatch
* context back to the outer result, and a leaf tool may mint a fresh
@@ -294,16 +376,16 @@ interface PtcDispatchLog {
```ts type-equiv
/**
- * One pending tool call inside the registry pipeline. Parsed arguments cross
+ * One pending tool call inside the executor pipeline. Parsed arguments cross
* one lossless-JSON materialization boundary before policy and are deep-frozen;
- * call identity, the caller signal, and the registry-assigned {@link token} are
- * readonly. The registry freezes the complete object before `tools/result`
+ * call identity, the caller signal, and the executor-assigned {@link token} are
+ * readonly. The executor freezes the complete object before `tools/result`
* observers run.
*/
interface ToolExecution extends ToolExecutionInput {
/** Root model-requested call, resolved for every root and nested execution. */
readonly rootCallId: ToolCallId
- /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
+ /** Executor-assigned identity shared with nested calls only as their opaque `parent` token. */
readonly token: ToolExecutionToken
}
```
@@ -312,7 +394,7 @@ interface ToolExecution extends ToolExecutionInput {
/**
* Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
* may replace the signal for its delegated lifetime, but it cannot remove it.
- * The registry fuses every replacement with the captured caller signal.
+ * The executor fuses every replacement with the captured caller signal.
*/
interface ToolDispatchExecution extends Omit {
/** Cancellation signal visible to the next wrapper or tool body. */
@@ -501,26 +583,13 @@ The full presentation field docs live in [`packages/core/tools/src/presentation.
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
+
-### `ctx.tools` — `ToolRuntime`
+### `ctx.tools` — `ToolsService`
-Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+Concrete tool registry and scoped executor dispatcher.
```ts cordis-catalog
-/**
- * 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.
- *
- * Scoped 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.
- * @param mode - the presentation the covered agents' models see.
- * @returns the exact disposer that restores the deployment default.
- */
-presentAs(mode: ToolPresentationMode): () => void
-
/**
* Register globally or in the calling agent scope. Scoped tools shadow
* globals; duplicates within one layer and the reserved `run_code` name fail.
@@ -538,18 +607,6 @@ register(definition: ToolDefinition): () => void
*/
restrict(filter: ToolRestriction): () => void
-/**
- * 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.
- * @param guard - synchronous check; a returned string denies the execution.
- * @returns the exact disposer that unregisters the guard.
- */
-guard(guard: ToolGuard): () => void
-
/**
* Look up a tool as one scope sees it (scoped
* shadows global; a restricted-away global reads as absent). Presenters pass
@@ -561,6 +618,13 @@ guard(guard: ToolGuard): () => void
*/
get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+/**
+ * Read the visible capability definitions for descriptions and program bindings.
+ * @param scope - viewing Agent or preset; omitted selects the global view.
+ * @returns definitions after scoped shadowing and restrictions.
+ */
+definitions(scope?: ScopeKey): readonly ToolDefinition[]
+
/**
* Project visible definitions onto the allowlisted model-facing schema fields,
* excluding execution and presentation callbacks.
@@ -570,29 +634,33 @@ get(name: string, scope?: ScopeKey): ToolDefinition | undefined
schemas(scope?: ScopeKey): ToolSchema[]
/**
- * 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.
- * @param exec - call name, parsed arguments, and optional agent scope.
- * @returns the fail-closed scheduling mode.
+ * Provide the executor for the calling scope; an unscoped contribution is the deployment default.
+ * @param executor - initialized provider owned by the contributing plugin.
+ * @returns the effect disposer. Unloading leaves the selection unavailable until it is replaced.
*/
-executionMode(exec: ToolExecutionInput): ToolExecutionMode
+setExecutor(executor: ToolExecutor): () => void
/**
- * 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.
- * @param exec - the typed same-process call input. The registry assigns its
- * correlation token before policy begins.
- * @returns the materialized final result.
+ * Delegate a raw call batch to its Agent's provider or the deployment default.
+ * Select at dispatch; accepted batches settle through that provider even if it unloads.
+ * @param input - original calls, optional owning Agent, and optional logging step.
+ * @returns the selected executor's settled batch; unavailable selections reject.
*/
-async execute(exec: ToolExecutionInput): Promise
+async execute(input: ToolBatchInput): Promise
+
+/**
+ * Register a monotonic denial in the calling scope.
+ * @param guard - evaluated after extensible pre-execute policy by the shared pipeline.
+ * @returns the effect disposer that removes this guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Check global and inherited guards after pre-execute policy and approval resolve.
+ * @param exec - invocation whose guards are checked before dispatch.
+ * @returns the first denial reason, or undefined when no guard denies.
+ */
+checkGuards(exec: ToolExecution): string | undefined
```
Types: [ScopeKey](scope.md)
@@ -607,22 +675,19 @@ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index
#### `tools/change` — emit
-A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+A tool or executor was registered or unregistered, or a scoped restriction changed. Unfiltered registry notification: scoped listeners receive changes from every scope because a global contribution can affect every agent's next assembly.
```ts cordis-catalog
/**
- * A tool was registered or unregistered, or a scoped restriction changed
- * (the available tool set changed — possibly for one scope only). An
- * UNFILTERED registry-subject notification, deliberately not scope-filtered
- * dispatch: a global change concerns every agent's next assembly, so a
- * scoped listener subscribing here sees every change, not just its own
- * scope's.
+ * A tool or executor was registered or unregistered, or a scoped restriction changed.
+ * Unfiltered registry notification: scoped listeners receive changes from every
+ * scope because a global contribution can affect every agent's next assembly.
* @mode emit
*/
'tools/change'(): void
```
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -641,12 +706,12 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
* @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
* @mode waterfall
*/
-'tools/execute'(this: Scoped, exec: ToolDispatchExecution, next: () => Promise): Promise
+'tools/execute'(this: Scoped, exec: ToolDispatchExecution, next: () => Promise): Promise
```
Types: [Scoped](scope.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -666,12 +731,12 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
* @param result - the dispatch outcome a listener may accept, replace, or block.
* @mode waterfall
*/
-'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise
+'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise
```
Types: [Scoped](scope.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -690,12 +755,12 @@ Allow, deny, cancel, or ask before dispatch. `next()` delegates to allow; `cance
* @param exec - the pending call (name, parsed arguments, caller agent).
* @mode waterfall
*/
-'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
+'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
```
Types: [Scoped](scope.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -717,12 +782,12 @@ Allow a listener to replace content in the DURABLE LOG COPY of one `run_code` su
* @param dispatch - the parent execution, sub-call identity, and the settled content to log.
* @mode waterfall
*/
-'tools/ptc-dispatch-log'(this: Scoped, dispatch: PtcDispatchLog, next: () => Promise): Promise
+'tools/ptc-dispatch-log'(this: Scoped, dispatch: PtcDispatchLog, next: () => Promise): Promise
```
Types: [ContentBlock](llm-streaming.md) · [Scoped](scope.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tool-executor-ptc/src/types.ts`](../../packages/core/tool-executor-ptc/src/types.ts)
@@ -738,10 +803,10 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
* @param result - a deep-frozen snapshot of the final returned result.
* @mode emit
*/
-'tools/result'(this: Scoped, exec: Readonly, result: Readonly): undefined
+'tools/result'(this: Scoped, exec: Readonly, result: Readonly): undefined
```
Types: [Scoped](scope.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
diff --git a/docs/subsystems/tools.zh.md b/docs/subsystems/tools.zh.md
index 4ee27fcb4d..a0fecf88cc 100644
--- a/docs/subsystems/tools.zh.md
+++ b/docs/subsystems/tools.zh.md
@@ -30,7 +30,7 @@ interface ToolDefinition extends ToolSchema {
/**
* Run one accepted call and return only its canonical lossless-JSON value.
* Async work must observe or forward `exec.signal` and settle only after its
- * owned work reaches quiescence. The registry preserves caller cancellation
+ * owned work reaches quiescence. The executor preserves caller cancellation
* through around-dispatch signal replacement and does not abandon this
* promise, but it cannot hard-kill same-process code.
* @param args - losslessly snapshotted, frozen model arguments.
@@ -49,12 +49,12 @@ interface ToolDefinition extends ToolSchema {
*/
projectContent?(exec: Readonly, result: Readonly): ContentBlock[] | undefined
/**
- * Synchronous last-mile transform for model-facing content. The registry
+ * Synchronous last-mile transform for model-facing content. The executor
* snapshots this callback when execution starts and invokes it exactly once
* for every normalized outcome, including pipeline failures that bypass
* `tools/post-execute`, immediately before lossless materialization.
* Returning `undefined` preserves the content; every other result field
- * remains registry-owned. The callback must be total and must not throw.
+ * remains executor-owned. The callback must be total and must not throw.
* @param exec - immutable execution identity and arguments.
* @param result - complete normalized outcome before materialization.
* @returns replacement content, or `undefined` to preserve it.
@@ -177,9 +177,91 @@ interface ToolRestriction {
}
```
+## 执行器与原始调用批次
+
+`ctx.tools.execute()` 把完整的原始模型调用批次委托给最近作用域的执行器。服务在每个批次开始时选择当前提供者；提示词组装仅返回模型输入。`agent` 在独立服务调用中不存在；`log` 在模型步骤之外的程序调用（例如初始化钩子）中不存在。有 Agent 而没有 `log` 时，调用仍受该 Agent 的工具作用域约束，但不记录根调用／结果事件。工具自身的事件仍可使用 Agent 的 Session。
+
+```ts type-equiv
+/** Model-call schemas produced by an executor. */
+type ToolModelInput = Pick
+```
+
+```ts type-equiv
+/** Raw model calls, with optional Agent ownership and model-step logging. */
+interface ToolBatchInput {
+ readonly calls: readonly ToolCallBlock[]
+ readonly signal: AbortSignal
+ /**
+ * Positive integer overriding the executor's concurrency limit for this batch.
+ * Applies to concurrency-safe root calls; program subcall limits remain separate.
+ * Undefined uses the executor's configured limit.
+ */
+ readonly maxParallelToolCalls?: number
+ /**
+ * Owning Agent supplies scoped tools and execution context, including outside a turn.
+ * Undefined for standalone calls outside an Agent, such as a service invocation.
+ */
+ readonly agent?: Agent
+ /**
+ * Committed model step receiving root call/result events; requires `agent`.
+ * Undefined when `agent` is absent or for calls outside a model response, such
+ * as session initialization hooks. Without `log`, root call/result events are
+ * omitted while `agent`, when provided, still supplies scope and execution context.
+ */
+ readonly log?: {
+ readonly turn: number
+ readonly step: number
+ }
+}
+```
+
+```ts type-equiv
+/** One settled result correlated with its original model call. */
+interface ToolCallResult {
+ readonly callId: ToolCallId
+ readonly result: ToolExecutionResult
+}
+```
+
+```ts type-equiv
+/** Model-ordered outcomes and context accepted for the next step. */
+interface ToolBatchResult {
+ readonly results: readonly ToolCallResult[]
+ readonly additionalContexts: readonly UserMessage[]
+ readonly concluded: boolean
+}
+```
+
+```ts type-equiv
+/** A plugin owns argument parsing, dispatch, scheduling, cancellation, and logging. */
+interface ToolExecutor {
+ /** Guidance registered and disposed with this executor; absent means no executor-owned sections. */
+ readonly sections?: readonly ToolPromptSection[]
+ /**
+ * Describe the model's callable tools.
+ * @param tools - currently visible capability definitions, after scoped restrictions.
+ * @returns schemas and names used to validate tool ordering.
+ */
+ describe(tools: readonly ToolDefinition[]): ToolModelInput
+ /**
+ * Execute a complete batch. With log, commit root call/result events to the
+ * Agent's Session; without log, omit those events. Tool-owned events may still
+ * use the owning Agent's Session. Return
+ * one outcome per input call in input order, including skipped calls on abort.
+ * Never settle while started work is still running. Internal failures reject
+ * with ToolBatchExecutionError after draining, preserving committed outcomes
+ * and context; callers must stop dependent work and repair missing log results.
+ * An explicit maxParallelToolCalls takes precedence over executor configuration.
+ * @param input - original calls, cancellation, optional concurrency override, Agent and logging step.
+ * @returns settled results, deferred context, and whether a success concludes the turn.
+ */
+ execute(input: ToolBatchInput): Promise
+}
+```
+
## 执行：可扩展的 waterfall（瀑布式事件）加单调策略
-`ctx.tools.execute()` 接受由调用方拥有且包含必需 readonly `signal` 的 `ToolExecutionInput`，将其解析后的 JSON 参数一次性物化为流水线拥有的 `ToolExecution`，然后让调用依次经过 `tools/pre-execute`（可重排的 allow/deny/ask waterfall）→ 已注册的单调 guard → `tools/execute`（环绕分派包装层）→ `projectContent` → `tools/post-execute`（检查/替换结果）→ 可选且由定义拥有的 `finalizeContent` → `tools/result`（不可变的权威结果）。只有 `tools/execute` 视图可以替换必需的 signal。最终产出为 `ToolExecutionResult`。
+内置执行器把解析后的 `ToolExecutionInput` 交给共享 `ToolExecutionPipeline`。流水线负责参数快照、执行身份、策略瀑布、工具分发和最终结果通知，每次返回一个 `ToolExecutionResult`。自定义执行器可以独立实现这些行为；公开的 `ToolExecutor` 只要求工具描述和批次执行方法。
```ts type-equiv
/** Opaque call identity that permits correlation without exposing mutable execution state. */
@@ -188,8 +270,8 @@ type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]: true }
```ts type-equiv
/**
- * Caller-supplied description of one tool call. {@link ToolRuntime.execute}
- * adds the registry-owned token to form a pipeline {@link ToolExecution};
+ * Parsed input to the shared invocation pipeline. The pipeline
+ * adds its own token to form a {@link ToolExecution};
* callers do not choose that token.
*/
interface ToolExecutionInput {
@@ -213,7 +295,7 @@ interface ToolExecutionInput {
* The token also marks the call as a transport sub-dispatch rather than a
* model-direct call: under `mode: 'ptc'`, only calls WITH a parent may
* execute a native tool name — a model-direct call (no parent) is denied as
- * `UNKNOWN_TOOL` before the policy pipeline. See {@link ToolRuntime.execute}.
+ * `UNKNOWN_TOOL` before the policy pipeline.
*/
readonly parent?: ToolExecutionToken
/** Required caller-owned cancellation for this invocation. */
@@ -225,7 +307,7 @@ interface ToolExecutionInput {
```ts type-equiv
/**
- * Runtime context handed to a tool implementation after the registry has
+ * Runtime context handed to a tool implementation after the executor has
* accepted a {@link ToolExecution}. {@link deferContext} attaches context to
* this execution's own result — a composite tool ferries nested-dispatch
* context back to the outer result, and a leaf tool may mint a fresh
@@ -294,16 +376,16 @@ interface PtcDispatchLog {
```ts type-equiv
/**
- * One pending tool call inside the registry pipeline. Parsed arguments cross
+ * One pending tool call inside the executor pipeline. Parsed arguments cross
* one lossless-JSON materialization boundary before policy and are deep-frozen;
- * call identity, the caller signal, and the registry-assigned {@link token} are
- * readonly. The registry freezes the complete object before `tools/result`
+ * call identity, the caller signal, and the executor-assigned {@link token} are
+ * readonly. The executor freezes the complete object before `tools/result`
* observers run.
*/
interface ToolExecution extends ToolExecutionInput {
/** Root model-requested call, resolved for every root and nested execution. */
readonly rootCallId: ToolCallId
- /** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
+ /** Executor-assigned identity shared with nested calls only as their opaque `parent` token. */
readonly token: ToolExecutionToken
}
```
@@ -312,7 +394,7 @@ interface ToolExecution extends ToolExecutionInput {
/**
* Around-dispatch view of a {@link ToolExecution}. A `tools/execute` wrapper
* may replace the signal for its delegated lifetime, but it cannot remove it.
- * The registry fuses every replacement with the captured caller signal.
+ * The executor fuses every replacement with the captured caller signal.
*/
interface ToolDispatchExecution extends Omit {
/** Cancellation signal visible to the next wrapper or tool body. */
@@ -501,26 +583,13 @@ type ObjectJsonSchema = JsonSchemaNode & { type: 'object' }
Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
+
-### `ctx.tools` — `ToolRuntime`
+### `ctx.tools` — `ToolsService`
-Tool registry and execution pipeline. Scoped registrations shadow globals; one visibility resolver feeds presentation, lookup, and dispatch.
+Concrete tool registry and scoped executor dispatcher.
```ts cordis-catalog
-/**
- * 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.
- *
- * Scoped 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.
- * @param mode - the presentation the covered agents' models see.
- * @returns the exact disposer that restores the deployment default.
- */
-presentAs(mode: ToolPresentationMode): () => void
-
/**
* Register globally or in the calling agent scope. Scoped tools shadow
* globals; duplicates within one layer and the reserved `run_code` name fail.
@@ -538,18 +607,6 @@ register(definition: ToolDefinition): () => void
*/
restrict(filter: ToolRestriction): () => void
-/**
- * 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.
- * @param guard - synchronous check; a returned string denies the execution.
- * @returns the exact disposer that unregisters the guard.
- */
-guard(guard: ToolGuard): () => void
-
/**
* Look up a tool as one scope sees it (scoped
* shadows global; a restricted-away global reads as absent). Presenters pass
@@ -561,6 +618,13 @@ guard(guard: ToolGuard): () => void
*/
get(name: string, scope?: ScopeKey): ToolDefinition | undefined
+/**
+ * Read the visible capability definitions for descriptions and program bindings.
+ * @param scope - viewing Agent or preset; omitted selects the global view.
+ * @returns definitions after scoped shadowing and restrictions.
+ */
+definitions(scope?: ScopeKey): readonly ToolDefinition[]
+
/**
* Project visible definitions onto the allowlisted model-facing schema fields,
* excluding execution and presentation callbacks.
@@ -570,29 +634,33 @@ get(name: string, scope?: ScopeKey): ToolDefinition | undefined
schemas(scope?: ScopeKey): ToolSchema[]
/**
- * 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.
- * @param exec - call name, parsed arguments, and optional agent scope.
- * @returns the fail-closed scheduling mode.
+ * Provide the executor for the calling scope; an unscoped contribution is the deployment default.
+ * @param executor - initialized provider owned by the contributing plugin.
+ * @returns the effect disposer. Unloading leaves the selection unavailable until it is replaced.
*/
-executionMode(exec: ToolExecutionInput): ToolExecutionMode
+setExecutor(executor: ToolExecutor): () => void
/**
- * 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.
- * @param exec - the typed same-process call input. The registry assigns its
- * correlation token before policy begins.
- * @returns the materialized final result.
+ * Delegate a raw call batch to its Agent's provider or the deployment default.
+ * Select at dispatch; accepted batches settle through that provider even if it unloads.
+ * @param input - original calls, optional owning Agent, and optional logging step.
+ * @returns the selected executor's settled batch; unavailable selections reject.
*/
-async execute(exec: ToolExecutionInput): Promise
+async execute(input: ToolBatchInput): Promise
+
+/**
+ * Register a monotonic denial in the calling scope.
+ * @param guard - evaluated after extensible pre-execute policy by the shared pipeline.
+ * @returns the effect disposer that removes this guard.
+ */
+guard(guard: ToolGuard): () => void
+
+/**
+ * Check global and inherited guards after pre-execute policy and approval resolve.
+ * @param exec - invocation whose guards are checked before dispatch.
+ * @returns the first denial reason, or undefined when no guard denies.
+ */
+checkGuards(exec: ToolExecution): string | undefined
```
Types: [ScopeKey](scope.zh.md)
@@ -607,22 +675,19 @@ Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index
#### `tools/change` — emit
-A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only). An UNFILTERED registry-subject notification, deliberately not scope-filtered dispatch: a global change concerns every agent's next assembly, so a scoped listener subscribing here sees every change, not just its own scope's.
+A tool or executor was registered or unregistered, or a scoped restriction changed. Unfiltered registry notification: scoped listeners receive changes from every scope because a global contribution can affect every agent's next assembly.
```ts cordis-catalog
/**
- * A tool was registered or unregistered, or a scoped restriction changed
- * (the available tool set changed — possibly for one scope only). An
- * UNFILTERED registry-subject notification, deliberately not scope-filtered
- * dispatch: a global change concerns every agent's next assembly, so a
- * scoped listener subscribing here sees every change, not just its own
- * scope's.
+ * A tool or executor was registered or unregistered, or a scoped restriction changed.
+ * Unfiltered registry notification: scoped listeners receive changes from every
+ * scope because a global contribution can affect every agent's next assembly.
* @mode emit
*/
'tools/change'(): void
```
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -641,12 +706,12 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
* @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
* @mode waterfall
*/
-'tools/execute'(this: Scoped, exec: ToolDispatchExecution, next: () => Promise): Promise
+'tools/execute'(this: Scoped, exec: ToolDispatchExecution, next: () => Promise): Promise
```
Types: [Scoped](scope.zh.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -666,12 +731,12 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
* @param result - the dispatch outcome a listener may accept, replace, or block.
* @mode waterfall
*/
-'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise
+'tools/post-execute'(this: Scoped, exec: ToolExecution, result: Readonly, next: () => Promise): Promise
```
Types: [Scoped](scope.zh.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -690,12 +755,12 @@ Allow, deny, cancel, or ask before dispatch. `next()` delegates to allow; `cance
* @param exec - the pending call (name, parsed arguments, caller agent).
* @mode waterfall
*/
-'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
+'tools/pre-execute'(this: Scoped, exec: ToolExecution, next: () => Promise): Promise
```
Types: [Scoped](scope.zh.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
@@ -717,12 +782,12 @@ Allow a listener to replace content in the DURABLE LOG COPY of one `run_code` su
* @param dispatch - the parent execution, sub-call identity, and the settled content to log.
* @mode waterfall
*/
-'tools/ptc-dispatch-log'(this: Scoped, dispatch: PtcDispatchLog, next: () => Promise): Promise
+'tools/ptc-dispatch-log'(this: Scoped, dispatch: PtcDispatchLog, next: () => Promise): Promise
```
Types: [ContentBlock](llm-streaming.zh.md) · [Scoped](scope.zh.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tool-executor-ptc/src/types.ts`](../../packages/core/tool-executor-ptc/src/types.ts)
@@ -738,10 +803,10 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
* @param result - a deep-frozen snapshot of the final returned result.
* @mode emit
*/
-'tools/result'(this: Scoped, exec: Readonly, result: Readonly): undefined
+'tools/result'(this: Scoped, exec: Readonly, result: Readonly): undefined
```
Types: [Scoped](scope.zh.md)
-Source: [`packages/core/tools/src/index.ts`](../../packages/core/tools/src/index.ts)
+Source: [`packages/core/tools/src/events.ts`](../../packages/core/tools/src/events.ts)
diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml
index 4710703fe5..1204706b45 100644
--- a/docs/tool-catalog.i18n.yaml
+++ b/docs/tool-catalog.i18n.yaml
@@ -9,8 +9,8 @@
en: 6cc2cd9ced70bb09
zh: 1c0e6cb4ba2ed637
/tool-schema-catalog/tool-package-map:
- en: e72ad7af437fa362
- zh: d8f3683a4efe01b0
+ en: 9a7a2e1344b75e80
+ zh: e5e8857de37f012d
/tool-schema-catalog/deepseek-ai-dsh-plugin-manager:
en: e0143916bb634762
zh: e0143916bb634762
@@ -60,14 +60,14 @@
en: e713a4a11a15d13c
zh: e713a4a11a15d13c
/tool-schema-catalog/deepseek-ai-dsh-tool-ask-user/ask-user-question:
- en: 055268ba4dcd32f9
- zh: a1a3c4bfcbf698ed
-/tool-schema-catalog/deepseek-ai-dsh-tools:
- en: 76fbbf0fe38aef10
- zh: 76fbbf0fe38aef10
-/tool-schema-catalog/deepseek-ai-dsh-tools/run-code:
- en: a2368a9d8136276e
- zh: d1a4918fc45a7c87
+ en: 2f86adf8ae823afb
+ zh: a5dad3d821e75e55
+/tool-schema-catalog/deepseek-ai-dsh-tool-executor-ptc:
+ en: 8c8643ef46fd075f
+ zh: 8c8643ef46fd075f
+/tool-schema-catalog/deepseek-ai-dsh-tool-executor-ptc/run-code:
+ en: a5d49232a604a2fb
+ zh: 720040d11a3e31c2
/tool-schema-catalog/deepseek-ai-dsh-plan-mode:
en: b500b530845e26a9
zh: b500b530845e26a9
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index cfa5192198..f9d1676beb 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -20,7 +20,7 @@ This table connects model-visible tool names to the plugin package and service s
| `@deepseek-ai/dsh-mcp-resources` | `list_mcp_resource_templates`, `list_mcp_resources`, `read_mcp_resource` | `ctx.tools`, `ctx.mcpResources` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` | `stagehand_act`, `stagehand_extract`, `stagehand_navigate`, `stagehand_observe`, `stagehand_screenshot`, `stagehand_tabs` | `ctx.browserUse`, `ctx.agents`, `ctx.tools`, `ctx.systemPrompt` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`, `ctx.userQuestions` | `tool/call`, `tool/result after an answer or timeout`, `late user/message` | - | ask_user_question keeps the original blocking behavior by default; set `mode: timed` to opt into a foreground timeout and pending result while the question remains answerable. In timed mode, `timeout: -1` keeps that call blocking indefinitely. |
-| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.workingDirectory (Agent executions)`, `ctx.tools`, `ctx.ptcRuntime (execution time)`, `ctx.systemPrompt` | `tool/call`, `one tool/ptc-dispatch-start + tool/ptc-dispatch pair per bridged sub-call`, `tool/result` | - | Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: ptc` (see the PTC mode Agent Note). Under `ptc` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result. |
+| `@deepseek-ai/dsh-tool-executor-ptc` | `run_code` | `ctx.workingDirectory (Agent executions)`, `ctx.tools`, `ctx.ptcRuntime`, `ctx.systemPrompt` | `tool/call`, `one tool/ptc-dispatch-start + tool/ptc-dispatch pair per bridged sub-call`, `tool/result` | - | The PTC executor exposes only run_code to the model and declares other visible capabilities in a generated SDK in the runtime’s language. Program bindings enter the shared guarded tool pipeline in submission order; concurrency-safe bodies overlap up to maxParallelSubCalls, and nested results remain linked to the outer program. |
| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`, `ctx.systemPrompt`, `ctx.userQuestions (execution time, opportunistic)` | `tool/call`, `plan/mode inactive on an approved review`, `tool/result` | - | exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-questions seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary. |
| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.workingDirectory`, `ctx.tools`, `ctx.shell`, `ctx.systemPrompt`, `ctx.shellEnv`, `ctx.jobs for run_in_background and the job-backed foreground path` | `tool/call`, `tool/result` | - | The bash tool is the model-facing consumer of the bash executor seam. With a job registry composed every call registers with the generic `ctx.jobs` runtime as it starts, collected/stopped through the `job_*` tools from `@deepseek-ai/dsh-tool-jobs`; without one, or with `enableRunInBackground: false`, the tool registers a foreground-only schema without the `run_in_background` parameter. |
| `@deepseek-ai/dsh-tool-present` | `present` | `ctx.workingDirectory`, `ctx.tools`, `ctx.fs`, `ctx.sessionProjections` | `tool/call`, `deliverables/presented after a successful final result`, `tool/result` | - | Deliveries belong to the calling Session; Web ui-deliverables supplies source-file opening and cards. |
@@ -570,13 +570,13 @@ Source: [`packages/interaction/tool-ask-user/src/index.ts`](../packages/interact
ask_user_question keeps the original blocking behavior by default; set `mode: timed` to opt into a foreground timeout and pending result while the question remains answerable. In timed mode, `timeout: -1` keeps that call blocking indefinitely.
-
+
-## `@deepseek-ai/dsh-tools`
+## `@deepseek-ai/dsh-tool-executor-ptc`
### `run_code`
-Execute a TypeScript program against the available tools. Takes two required arguments: `code`, the program to execute, and `description`, a short summary of what the program does. Call tools as `await tools.name(args)` per the declarations in the system prompt. Curate the program output. Image-bearing subtool results are attached after the run.
+Execute a TypeScript program against the available tools. Takes two required arguments: `code`, the BODY of an async function (erasable syntax only; top-level `await` and `return` work), and `description`, a short summary of what the program does. Call tools as `await tools.name(args)` per the declarations in the system prompt. Only what you print or return is program output — curate it. Image-bearing subtool results are attached after the run. The program is the body of an async TypeScript function; only erasable syntax is accepted, with no enum or namespaces. Type annotations are advisory. Top-level await and return are supported. Emit output with console.log(...) or return a lossless JSON value. Only printed values and the returned value become program output. Each call runs in a fresh Node process. Node APIs are available through await import(...). Relative paths use the supplied working directory; process.env starts empty. Direct filesystem access follows this execution's sandbox policy. Each program starts in the Session's current directory. Running programs keep their initial directory. A sandbox escalation approves this complete program for one execution only. Nested tools retain their own policies and approvals. Request wider access only after evidence of a denial. Earlier effects may already have completed: inspect them before explicitly retrying. Programs are never replayed automatically.
```json
{
@@ -584,7 +584,7 @@ Execute a TypeScript program against the available tools. Takes two required arg
"properties": {
"code": {
"type": "string",
- "description": "The TypeScript program to execute, following this tool's execution instructions."
+ "description": "The program: the body of an async TypeScript function."
},
"description": {
"type": "string",
@@ -592,7 +592,7 @@ Execute a TypeScript program against the available tools. Takes two required arg
},
"timeoutMs": {
"type": "number",
- "description": "Positive elapsed-time budget in milliseconds, capped by the deployment maximum."
+ "description": "Positive elapsed-time budget in milliseconds, including nested tool and approval waits. Default 120000; capped at 600000. Zero does not disable the deadline."
},
"sandbox_permissions": {
"type": "string",
@@ -614,9 +614,9 @@ Execute a TypeScript program against the available tools. Takes two required arg
}
```
-Source: [`packages/core/tools/src/ptc.ts`](../packages/core/tools/src/ptc.ts)
+Source: [`packages/core/tool-executor-ptc/src/ptc.ts`](../packages/core/tool-executor-ptc/src/ptc.ts)
-Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: ptc` (see the PTC mode Agent Note). Under `ptc` it is the registry's only wire contribution; the other visible capabilities are declared in a generated SDK section in the loaded runtime's language, and a program calls them through bindings scheduled under the native concurrency contract (submission-ordered starts and policy; concurrency-safe bodies overlap up to `maxParallelSubCalls`) that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.
+The PTC executor exposes only run_code to the model and declares other visible capabilities in a generated SDK in the runtime’s language. Program bindings enter the shared guarded tool pipeline in submission order; concurrency-safe bodies overlap up to maxParallelSubCalls, and nested results remain linked to the outer program.
diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md
index fd304d6ddc..91e4dd57dd 100644
--- a/docs/tool-catalog.zh.md
+++ b/docs/tool-catalog.zh.md
@@ -24,7 +24,7 @@
| `@deepseek-ai/dsh-mcp-resources` | `list_mcp_resource_templates`, `list_mcp_resources`, `read_mcp_resource` | `ctx.tools`, `ctx.mcpResources` | `tool/call`, `tool/result` | - | - |
| `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` | `stagehand_act`、`stagehand_extract`、`stagehand_navigate`、`stagehand_observe`、`stagehand_screenshot`、`stagehand_tabs` | `ctx.browserUse`、`ctx.agents`、`ctx.tools`、`ctx.systemPrompt` | `tool/call`、`tool/result` | - | - |
| `@deepseek-ai/dsh-tool-ask-user` | `ask_user_question` | `ctx.tools`、`ctx.userQuestions` | `tool/call`、`tool/result after an answer or timeout`、`late user/message` | - | ask_user_question 默认保持原有阻塞行为；设置 `mode: timed` 后才启用前台超时与 pending 结果，同时问题仍可回答；timed 模式内 `timeout: -1` 让本次调用无限期阻塞。 |
-| `@deepseek-ai/dsh-tools` | `run_code` | `ctx.workingDirectory (Agent executions)`、`ctx.tools`、`ctx.ptcRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/ptc-dispatch-start + tool/ptc-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: ptc` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 PTC mode Agent Note）。在 `ptc` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 |
+| `@deepseek-ai/dsh-tool-executor-ptc` | `run_code` | `ctx.workingDirectory (Agent executions)`、`ctx.tools`、`ctx.ptcRuntime`、`ctx.systemPrompt` | `tool/call`、`one tool/ptc-dispatch-start + tool/ptc-dispatch pair per bridged sub-call`、`tool/result` | - | PTC 执行器只向模型公开 run_code，并在运行时语言生成的 SDK 中声明其他可见能力。程序绑定按提交顺序进入共享的受守卫工具流水线；并行安全的函数体最多重叠 maxParallelSubCalls 个，嵌套结果保持与外层程序关联。 |
| `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userQuestions (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 |
| `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.workingDirectory`、`ctx.tools`、`ctx.shell`、`ctx.systemPrompt`、`ctx.shellEnv`、`ctx.jobs for run_in_background and the job-backed foreground path` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。组合中有 job 注册表时，每次调用一启动就注册到通用 `ctx.jobs` 运行时，并通过 `job_*` 工具（来自 `@deepseek-ai/dsh-tool-jobs`）收集／停止；没有注册表或 `enableRunInBackground: false` 时，工具注册不带 `run_in_background` 参数的纯前台 schema。 |
| `@deepseek-ai/dsh-tool-present` | `present` | `ctx.workingDirectory`、`ctx.tools`, `ctx.fs`, `ctx.sessionProjections` | `tool/call`, `deliverables/presented 在成功的最终结果之后`, `tool/result` | - | 交付归调用方 Session 所有；Web ui-deliverables 提供源文件打开与卡片。 |
@@ -574,13 +574,13 @@
ask_user_question 默认保持原有阻塞行为；设置 `mode: timed` 后才启用前台超时与 pending 结果，同时问题仍可回答；timed 模式内 `timeout: -1` 让本次调用无限期阻塞。
-
+
-## `@deepseek-ai/dsh-tools`
+## `@deepseek-ai/dsh-tool-executor-ptc`
### `run_code`
-针对可用工具执行 TypeScript 程序。接受两个必填参数：`code`，要执行的程序；以及 `description`，简要说明该程序做什么。请根据系统提示词中的声明，以 `await tools.name(args)` 形式调用工具。请筛选程序输出。含图片的子工具结果会在运行结束后附加。
+针对可用工具执行 TypeScript 程序。接受两个必填参数：`code`，异步函数的函数体（仅限可擦除语法，支持顶层 `await` 和 `return`）；以及 `description`，简要说明程序做什么。请按系统提示词中的声明，以 `await tools.name(args)` 调用工具。只有打印或返回的内容构成程序输出，请筛选这些内容。含图片的子工具结果会在运行结束后附加。程序是异步 TypeScript 函数的函数体，只接受可擦除语法，不支持 enum 或 namespace。类型标注只作提示。支持顶层 await 和 return。使用 console.log(...) 或返回无损 JSON 值来输出。只有打印值和返回值成为程序输出。每次调用在新的 Node 进程中运行，可通过 await import(...) 使用 Node API。相对路径以传入的工作目录为准；process.env 初始为空。直接文件系统访问遵循本次执行的沙箱策略。每个程序从 Session 的当前目录启动，运行中保留初始目录。沙箱提权只为本次完整程序执行授权。嵌套工具保留自身策略与审批。只有在获得拒绝证据后才请求更宽访问。先前效果可能已经发生，请在显式重试前检查。程序不会自动重放。
```json
{
@@ -588,7 +588,7 @@ ask_user_question 默认保持原有阻塞行为；设置 `mode: timed` 后才
"properties": {
"code": {
"type": "string",
- "description": "The TypeScript program to execute, following this tool's execution instructions."
+ "description": "The program: the body of an async TypeScript function."
},
"description": {
"type": "string",
@@ -596,7 +596,7 @@ ask_user_question 默认保持原有阻塞行为；设置 `mode: timed` 后才
},
"timeoutMs": {
"type": "number",
- "description": "Positive elapsed-time budget in milliseconds, capped by the deployment maximum."
+ "description": "Positive elapsed-time budget in milliseconds, including nested tool and approval waits. Default 120000; capped at 600000. Zero does not disable the deadline."
},
"sandbox_permissions": {
"type": "string",
@@ -618,9 +618,9 @@ ask_user_question 默认保持原有阻塞行为；设置 `mode: timed` 后才
}
```
-来源：[`packages/core/tools/src/ptc.ts`](../packages/core/tools/src/ptc.ts)
+来源：[`packages/core/tool-executor-ptc/src/ptc.ts`](../packages/core/tool-executor-ptc/src/ptc.ts)
-在 `mode: ptc` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 PTC mode Agent Note）。在 `ptc` 下，它是注册表对协议格式的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。
+PTC 执行器只向模型公开 run_code，并在运行时语言生成的 SDK 中声明其他可见能力。程序绑定按提交顺序进入共享的受守卫工具流水线；并行安全的函数体最多重叠 maxParallelSubCalls 个，嵌套结果保持与外层程序关联。
diff --git a/docs/tool-execution-pipeline.i18n.yaml b/docs/tool-execution-pipeline.i18n.yaml
index 7269b198f5..0d35b299dd 100644
--- a/docs/tool-execution-pipeline.i18n.yaml
+++ b/docs/tool-execution-pipeline.i18n.yaml
@@ -6,5 +6,5 @@
en: 41d772192075e133
zh: 0eb190f00f396176
/tool-execution-pipeline:
- en: f2811b12640c6f8e
- zh: 9e0323523dcbb04c
+ en: a1103f6055f81a4b
+ zh: 6eefe6bfa59b1692
diff --git a/docs/tool-execution-pipeline.md b/docs/tool-execution-pipeline.md
index 53b7481183..bdb8152984 100644
--- a/docs/tool-execution-pipeline.md
+++ b/docs/tool-execution-pipeline.md
@@ -3,7 +3,7 @@
# Tool Execution Pipeline
-This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
+Built-in executors own raw batch parsing, scheduling, cancellation, and Session call/result logging. This graph shows where their shared invocation pipeline applies policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `projectContent` installs prepared content before post-execute; `finalizeContent` and `tools/result` run afterward.
```mermaid
flowchart TD
@@ -20,14 +20,15 @@ flowchart TD
owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result, tool/ptc-dispatch"]
project["ToolDefinition.projectContent
execution-prepared text and images"]
post["tools/post-execute waterfall
accept, block, replace, add context"]
- normalized["Registry outer normalization
pipeline/result snapshot throws become isError"]
+ normalized["Invocation pipeline normalization
pipeline/result snapshot throws become isError"]
finalize["ToolDefinition.finalizeContent
last content-only invariant"]
final["tools/result synchronous notification
frozen authoritative outcome"]
context["Active-batch additionalContexts FIFO
injected user/message after recorded tool results"]
toolResult["Session event: tool/result
single model-facing outcome"]
allResults["Tool batch settled
recorded tool/result events complete"]
presentResult["UI completed card
presentResult(args, result)"]
- model --> toolCall
+ executor["Selected ToolExecutor.execute
raw batch, Agent, optional logging step"]
+ model --> executor --> toolCall
toolCall --> presentCall
toolCall --> pre
pre -->|allow| guards
@@ -60,6 +61,6 @@ flowchart TD
allResults --> context
```
-Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The pipeline losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its ordered sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.
diff --git a/docs/tool-execution-pipeline.zh.md b/docs/tool-execution-pipeline.zh.md
index 89d2ba505e..823c5f62df 100644
--- a/docs/tool-execution-pipeline.zh.md
+++ b/docs/tool-execution-pipeline.zh.md
@@ -5,7 +5,7 @@
[English](tool-execution-pipeline.md) | 中文
-此图展示策略、钩子、沙箱、文件系统守卫、结果重写、最终结果观察和 UI 渲染在不改变循环的情况下何时运行。`tools/pre-execute` waterfall（瀑布式事件）首先运行，随后是单调守卫，然后运行 `tools/execute` 和 `tools/post-execute` waterfall；这三个 waterfall 可以改写一次调用。由定义自身控制的 `projectContent` 在执行后策略之前安装已准备内容；`finalizeContent` 和 `tools/result` 在此之后运行。
+内置执行器负责原始批次解析、调度、取消和 Session 调用／结果日志。此图展示其共享调用流水线如何执行策略、钩子、沙箱、文件系统守卫、结果改写、最终结果观测和 UI 呈现，而无需改动循环。`tools/pre-execute` 瀑布先执行，然后是单调守卫，再是 `tools/execute` 和 `tools/post-execute` 瀑布；三个瀑布可以转换调用。定义拥有的 `projectContent` 在后置策略之前安装准备好的内容，`finalizeContent` 和 `tools/result` 在之后执行。
```mermaid
flowchart TD
@@ -22,14 +22,15 @@ flowchart TD
owned["Tool-owned session events
todo/write, fs/observed, hook/invoked, hook/result, tool/ptc-dispatch"]
project["ToolDefinition.projectContent
execution-prepared text and images"]
post["tools/post-execute waterfall
accept, block, replace, add context"]
- normalized["Registry outer normalization
pipeline/result snapshot throws become isError"]
+ normalized["Invocation pipeline normalization
pipeline/result snapshot throws become isError"]
finalize["ToolDefinition.finalizeContent
last content-only invariant"]
final["tools/result synchronous notification
frozen authoritative outcome"]
context["Active-batch additionalContexts FIFO
injected user/message after recorded tool results"]
toolResult["Session event: tool/result
single model-facing outcome"]
allResults["Tool batch settled
recorded tool/result events complete"]
presentResult["UI completed card
presentResult(args, result)"]
- model --> toolCall
+ executor["Selected ToolExecutor.execute
raw batch, Agent, optional logging step"]
+ model --> executor --> toolCall
toolCall --> presentCall
toolCall --> pre
pre -->|allow| guards
diff --git a/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.i18n.yaml b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.i18n.yaml
new file mode 100644
index 0000000000..ed97c6a3df
--- /dev/null
+++ b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.i18n.yaml
@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.md
+/:
+ en: 3b1ca9e0f78709e0
+ zh: 13f23adcc722f319
+/mount-a-tool-executor:
+ en: de4970d25f6e3cf0
+ zh: 1c4d11dcb0d32322
+/mount-a-tool-executor/change:
+ en: 2adab658221d48a2
+ zh: 91573940e81bcba2
+/mount-a-tool-executor/migration:
+ en: 411860d06f1013ea
+ zh: 615e044545d89b55
diff --git a/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.md b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.md
new file mode 100644
index 0000000000..aac2697ee9
--- /dev/null
+++ b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.md
@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Tool execution modes move from dsh-tools configuration into explicit executor plugins."
+---
+
+# Mount a tool executor
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-tools` keeps tool registration and executor selection, but no longer accepts `mode` or `maxParallelSubCalls`. Native and PTC execution require `@deepseek-ai/dsh-tool-executor-native` or `@deepseek-ai/dsh-tool-executor-ptc`. Shipped profiles mount an executor; custom compositions must add one. The existing `dsh-agent-tool-presentation` selector remains supported but is deprecated.
+
+## Migration
+
+1. Keep the `dsh-tools` row and remove its execution configuration. Mount one native or PTC executor in the intended deployment or preset scope. For shipped profile patches, target the executor row instead of the `tools` row.
+2. Move `maxParallelSubCalls` to the PTC executor configuration. PTC still requires a compatible runtime. `agent-loop.maxParallelToolCalls` and saved overrides stay in place with default `10`. The loop forwards the current limit to each batch; live edits apply to the next batch instead of the next tool group.
+3. Custom executors implement `describe` and `execute`. Programmatic callers pass raw `calls` and `signal`, optional `agent`, and optional `log: { turn, step }`; read single-call outcomes from `results`. Omit `log` outside a committed model step.
+4. Import PTC SDK renderers and `CodeRunFailedError` from `@deepseek-ai/dsh-tool-executor-ptc`. Run a task with the selected interaction mode and confirm its tool results appear in the Session.
+5. Import `ToolExecutionPipeline` and `executeToolBatch` from `@deepseek-ai/dsh-tools/pipeline`. Complete calls, including single calls, use batches; custom schedulers call `prepare`, `dispatch`, and `complete` directly. Add `@deepseek-ai/dsh-tool-testkit` as a development dependency for tool fixtures and import them from that package. Neither is exported by the tool registry entry.
+6. Import `PtcDispatchLog` from the PTC executor package using `import type`. Detached Session readers use `@deepseek-ai/dsh-tool-executor-ptc/types` for durable dispatch events. Live PTC policy and message-source declarations remain on the executor package entry.
diff --git a/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.zh.md b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.zh.md
new file mode 100644
index 0000000000..f8161ebf9c
--- /dev/null
+++ b/docs/upgrade-guide/v0.2.1-alpha.4/tool-executor-plugins/guide.zh.md
@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "工具执行模式从 dsh-tools 配置移至显式执行器插件。"
+---
+
+# 挂载工具执行器
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-tools` 保留工具注册和执行器选择，但不再接受 `mode` 或 `maxParallelSubCalls`。原生和 PTC 执行分别要求 `@deepseek-ai/dsh-tool-executor-native` 或 `@deepseek-ai/dsh-tool-executor-ptc`。内置 profile 已挂载执行器，自定义组合必须添加一个。现有 `dsh-agent-tool-presentation` 选择器仍受支持，但已弃用。
+
+## 迁移
+
+1. 保留 `dsh-tools` 条目并移除其执行配置。在目标部署或预设作用域挂载一个原生或 PTC 执行器。内置 profile 的补丁应修改执行器条目，而非 `tools` 条目。
+2. 把 `maxParallelSubCalls` 移到 PTC 执行器配置。PTC 仍要求兼容的运行时。`agent-loop.maxParallelToolCalls` 和已保存的覆盖值保留原位，默认值为 `10`。循环向每个批次传入当前上限；实时修改从下一个批次生效，不再从下一个工具组生效。
+3. 自定义执行器实现 `describe` 和 `execute`。程序调用方传入原始 `calls` 和 `signal`，以及可选的 `agent` 和 `log: { turn, step }`；从 `results` 读取单次结果。不属于已提交模型步骤的调用应省略 `log`。
+4. 从 `@deepseek-ai/dsh-tool-executor-ptc` 导入 PTC SDK 渲染器和 `CodeRunFailedError`。用所选交互模式运行任务，确认工具结果出现在 Session 中。
+5. 从 `@deepseek-ai/dsh-tools/pipeline` 导入 `ToolExecutionPipeline` 和 `executeToolBatch`。完整执行（包括单次调用）使用批次；自定义调度器直接调用 `prepare`、`dispatch` 和 `complete`。把 `@deepseek-ai/dsh-tool-testkit` 添加为开发依赖，并从该包导入工具 fixture。工具注册表主入口不再导出这些成员。
+6. 使用 `import type` 从 PTC 执行器包导入 `PtcDispatchLog`。独立 Session 读取者通过 `@deepseek-ai/dsh-tool-executor-ptc/types` 获取持久化分派事件；PTC 实时策略与消息来源声明由执行器包主入口提供。
diff --git a/packages/core/agent-loop/README.i18n.yaml b/packages/core/agent-loop/README.i18n.yaml
index 0bbdb05d37..27e4818160 100644
--- a/packages/core/agent-loop/README.i18n.yaml
+++ b/packages/core/agent-loop/README.i18n.yaml
@@ -9,8 +9,8 @@
en: b711ded29c7b9a17
zh: cbccba927743f35f
/deepseek-ai-dsh-agent-loop/summary:
- en: 9256331cd3baf930
- zh: 02b4c10cf3286eb3
+ en: b2971780b74fd785
+ zh: 05a3043f49fb646d
/deepseek-ai-dsh-agent-loop/table-of-contents:
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
@@ -18,14 +18,14 @@
en: 35a960c0100a6aa4
zh: 438e133fb4c24a9e
/deepseek-ai-dsh-agent-loop/use-this-package/configure-declarative-agents:
- en: 96295035babf4f90
- zh: 8848f9497019ee63
+ en: 600bbdfbeb743521
+ zh: 7e1dc69e728fa2aa
/deepseek-ai-dsh-agent-loop/use-this-package/create-or-resume-agents-programmatically:
en: 82ec792637e8e57f
zh: e32f8ec5ee17afcf
/deepseek-ai-dsh-agent-loop/use-this-package/what-a-step-does:
- en: 15ce4783b53532a2
- zh: b04a18337281237a
+ en: b789acbbfd6a3094
+ zh: 85b4d093ae23ce7d
/deepseek-ai-dsh-agent-loop/understand-the-implementation:
en: ce7e776e9d516bdb
zh: 59d2751743db7795
@@ -36,8 +36,8 @@
en: b3b3f0ad930961c3
zh: f281e27136e686bc
/deepseek-ai-dsh-agent-loop/understand-the-implementation/source-map:
- en: 2a8b93869eb5a2f9
- zh: ddab8e738d188a61
+ en: ec2bf804bd1a5439
+ zh: 316e767507e859ef
/deepseek-ai-dsh-agent-loop/understand-the-implementation/creation-and-teardown:
en: d079cf181ece9267
zh: 047f76fecfc5497c
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 62dcd35a92..80b8705e0b 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
## Summary
-`dsh-agent-loop` creates fresh agents or resumes persisted sessions, then drives each turn through model requests, streamed responses, tool execution, and durable session history. Mount it for standard agent compositions; declarative entries start agents at boot, while the public `ctx.agents` API supports programmatic creation and resume. `maxParallelToolCalls` limits concurrent parallel-safe calls, and exclusive calls retain ordering. Cancellation preserves streamed text already delivered to the user. Choose a custom `Agent` implementation only when the standard "call model, run tools, repeat" lifecycle is insufficient.
+`dsh-agent-loop` creates fresh agents or resumes persisted sessions, then drives each turn through model requests, streamed responses, tool execution, and durable session history. Mount it for standard agent compositions; declarative entries start agents at boot, while the public `ctx.agents` API supports programmatic creation and resume. The selected tool executor owns dispatch, concurrency, cancellation, and tool logging. Cancellation preserves streamed text already delivered to the user. Choose a custom `Agent` implementation only when the standard "call model, run tools, repeat" lifecycle is insufficient.
## Table of Contents
@@ -34,7 +34,6 @@ Agents declared in the config start automatically when the plugin loads. Each en
```yaml
- name: '@deepseek-ai/dsh-agent-loop'
config:
- maxParallelToolCalls: 10
agents:
- id: 'main'
provider: deepseek
@@ -45,7 +44,6 @@ Agents declared in the config start automatically when the plugin loads. Each en
| Field | Default | Meaning |
|---|---|---|
-| `maxParallelToolCalls` | `10` | Parallel-safe tool calls in flight per step; `1` is serial |
| `agents[].id` | required | Stable label; a fresh session mints `${id}-session-` unless `sessionId` is set |
| `agents[].provider` / `agents[].model` | — | Model route; both required before dispatch |
| `agents[].reasoningEffort` | — | Non-empty initial reasoning effort; `agent/request` may override it |
@@ -54,7 +52,7 @@ Agents declared in the config start automatically when the plugin loads. Each en
| `agents[].sessionId` | — | Exact identity: first use creates, a remount resumes materialized history |
| `agents[].resumeSessionId` | — | Load this persisted session instead of creating one; mutually exclusive with `sessionId` |
-The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-agent-loop) lists every accepted field. `maxParallelToolCalls` is a volatile Config field sampled for the next tool group; `agents` remains startup configuration.
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-agent-loop) lists every accepted field. `maxParallelToolCalls` remains a volatile positive-integer Config field with default `10`; `1` selects serial execution. The loop passes its current value to each batch's `execute()` call, taking precedence over executor configuration. Live edits apply to the next batch; `agents` remains startup configuration.
### Create or resume agents programmatically
@@ -72,7 +70,7 @@ Every inbox mutation commits one normalized `agent/inbox/spliced` event. The pro
### What a step does
-Each step sends the session's derived history — with the latest non-empty `system/message` node as the effective prompt, or no system messages when the rendered prompt is empty — and its visible tool schemas; the model's tool calls run through the guarded tool pipeline and every accepted fact is appended to the session log before the next step derives from it. Parallel-safe calls may overlap up to `maxParallelToolCalls`; exclusive calls run alone as ordering barriers. Cancellation is cooperative: `agent.cancel()` aborts the current activity and, unless `keepInbox` is set, clears pending work; a cancelled stream finalizes the text already delivered to the user.
+Each step sends the session's derived history — with the latest non-empty `system/message` node as the effective prompt, or no system messages when the rendered prompt is empty — and its visible tool schemas; the model's tool calls run through the guarded tool pipeline and every accepted fact is appended to the session log before the next step derives from it. The loop passes the complete raw call batch to `ctx.tools.execute()`; built-in executors preserve model-order results and exclusive barriers. Cancellation is cooperative: `agent.cancel()` aborts the current activity and, unless `keepInbox` is set, clears pending work; a cancelled stream finalizes the text already delivered to the user.
-----
@@ -101,9 +99,7 @@ The loop deep-freezes each derived message identity on its first request and reu
| [`src/index.ts`](src/index.ts) | Plugin entry: `AgentLoop` service, config schema, declarative agent startup, factory registration |
| [`src/agent.ts`](src/agent.ts) | The concrete `ReactLoopAgent` driver: inbox, turn/step machine, cancellation |
| [`src/inbox.ts`](src/inbox.ts) | Package-internal `ReactLoopInbox`: durable projection, structural commands, and loop-only claim state |
-| [`src/tool-calls.ts`](src/tool-calls.ts) | Tool scheduling: exclusive barriers and the bounded parallel pool |
| [`src/runtime-context.ts`](src/runtime-context.ts) | Per-step runtime-context snapshot handling |
-| [`src/constants.ts`](src/constants.ts) | `DEFAULT_MAX_PARALLEL_TOOL_CALLS` |
### Creation and teardown
diff --git a/packages/core/agent-loop/README.zh.md b/packages/core/agent-loop/README.zh.md
index ee355a328d..64486dccd9 100644
--- a/packages/core/agent-loop/README.zh.md
+++ b/packages/core/agent-loop/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
## 概述
-`dsh-agent-loop` 创建全新 agent 或恢复持久化会话，随后通过模型请求、流式响应、工具执行和持久会话历史驱动每个轮次。标准 agent 组合应挂载本包；声明式条目会在启动时启动 agent，公开的 `ctx.agents` API 则支持以编程方式创建和恢复 agent。`maxParallelToolCalls` 限制同时运行的并行安全调用数量，独占调用保留顺序。取消会保留已经流式交付给用户的文本。只有标准的「调用模型、运行工具、重复」生命周期无法满足需求时，才应选择自定义 `Agent` 实现。
+`dsh-agent-loop` 创建全新 agent 或恢复持久化会话，随后通过模型请求、流式响应、工具执行和持久会话历史驱动每个轮次。标准 agent 组合应挂载本包；声明式条目会在启动时启动 agent，公开的 `ctx.agents` API 则支持以编程方式创建和恢复 agent。所选工具执行器负责分发、并发、取消和工具日志。取消会保留已经流式交付给用户的文本。只有标准的「调用模型、运行工具、重复」生命周期无法满足需求时，才应选择自定义 `Agent` 实现。
## 目录
@@ -34,7 +34,6 @@ kind: "package-reference"
```yaml
- name: '@deepseek-ai/dsh-agent-loop'
config:
- maxParallelToolCalls: 10
agents:
- id: 'main'
provider: deepseek
@@ -45,7 +44,6 @@ kind: "package-reference"
| 字段 | 默认值 | 含义 |
|---|---|---|
-| `maxParallelToolCalls` | `10` | 每个步骤同时在途的并行安全工具调用数；`1` 为串行 |
| `agents[].id` | 必填 | 稳定标签；未设置 `sessionId` 时，全新会话会生成 `${id}-session-` |
| `agents[].provider` / `agents[].model` | — | 模型路由；分发前两者都必须存在 |
| `agents[].reasoningEffort` | — | 非空的初始推理强度；`agent/request` 可以覆盖它 |
@@ -54,7 +52,7 @@ kind: "package-reference"
| `agents[].sessionId` | — | 确切身份：首次使用创建，重新挂载时恢复已实体化的历史 |
| `agents[].resumeSessionId` | — | 加载这个持久化会话而不是创建新会话；与 `sessionId` 互斥 |
-生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-agent-loop) 列出所有接受的字段。`maxParallelToolCalls` 是在下一个工具组开始时读取的 volatile Config 字段；`agents` 仍是启动配置。
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-agent-loop) 列出所有接受的字段。`maxParallelToolCalls` 仍是 volatile 正整数 Config 字段，默认值为 `10`；`1` 表示串行执行。循环在每个批次调用 `execute()` 时传入当前值，其优先级高于执行器配置。实时修改从下一个批次生效；`agents` 仍是启动配置。
### 以编程方式创建或恢复 agent
@@ -72,7 +70,7 @@ const handle = await ctx.agents.create({
### 一个步骤做什么
-每个步骤都会发送会话的派生历史——最新的非空 `system/message` 节点是有效提示词，渲染提示词为空时则没有系统消息——及其可见工具 schema；模型的工具调用经过受守卫的工具流水线，每个被接纳的事实都会在下一步据此派生之前追加到会话日志。并行安全调用最多可重叠 `maxParallelToolCalls` 个；独占调用单独运行并构成排序屏障。取消是协作式的：`agent.cancel()` 中止当前活动，并在未设置 `keepInbox` 时清除待处理工作；被取消的流会终结已送达用户的文本。
+每个步骤都会发送会话的派生历史——最新的非空 `system/message` 节点是有效提示词，渲染提示词为空时则没有系统消息——及其可见工具 schema；模型的工具调用经过受守卫的工具流水线，每个被接纳的事实都会在下一步据此派生之前追加到会话日志。循环把完整的原始调用批次传给 `ctx.tools.execute()`；内置执行器保留模型顺序的结果和独占屏障。取消是协作式的：`agent.cancel()` 中止当前活动，并在未设置 `keepInbox` 时清除待处理工作；被取消的流会终结已送达用户的文本。
-----
@@ -101,9 +99,7 @@ const handle = await ctx.agents.create({
| [`src/index.ts`](src/index.ts) | 插件入口：`AgentLoop` 服务、配置 schema、声明式 agent 启动、工厂注册 |
| [`src/agent.ts`](src/agent.ts) | 具体 `ReactLoopAgent` 驱动器：收件箱、轮次／步骤状态机、取消 |
| [`src/inbox.ts`](src/inbox.ts) | 包内部的 `ReactLoopInbox`：持久投影、结构化命令与仅供循环使用的领取状态 |
-| [`src/tool-calls.ts`](src/tool-calls.ts) | 工具调度：独占屏障与有界并行池 |
| [`src/runtime-context.ts`](src/runtime-context.ts) | 逐步骤运行时上下文快照处理 |
-| [`src/constants.ts`](src/constants.ts) | `DEFAULT_MAX_PARALLEL_TOOL_CALLS` |
### 创建与拆除
diff --git a/packages/core/agent-tool-presentation/README.i18n.yaml b/packages/core/agent-tool-presentation/README.i18n.yaml
index a1ca4c3c4e..2a2ed58937 100644
--- a/packages/core/agent-tool-presentation/README.i18n.yaml
+++ b/packages/core/agent-tool-presentation/README.i18n.yaml
@@ -6,22 +6,22 @@
en: 1c67fea11cb4a325
zh: 7dc1256148273b02
/deepseek-ai-dsh-agent-tool-presentation:
- en: e3bfa19f60197528
- zh: c8e9adfb80141de2
+ en: db5b1de2af3a6f37
+ zh: e4b10a1484df8b29
/deepseek-ai-dsh-agent-tool-presentation/summary:
- en: 9c67450fb880d639
- zh: 74b88ce5e4ac1e64
+ en: ae29d1ab4c22566f
+ zh: c363959591dce513
/deepseek-ai-dsh-agent-tool-presentation/table-of-contents:
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
/deepseek-ai-dsh-agent-tool-presentation/use-this-package:
- en: ed4e4b103ea482bf
- zh: 41754979babb3649
+ en: 9ad88c3b4d6e389e
+ zh: f5d78ac15598aabb
/deepseek-ai-dsh-agent-tool-presentation/use-this-package/add-the-row-to-a-preset:
en: 1550e3dcc5a3aa1e
zh: 47b2d1e0e3e3cbf2
/deepseek-ai-dsh-agent-tool-presentation/use-this-package/what-ptc-mode-requires:
- en: efaec011a8267e5f
+ en: d5004b2caa31b245
zh: 32619d7e03c7c2ac
/deepseek-ai-dsh-agent-tool-presentation/use-this-package/one-presentation-per-agent:
en: 46bf80f051175567
@@ -30,17 +30,17 @@
en: ce7e776e9d516bdb
zh: 59d2751743db7795
/deepseek-ai-dsh-agent-tool-presentation/understand-the-implementation/design-concept:
- en: 6f8bb6bd853cbc13
- zh: 422fca4b20b79fbd
+ en: 0fbb3dd32193e54c
+ zh: 5b3835aef5115bb7
/deepseek-ai-dsh-agent-tool-presentation/understand-the-implementation/source-map:
- en: 2a0a0fb2dfdfce75
- zh: c425560fedcdb31a
+ en: 89ecdb3d5d032e7f
+ zh: 64ae2feb4344c679
/deepseek-ai-dsh-agent-tool-presentation/understand-the-implementation/behavior-notes:
- en: 562acace386b25ca
- zh: 3eb362bd2730a64c
+ en: 7996925328f0e771
+ zh: 40146455aac119d2
/deepseek-ai-dsh-agent-tool-presentation/further-exploration:
- en: 0f8de64b5862b78e
- zh: 4bba0c1ab780aa54
+ en: 6a1d0096e4da25e4
+ zh: 9d5de770addb69d2
/deepseek-ai-dsh-agent-tool-presentation/model-experience:
en: 35621b26757d462e
zh: a8869139783ae475
diff --git a/packages/core/agent-tool-presentation/README.md b/packages/core/agent-tool-presentation/README.md
index 430e272e71..569ee37d63 100644
--- a/packages/core/agent-tool-presentation/README.md
+++ b/packages/core/agent-tool-presentation/README.md
@@ -7,9 +7,11 @@ kind: "package-reference"
English | [中文](README.zh.md)
+> **Deprecated:** For new configurations, mount `@deepseek-ai/dsh-tool-executor-native` or `@deepseek-ai/dsh-tool-executor-ptc` directly. Existing configurations remain supported. To migrate, replace this selector row with the corresponding executor row and remove `config.mode`; do not load both in the same scope.
+
## Summary
-Use `dsh-agent-tool-presentation` in an [agent preset](../../preset/agent-preset-registry/README.md) to fix whether models see every native tool schema or only `run_code` with a generated SDK. Each preset can choose independently, so native and PTC agents can share one process without sharing tool catalogs. Selecting `ptc` requires a compatible PTC runtime; a deployment without one rejects the preset at mount time before its first prompt. The `mode` field is required when this package is present, while omitting the package keeps the deployment default.
+Existing [agent presets](../../preset/agent-preset-registry/README.md) can keep using `dsh-agent-tool-presentation` to select whether models see every native tool schema or only `run_code` with a generated SDK. Each preset can choose independently, so native and PTC agents can share one process without sharing tool catalogs. Selecting `ptc` requires a compatible PTC runtime; a deployment without one rejects the preset at mount time before its first prompt. The `mode` field is required when this package is present, while omitting the package keeps the deployment default.
## Table of Contents
@@ -25,7 +27,7 @@ Use `dsh-agent-tool-presentation` in an [agent preset](../../preset/agent-preset
## Use this package
-Add this row to an agent preset to fix how every agent joined to that preset sees its tools. `native` presents each visible tool schema as a function definition; `ptc` presents only the `run_code` transport plus a generated SDK and the rule that only `run_code` may be called directly. Agents that declare nothing get the deployment-wide `mode` on the [`dsh-tools`](../tools/README.md) row.
+Add this row to an agent preset to fix how every agent joined to that preset sees its tools. `native` presents each visible tool schema as a function definition; `ptc` presents only the `run_code` transport plus a generated SDK and the rule that only `run_code` may be called directly. Agents that declare nothing inherit the nearest executor mounted in their composition.
### Add the row to a preset
@@ -43,7 +45,7 @@ The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-a
### What PTC mode requires
-Selecting `ptc` needs a composed PTC runtime (`ctx.ptcRuntime`) whose language has a registered SDK renderer — the TypeScript runtime ships via [`dsh-ptc-runtime-node`](../../ptc-runtime/ptc-runtime-node/README.md), and both the TypeScript and Python SDK renderers are built into `dsh-tools`. A preset that selects a PTC mode against a deployment composing no such runtime refuses to mount, naming this row, so the failure lands where the operator can act instead of at the session's first request.
+Selecting `ptc` needs a composed PTC runtime (`ctx.ptcRuntime`) whose language has a registered SDK renderer — the TypeScript runtime ships via [`dsh-ptc-runtime-node`](../../ptc-runtime/ptc-runtime-node/README.md), and both the TypeScript and Python SDK renderers are built into `dsh-tool-executor-ptc`. A preset that selects a PTC mode against a deployment composing no such runtime refuses to mount, naming this row, so the failure lands where the operator can act instead of at the session's first request.
### One presentation per agent
@@ -61,17 +63,17 @@ This section explains how the package realizes the behavior above; the observabl
### Design concept
-The tool registry cannot move into a preset: its consumers are all host-plane — the agent loop reads its scheduler, the API proxy reads its presenters, and every tool plugin registers into it — and a service only moves down when all of its consumers move with it. What a preset can own is the presentation of that registry. `ctx.tools.presentAs()` declares it for the mounting scope, which is the preset's standing mount, so the declaration covers every agent joined to that preset and a PTC mode preset runs beside native ones in one process. One row per composition, not one per session.
+The tool registry cannot move into a preset: its consumers are all host-plane — the agent loop resolves its executor, the API proxy reads its presenters, and every tool plugin registers into it — and a service only moves down when all of its consumers move with it. What a preset can own is the presentation of that registry. `ctx.tools.setExecutor()` declares an executor for the mounting scope, which is the preset's standing mount, so the declaration covers every agent joined to that preset and a PTC mode preset runs beside native ones in one process. One row per composition, not one per session.
### Source map
| File | Role |
|---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: `mode` config, `apply` wiring `ctx.tools.presentAs` for the mounting scope |
+| [`src/index.ts`](src/index.ts) | Plugin entry: `mode` config, `apply` wiring `ctx.tools.setExecutor` for the mounting scope |
### Behavior notes
-`native` applies immediately. A PTC mode instead waits for `ctx.ptcRuntime`, a host-plane service: a preset selecting PTC mode against a deployment composing no runtime holds this row pending, and `dsh-agent-preset-registry` refuses the mount naming this id. `presentAs` is itself the effect, so the declaration unwinds with this row without a second wrapper owning it.
+`native` applies immediately. A PTC mode instead waits for `ctx.ptcRuntime`, a host-plane service: a preset selecting PTC mode against a deployment composing no runtime holds this row pending, and `dsh-agent-preset-registry` refuses the mount naming this id. `setExecutor` is itself the effect, so the declaration unwinds with this row without a second wrapper owning it.
@@ -82,7 +84,7 @@ The tool registry cannot move into a preset: its consumers are all host-plane
The package-level contract is enough for most consumers; read these when you need the surrounding domain.
-- [tools package](../tools/README.md) — the tool presentation modes and `presentAs` API.
+- [tools package](../tools/README.md) — the scoped registry and executor API.
- [agent-presets package](../../preset/agent-preset-registry/README.md) — how presets compose agents and their standing mounts.
- [Node ptc-runtime package](../../ptc-runtime/ptc-runtime-node/README.md) — the TypeScript runtime a PTC mode needs.
- [historical PTC mode executor-collapse note](../../../.agents/notes/archived/bug-fix/2026-08-07-ptc-executor-collapse.md) — why the announced and callable surfaces stay the same.
diff --git a/packages/core/agent-tool-presentation/README.zh.md b/packages/core/agent-tool-presentation/README.zh.md
index a7b63c2311..e30fc01cb5 100644
--- a/packages/core/agent-tool-presentation/README.zh.md
+++ b/packages/core/agent-tool-presentation/README.zh.md
@@ -7,9 +7,11 @@ kind: "package-reference"
[English](README.md) | 中文
+> **已弃用：** 新配置请直接挂载 `@deepseek-ai/dsh-tool-executor-native` 或 `@deepseek-ai/dsh-tool-executor-ptc`。现有配置仍受支持。迁移时，将本选择器条目替换为对应的 executor 条目，并移除 `config.mode`；不要在同一作用域同时加载两者。
+
## 概述
-在 [agent preset](../../preset/agent-preset-registry/README.zh.md) 中使用 `dsh-agent-tool-presentation`，可固定模型看到全部原生工具 schema，还是只有带生成 SDK 的 `run_code`。每个 preset 可独立选择，因此 native 与 PTC agent 可以共享同一进程，而不共享工具目录。选择 `ptc` 需要兼容的 PTC 运行时；没有该运行时的部署会在挂载时拒绝 preset，不会等到收到第一条提示词。使用本包时 `mode` 字段为必填；省略本包则沿用部署默认值。
+现有 [agent preset](../../preset/agent-preset-registry/README.zh.md) 可以继续使用 `dsh-agent-tool-presentation`，选择模型看到全部原生工具 schema，还是只有带生成 SDK 的 `run_code`。每个 preset 可独立选择，因此 native 与 PTC agent 可以共享同一进程，而不共享工具目录。选择 `ptc` 需要兼容的 PTC 运行时；没有该运行时的部署会在挂载时拒绝 preset，不会等到收到第一条提示词。使用本包时 `mode` 字段为必填；省略本包则沿用部署默认值。
## 目录
@@ -25,7 +27,7 @@ kind: "package-reference"
## 使用本包
-把这一行加入 agent preset，以固定每个加入该 preset 的 agent 看到其工具的方式。`native` 以函数定义的形式呈现每个可见工具 schema；`ptc` 只呈现 `run_code` 传输、一份生成的 SDK 以及「只有 `run_code` 可被直接调用」这条规则。未作声明的 agent 会拿到 [`dsh-tools`](../tools/README.zh.md) 那一行上的部署级 `mode`。
+把这一行加入 agent preset，以固定每个加入该 preset 的 agent 看到其工具的方式。`native` 以函数定义的形式呈现每个可见工具 schema；`ptc` 只呈现 `run_code` 传输、一份生成的 SDK 以及「只有 `run_code` 可被直接调用」这条规则。未作声明的 agent 继承组合中最近的执行器。
### 把这一行加入 preset
@@ -61,17 +63,17 @@ kind: "package-reference"
### 设计理念
-工具注册表搬不进 preset：它的消费方全在宿主平面——agent loop（智能体循环）读它的调度器，API proxy 读它的展示转换器，每个工具插件都往里注册——而一个服务只有在所有消费方一起下沉时才能下沉。preset 能拥有的是这份注册表的呈现方式。`ctx.tools.presentAs()` 为挂载作用域声明它，而挂载作用域就是 preset 的常驻挂载，因此该声明覆盖每个加入该 preset 的 agent，一个 PTC mode preset 可以与多个 native preset 同进程并存。每个组合一行，而不是每个会话一行。
+工具注册表搬不进 preset：它的消费方全在宿主平面——agent loop（智能体循环）读它的调度器，API proxy 读它的展示转换器，每个工具插件都往里注册——而一个服务只有在所有消费方一起下沉时才能下沉。preset 能拥有的是这份注册表的呈现方式。`ctx.tools.setExecutor()` 为挂载作用域声明它，而挂载作用域就是 preset 的常驻挂载，因此该声明覆盖每个加入该 preset 的 agent，一个 PTC mode preset 可以与多个 native preset 同进程并存。每个组合一行，而不是每个会话一行。
### 源码地图
| 文件 | 职责 |
|---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：`mode` 配置、把 `ctx.tools.presentAs` 接到挂载作用域的 `apply` |
+| [`src/index.ts`](src/index.ts) | 插件入口：`mode` 配置、把 `ctx.tools.setExecutor` 接到挂载作用域的 `apply` |
### 行为说明
-`native` 立即生效。PTC 模式则等待 `ctx.ptcRuntime`——这是一个宿主平面服务：针对未组装运行时的部署选择 PTC mode 的 preset 会让这一行停在 pending，`dsh-agent-preset-registry` 会指名此 id 拒绝挂载。`presentAs` 本身就是 effect，因此该声明随这一行撤销，无需第二个包装层拥有它。
+`native` 立即生效。PTC 模式则等待 `ctx.ptcRuntime`——这是一个宿主平面服务：针对未组装运行时的部署选择 PTC mode 的 preset 会让这一行停在 pending，`dsh-agent-preset-registry` 会指名此 id 拒绝挂载。`setExecutor` 本身就是 effect，因此该声明随这一行撤销，无需第二个包装层拥有它。
@@ -82,7 +84,7 @@ kind: "package-reference"
包级约定对大多数消费方已经足够；需要周边领域时再阅读以下页面。
-- [tools 包](../tools/README.zh.md)——工具呈现模式与 `presentAs` API。
+- [tools 包](../tools/README.zh.md)——工具呈现模式与 `setExecutor` API。
- [agent-presets 包](../../preset/agent-preset-registry/README.zh.md)——preset 如何组合 agent 及其常驻挂载。
- [Node ptc-runtime 包](../../ptc-runtime/ptc-runtime-node/README.zh.md)——PTC 模式所需的 TypeScript 运行时。
- [历史PTC mode 执行器塌缩 note](../../../.agents/notes/archived/bug-fix/2026-08-07-ptc-executor-collapse.md)——通告面与可调用面为何保持一致。
diff --git a/packages/core/system-prompt/README.i18n.yaml b/packages/core/system-prompt/README.i18n.yaml
index a5c3f5913c..637bafaf9a 100644
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -72,8 +72,8 @@
en: 3039bc5e7a796b21
zh: 6b7a9eaf69c9ea53
/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas/what-the-model-sees:
- en: a983ef220593cf73
- zh: 28770612ffc1be60
+ en: 793f59c178ee2b7e
+ zh: 871fbaee803335c5
/deepseek-ai-dsh-system-prompt/model-experience/tool-schemas/token-effect:
en: f3a7d374c55e1720
zh: 0ee48af678cb875f
diff --git a/packages/core/system-prompt/README.md b/packages/core/system-prompt/README.md
index 6c9d7338ec..b554f11205 100644
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -157,7 +157,7 @@ Prefix-stable while identity, persona, variables, section text, and order render
#### What the model sees
-For shipped tools, the model receives the per-agent-visible subset of the [generated tool schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tools), ordered by configuration or lexicographically after restrictions and assembly interception. Extensions can contribute additional definitions through the same registry. Sections and schema providers are separate assembly inputs. A restriction does not remove a section registration: tool-guidance plugins use `text({ scope })` and `ctx.tools.get(name, scope)` to return empty text or select applicable fragments. Arbitrary static sections are not automatically rewritten.
+For shipped tools, the model receives the per-agent-visible subset of the [generated tool schemas](../../../docs/tool-catalog.md#deepseek-aidsh-tool-executor-ptc), ordered by configuration or lexicographically after restrictions and assembly interception. Extensions can contribute additional definitions through the same registry. Sections and schema providers are separate assembly inputs. A restriction does not remove a section registration: tool-guidance plugins use `text({ scope })` and `ctx.tools.get(name, scope)` to return empty text or select applicable fragments. Arbitrary static sections are not automatically rewritten.
#### Token effect
diff --git a/packages/core/system-prompt/README.zh.md b/packages/core/system-prompt/README.zh.md
index 1807bf0411..739ea878d3 100644
--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -157,7 +157,7 @@ You are an AI agent powered by DeepSeek Harness.
#### 模型看到什么
-对于已交付工具，模型会收到[生成工具 schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tools)中对每个 agent 可见的子集；限制与组装拦截完成后，按配置或字典序排列。扩展可以通过同一注册表贡献其他定义。段与 schema 提供方是独立的组装输入。限制不会移除段落注册：工具指导插件通过 `text({ scope })` 与 `ctx.tools.get(name, scope)` 返回空文本或选择适用片段。任意静态段落不会被自动改写。
+对于已交付工具，模型会收到[生成工具 schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-executor-ptc)中对每个 agent 可见的子集；限制与组装拦截完成后，按配置或字典序排列。扩展可以通过同一注册表贡献其他定义。段与 schema 提供方是独立的组装输入。限制不会移除段落注册：工具指导插件通过 `text({ scope })` 与 `ctx.tools.get(name, scope)` 返回空文本或选择适用片段。任意静态段落不会被自动改写。
#### Token 影响
diff --git a/packages/core/tool-executor-native/README.i18n.yaml b/packages/core/tool-executor-native/README.i18n.yaml
new file mode 100644
index 0000000000..118a6d84fb
--- /dev/null
+++ b/packages/core/tool-executor-native/README.i18n.yaml
@@ -0,0 +1,46 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write packages/core/tool-executor-native/README.md
+/:
+ en: a167e9f03780ad63
+ zh: 2e5dc0bd2d08c46e
+/deepseek-ai-dsh-tool-executor-native:
+ en: 7e09b7d3b4389e09
+ zh: 2c774c33639bdd64
+/deepseek-ai-dsh-tool-executor-native/summary:
+ en: 0ef12f2cb7b8f23e
+ zh: bc79ea00254bfb21
+/deepseek-ai-dsh-tool-executor-native/table-of-contents:
+ en: d152484eb41ac6b4
+ zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-executor-native/use-this-package:
+ en: 176f69450bacc28e
+ zh: fc3c2d876195a4a4
+/deepseek-ai-dsh-tool-executor-native/understand-the-implementation:
+ en: d005036097c11788
+ zh: 65fcaec551dc1697
+/deepseek-ai-dsh-tool-executor-native/further-exploration:
+ en: e8ae407b0ecdc5d3
+ zh: 022a8a714d24da4b
+/deepseek-ai-dsh-tool-executor-native/model-experience:
+ en: 215e7ba838619b7b
+ zh: a311da3843709f90
+/deepseek-ai-dsh-tool-executor-native/model-experience/visible-tools:
+ en: 735cc6f4f3bf4cda
+ zh: 8dab814b4bba5a7d
+/deepseek-ai-dsh-tool-executor-native/model-experience/visible-tools/what-the-model-sees:
+ en: e1f3bbf06e45c22b
+ zh: 490cb060c38ccd4e
+/deepseek-ai-dsh-tool-executor-native/model-experience/visible-tools/token-effect:
+ en: 81684f49f932e3a3
+ zh: 6db2d0a125d990d8
+/deepseek-ai-dsh-tool-executor-native/model-experience/visible-tools/kv-cache-effect:
+ en: c0d457297034cf64
+ zh: 1dfb5c7f83033d92
+/deepseek-ai-dsh-tool-executor-native/known-limitations-and-deferred-work:
+ en: 4271a88c7d41a6a2
+ zh: 99e9db876937a281
+/deepseek-ai-dsh-tool-executor-native/known-limitations-and-deferred-work/dev-note:
+ en: e67f633dc6fe7773
+ zh: 3bb0c20c93f16f98
diff --git a/packages/core/tool-executor-native/README.md b/packages/core/tool-executor-native/README.md
new file mode 100644
index 0000000000..5d6103c5fc
--- /dev/null
+++ b/packages/core/tool-executor-native/README.md
@@ -0,0 +1,98 @@
+---
+description: "Native function calls with scoped tools and bounded batch execution."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-executor-native
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this executor when models should call each visible tool directly. Mount it beside the tool registry in the deployment, a preset, or an Agent scope. Parallel-safe calls can overlap; exclusive calls form barriers, and results remain in model order.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+
+## Use this package
+
+Add this row to a composition with `dsh-tools` mounted. The nearest scoped executor selects tool behavior; one scope permits only one executor.
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-executor-native'
+ config:
+ maxParallelToolCalls: 10
+```
+
+For Agent steps, configure [agent-loop concurrency](../agent-loop/README.md); the loop always forwards its resolved limit to `execute()`. The executor's `maxParallelToolCalls` supplies the limit only when the caller omits it. This fallback is volatile, defaults to `10`, and is sampled for the next tool group. It must be a positive integer; `1` selects serial execution.
+
+[Configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-executor-native)
+
+-----
+
+
+## Understand the implementation
+
+
+Implementation internals — click to expand
+
+The executor receives the entire raw call batch and owns parsing, scheduling, cancellation, and optional model-step logging. It reuses the shared invocation pipeline for policy, tool bodies, and result notifications. After abort, it waits for started work and returns ordered error results for skipped calls.
+
+- [`src/index.ts`](src/index.ts) — Validated configuration and scoped registration; tool descriptions and batch execution.
+
+
+
+-----
+
+
+## Further Exploration
+
+- [Tool registry](../tools/README.md)
+- [Agent loop](../agent-loop/README.md)
+- [Alternative executor](../tool-executor-ptc/README.md)
+
+-----
+
+
+## Model Experience
+
+### Visible tools
+
+#### What the model sees
+
+Each visible tool’s `name`, `description`, and JSON Schema parameters; no additional prompt section.
+
+#### Token effect
+
+Request cost grows with visible definitions; hiding a definition removes its schema cost.
+
+#### KV Cache effect
+
+The prefix remains stable while tool descriptions and ordering stay unchanged.
+
+## Known Limitations and Deferred Work
+
+
+
+These constraints apply to accepted calls.
+
+- Same-process tools must observe cancellation; the executor cannot forcibly terminate a tool that ignores its signal.
+
+
+### Dev Note
+
+
+Working context for maintainers — click to expand
+
+None.
+
+
diff --git a/packages/core/tool-executor-native/README.zh.md b/packages/core/tool-executor-native/README.zh.md
new file mode 100644
index 0000000000..82f71691e6
--- /dev/null
+++ b/packages/core/tool-executor-native/README.zh.md
@@ -0,0 +1,98 @@
+---
+description: "具有作用域工具和有界批次执行的原生函数调用。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-executor-native
+
+[English](README.md) | 中文
+
+## 概述
+
+当模型应直接调用每个可见工具时，使用此执行器。在部署、预设或 Agent 作用域中，将它与工具注册表一同挂载。并行安全调用可以重叠，独占调用构成屏障，结果保留模型顺序。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+
+## 使用本包
+
+将此行加入已经挂载 `dsh-tools` 的组合。最近作用域的执行器决定工具行为；同一作用域只允许一个执行器。
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-executor-native'
+ config:
+ maxParallelToolCalls: 10
+```
+
+Agent 步骤使用 [agent-loop 并发配置](../agent-loop/README.zh.md)，循环始终向 `execute()` 传入解析后的上限。只有调用方未传入上限时，才使用执行器的 `maxParallelToolCalls`。这个后备配置是 volatile 字段，默认值为 `10`，在下一个工具组开始时读取。值必须是正整数；`1` 表示串行执行。
+
+[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-executor-native)
+
+-----
+
+
+## 理解实现
+
+
+实现细节——点击展开
+
+执行器接收完整的原始调用批次，负责解析、调度、取消和可选的模型步骤日志。它复用共享调用流水线来执行策略、工具和结果通知。中止后，它等待已开始的工作完成，并为跳过的调用返回有序错误结果。
+
+- [`src/index.ts`](src/index.ts) — 配置校验和作用域注册；工具描述和批次执行。
+
+
+
+-----
+
+
+## 进一步探索
+
+- [工具注册表](../tools/README.zh.md)
+- [Agent 循环](../agent-loop/README.zh.md)
+- [其他执行器](../tool-executor-ptc/README.zh.md)
+
+-----
+
+
+## 模型体验
+
+### 可见工具
+
+#### 模型看到什么
+
+每个可见工具的 `name`、`description` 和 JSON Schema 参数；不会增加提示词章节。
+
+#### Token 影响
+
+请求成本与可见定义成正比；隐藏定义会移除对应 schema 成本。
+
+#### KV Cache 影响
+
+只要工具描述和顺序不变，前缀就保持稳定。
+
+## 已知限制与延期工作
+
+
+
+以下约束适用于已开始的调用。
+
+- 同进程工具必须遵守取消信号；执行器无法强制终止忽略信号的工具。
+
+
+### 开发备注
+
+
+维护者的工作上下文——点击展开
+
+无。
+
+
diff --git a/packages/core/tool-executor-ptc/README.i18n.yaml b/packages/core/tool-executor-ptc/README.i18n.yaml
new file mode 100644
index 0000000000..3a3836c1d0
--- /dev/null
+++ b/packages/core/tool-executor-ptc/README.i18n.yaml
@@ -0,0 +1,52 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write packages/core/tool-executor-ptc/README.md
+/:
+ en: 93b346254eff025a
+ zh: 69aa6364ca2ffa7d
+/deepseek-ai-dsh-tool-executor-ptc:
+ en: e253ed9cec03a396
+ zh: 922fde282e2b0fd2
+/deepseek-ai-dsh-tool-executor-ptc/summary:
+ en: 60fb16b4d443d265
+ zh: 6b0df6471c370c6b
+/deepseek-ai-dsh-tool-executor-ptc/table-of-contents:
+ en: d152484eb41ac6b4
+ zh: 09388d293f9be9cb
+/deepseek-ai-dsh-tool-executor-ptc/use-this-package:
+ en: 5cfc28690358a419
+ zh: d066d078ca649022
+/deepseek-ai-dsh-tool-executor-ptc/understand-the-implementation:
+ en: f054dc0faabb468f
+ zh: 10f13508bfa9ef84
+/deepseek-ai-dsh-tool-executor-ptc/understand-the-implementation/ptc-mode:
+ en: 11d32e05ba397f86
+ zh: 4e071ec4e6222d9d
+/deepseek-ai-dsh-tool-executor-ptc/further-exploration:
+ en: ee69078c38c655a9
+ zh: fb0873407f23c8c5
+/deepseek-ai-dsh-tool-executor-ptc/model-experience:
+ en: 215e7ba838619b7b
+ zh: a311da3843709f90
+/deepseek-ai-dsh-tool-executor-ptc/model-experience/ptc-mode-schema-and-system-prompt:
+ en: eaefd7303f22977d
+ zh: 9c425f9501128224
+/deepseek-ai-dsh-tool-executor-ptc/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees:
+ en: 4980bfab8310efc0
+ zh: ef318d5b8ac7bf76
+/deepseek-ai-dsh-tool-executor-ptc/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees/typescript-ptc-mode-sdk-instructions-with-bash:
+ en: 3a8df15e4ae32f9e
+ zh: fc4a800ba363e835
+/deepseek-ai-dsh-tool-executor-ptc/model-experience/ptc-mode-schema-and-system-prompt/token-effect:
+ en: 12296fcafc14562c
+ zh: f8e9351bb8c6437d
+/deepseek-ai-dsh-tool-executor-ptc/model-experience/ptc-mode-schema-and-system-prompt/kv-cache-effect:
+ en: 78906628d634441f
+ zh: 492f133aea50cfe3
+/deepseek-ai-dsh-tool-executor-ptc/known-limitations-and-deferred-work:
+ en: 73836fc806368269
+ zh: 943ecf50e19b3c69
+/deepseek-ai-dsh-tool-executor-ptc/known-limitations-and-deferred-work/dev-note:
+ en: e67f633dc6fe7773
+ zh: 3bb0c20c93f16f98
diff --git a/packages/core/tool-executor-ptc/README.md b/packages/core/tool-executor-ptc/README.md
new file mode 100644
index 0000000000..b7b56146a5
--- /dev/null
+++ b/packages/core/tool-executor-ptc/README.md
@@ -0,0 +1,134 @@
+---
+description: "Program-based tool execution, generated SDKs, and nested-call limits."
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-executor-ptc
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this executor when models should call tools through `run_code` programs. Mount a compatible PTC runtime and tool registry first. Scoped restrictions determine the generated SDK; only `run_code` is directly callable. Configure root-call and program-subcall concurrency independently.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+
+## Use this package
+
+Add this row to a composition with `dsh-tools` mounted. The nearest scoped executor selects tool behavior; one scope permits only one executor.
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-executor-ptc'
+ config:
+ maxParallelToolCalls: 10
+ maxParallelSubCalls: 10
+```
+
+For Agent steps, configure [agent-loop concurrency](../agent-loop/README.md); the loop always forwards its resolved limit to `execute()`. The executor's `maxParallelToolCalls` supplies the limit only when the caller omits it. This fallback is volatile, defaults to `10`, and is sampled for the next tool group. It must be a positive integer; `1` selects serial execution.
+
+This package also requires `ctx.ptcRuntime` and `ctx.systemPrompt`; Agent-owned programs need `ctx.workingDirectory`. `maxParallelSubCalls` limits overlapping parallel-safe calls within each program and defaults to `10`.
+
+Import durable event payloads from `@deepseek-ai/dsh-tool-executor-ptc/types`; this entry is safe for detached readers and client compilation. Host policy extensions import `PtcDispatchLog`, `tools/ptc-dispatch-log`, and the `ptc-mode` message-source declaration through a type-only import of the package entry, without mounting an executor.
+
+[Configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-executor-ptc)
+
+-----
+
+
+## Understand the implementation
+
+
+Implementation internals — click to expand
+
+The executor receives the entire raw call batch and owns parsing, scheduling, cancellation, and optional model-step logging. It reuses the shared invocation pipeline for policy, tool bodies, and result notifications. After abort, it waits for started work and returns ordered error results for skipped calls.
+
+### PTC mode
+
+The PTC executor exposes the reserved `run_code` transport plus a deterministic SDK generated in the loaded runtime's language. Each SDK binding captures a frozen ToolSchema and passes it through the scheduler to its execution context. Before policy, a started call records only pairing ids, name, and normalized arguments; its settle event preserves the rendered result, optional presentation metadata, and structured error. Metadata is projected from that call’s canonical value and frozen; it changes neither the program value nor model content. Description and parameters remain transient and never enter Session events or SDK output. Calls are scheduled through a per-run pool that reuses the native concurrency contract. Under `ptc` alone, a model-direct call naming any other visible tool resolves to `UNKNOWN_TOOL` before policy — the announced surface and the callable surface stay the same. Intermediate binding values are execution-local; only the outer `run_code` result has a hard size cap.
+
+New sub-calls use `:ptc:` ids. Consumers treat these ids as opaque and correlate events by exact equality; restored historical ids retain their original bytes. The [PTC mode decision](../../../.agents/notes/implemented/feature/2026-06-15-ptc.md) owns durable naming and restoration rules.
+
+Successful image-bearing subcall results become deferred user-message context with `source.kind` set to `ptc-mode`. Other additional contexts retain their producing tool's attribution.
+
+`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, and the runtime's usage instructions. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The schema asks the model to write that reason in the current user's language. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program. Retained PTC environments follow the standing file policy. PTC observes committed Session mode changes and immediately cancels affected calls in both Node modes. Later PTC calls wait for their nested-tool cleanup before resolving the latest policy. The runtime owns process invalidation and cleanup; permission setters remain synchronous. One-time escalations omit the state owner and complete in a temporary environment; standing variables remain available to ordinary calls.
+
+- [`src/index.ts`](src/index.ts) — Validated configuration and scoped registration; tool descriptions and batch execution.
+
+
+
+-----
+
+
+## Further Exploration
+
+- [Tool registry](../tools/README.md)
+- [Agent loop](../agent-loop/README.md)
+- [Alternative executor](../tool-executor-native/README.md)
+
+-----
+
+
+## Model Experience
+
+### PTC mode schema and system prompt
+
+#### What the model sees
+
+PTC mode exposes the generated [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-executor-ptc), the SDK instructions below, and the generated exact SDK block for the loaded runtime's language. Both runtime languages list `code` before `description`; this is presentation order, not an enforced JSON member order. The TypeScript instructions use a return-value example for function-body runtimes and a printed-output example for REPL runtimes. They identify generated declarations as program-only bindings. When the current `bash` parameter schema accepts the example arguments, they also show a complete `run_code` call around `tools.bash(...)`. The `tools:sdk` section uses first-party order 5000 and disables prompt-variable interpolation, preserving literal `{{…}}` text in tool descriptions and schemas for both runtime languages. Under `ptc`, the prompt also carries the `tools:ptc-only` rule earlier in the first-party order, so the model reads which tools it may call before it reads what each one is for.
+
+##### TypeScript PTC mode SDK instructions with bash
+
+```markdown
+## Writing code for run_code
+
+`run_code` takes two required arguments: `code`, the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped), and `description`, a short summary of what the program does. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly. When no separate `bash` schema is supplied, invoke a declared `bash` binding inside `run_code`:
+
+`run_code({ code: "return await tools.bash({ description: 'Show current directory', command: 'pwd' })", description: "Show current directory" })`
+
+Inside the program:
+
+- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
+- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.
+- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.
+- Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+
+Program-only SDK bindings:
+```
+
+#### Token effect
+
+Fixed per-request cost proportional to the visible definitions. PTC mode trades end-tool schemas for generated SDK text plus one transport schema rather than promising a universal reduction.
+
+#### KV Cache effect
+
+Prefix-stable while the PTC mode selection, generated SDK, transport schema, and visible tool set are unchanged. Mode or filter changes may invalidate reuse from the first changed prompt or schema token.
+
+## Known Limitations and Deferred Work
+
+
+
+These constraints apply to accepted calls.
+
+- **PTC mode's SDK language follows the one loaded runtime, and a presentation is per agent rather than per tool** — PTC execution rejects prompt assembly unless `ctx.ptcRuntime.language` has a registered SDK renderer; within one agent no tool can be native-only while another is ptc-only.
+- **PTC mode intermediate values are execution-local and unbounded by bytes** — they cannot be reconstructed from session replay and may exhaust process or worker memory; only the outer `run_code` output has the worker's configurable hard cap.
+- **State depends on the runtime**: the default backend starts fresh; a REPL backend retains memory per live Agent. Agent disposal awaits release. Restart and execution failures can clear memory; model-visible guidance explains how to recreate missing variables. Programs and results remain in the Session log, without serializing live objects.
+
+
+### Dev Note
+
+
+Working context for maintainers — click to expand
+
+None.
+
+
diff --git a/packages/core/tool-executor-ptc/README.zh.md b/packages/core/tool-executor-ptc/README.zh.md
new file mode 100644
index 0000000000..f4d60631ea
--- /dev/null
+++ b/packages/core/tool-executor-ptc/README.zh.md
@@ -0,0 +1,134 @@
+---
+description: "基于程序的工具执行、生成 SDK 与嵌套调用限制。"
+kind: "package-reference"
+---
+
+# @deepseek-ai/dsh-tool-executor-ptc
+
+[English](README.md) | 中文
+
+## 概述
+
+当模型应通过 `run_code` 程序调用工具时，使用此执行器。先挂载兼容的 PTC 运行时和工具注册表。作用域限制决定生成的 SDK；只有 `run_code` 能被直接调用。根调用和程序子调用的并发限制分别配置。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+
+## 使用本包
+
+将此行加入已经挂载 `dsh-tools` 的组合。最近作用域的执行器决定工具行为；同一作用域只允许一个执行器。
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-executor-ptc'
+ config:
+ maxParallelToolCalls: 10
+ maxParallelSubCalls: 10
+```
+
+Agent 步骤使用 [agent-loop 并发配置](../agent-loop/README.zh.md)，循环始终向 `execute()` 传入解析后的上限。只有调用方未传入上限时，才使用执行器的 `maxParallelToolCalls`。这个后备配置是 volatile 字段，默认值为 `10`，在下一个工具组开始时读取。值必须是正整数；`1` 表示串行执行。
+
+本包还要求 `ctx.ptcRuntime` 和 `ctx.systemPrompt`；带 Agent 的程序要求 `ctx.workingDirectory`。`maxParallelSubCalls` 限制每个程序内重叠的并行安全调用，默认值为 `10`。
+
+持久化事件载荷从 `@deepseek-ai/dsh-tool-executor-ptc/types` 导入；该入口可用于独立读取者与 Client 编译。Host 策略扩展通过包主入口的仅类型导入获取 `PtcDispatchLog`、`tools/ptc-dispatch-log` 与 `ptc-mode` 消息来源声明，无需挂载执行器。
+
+[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-executor-ptc)
+
+-----
+
+
+## 理解实现
+
+
+实现细节——点击展开
+
+执行器接收完整的原始调用批次，负责解析、调度、取消和可选的模型步骤日志。它复用共享调用流水线来执行策略、工具和结果通知。中止后，它等待已开始的工作完成，并为跳过的调用返回有序错误结果。
+
+### PTC mode
+
+PTC 执行器公开保留的 `run_code` 传输以及按所加载运行时语言生成的确定性 SDK。每个 SDK 绑定捕获冻结的 ToolSchema，经由调度器传入该次执行上下文。已开始的调用在策略之前只记录配对 id、名称和规范化参数；其结算事件保留渲染结果、可选展示元数据与结构化错误；元数据由该次调用的规范值投影并冻结，不改变程序读取的值或模型内容。描述与参数 schema 仅临时存活，不进入 Session 事件或 SDK 输出。调用通过复用原生并发约定的每次运行独有池调度。在纯 `ptc` 下，模型直呼其他任何可见工具都会在策略之前解析为 `UNKNOWN_TOOL`——通告面与可调用面保持一致。中间绑定值只存在于执行局部；只有外层 `run_code` 结果有硬大小上限。
+
+新子调用使用 `:ptc:` 标识。消费方将这些标识视为不透明值，并通过精确相等关联事件；恢复的历史标识保留原始字节。[PTC mode 决策](../../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md) 负责持久化命名与恢复规则。
+
+成功且包含图片的子调用结果会成为延后的 user-message 上下文，其 `source.kind` 为 `ptc-mode`。其他 additional context 保留其生产工具的归属。
+
+当已挂载运行时支持覆盖时，`run_code` 接受 `timeoutMs`；其 schema 报告配置的默认值和上限以及运行时使用说明。Node 默认值为 120,000 ms，上限为 600,000 ms，包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`，并在程序启动前获得审批。schema 提示模型使用当前用户的语言撰写理由。授权仅用于该次完整执行；常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放：显式重试被拒程序前，应检查先前已发生的效果。 保留状态的 PTC 环境遵循会话文件策略。PTC 观察已提交的 Session 模式变化，并立即取消两种 Node 模式下受影响的调用。后续 PTC 调用等待这些调用的嵌套工具清理后，再解析最新策略。运行时负责进程失效和清理，权限设置保持同步。单次提权省略状态所有者，在临时环境中执行；普通调用仍可访问原环境的变量。
+
+- [`src/index.ts`](src/index.ts) — 配置校验和作用域注册；工具描述和批次执行。
+
+
+
+-----
+
+
+## 进一步探索
+
+- [工具注册表](../tools/README.zh.md)
+- [Agent 循环](../agent-loop/README.zh.md)
+- [其他执行器](../tool-executor-native/README.zh.md)
+
+-----
+
+
+## 模型体验
+
+### PTC mode schema 与系统提示词
+
+#### 模型看到什么
+
+PTC mode 会公开生成的 [`run_code` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-executor-ptc)、下方 SDK 说明，以及按所加载运行时语言生成的精确 SDK 块。两种运行时语言都将 `code` 列在 `description` 前；这是呈现顺序，不强制 JSON 成员顺序。TypeScript 说明对函数体运行时使用返回值示例，对 REPL 运行时使用打印输出示例，并把生成声明明确标为只能在程序内使用的绑定。当当前 `bash` 参数 schema 接受示例参数时，说明还会给出以 `run_code` 包住 `tools.bash(...)` 的完整调用。`tools:sdk` 段使用 first-party 顺序 5000，并关闭提示词变量插值，使两种运行时语言都原样保留工具描述和 schema 中的 `{{…}}` 文本。在 `ptc` 下，提示词还会带上处于更早 first-party 顺序的 `tools:ptc-only` 规则，让模型先读到「可以调用哪些工具」再读「每个工具做什么」。
+
+##### 带 bash 的 TypeScript PTC mode SDK 说明
+
+```markdown
+## Writing code for run_code
+
+`run_code` takes two required arguments: `code`, the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped), and `description`, a short summary of what the program does. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly. When no separate `bash` schema is supplied, invoke a declared `bash` binding inside `run_code`:
+
+`run_code({ code: "return await tools.bash({ description: 'Show current directory', command: 'pwd' })", description: "Show current directory" })`
+
+Inside the program:
+
+- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
+- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.
+- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.
+- Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
+
+Program-only SDK bindings:
+```
+
+#### Token 影响
+
+每次请求的固定成本与可见定义成正比。PTC mode 使用生成的 SDK 文本加一个传输 schema 取代最终工具 schema，但不承诺普遍减少成本。
+
+#### KV Cache 影响
+
+只要 PTC mode 选择、生成的 SDK、传输 schema 与可见工具集合不变，前缀就保持稳定。模式或筛选器变更可能从第一个改变的提示词或 schema token 起使复用失效。
+
+## 已知限制与延期工作
+
+
+
+以下约束适用于已开始的调用。
+
+- **PTC mode 的 SDK 语言由当前加载的运行时决定，且呈现方式按 agent 而非按工具**：PTC 会拒绝组装提示词，除非 `ctx.ptcRuntime.language` 有已注册的 SDK 渲染器；同一个 agent 内不能让一个工具仅使用 Native，而另一个仅使用 PTC。
+- **PTC mode 中间值只存在于执行局部，且没有字节上限**：它们无法从会话回放重建，并可能耗尽进程或 worker 内存；只有外层 `run_code` 输出受 worker 可配置的硬上限约束。
+- **状态由运行时决定**：默认后端每次重新开始；REPL 后端按存活 Agent 保留内存。Agent 销毁时等待环境释放。重启与执行失败可能清除内存；模型说明会指导重新创建缺失变量。程序与结果仍写入 Session 日志，不序列化运行中的对象。
+
+
+### 开发备注
+
+
+维护者的工作上下文——点击展开
+
+无。
+
+
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index f90a284f26..ff0a69e461 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -9,20 +9,20 @@
en: bb2af1250bfefe4b
zh: 893e3ab2e563a8a5
/deepseek-ai-dsh-tools/summary:
- en: 8c0a34155997a980
- zh: ae6031db472b33e3
+ en: ad53df5cc542fc32
+ zh: 1ab915da46e01d20
/deepseek-ai-dsh-tools/table-of-contents:
en: d152484eb41ac6b4
zh: 09388d293f9be9cb
/deepseek-ai-dsh-tools/use-this-package:
- en: dec8e6df8cc94bc2
- zh: e2f1f15ea7afd7b3
+ en: d382227271bf92ae
+ zh: 1f66b181418c91b9
/deepseek-ai-dsh-tools/use-this-package/register-a-tool:
en: 9d2e6caa39c53d62
zh: 096a777f828c7565
-/deepseek-ai-dsh-tools/use-this-package/configure-the-presentation-mode:
- en: 4e27c45ae889369e
- zh: 7a0cd7a9dc7fe139
+/deepseek-ai-dsh-tools/use-this-package/select-an-executor:
+ en: f3efeb3d996cb9c5
+ zh: 442cf4ca6d68fea0
/deepseek-ai-dsh-tools/use-this-package/restrict-tools-per-agent:
en: c6f98b2283cc2e47
zh: c2cdce5d13473f15
@@ -36,23 +36,23 @@
en: ce7e776e9d516bdb
zh: 59d2751743db7795
/deepseek-ai-dsh-tools/understand-the-implementation/design-concept:
- en: 92e8af53e6067bad
+ en: 516a6195a21e742b
zh: 33c7b99b42c5acac
/deepseek-ai-dsh-tools/understand-the-implementation/source-map:
- en: c14e20d6a5c4c408
- zh: ab9dc0fd38006749
+ en: 2dee0a37e0c1fa38
+ zh: 0963cba32685612e
/deepseek-ai-dsh-tools/understand-the-implementation/execution-and-cancellation:
en: dc44a88997777988
zh: 56454aeace1c8b77
/deepseek-ai-dsh-tools/understand-the-implementation/ptc-mode:
- en: 387700aa396f7ca2
- zh: d440b283027e4fbd
+ en: 83cf9a5077158879
+ zh: 80508a70a3674226
/deepseek-ai-dsh-tools/understand-the-implementation/extension-points:
en: c2a14d6f22bc9428
zh: 89c1414fca465931
/deepseek-ai-dsh-tools/further-exploration:
- en: d8e2dfcfef2a2284
- zh: b33111cbc20dc498
+ en: b112e13c7db15bf3
+ zh: 39e726a15ca40f21
/deepseek-ai-dsh-tools/model-experience:
en: 215e7ba838619b7b
zh: a311da3843709f90
@@ -60,29 +60,14 @@
en: 483b01d9bb2cb49a
zh: 1d95095e76fb0996
/deepseek-ai-dsh-tools/model-experience/normal-tool-schemas/what-the-model-sees:
- en: beda295a874b30a1
- zh: 253c4cf007c4db3f
+ en: d6a5c32a421bfe97
+ zh: 542d49df376e70a4
/deepseek-ai-dsh-tools/model-experience/normal-tool-schemas/token-effect:
en: d594b71ff5e4cc87
zh: dcec1ea0dd2a0fa6
/deepseek-ai-dsh-tools/model-experience/normal-tool-schemas/kv-cache-effect:
en: 7c5e75964e020b2c
zh: d50d0402d15232d9
-/deepseek-ai-dsh-tools/model-experience/ptc-mode-schema-and-system-prompt:
- en: eaefd7303f22977d
- zh: 9c425f9501128224
-/deepseek-ai-dsh-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees:
- en: 3e170a222d746e98
- zh: 1ea442fc59874cc5
-/deepseek-ai-dsh-tools/model-experience/ptc-mode-schema-and-system-prompt/what-the-model-sees/typescript-ptc-mode-sdk-instructions-with-bash:
- en: 3a8df15e4ae32f9e
- zh: fc4a800ba363e835
-/deepseek-ai-dsh-tools/model-experience/ptc-mode-schema-and-system-prompt/token-effect:
- en: 12296fcafc14562c
- zh: f8e9351bb8c6437d
-/deepseek-ai-dsh-tools/model-experience/ptc-mode-schema-and-system-prompt/kv-cache-effect:
- en: 78906628d634441f
- zh: 492f133aea50cfe3
/deepseek-ai-dsh-tools/model-experience/tool-call-history-and-results:
en: a8503137ad03720c
zh: 611a2dadf7c0c706
@@ -96,8 +81,8 @@
en: 2fbf2175168e8244
zh: ad59a120b54a0996
/deepseek-ai-dsh-tools/known-limitations-and-deferred-work:
- en: 4a412f89b8a71b5a
- zh: 803d995b036d5dbf
+ en: e8c410dee66e1639
+ zh: ae4965fa70234fd1
/deepseek-ai-dsh-tools/known-limitations-and-deferred-work/dev-note:
en: e67f633dc6fe7773
zh: 3bb0c20c93f16f98
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index a5a7044916..bcd25bc40f 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
## Summary
-Use `dsh-tools` to expose typed capabilities to models, validate calls, enforce allow/deny/ask policy, and return finalized results without ending a turn on ordinary tool failures. Choose native Function Calling or [PTC mode](#ptc-mode) with `mode`; an agent can override the default through `presentAs`. Tool authors use `defineTool` to declare typed parameters and outputs, cooperative timeouts, parallel-safety, and optional UI presentation. Models see each permitted tool's declared name, description, and parameter schema; per-agent restrictions can narrow that visible set.
+Use `dsh-tools` to expose typed capabilities to models, validate calls, enforce allow/deny/ask policy, and return finalized results without ending a turn on ordinary tool failures. Mount a native or PTC executor to choose the model interaction and batch execution behavior. Tool authors use `defineTool` to declare typed parameters and outputs, cooperative timeouts, parallel-safety, and optional UI presentation. Models see each permitted tool's declared name, description, and parameter schema; per-agent restrictions can narrow that visible set.
## Table of Contents
@@ -25,9 +25,9 @@ Use `dsh-tools` to expose typed capabilities to models, validate calls, enforce
## Use this package
-Each `run_code` program captures the Session's current working directory when it starts. A nested directory change affects subsequent tool calls, while the running program keeps its initial directory.
+`ctx.tools.execute()` accepts a complete raw call batch. `agent` is absent for standalone service calls; `log` is absent for programmatic calls outside a model step, including initialization hooks. An Agent without `log` still supplies tool scope but does not produce root call/result events.
-Mount `dsh-tools` wherever agents call tools: it provides `ctx.tools`, the registry every tool plugin registers into and the loop dispatches through. Registering a tool is enough to make it visible — the registry feeds its schemas into the system-prompt assembly automatically.
+Mount `dsh-tools` wherever agents call tools: it provides `ctx.tools`, the registry every tool plugin registers into and the selected executor resolves. Registering a tool is enough to make it visible — the registry feeds its schemas into the system-prompt assembly automatically.
### Register a tool
@@ -63,22 +63,16 @@ ctx.tools.register(defineTool({
The unified schema DSL supports `string`, `number`, `integer`, `boolean`, `null`, `array`, `object`, author-only `json`, and exact-one `oneOf`; `InferValue` preserves exact types through 16 container levels before widening to `JsonValue`. A raw JSON Schema (`JsonSchemaNode`) is the wire-level counterpart shared with subagents, workflows, and MCP.
-### Configure the presentation mode
+### Select an executor
-The `mode` config decides what the model sees: `native` (every visible schema) or `ptc` (only `run_code` plus a generated SDK). The runtime supplies evaluation syntax, output syntax and state-retention guidance through `executionInstructions`; this package owns tool-call rules, SDK declarations and image-result attachment.
+Mount one executor in the deployment, preset, or Agent scope. The nearest scope selects the provider; duplicate providers in one scope fail. Native exposes visible capabilities directly; PTC exposes `run_code` and a generated SDK.
```yaml
- name: '@deepseek-ai/dsh-tools'
- config:
- mode: native
+- name: '@deepseek-ai/dsh-tool-executor-native'
```
-| Field | Default | Meaning |
-|---|---|---|
-| `mode` | `native` | How visible tools are presented to the model: `native` or `ptc` |
-| `maxParallelSubCalls` | `10` | Concurrency cap for a `run_code` program's overlapping sub-calls; `1` restores strictly serial dispatch |
-
-The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tools) is the exhaustive source for every accepted field. Non-native modes require a composed `ctx.ptcRuntime` whose language has a registered SDK renderer; an agent preset selects its own presentation with [`dsh-agent-tool-presentation`](../agent-tool-presentation/README.md), and one agent can shadow the default with `presentAs(mode)`.
+Agent-step concurrency uses the [agent-loop configuration](../agent-loop/README.md). See the [native](../tool-executor-native/README.md) or [PTC](../tool-executor-ptc/README.md) package for executor settings. Custom providers implement only `describe(definitions)` and `execute(batch)`; the shared pipeline is optional. The registry selects the current scoped executor separately for prompt descriptions and each `ctx.tools.execute()` batch. An accepted batch finishes through its selected provider even if that provider unloads; new batches reject until a replacement is registered.
### Restrict tools per agent
@@ -106,20 +100,19 @@ This section explains how the package realizes the behavior above; the observabl
### Design concept
-The registry holds typed `ToolDefinition`s in scoped layers and projects them onto the model-facing `ToolSchema` set at request time — `output`, `execute`, `finalizeContent`, `timeoutMs`, and presentation callbacks never leak onto the wire. Every call runs a fixed pipeline: `tools/pre-execute` (extensible allow/deny/ask) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace, attach context) → definition-owned `finalizeContent` → the observe-only `tools/result` event. Only the `tools/execute` view may replace the required signal, and the registry re-fuses the caller signal before the body.
+The registry holds typed `ToolDefinition`s in scoped layers and projects them onto the model-facing `ToolSchema` set at request time — `output`, `execute`, `finalizeContent`, `timeoutMs`, and presentation callbacks never leak onto the wire. Built-in executors reuse the shared pipeline: `tools/pre-execute` (extensible allow/deny/ask) → registered monotonic guards → `tools/execute` (around-dispatch wrappers) → `tools/post-execute` (inspect/replace, attach context) → definition-owned `finalizeContent` → the observe-only `tools/result` event. Only the `tools/execute` view may replace the required signal, and the registry re-fuses the caller signal before the body.
### Source map
-| File | Role |
-|---|---|
-| [`src/index.ts`](src/index.ts) | Plugin entry: `ToolRuntime` service, config, registry, execution pipeline |
-| [`src/types.ts`](src/types.ts) | `ToolDefinition`, `ToolExecution`, `ToolExecutionResult`, guard and decision types |
-| [`src/schema.ts`](src/schema.ts) | The `defineTool` DSL: `ValueSchemaSpec`, `ParameterSchemaSpec`, `InferValue`, `InferArgs` |
-| [`src/json-schema.ts`](src/json-schema.ts) | The enforced raw JSON Schema subset and validation |
-| [`src/presentation.ts`](src/presentation.ts) | The `card`-tagged UI render intents |
-| [`src/ptc.ts`](src/ptc.ts) | PTC mode: SDK generation, `run_code` dispatch bridge, settlement |
-| [`src/ts-types.ts`](src/ts-types.ts) | TypeScript SDK type rendering |
-| [`src/py-types.ts`](src/py-types.ts) | Python SDK type rendering |
+- [`src/index.ts`](src/index.ts) — Plugin entry and public tool APIs; scoped tool service and executor selection.
+- [`src/contracts.ts`](src/contracts.ts) — Tool definitions, invocation results, guards and decisions.
+- [`src/executor.ts`](src/executor.ts) — Executor descriptions and batch input/output.
+- [`src/pipeline.ts`](src/pipeline.ts) — Shared `prepare`, `dispatch`, and `complete` stages, their result types, and the batch entry point.
+- [`src/batch.ts`](src/batch.ts) — Concurrency, ordered results and optional Session logging.
+- [`src/events.ts`](src/events.ts) — Shared execution policy events.
+- [`src/schema.ts`](src/schema.ts) — Typed tool definitions and model-facing schema projection.
+- [`src/json-schema.ts`](src/json-schema.ts) — Supported JSON Schema validation.
+- [`src/presentation.ts`](src/presentation.ts) — Tool-card render intents.
### Execution and cancellation
@@ -127,13 +120,7 @@ Each typed invocation materializes and freezes parsed arguments, assigns an opaq
### PTC mode
-Under `ptc`, the registry exposes the reserved `run_code` transport plus a deterministic SDK generated in the loaded runtime's language. Each SDK binding captures a frozen ToolSchema and passes it through the scheduler to its execution context. Before policy, a started call records only pairing ids, name, and normalized arguments; its settle event preserves the rendered result, optional presentation metadata, and structured error. Metadata is projected from that call’s canonical value and frozen; it changes neither the program value nor model content. Description and parameters remain transient and never enter Session events or SDK output. Calls are scheduled through a per-run pool that reuses the native concurrency contract. Under `ptc` alone, a model-direct call naming any other visible tool resolves to `UNKNOWN_TOOL` before policy — the announced surface and the callable surface stay the same. Intermediate binding values are execution-local; only the outer `run_code` result has a hard size cap.
-
-New sub-calls use `:ptc:` ids. Consumers treat these ids as opaque and correlate events by exact equality; restored historical ids retain their original bytes. The [PTC mode decision](../../../.agents/notes/implemented/feature/2026-06-15-ptc.md) owns durable naming and restoration rules.
-
-Successful image-bearing subcall results become deferred user-message context with `source.kind` set to `ptc-mode`. Other additional contexts retain their producing tool's attribution.
-
-`run_code` accepts `timeoutMs` when the mounted runtime supports an override; its schema reports the configured default and maximum, and the runtime's usage instructions. The Node default is 120,000 ms with a 600,000 ms cap, including nested tool and approval waits. A wider `sandbox_permissions` mode requires a non-empty `justification` and approval before the program starts. The schema asks the model to write that reason in the current user's language. The grant applies to that complete execution; standing Session policy and nested tools retain their own authority. Programs are never replayed automatically: inspect earlier effects before explicitly retrying a denied program. Retained PTC environments follow the standing file policy. PTC observes committed Session mode changes and immediately cancels affected calls in both Node modes. Later PTC calls wait for their nested-tool cleanup before resolving the latest policy. The runtime owns process invalidation and cleanup; permission setters remain synchronous. One-time escalations omit the state owner and complete in a temporary environment; standing variables remain available to ordinary calls.
+The [PTC executor](../tool-executor-ptc/README.md) owns program transport, SDK generation, nested dispatch, and image context.
### Extension points
@@ -150,9 +137,10 @@ Tool plugins call `ctx.tools.register()` and their schemas flow into prompt asse
The package-level contract is enough for most consumers; read these when you need the surrounding domain.
- [Tools subsystem](../../../docs/subsystems/tools.md) — the full pipeline types, schema DSL, and generated service API.
-- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tools) — the shipped tools' schemas the model receives.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-executor-ptc) — the shipped tools' schemas the model receives.
- [Tool execution pipeline](../../../docs/tool-execution-pipeline.md) — the pipeline visualized.
- [Adding a tool cookbook](../../../docs/cookbook/adding-a-tool.md) — step-by-step tool authoring.
+- [Tool testkit](../../test-support/tool-testkit/README.md) — tool-definition and execution fixtures for tests and benchmarks.
- [Cooperative cancellation Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.md) — the full cancellation contract.
- [Core group map](../README.md) — how the core packages compose.
@@ -165,7 +153,7 @@ The package-level contract is enough for most consumers; read these when you nee
#### What the model sees
-In normal mode the model sees each visible definition's exact name, description, and JSON Schema; the shipped definitions are recorded in the generated [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tools). Agent-scoped restrictions, shadows, and extension registrations change that agent's end-tool set.
+In normal mode the model sees each visible definition's exact name, description, and JSON Schema; the shipped definitions are recorded in the generated [tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-executor-ptc). Agent-scoped restrictions, shadows, and extension registrations change that agent's end-tool set.
#### Token effect
@@ -175,39 +163,6 @@ Fixed per-request cost proportional to the visible definitions. Restrictions tha
Prefix-stable while visible definitions and their order are unchanged. Registration, disposal, or scoped restriction may invalidate reuse from the first changed schema token.
-### PTC mode schema and system prompt
-
-#### What the model sees
-
-PTC mode exposes the generated [`run_code` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tools), the SDK instructions below, and the generated exact SDK block for the loaded runtime's language. Both runtime languages list `code` before `description`; this is presentation order, not an enforced JSON member order. The TypeScript instructions use a return-value example for function-body runtimes and a printed-output example for REPL runtimes. They identify generated declarations as program-only bindings. When the current `bash` parameter schema accepts the example arguments, they also show a complete `run_code` call around `tools.bash(...)`. The `tools:sdk` section uses first-party order 5000 and disables prompt-variable interpolation, preserving literal `{{…}}` text in tool descriptions and schemas for both runtime languages. Under `ptc`, the prompt also carries the `tools:ptc-only` rule earlier in the first-party order, so the model reads which tools it may call before it reads what each one is for.
-
-##### TypeScript PTC mode SDK instructions with bash
-
-```markdown
-## Writing code for run_code
-
-`run_code` takes two required arguments: `code`, the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped), and `description`, a short summary of what the program does. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly. When no separate `bash` schema is supplied, invoke a declared `bash` binding inside `run_code`:
-
-`run_code({ code: "return await tools.bash({ description: 'Show current directory', command: 'pwd' })", description: "Show current directory" })`
-
-Inside the program:
-
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
-- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.
-- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.
-- Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
-
-Program-only SDK bindings:
-```
-
-#### Token effect
-
-Fixed per-request cost proportional to the visible definitions. PTC mode trades end-tool schemas for generated SDK text plus one transport schema rather than promising a universal reduction.
-
-#### KV Cache effect
-
-Prefix-stable while the PTC mode selection, generated SDK, transport schema, and visible tool set are unchanged. Mode or filter changes may invalidate reuse from the first changed prompt or schema token.
-
### Tool-call history and results
#### What the model sees
@@ -233,9 +188,6 @@ These limits define when the registry needs special care. They are current packa
- **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
- **Caller-defined subagent and workflow structured outputs remain object-rooted** — this is a consumer-level guard; the shared schema vocabulary and tool outputs support every JSON root.
- **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-tool-call-timeout-policy` wrapper.
-- **PTC mode's SDK language follows the one loaded runtime, and a presentation is per agent rather than per tool** — `mode: ptc` rejects prompt assembly unless `ctx.ptcRuntime.language` has a registered SDK renderer; within one agent no tool can be native-only while another is ptc-only.
-- **PTC mode intermediate values are execution-local and unbounded by bytes** — they cannot be reconstructed from session replay and may exhaust process or worker memory; only the outer `run_code` output has the worker's configurable hard cap.
-- **State depends on the runtime**: the default backend starts fresh; a REPL backend retains memory per live Agent. Agent disposal awaits release. Restart and execution failures can clear memory; model-visible guidance explains how to recreate missing variables. Programs and results remain in the Session log, without serializing live objects.
`defineTool()`, registry schema projection, and system-prompt assembly preserve `deferLoading: true`. The marker requests deferred definition loading and does not imply a `tool-addition` record; the [LLM package](../../../packages/llm/llm/README.md#known-limitations-and-deferred-work) documents provider enforcement limits.
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 6316543088..c7f07ab753 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -9,7 +9,7 @@ kind: "package-reference"
## 概述
-使用 `dsh-tools` 可向模型公开类型化能力、校验调用、执行允许／拒绝／询问策略，并在普通工具失败时返回最终结果而不中止当前轮次。通过 `mode` 选择原生 Function Calling（函数调用）或 [PTC mode](#ptc-mode)；单个 agent（智能体）可用 `presentAs` 覆盖默认值。工具作者使用 `defineTool` 声明类型化参数与输出、协作式超时、并行安全属性和可选 UI 展示。模型会看到每个获准工具声明的名称、描述与参数 schema；按 agent 设置的限制可缩小该可见集合。
+使用 `dsh-tools` 可向模型公开类型化能力、校验调用、执行允许／拒绝／询问策略，并在普通工具失败时返回最终结果而不中止当前轮次。挂载原生或 PTC 执行器以选择模型交互和批次执行行为。工具作者使用 `defineTool` 声明类型化参数与输出、协作式超时、并行安全属性和可选 UI 展示。模型会看到每个获准工具声明的名称、描述与参数 schema；按 agent 设置的限制可缩小该可见集合。
## 目录
@@ -25,7 +25,7 @@ kind: "package-reference"
## 使用本包
-每个 `run_code` 程序启动时会固定使用 Session 当时的工作目录。嵌套目录切换会影响后续工具调用，而运行中的程序仍保留启动目录。
+`ctx.tools.execute()` 接受完整的原始调用批次。独立服务调用没有 `agent`；模型步骤之外的程序调用（包括初始化钩子）没有 `log`。没有 `log` 的 Agent 仍提供工具作用域，但不会产生根调用／结果事件。
在任何 agent 调用工具的地方挂载 `dsh-tools`：它提供 `ctx.tools`，即每个工具插件注册进去、循环分发所经过的注册表。注册一个工具就足以让它可见——注册表会自动把其 schema 送入系统提示词组装。
@@ -63,22 +63,16 @@ ctx.tools.register(defineTool({
统一 schema DSL 支持 `string`、`number`、`integer`、`boolean`、`null`、`array`、`object`、仅供作者使用的 `json` 与恰好匹配一个分支的 `oneOf`；`InferValue` 在 16 层容器内保留精确类型，之后加宽为 `JsonValue`。原始 JSON Schema（`JsonSchemaNode`）是与 subagent、工作流和 MCP 共享的协议级对应类型。
-### 配置呈现模式
+### 选择执行器
-`mode` 配置决定模型看到什么：`native`（每个可见 schema）或 `ptc`（只有 `run_code` 加一份生成 SDK）。运行时通过 `executionInstructions` 提供求值语法、输出方式和状态保留指引；本包负责工具调用规则、SDK 声明和图片结果附加。
+在部署、预设或 Agent 作用域中挂载一个执行器。最近的作用域决定提供者，同一作用域的重复提供者会报错。原生执行器直接公开可见能力；PTC 执行器公开 `run_code` 和生成的 SDK。
```yaml
- name: '@deepseek-ai/dsh-tools'
- config:
- mode: native
+- name: '@deepseek-ai/dsh-tool-executor-native'
```
-| 字段 | 默认值 | 含义 |
-|---|---|---|
-| `mode` | `native` | 可见工具向模型呈现的方式：`native` 或 `ptc` |
-| `maxParallelSubCalls` | `10` | `run_code` 程序重叠子调用的并发上限；`1` 恢复严格串行分发 |
-
-生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tools)是每个受支持字段的穷尽式真源。非原生模式要求已组合的 `ctx.ptcRuntime` 且其语言有已注册的 SDK 渲染器；agent preset 通过 [`dsh-agent-tool-presentation`](../agent-tool-presentation/README.zh.md) 自行选择呈现方式，单个 agent 可用 `presentAs(mode)` 遮蔽默认值。
+Agent 步骤的并发上限使用 [agent-loop 配置](../agent-loop/README.zh.md)。执行器设置参见[原生](../tool-executor-native/README.zh.md)或 [PTC](../tool-executor-ptc/README.zh.md) 包。自定义提供者只需实现 `describe(definitions)` 和 `execute(batch)`，共享流水线为可选项。注册表分别为提示词描述和每次 `ctx.tools.execute()` 批次选择当前作用域的执行器。已接纳的批次由所选提供者完成，即使该提供者已卸载；注册替代提供者之前，新批次会被拒绝。
### 按 agent 限制工具
@@ -110,16 +104,15 @@ ctx.tools.register(defineTool({
### 源码地图
-| 文件 | 职责 |
-|---|---|
-| [`src/index.ts`](src/index.ts) | 插件入口：`ToolRuntime` 服务、配置、注册表、执行流水线 |
-| [`src/types.ts`](src/types.ts) | `ToolDefinition`、`ToolExecution`、`ToolExecutionResult`、守卫与决策类型 |
-| [`src/schema.ts`](src/schema.ts) | `defineTool` DSL：`ValueSchemaSpec`、`ParameterSchemaSpec`、`InferValue`、`InferArgs` |
-| [`src/json-schema.ts`](src/json-schema.ts) | 强制执行的原始 JSON Schema 子集与校验 |
-| [`src/presentation.ts`](src/presentation.ts) | 带 `card` 标签的 UI 呈现意图 |
-| [`src/ptc.ts`](src/ptc.ts) | PTC mode：SDK 生成、`run_code` 分发桥接层、结算 |
-| [`src/ts-types.ts`](src/ts-types.ts) | TypeScript SDK 类型渲染 |
-| [`src/py-types.ts`](src/py-types.ts) | Python SDK 类型渲染 |
+- [`src/index.ts`](src/index.ts) — 插件入口与公共工具 API；作用域工具服务与执行器选择.
+- [`src/contracts.ts`](src/contracts.ts) — 工具定义、调用结果、守卫与策略决策.
+- [`src/executor.ts`](src/executor.ts) — 执行器描述与批量输入输出.
+- [`src/pipeline.ts`](src/pipeline.ts) — 共享的 `prepare`、`dispatch`、`complete` 阶段、阶段结果类型与批次入口。
+- [`src/batch.ts`](src/batch.ts) — 并发调度、结果顺序与可选 Session 日志.
+- [`src/events.ts`](src/events.ts) — 共享执行策略事件.
+- [`src/schema.ts`](src/schema.ts) — 类型化工具定义与面向模型的 schema 投影。
+- [`src/json-schema.ts`](src/json-schema.ts) — 支持的 JSON Schema 校验.
+- [`src/presentation.ts`](src/presentation.ts) — 工具卡片呈现意图.
### 执行与取消
@@ -127,13 +120,7 @@ ctx.tools.register(defineTool({
### PTC mode
-在 `ptc` 下，注册表公开保留的 `run_code` 传输以及按所加载运行时语言生成的确定性 SDK。每个 SDK 绑定捕获冻结的 ToolSchema，经由调度器传入该次执行上下文。已开始的调用在策略之前只记录配对 id、名称和规范化参数；其结算事件保留渲染结果、可选展示元数据与结构化错误；元数据由该次调用的规范值投影并冻结，不改变程序读取的值或模型内容。描述与参数 schema 仅临时存活，不进入 Session 事件或 SDK 输出。调用通过复用原生并发约定的每次运行独有池调度。在纯 `ptc` 下，模型直呼其他任何可见工具都会在策略之前解析为 `UNKNOWN_TOOL`——通告面与可调用面保持一致。中间绑定值只存在于执行局部；只有外层 `run_code` 结果有硬大小上限。
-
-新子调用使用 `:ptc:` 标识。消费方将这些标识视为不透明值，并通过精确相等关联事件；恢复的历史标识保留原始字节。[PTC mode 决策](../../../.agents/notes/implemented/feature/2026-06-15-ptc.zh.md) 负责持久化命名与恢复规则。
-
-成功且包含图片的子调用结果会成为延后的 user-message 上下文，其 `source.kind` 为 `ptc-mode`。其他 additional context 保留其生产工具的归属。
-
-当已挂载运行时支持覆盖时，`run_code` 接受 `timeoutMs`；其 schema 报告配置的默认值和上限以及运行时使用说明。Node 默认值为 120,000 ms，上限为 600,000 ms，包含嵌套工具和审批等待。更宽的 `sandbox_permissions` 模式要求非空 `justification`，并在程序启动前获得审批。schema 提示模型使用当前用户的语言撰写理由。授权仅用于该次完整执行；常驻 Session 策略与嵌套工具保留各自权限。程序不会自动重放：显式重试被拒程序前，应检查先前已发生的效果。 保留状态的 PTC 环境遵循会话文件策略。PTC 观察已提交的 Session 模式变化，并立即取消两种 Node 模式下受影响的调用。后续 PTC 调用等待这些调用的嵌套工具清理后，再解析最新策略。运行时负责进程失效和清理，权限设置保持同步。单次提权省略状态所有者，在临时环境中执行；普通调用仍可访问原环境的变量。
+[PTC 执行器](../tool-executor-ptc/README.zh.md) 负责程序传输、SDK 生成、嵌套分发和图片上下文。
### 扩展点
@@ -150,9 +137,10 @@ ctx.tools.register(defineTool({
包级约定对大多数消费方已经足够；需要周边领域时再阅读以下页面。
- [工具子系统](../../../docs/subsystems/tools.zh.md)——完整流水线类型、schema DSL 与生成的服务 API。
-- [生成工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tools)——模型收到的已交付工具 schema。
+- [生成工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-executor-ptc)——模型收到的已交付工具 schema。
- [工具执行流水线](../../../docs/tool-execution-pipeline.zh.md)——可视化流水线。
- [添加工具实操手册](../../../docs/cookbook/adding-a-tool.zh.md)——分步骤的工具编写指南。
+- [工具测试工具包](../../test-support/tool-testkit/README.zh.md)——测试和基准测试使用的工具定义与执行 fixture。
- [协作式取消 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-19-cooperative-tool-cancellation.zh.md)——完整取消约定。
- [core 分组地图](../README.zh.md)——core 各包如何组合。
@@ -165,7 +153,7 @@ ctx.tools.register(defineTool({
#### 模型看到什么
-在普通模式下，模型会看到每个可见定义的确切名称、描述与 JSON Schema；已交付定义记录在生成的[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tools)中。agent 作用域的限制、遮蔽与扩展注册会改变该 agent 的最终工具集合。
+在普通模式下，模型会看到每个可见定义的确切名称、描述与 JSON Schema；已交付定义记录在生成的[工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-executor-ptc)中。agent 作用域的限制、遮蔽与扩展注册会改变该 agent 的最终工具集合。
#### Token 影响
@@ -175,39 +163,6 @@ ctx.tools.register(defineTool({
只要可见定义及其顺序不变，前缀就保持稳定。注册、dispose 或作用域限制可能从第一个改变的 schema token 起使复用失效。
-### PTC mode schema 与系统提示词
-
-#### 模型看到什么
-
-PTC mode 会公开生成的 [`run_code` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tools)、下方 SDK 说明，以及按所加载运行时语言生成的精确 SDK 块。两种运行时语言都将 `code` 列在 `description` 前；这是呈现顺序，不强制 JSON 成员顺序。TypeScript 说明对函数体运行时使用返回值示例，对 REPL 运行时使用打印输出示例，并把生成声明明确标为只能在程序内使用的绑定。当当前 `bash` 参数 schema 接受示例参数时，说明还会给出以 `run_code` 包住 `tools.bash(...)` 的完整调用。`tools:sdk` 段使用 first-party 顺序 5000，并关闭提示词变量插值，使两种运行时语言都原样保留工具描述和 schema 中的 `{{…}}` 文本。在 `ptc` 下，提示词还会带上处于更早 first-party 顺序的 `tools:ptc-only` 规则，让模型先读到「可以调用哪些工具」再读「每个工具做什么」。
-
-##### 带 bash 的 TypeScript PTC mode SDK 说明
-
-```markdown
-## Writing code for run_code
-
-`run_code` takes two required arguments: `code`, the body of an async TypeScript function (erasable syntax only — no `enum` or namespaces; type annotations are advisory, the code runs type-stripped), and `description`, a short summary of what the program does. The declarations below are SDK bindings for this program. A declaration does not make its name a directly callable tool; only names supplied as separate tool schemas may be called directly. When no separate `bash` schema is supplied, invoke a declared `bash` binding inside `run_code`:
-
-`run_code({ code: "return await tools.bash({ description: 'Show current directory', command: 'pwd' })", description: "Show current directory" })`
-
-Inside the program:
-
-- Call tools as `await tools.name(args)` — quoted access for exotic names: `tools["my-tool"](args)`. Every call resolves to the tool's typed canonical JSON value. Tool arguments must be lossless JSON.
-- A FAILED tool call rejects with `ToolCallError`, whose `toolName` identifies the failed tool and whose `message` is human-readable — `try/catch` it to handle and continue.
-- Independent read-only calls MAY overlap under `Promise.all` (safe calls run concurrently; mutating calls run alone, in submission order). Sequence dependent work with `await`.
-- Emit results with `return` and/or `console.log(...)`. Only what you print or return is program output. A successful tool result containing an image is attached after the run so you can inspect it on the next step; every other intermediate result stays out of the conversation, so extract just what you need.
-
-Program-only SDK bindings:
-```
-
-#### Token 影响
-
-每次请求的固定成本与可见定义成正比。PTC mode 使用生成的 SDK 文本加一个传输 schema 取代最终工具 schema，但不承诺普遍减少成本。
-
-#### KV Cache 影响
-
-只要 PTC mode 选择、生成的 SDK、传输 schema 与可见工具集合不变，前缀就保持稳定。模式或筛选器变更可能从第一个改变的提示词或 schema token 起使复用失效。
-
### 工具调用历史与结果
#### 模型看到什么
@@ -233,9 +188,6 @@ Program-only SDK bindings:
- **`tools/pre-execute` 有意不允许改写 `exec.arguments`**：否则日志记录与呈现的参数会与实际运行内容失去同步；改写设计记录在[拟议的 Agent Note](../../../.agents/notes/proposed/feature/2026-06-30-pre-tool-input-rewrite.zh.md)中。
- **调用方定义的 subagent 与工作流结构化输出仍要求对象根**：这是消费方层面的守卫；共享 schema 词汇与工具输出支持任意 JSON 根。
- **定义中的 `timeoutMs` 仅作声明之用**：注册表绝不会强制执行截止时间；要强制执行，必须使用 `@deepseek-ai/dsh-tool-call-timeout-policy` 包装层。
-- **PTC mode 的 SDK 语言由当前加载的运行时决定，且呈现方式按 agent 而非按工具**：`mode: ptc` 会拒绝组装提示词，除非 `ctx.ptcRuntime.language` 有已注册的 SDK 渲染器；同一个 agent 内不能让一个工具仅使用 Native，而另一个仅使用 PTC。
-- **PTC mode 中间值只存在于执行局部，且没有字节上限**：它们无法从会话回放重建，并可能耗尽进程或 worker 内存；只有外层 `run_code` 输出受 worker 可配置的硬上限约束。
-- **状态由运行时决定**：默认后端每次重新开始；REPL 后端按存活 Agent 保留内存。Agent 销毁时等待环境释放。重启与执行失败可能清除内存；模型说明会指导重新创建缺失变量。程序与结果仍写入 Session 日志，不序列化运行中的对象。
`defineTool()`、注册表模式投影和系统提示组装会保留 `deferLoading: true`。该标记请求延迟加载工具定义，并不意味着存在 `tool-addition` 记录；提供方执行语义的限制见 [LLM 包](../../../packages/llm/llm/README.zh.md#known-limitations-and-deferred-work)。
diff --git a/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md b/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
index 87b03eba27..b1ad87862a 100644
--- a/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
+++ b/packages/preset/agent-preset/skills/cordis-composition-reference/references/packages.md
@@ -153,10 +153,12 @@ Every package below exports a Cordis plugin that a bundle patch can name in a Lo
| `@deepseek-ai/dsh-agent` | no | Agent interface, registry, initiator scope, and event vocabulary for the DeepSeek Harness |
| `@deepseek-ai/dsh-agent-default-model` | yes | Default model selection shared by Agent entry points |
| `@deepseek-ai/dsh-agent-loop` | yes | The concrete agent loop plugin for the DeepSeek Harness |
-| `@deepseek-ai/dsh-agent-tool-presentation` | yes | Agent-plane presentation selector: composes one agent's tools as PTC mode or native tool calls |
+| `@deepseek-ai/dsh-agent-tool-presentation` | yes | Deprecated tool presentation selector; use dsh-tool-executor-native or dsh-tool-executor-ptc directly |
| `@deepseek-ai/dsh-session` | no | Event-sourced session store for the DeepSeek Harness |
| `@deepseek-ai/dsh-system-prompt` | yes | System prompt assembly registry for the DeepSeek Harness |
-| `@deepseek-ai/dsh-tools` | yes | Tool registry and execution pipeline for the DeepSeek Harness |
+| `@deepseek-ai/dsh-tool-executor-native` | yes | Native tool execution plugin |
+| `@deepseek-ai/dsh-tool-executor-ptc` | yes | PTC program execution, tool bindings, and generated SDK prompts |
+| `@deepseek-ai/dsh-tools` | no | Tool registry and execution pipeline for the DeepSeek Harness |
## credentials
diff --git a/packages/test-support/README.i18n.yaml b/packages/test-support/README.i18n.yaml
index ac02c6c827..4075580b2a 100644
--- a/packages/test-support/README.i18n.yaml
+++ b/packages/test-support/README.i18n.yaml
@@ -15,8 +15,8 @@
en: 1eb35b015a6c423f
zh: a8a3dceee2c9e943
/packages-test-support/packages:
- en: 94395ff952ce77ee
- zh: 4ae6afc3fe0c71dd
+ en: 15c602cea9f84f94
+ zh: d806d9eb4d958356
/packages-test-support/related-documentation:
en: 938bb087afd96c3e
zh: 0d51d0d7c0915602
diff --git a/packages/test-support/README.md b/packages/test-support/README.md
index 7608dc8696..a87f0a18fc 100644
--- a/packages/test-support/README.md
+++ b/packages/test-support/README.md
@@ -26,6 +26,7 @@ The test-support group gives repository tests deterministic, keyless ways to exe
|---|---|
| [`session-snapshot`](session-snapshot/README.md) | Provides session-log snapshot support and protocol adapters for profile-driven tests |
| [`agent-loop-testkit`](agent-loop-testkit/README.md) | Provides the shared prerequisite services for tests that exercise the concrete AgentLoop |
+| [`tool-testkit`](tool-testkit/README.md) | Defines tool fixtures and exercises invocation or executor behavior in tests |
| [`client-runtime`](client-runtime/README.md) | Provides the jsdom slot test bench for browser feature specs |
| [`remote-mock`](remote-mock/README.md) | Provides the endpoint-named Typert Remote mock and the Connection carrier face whole-client specs install |
| [`loader-smoke`](loader-smoke/README.md) | Boots Loader-composed applications and drives fixture turns for smoke tests |
diff --git a/packages/test-support/README.zh.md b/packages/test-support/README.zh.md
index f82c47d835..0138f77e63 100644
--- a/packages/test-support/README.zh.md
+++ b/packages/test-support/README.zh.md
@@ -26,6 +26,7 @@ test-support 组为仓库测试提供确定且无须密钥的真实产品测试
|---|---|
| [`session-snapshot`](session-snapshot/README.zh.md) | 为 profile 驱动的测试提供 session-log 快照支持与协议适配器 |
| [`agent-loop-testkit`](agent-loop-testkit/README.zh.md) | 为运行具体 AgentLoop 的测试提供共享先决服务 |
+| [`tool-testkit`](tool-testkit/README.zh.md) | 定义工具 fixture，并在测试中执行工具调用或执行器行为 |
| [`client-runtime`](client-runtime/README.zh.md) | 为浏览器功能测试提供 jsdom slot 测试台 |
| [`remote-mock`](remote-mock/README.zh.md) | 为整体客户端测试提供端点具名的 Typert Remote mock 与它们安装的 Connection 载体面 |
| [`loader-smoke`](loader-smoke/README.zh.md) | 启动由 Loader 组合的应用并驱动 fixture（测试前置数据）轮次以执行冒烟测试 |
diff --git a/packages/test-support/tool-testkit/README.i18n.yaml b/packages/test-support/tool-testkit/README.i18n.yaml
new file mode 100644
index 0000000000..378182bb6c
--- /dev/null
+++ b/packages/test-support/tool-testkit/README.i18n.yaml
@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write packages/test-support/tool-testkit/README.md
+/:
+ en: 6c56a58c1397154b
+ zh: 7e37b4f4915f0a75
+/deepseek-ai-dsh-tool-testkit:
+ en: 6f5f9186228a4b87
+ zh: e05d9c94ad8a6c2e
+/deepseek-ai-dsh-tool-testkit/summary:
+ en: 36a296389a56ac64
+ zh: f1aecbfb8f0ce528
+/deepseek-ai-dsh-tool-testkit/table-of-contents:
+ en: d152484eb41ac6b4
+ zh: 1db86285abf6c499
+/deepseek-ai-dsh-tool-testkit/use-this-package:
+ en: 0489d9c434d64281
+ zh: 02e72be3ec225898
+/deepseek-ai-dsh-tool-testkit/understand-the-implementation:
+ en: 236c624cc2445cd1
+ zh: 60d9dbafe03332b9
+/deepseek-ai-dsh-tool-testkit/further-exploration:
+ en: db619f3ee3d024ef
+ zh: 02e35fcebaebd40e
+/deepseek-ai-dsh-tool-testkit/model-experience:
+ en: 478835c82631e8c3
+ zh: cb4f938bcaa046be
+/deepseek-ai-dsh-tool-testkit/model-experience/kv-cache-effect:
+ en: be3fa044c8f27bf0
+ zh: 35fdb79b58ba91f6
+/deepseek-ai-dsh-tool-testkit/known-limitations-and-deferred-work:
+ en: c21236a743177477
+ zh: 8cc8678c2133a8be
+/deepseek-ai-dsh-tool-testkit/known-limitations-and-deferred-work/dev-note:
+ en: e67f633dc6fe7773
+ zh: e88aeb617ffb74ea
diff --git a/packages/test-support/tool-testkit/README.md b/packages/test-support/tool-testkit/README.md
new file mode 100644
index 0000000000..adb881d574
--- /dev/null
+++ b/packages/test-support/tool-testkit/README.md
@@ -0,0 +1,91 @@
+---
+description: "Define test tools and invoke tool pipelines or selected executors in repository tests and benchmarks."
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-tool-testkit
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use this package to define content-producing test tools and exercise tool execution without running an Agent turn. Tests and benchmarks import its helpers as a development dependency. Callers own the Cordis context, plugin composition, and teardown.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+
+## Use this package
+
+Add `@deepseek-ai/dsh-tool-testkit` to the consuming package's `devDependencies`. Define a fixture when the test needs rendered content without a domain-specific result value:
+
+```ts
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tool-testkit'
+
+const tool = defineContentToolFixture({
+ name: 'echo',
+ description: 'Return a test message.',
+ parameters: {},
+ execute: async () => [{ type: 'text', text: 'hello' }],
+})
+```
+
+Register the returned definition through the caller's tool registry. Use `executeToolFixture` for an already-parsed invocation, or `executeModelToolFixture` to pass one JSON-encoded call through the selected executor. The latter requires the caller to mount that executor and rejects arguments that cannot be JSON-encoded or an executor response without a result. See [`src/index.ts`](src/index.ts) for invocation fields.
+
+-----
+
+
+## Understand the implementation
+
+
+Implementation internals — click to expand
+
+[`src/index.ts`](src/index.ts) adapts content blocks into a tool's canonical JSON value and delegates execution to the production pipeline or registry. It creates no context and owns no plugin registrations.
+
+
+
+-----
+
+
+## Further Exploration
+
+- [Tools package](../../core/tools/README.md) — tool definitions, registry, and execution policy.
+- [Testing policy](../../../docs/testing.md) — choosing verification for production behavior.
+- [Test-support group map](../README.md) — sibling test utilities.
+
+-----
+
+
+## Model Experience
+
+None, as these test helpers do not assemble or send model requests.
+
+#### KV Cache effect
+
+None; the package itself sends no provider request.
+
+## Known Limitations and Deferred Work
+
+
+
+- Content-array values are test fixtures; product tools declare domain-owned output schemas.
+- Direct pipeline execution omits model-batch scheduling. Both execution helpers omit root Session logging; use an Agent turn when verifying the recorded conversation.
+- Plugin composition and context disposal remain caller-owned.
+
+
+### Dev Note
+
+
+Working context for maintainers — click to expand
+
+None.
+
+
diff --git a/packages/test-support/tool-testkit/README.zh.md b/packages/test-support/tool-testkit/README.zh.md
new file mode 100644
index 0000000000..7af0575834
--- /dev/null
+++ b/packages/test-support/tool-testkit/README.zh.md
@@ -0,0 +1,91 @@
+---
+description: "在仓库测试和基准测试中定义测试工具，并调用工具流水线或选定的执行器。"
+kind: "package-library"
+---
+
+# @deepseek-ai/dsh-tool-testkit
+
+[English](README.md) | 中文
+
+## 概述
+
+使用本包定义生成内容的测试工具，并在不运行 Agent 回合的情况下测试工具执行。测试和基准测试将这些辅助函数作为开发依赖导入。调用方负责 Cordis context、插件组合和资源清理。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与后续工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+
+## 使用本包
+
+将 `@deepseek-ai/dsh-tool-testkit` 加入消费包的 `devDependencies`。测试只需要渲染内容而不需要领域结果值时，可以定义以下 fixture：
+
+```ts
+import { defineContentToolFixture } from '@deepseek-ai/dsh-tool-testkit'
+
+const tool = defineContentToolFixture({
+ name: 'echo',
+ description: 'Return a test message.',
+ parameters: {},
+ execute: async () => [{ type: 'text', text: 'hello' }],
+})
+```
+
+通过调用方的工具注册表注册返回的定义。使用 `executeToolFixture` 执行已解析的调用，或使用 `executeModelToolFixture` 将一次 JSON 编码的调用交给选定的执行器。后者要求调用方挂载该执行器，并在参数无法编码为 JSON 或执行器响应缺少结果时拒绝。调用字段见 [`src/index.ts`](src/index.ts)。
+
+-----
+
+
+## 理解实现
+
+
+实现细节——点击展开
+
+[`src/index.ts`](src/index.ts) 将内容块适配为工具的规范 JSON 值，并将执行委托给生产流水线或注册表。它不创建 context，也不持有插件注册。
+
+
+
+-----
+
+
+## 进一步探索
+
+- [工具包](../../core/tools/README.zh.md)——工具定义、注册表和执行策略。
+- [测试策略](../../../docs/testing.zh.md)——为生产行为选择验证方式。
+- [test-support 分组地图](../README.zh.md)——同组测试工具。
+
+-----
+
+
+## 模型体验
+
+无，这些测试辅助函数不组装或发送模型请求。
+
+#### KV Cache 影响
+
+无；本包自身不发送 provider 请求。
+
+## 已知限制与后续工作
+
+
+
+- 内容数组值仅用于测试 fixture；产品工具声明领域自己的输出 schema。
+- 直接执行流水线不包含模型批次调度。两种执行辅助函数都不记录根 Session 日志；验证会话记录时应运行 Agent 回合。
+- 插件组合和 context 释放仍由调用方负责。
+
+
+### 开发备注
+
+
+维护者工作上下文——点击展开
+
+无。
+
+