dsh-plugin-dev-kb 1.5.2 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-model-catalog/guide.zh.md

@@ -0,0 +1,53 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 目录移除了部分模型 ID，并降低了部分模型容量。"
+---
+
+# pi-ai 1.3.0 模型目录变更
+
+[English](guide.md) | 中文
+
+## 变更
+
+pi-ai 依赖从 1.1.0 升级到 1.3.0。以下聊天模型 ID 不再包含在目录中。已保存的 `modelOverrides` 会报告目录条目缺失诊断；新的覆盖配置会被拒绝。显式 `models` 条目会失去目录默认值。
+
+| 提供商 | 已移除的模型 ID |
+|---|---|
+| `google-vertex` | `gemini-flash-latest`, `gemini-flash-lite-latest` |
+| `nvidia` | `moonshotai/kimi-k3`, `nvidia/nemotron-3-super-120b-a12b` |
+| `opencode` | `exo-free`, `fledge-alpha-free`, `ling-3.0-flash-fin-free`, `ling-3.1-flash-free` |
+| `opencode-go` | `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`, `grok-4.6`, `minimax-m2.7` |
+| `openrouter` | `anthropic/claude-sonnet-4`, `apodex/apodex-1.1-mini:free`, `inclusionai/ling-3.0-flash-fin`, `inclusionai/ling-3.0-flash-sante:free`, `qwen/qwen-plus-2025-07-28`, `qwen/qwen3-235b-a22b`, `qwen/qwen3-30b-a3b-thinking-2507`, `qwen/qwen3-8b`, `qwen/qwen3-coder-plus`, `qwen/qwen3-max`, `qwen/qwen3-max-thinking`, `qwen/qwen3-vl-235b-a22b-thinking`, `qwen/qwen3-vl-32b-instruct`, `qwen/qwen3-vl-8b-thinking`, `qwen/qwen3.6-max-preview`, `sao10k/l3.1-euryale-70b`, `unbiased/pareto`, `unbiased/pareto-26.10-preview` |
+| `vercel-ai-gateway` | `alibaba/qwen-3.6-max-preview`, `alibaba/qwen3-235b-a22b-thinking`, `alibaba/qwen3-coder-plus`, `alibaba/qwen3-max`, `alibaba/qwen3-max-preview`, `alibaba/qwen3-vl-235b-a22b-instruct`, `alibaba/qwen3-vl-thinking`, `anthropic/claude-3-haiku`, `anthropic/claude-opus-4`, `inclusionai/ling-3.1-flash-free` |
+
+以下目录限制降低。数值以 token 为单位；`—` 表示该限制未降低。显式覆盖值仍然优先。`maxTokens` 描述模型容量，不是隐式的请求限制。
+
+| 提供商/模型 | 新 contextWindow / maxTokens |
+|---|---|
+| `anthropic/claude-sonnet-4-5` | 200000 / — |
+| `anthropic/claude-sonnet-4-5-20250929` | 200000 / — |
+| `openrouter/deepseek/deepseek-v4-flash` | 1048575 / 943717 |
+| `openrouter/inclusionai/ling-3.0-flash-vl` | 131072 / — |
+| `openrouter/meta-llama/llama-4-scout` | 131072 / — |
+| `openrouter/minimax/minimax-m2` | — / 131072 |
+| `openrouter/minimax/minimax-m2.5` | 198000 / 32768 |
+| `openrouter/minimax/minimax-m2.7` | — / 131072 |
+| `openrouter/moonshotai/kimi-k2-thinking` | — / 98304 |
+| `openrouter/nvidia/nemotron-3-ultra-550b-a55b` | 202800 / — |
+| `openrouter/openai/gpt-oss-120b` | — / 65536 |
+| `openrouter/qwen/qwen3-235b-a22b-thinking-2507` | 128000 / 16384 |
+| `openrouter/qwen/qwen3.5-35b-a3b` | 256000 / 16384 |
+| `openrouter/qwen/qwen3.8-2.4t-a95b` | 1000000 / — |
+| `openrouter/qwen/qwen3.8-27b` | 262144 / — |
+| `openrouter/~z-ai/glm-latest` | — / 131072 |
+| `radius/claude-sonnet-4-5` | 200000 / — |
+| `vercel-ai-gateway/alibaba/qwen3-coder` | — / 32768 |
+| `vercel-ai-gateway/deepseek/deepseek-v4.1-flash-fast` | — / 32768 |
+
+`vercel-ai-gateway` 的 `alibaba/qwen-3-235b` 模型现在被声明为非推理模型。协议与推理强度变更见[单独的指南](../pi-ai-protocol-replay/guide.zh.md)。
+
+## 迁移
+
+1. 在“设置 → 模型”中，将已移除的 ID 替换为受支持的模型。检查端点、能力和价格；ID 没有自动替代项。
+2. 更新 `cordis.patch.yml`、preset patch 和受影响 Session 中的模型选择。移除过时的 `providers.<provider>.modelOverrides.<id>` 条目，并替换 `providers.<provider>.models` 列表中已移除的 ID。参见[配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。
+3. 根据端点支持的值检查容量与推理覆盖配置。启动 profile，确认模型没有配置诊断，再发送一个简短提示。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-protocol-replay/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 changes provider protocols, reasoning choices, history replay, and invalid tool-argument handling."
+---
+
+# pi-ai 1.3.0 protocol and replay changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The pi-ai upgrade from 1.1.0 to 1.3.0 changes these defaults. Explicit profile overrides still win.
+
+| Route or behavior | New behavior |
+|---|---|
+| `kimi-coding` | Uses `openai-completions` at `https://api.kimi.com/coding/v1` instead of `anthropic-messages` at `/coding` |
+| `opencode`, `opencode-go` | Endpoints replace `/zen` with `/inference`; `/go` and `/v1` suffixes remain model-specific |
+| Xiaomi MiMo catalogs, including token-plan routes | Offer only `off` and `high` reasoning |
+| `kimi-coding/kimi-for-coding-highspeed` | Does not offer reasoning `off` |
+| Assistant reasoning history | Outgoing requests omit thinking from another provider, API, or model instead of converting it to text; degraded replay without native metadata also omits thinking |
+| Invalid completed tool arguments | The attempt fails with `MALFORMED_RESPONSE`; it executes no tools and publishes no successful replay state. The default normal retry policy excludes this code |
+
+Stored history is retained. Returning to the original model restores its valid native replay metadata. Output truncated by the token limit still drops incomplete tool calls and can continue normally. Credentials do not require migration.
+
+## Migration
+
+1. Review `providers.<provider>.baseURL`, `api`, and `compat` overrides in `cordis.patch.yml`. For overrides that follow the upstream Kimi Coding endpoint, use the Completions protocol and `/v1` path. Custom gateways must explicitly retain their actual protocol and path. Update OpenCode URLs to `/inference` where applicable. Omit overrides when catalog defaults are intended.
+2. Replace unsupported reasoning selections in profiles, presets, and Sessions with a level shown by the current model metadata.
+3. Put facts needed across model changes in user messages or normal assistant replies; do not rely on prior private reasoning becoming visible text.
+4. For `MALFORMED_RESPONSE`, inspect the reported invalid arguments and correct the model or gateway output. Verify the affected route with a short prompt and a tool call. See the [configuration reference](../../../../packages/llm/llm-pi-ai/README.md).

package/kb/extra/upgrade-guide/v0.2.1-rc.2/pi-ai-protocol-replay/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 改变了提供方协议、推理选项、历史回放以及无效工具参数的处理方式。"
+---
+
+# pi-ai 1.3.0 协议与回放变更
+
+[English](guide.md) | 中文
+
+## 变更
+
+pi-ai 从 1.1.0 升级到 1.3.0 时改变了以下默认行为。显式 profile 覆盖值仍然优先。
+
+| 路由或行为 | 新行为 |
+|---|---|
+| `kimi-coding` | 使用 `https://api.kimi.com/coding/v1` 上的 `openai-completions`，替代 `/coding` 上的 `anthropic-messages` |
+| `opencode`、`opencode-go` | 端点将 `/zen` 替换为 `/inference`；`/go` 和 `/v1` 后缀仍由模型决定 |
+| Xiaomi MiMo 目录，包括 token-plan 路由 | 只提供 `off` 和 `high` 推理选项 |
+| `kimi-coding/kimi-for-coding-highspeed` | 不提供推理 `off` 选项 |
+| assistant 推理历史 | 发出的请求会省略来自另一提供方、API 或模型的思考，而不再将其转换为文本；缺少原生元数据的降级回放也会省略思考 |
+| 已完成调用的工具参数无效 | 本次尝试以 `MALFORMED_RESPONSE` 失败，不执行任何工具，也不发布成功的回放状态。默认的普通重试策略不重试此错误码 |
+
+存储的历史保持不变。切回原模型时会恢复其有效的原生回放元数据。达到 token 限制而截断的输出仍会丢弃未完成的工具调用，并可正常续写。凭据无需迁移。
+
+## 迁移
+
+1. 检查 `cordis.patch.yml` 中的 `providers.<provider>.baseURL`、`api` 和 `compat` 覆盖配置。对于跟随上游 Kimi Coding 端点的覆盖配置，使用 Completions 协议和 `/v1` 路径。自定义网关必须显式保留其实际协议和路径。按需将 OpenCode URL 更新为 `/inference`。若希望使用目录默认值，请省略覆盖配置。
+2. 将 profile、preset 和 Session 中不受支持的推理选项替换为当前模型元数据列出的级别。
+3. 将切换模型后仍需要的事实放入用户消息或普通 assistant 回复；不要依赖先前的私有推理转换为可见文本。
+4. 出现 `MALFORMED_RESPONSE` 时，检查诊断中的无效参数，并修正模型或网关输出。用一个简短提示和一次工具调用验证受影响的路由。参见[配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "PTC programFormat includes Script syntax, and consumers read retainsState for cross-call memory."
+---
+
+# Handle Script programs and explicit state retention
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The published `@deepseek-ai/dsh-ptc-runtime` service widens `PtcRuntime.programFormat` from `'function-body' | 'repl'` to include `'script'`. External consumers that exhaustively match the old union must handle the new value. `retainsState` reports whether a provider preserves memory for a `stateOwner`; its base implementation returns `false`, so custom retained providers must override it.
+
+Node keeps `per-call` as its default. The opt-in `executionMode: vm-script` accepts Script statements and top-level await, with `scriptPersistence` selecting cross-call memory independently. Existing Node function-body and REPL configurations remain valid.
+
+## Migration
+
+1. Import the exported `PtcProgramFormat` from `@deepseek-ai/dsh-ptc-runtime` instead of copying its union literals. Update `programFormat` switches in custom tool or workflow adapters. Handle `'script'` using statements or a final expression, without top-level `return`; consult the [Node syntax reference](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#use-this-package).
+2. Replace checks that infer memory retention from `programFormat === 'repl'` with `runtime.retainsState`. If a custom `PtcRuntime` provider retains owner-scoped memory, override `retainsState` to return `true` and continue implementing `release(owner)`.
+3. Rebuild external consumers against the new package declarations. Confirm that each supported format compiles and that persistence controls follow `retainsState` for both REPL and Script providers.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "PTC programFormat 新增 Script 语法，消费者通过 retainsState 判断跨调用内存保留。"
+---
+
+# 处理 Script 程序与显式状态保留
+
+[English](guide.md) | 中文
+
+## 变更
+
+已发布的 `@deepseek-ai/dsh-ptc-runtime` 服务将 `PtcRuntime.programFormat` 从 `'function-body' | 'repl'` 扩展为包含 `'script'`。对旧联合类型做穷举匹配的外部消费者必须处理新值。`retainsState` 表示提供方是否为 `stateOwner` 保留内存；基类实现返回 `false`，因此自定义保留状态的提供方必须覆盖该 getter。
+
+Node 仍默认使用 `per-call`。显式启用的 `executionMode: vm-script` 接受 Script 语句和顶层 await，`scriptPersistence` 独立选择是否跨调用保留内存。已有 Node 函数体和 REPL 配置仍然有效。
+
+## 迁移
+
+1. 从 `@deepseek-ai/dsh-ptc-runtime` 导入已导出的 `PtcProgramFormat`，不复制其联合类型字面量。更新自定义工具或工作流适配器中的 `programFormat` 分支。使用语句或末尾表达式处理 `'script'`，不使用顶层 `return`；参见 [Node 语法参考](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#use-this-package)。
+2. 将通过 `programFormat === 'repl'` 推断内存保留的检查改为读取 `runtime.retainsState`。自定义 `PtcRuntime` 提供方若按所有者保留内存，应覆盖 `retainsState` 并返回 `true`，同时继续实现 `release(owner)`。
+3. 使用新的包声明重新构建外部消费者。确认所有支持的格式均可编译，并且持久化控制对 REPL 和 Script 提供方都按 `retainsState` 判断。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/sdk-desktop-context/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: The existing SDK profile includes native desktop tools and model context.
+---
+
+# SDK desktop tools and context
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The existing `sdk` profile now includes `present`, `ask_user_question`, schedule tools, file-reference guidance and time context. It does not start a Web server. Native tool execution remains the default; select PTC through an [executor overlay](../tool-executor-plugins/guide.md). `sdk-minimal` is unchanged.
+
+## Migration
+
+1. Keep selecting `sdk`. Provide `onUserQuestion` (TypeScript) or `on_user_question` (Python) to answer built-in questions over the native protocol, or retain an in-process `user-questions/request` answerer; without one, the tool reports `NO_PROVIDER`.
+2. Working directory and model still come from SDK initialization. The SDK profile does not mount the Web-specific checkout and GUI development context.
+3. Custom compositions that need the previous model-visible tool/context roster can disable the `present`, `tool-ask-user`, `tool-schedule`, `file-reference-local`, `deliverable-file-references`, and `time-context` rows. Review any pinned prompts and tool schemas before upgrading.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/sdk-desktop-context/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: 现有 SDK profile 包含原生桌面工具和模型上下文。
+---
+
+# SDK 桌面工具与上下文
+
+[English](guide.md) | 中文
+
+## 变更
+
+现有 `sdk` profile 现在包含 `present`、`ask_user_question`、定时任务工具、文件引用说明和时间上下文。它不启动 Web server。默认仍使用原生工具执行；通过[执行器 overlay](../tool-executor-plugins/guide.zh.md) 选择 PTC。`sdk-minimal` 保持不变。
+
+## 迁移
+
+1. 继续选择 `sdk`。通过 `onUserQuestion`（TypeScript）或 `on_user_question`（Python）使用原生协议回答内建问题，或保留进程内的 `user-questions/request` 回答方；没有回答方时，工具报告 `NO_PROVIDER`。
+2. 工作目录和模型仍来自 SDK 初始化。SDK profile 不挂载 Web 专用的 checkout 和 GUI 开发上下文。
+3. 需要保留之前模型可见工具/上下文组合的自定义配置，可以禁用 `present`、`tool-ask-user`、`tool-schedule`、`file-reference-local`、`deliverable-file-references` 和 `time-context` 配置项。升级前请检查固定的提示词和工具 schema。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/sdk-minimal-checkpoints/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The sdk-minimal profile now stops model and tool dispatch when session persistence cannot complete a checkpoint."
+---
+
+# SDK-minimal requires durable checkpoints
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `sdk-minimal` profile enables `session-checkpoint-policy`. It waits for session history to flush before model requests, top-level tool execution, and agent steps. Previously these operations could proceed while JSONL writes were buffered; persistence errors could remain background warnings. A checkpoint failure now stops the dependent operation. First-use file-lock initialization is paid before the first model request, and checkpoint writes contribute to request latency. This does not change the Session format or guarantee that forced termination preserves the final unflushed response.
+
+## Migration
+
+1. Keep the selected `dsh_home` writable and allow request deadlines to cover storage initialization and checkpoint writes. A longer shutdown timeout alone does not affect a pre-request checkpoint.
+2. Check profile and invocation patches for overrides of `session-checkpoint-policy`. To receive the durability policy, retain its enabled default alongside `sessions`.
+3. Run a short SDK turn, close normally, and use `resume_session()` with the same home and session ID to verify restoration. Investigate checkpoint failures before retrying model or tool work; the operation does not run until the checkpoint succeeds.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/sdk-minimal-checkpoints/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "sdk-minimal profile 现在会在会话持久化无法完成检查点时停止模型和工具调度。"
+---
+
+# SDK-minimal 要求持久化检查点
+
+[English](guide.md) | 中文
+
+## 变更
+
+`sdk-minimal` profile 启用 `session-checkpoint-policy`，在模型请求、顶层工具执行和 agent step 之前等待会话历史刷盘。此前，JSONL 写入尚在缓冲时这些操作也可以继续，持久化错误可能只记录为后台警告。现在，检查点失败会停止依赖它的操作。首次文件锁初始化发生在第一次模型请求之前，检查点写入也计入请求延迟。此变更不修改 Session 格式，也不保证强制终止时保留最后尚未刷盘的回复。
+
+## 迁移
+
+1. 确保选定的 `dsh_home` 可写，并让请求超时覆盖存储初始化和检查点写入。仅延长关闭超时不会影响请求前的检查点。
+2. 检查 profile 和调用级 patch 是否覆盖了 `session-checkpoint-policy`。要使用此持久化策略，应在 `sessions` 旁保留其默认启用状态。
+3. 运行一轮 SDK 短对话，正常关闭，再使用相同 home 和会话 ID 调用 `resume_session()` 验证恢复。重试模型或工具操作前，先排查检查点失败；只有检查点成功后，操作才会执行。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-projection-handles/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Session projection registration resolves asynchronously to a retained reader; the callable result and registry-level state reads are deprecated."
+---
+# Session projection registration handles
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-session-projection` changes `SessionProjectionRegistry.register(definition)` from a synchronous disposer to `Promise<ProjectionHandle<S>>`. The definition installs synchronously; awaiting the result yields a handle with `stateOf(session)` and `dispose()`, and registration errors reject it. The runtime value is a callable thenable, not a native Promise: calling it still releases the registration, but that call is deprecated. `typeof registration` is `"function"` and `registration instanceof Promise` is false, so code that branches on those checks or treats functions as callbacks is affected; Vitest's `.rejects` calls it instead of observing the rejection.
+
+Registry-level `stateOf(session, key): unknown` is deprecated. It returns `undefined` whenever no plugin currently registers the key: its owner is not composed, has not reached registration, or has released its last registration. `SessionProjectionStateMap` is removed; host state types stay local to `ProjectionDefinition<K, S>` and are inferred from `stateSchema`. After the last registration is disposed, the unit leaves snapshots, checkpoints, and live notifications, but retained handles still fold Session events on demand. [Runtime compatibility](../../../../packages/session/session-projection/README.md#deprecated-plugin-compatibility) details the deprecated calls.
+
+`@deepseek-ai/dsh-agent` and `@deepseek-ai/dsh-subagent` require `sessionProjections`. AgentRegistry owns turn and step state and provides `ctx.agents.turnBoundaryOf(session)`; `@deepseek-ai/dsh-agent-loop` no longer exports `turnBoundaryProjectionDefinition`. Turn-state consumers, including the Claude Code mods bridge, require `agents`. Preset and context-pressure reads use `ctx.agentPresets.presetForSession(session)` and `ctx.tokenMeter.contextPressure(session)`. The API controller and mods bridge no longer register those definitions independently; their optional-service behavior applies when the owning service is absent. `@deepseek-ai/dsh-api-session-controller` removes `installModelSelectionProjection`.
+
+## Migration
+
+1. Mount `SessionProjectionRegistry` before `AgentRegistry`, `SubagentRuntime`, and other projection owners in custom compositions. Include `@deepseek-ai/dsh-agent` wherever a plugin requires `agents`.
+2. For a plugin's own definitions, await `ctx.sessionProjections.register(definition)` in asynchronous `apply()` or `[Service.init]()` and retain the handle before publishing dependent operations. Remove `SessionProjectionStateMap` augmentations and pass the state type as the second `ProjectionDefinition<K, S>` argument. Keep client-value declarations in `SessionProjectionMap`.
+3. Replace `registry.stateOf(session, key)` with the owning service's method, such as `ctx.agents.turnBoundaryOf(session)`, or `handle.stateOf(session)` inside the owner; until then, handle its `undefined` result. Replace calls to the registration result with an awaited `handle.dispose()`; fiber disposal still releases registrations automatically.
+4. Where a native Promise is required, pass `Promise.resolve(registration)`, including `await expect(Promise.resolve(registration)).rejects.toThrow(...)` in Vitest. Replace `typeof` or `instanceof Promise` checks on the result with awaiting.
+5. Replace `installModelSelectionProjection(ctx)` with `await ctx.sessionProjections.register(modelSelectionProjection)`, importing the definition from `@deepseek-ai/dsh-api-session-controller/src/model-selection-projection.ts`.
+6. Typecheck custom plugins, then verify activation, a Session state read, a rejected registration, and owner disposal.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-projection-handles/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Session 投影注册异步解析为保留读取能力的句柄；可调用的注册结果与注册表级状态读取已弃用。"
+---
+# Session 投影注册句柄
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-projection` 的 `SessionProjectionRegistry.register(definition)` 从同步释放函数改为 `Promise<ProjectionHandle<S>>`。定义同步安装；等待结果得到带 `stateOf(session)` 与 `dispose()` 的句柄，注册错误使结果拒绝。运行时返回值是可调用的 thenable，而非原生 Promise：调用它仍会释放注册，但该调用已弃用。`typeof registration` 为 `"function"`，`registration instanceof Promise` 为 false，因此按这些检查分支或把函数视为回调的代码会受影响；Vitest 的 `.rejects` 会调用它，而不是观察拒绝。
+
+注册表级 `stateOf(session, key): unknown` 已弃用。当前没有任何插件注册该 key 时它返回 `undefined`：所属插件未组合、尚未执行到注册，或已释放最后一次注册。`SessionProjectionStateMap` 已移除；宿主状态类型保留在各自的 `ProjectionDefinition<K, S>` 中，并从 `stateSchema` 推导。最后一次注册释放后，该投影单元不再参与快照、检查点和实时通知，但保留的句柄仍可按需折叠 Session 事件。[运行时兼容说明](../../../../packages/session/session-projection/README.zh.md#deprecated-plugin-compatibility)详述这些已弃用调用。
+
+`@deepseek-ai/dsh-agent` 与 `@deepseek-ai/dsh-subagent` 依赖 `sessionProjections`。AgentRegistry 持有轮次和步骤状态，并提供 `ctx.agents.turnBoundaryOf(session)`；`@deepseek-ai/dsh-agent-loop` 不再导出 `turnBoundaryProjectionDefinition`。包括 Claude Code mods 桥接在内的轮次状态消费方依赖 `agents`。预设与上下文压力分别通过 `ctx.agentPresets.presetForSession(session)` 和 `ctx.tokenMeter.contextPressure(session)` 读取。API 控制器与 mods 桥接不再独立注册这些定义；所属服务缺席时采用各自的可选服务行为。`@deepseek-ai/dsh-api-session-controller` 移除了 `installModelSelectionProjection`。
+
+## 迁移
+
+1. 在自定义组合中，先挂载 `SessionProjectionRegistry`，再挂载 `AgentRegistry`、`SubagentRuntime` 及其他投影所有者。组合中的插件依赖 `agents` 时，加入 `@deepseek-ai/dsh-agent`。
+2. 对插件自己的定义，在异步 `apply()` 或 `[Service.init]()` 中等待 `ctx.sessionProjections.register(definition)`，并在提供依赖操作前保存句柄。删除 `SessionProjectionStateMap` 的声明合并，将状态类型作为 `ProjectionDefinition<K, S>` 的第二个类型参数。保留 `SessionProjectionMap` 中的客户端值声明。
+3. 将 `registry.stateOf(session, key)` 替换为所属服务的方法（例如 `ctx.agents.turnBoundaryOf(session)`），或所有者内部的 `handle.stateOf(session)`；替换之前须处理其 `undefined` 结果。将对注册结果的调用替换为等待 `handle.dispose()`；fiber 释放仍会自动释放注册。
+4. 需要原生 Promise 时传入 `Promise.resolve(registration)`，包括在 Vitest 中写 `await expect(Promise.resolve(registration)).rejects.toThrow(...)`。将对结果的 `typeof` 或 `instanceof Promise` 检查改为直接等待。
+5. 将 `installModelSelectionProjection(ctx)` 替换为 `await ctx.sessionProjections.register(modelSelectionProjection)`，从 `@deepseek-ai/dsh-api-session-controller/src/model-selection-projection.ts` 导入该定义。
+6. 对自定义插件执行类型检查，再验证激活、Session 状态读取、注册被拒绝以及 owner 释放。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-store-writes/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Store-owned Sessions reject writes before creation announcement completes and after removal."
+---
+# Store-owned Session writes follow publication
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`Session.append()` and `appendPluginRecord()` on store-owned instances reject writes until the instance enters a `SessionStore` and its synchronous `session/created` dispatch completes, and after it leaves. Store ownership starts at `prepare()` or `enter()`. Creation listeners cannot append; a failed announcement leaves writes disabled. Independent `Session.create()` and `Session.fromRestore()` instances remain writable without notifying store observers. Constructor, restore, and fork history still load normally. The Agent factory completes `session/created` before invoking setup; `agent/created` still follows setup. During `session/created`, `ctx.agents.get(session.id)` now returns `undefined`. Listeners registered inside setup miss their own Session’s creation announcement. Setup events now reach live Session subscribers as well as persisted history.
+
+A failed setup retains constructor history and setup events already written to persistence. A failed seeded creation, including a fork, can therefore leave a stored Session; its identity is no longer available for a new creation.
+
+Permission defaults are initialized during `agent/created`, so creating a bare Session no longer pins them. `dsh-permission-presets` now requires the `agents` service as well as its existing dependencies.
+
+## Migration
+
+1. Use `ctx.sessions.create()` for a writable Session owned by the calling fiber. For explicit lifecycle ownership, call `prepare()`, `enter()`, and `announce()` before appending; retain the returned disposer until all closing events finish.
+2. Keep `Session.create()` and `Session.fromRestore()` for independent log construction. Build history before handing the instance to `enter()`, or pass it as the seed to `prepare()`. Removal does not restore independent write access. Cold durable writes use the persistence write handle.
+3. Move writes and Agent-dependent work out of `session/created` listeners. Use setup or `agent/created` for writes; use the supplied Agent in setup and the `agent/created` payload instead of looking up an Agent during Session announcement.
+4. Replace setup-installed observers of their own `session/created` with `agent/created` listeners. Keep Session creation observers in a scope installed before factory creation starts.
+5. After failed creation with persisted history, retry with `ctx.agents.resume({ resumeSessionId })` instead of `create()` on the same id. Retain the stored history for recovery.
+6. Custom profiles mounting `dsh-permission-presets` must also mount `dsh-agent`, the provider of `agents`, and await permission plugin activation before creating Agents.
+7. Verify that creation observers see the expected registry state, permission initialization completes, failed creation can resume its stored history, and rejected appends leave history unchanged.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-store-writes/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Store 接管的 Session 拒绝创建宣告完成前和移除后的写入。"
+---
+# Store 接管的 Session 在发布后开放写入
+
+[English](guide.md) | 中文
+
+## 变更
+
+Store 接管的实例仅在进入 `SessionStore` 且同步 `session/created` 分发完成后，才能通过 `Session.append()` 和 `appendPluginRecord()` 写入，离开 Store 后再次拒绝写入。Store 从 `prepare()` 或 `enter()` 开始接管实例。创建监听器不能追加，宣告失败后仍不能写入。独立的 `Session.create()` 和 `Session.fromRestore()` 实例仍可写入，且不通知 Store 观察者。构造、恢复和 fork 历史仍可正常加载。Agent 工厂在调用 setup 前完成 `session/created`，`agent/created` 仍在 setup 后执行。在 `session/created` 期间，`ctx.agents.get(session.id)` 现在返回 `undefined`。setup 内注册的监听器会错过其所属 Session 的创建宣告。setup 事件现在除了进入持久化历史，也会传递给 Session 的实时订阅方。
+
+setup 失败后会保留已经写入持久化存储的构造历史和 setup 事件。因此，带 seed 的创建（包括 fork）失败后可能留下已存储的 Session，其标识不能再用于新建。
+
+权限默认值在 `agent/created` 中初始化，因此只创建 Session 不再固定这些默认值。`dsh-permission-presets` 除既有依赖外，现在还要求 `agents` 服务。
+
+## 迁移
+
+1. 使用 `ctx.sessions.create()` 创建由调用方 fiber 拥有的可写 Session。若显式拥有生命周期，依次调用 `prepare()`、`enter()` 和 `announce()` 后再追加；保留返回的 disposer，直到所有收尾事件完成。
+2. 独立日志构造继续使用 `Session.create()` 和 `Session.fromRestore()`。在把实例交给 `enter()` 前构造历史，或把历史作为 seed 传给 `prepare()`。移除不会恢复独立写入权限。冷日志的持久化写入使用持久化写句柄。
+3. 将写入和依赖 Agent 的工作移出 `session/created` 监听器。在 setup 或 `agent/created` 中写入；使用 setup 提供的 Agent 或 `agent/created` 载荷，不要在 Session 宣告期间查找 Agent。
+4. 将 setup 内监听所属 Session 的 `session/created` 的代码改为监听 `agent/created`。需要观察 Session 创建时，应在工厂创建开始前安装监听作用域。
+5. 创建失败但已持久化历史时，使用 `ctx.agents.resume({ resumeSessionId })` 重试，不要对同一 id 再次调用 `create()`；保留存储历史用于恢复。
+6. 挂载 `dsh-permission-presets` 的自定义 profile 也必须挂载提供 `agents` 的 `dsh-agent`，并等待权限插件激活后再创建 Agent。
+7. 验证创建观察者看到预期的注册表状态、权限完成初始化、创建失败后能恢复存储历史，以及被拒绝的追加不会改变历史。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-team-mode/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Agent Teams defaults off for new Sessions and uses a saved per-Session selection."
+---
+
+# Select Agent Teams per Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Agent Teams ships with base-backed profiles; new Sessions default to off. The Plugins page has no separate Agent Teams switch. The root Session’s selection controls task tools and Team guidance throughout its subagent tree. The model and reasoning menu offers **Use Agent Teams**, and the root conversation’s Subagent header control opens members above shared tasks in one panel while enabled. Child conversations retain navigation without a shared task board.
+
+Disabling Team retains tasks and subagents. Admitted task operations finish; queued operations check the current mode when they start. The selection survives restart. A historical task board without a saved selection remains enabled. The required `team/mode` event records selections; older readers reject this unfamiliar event. See the [persistence acknowledgement](../../../persistence-changes/2026-10-19-session-team-mode.md).
+
+## Migration
+
+1. Start each existing profile once. Profile loading removes the retired `@deepseek-ai/dsh-experimental-agent-team-profile` bundle selection; the base and Web bundles supply its plugins. Keep `agent-team`, `tool-agent-team`, and `ui-agent-team` row overrides. Custom compositions replace package names `@deepseek-ai/dsh-experimental-agent-team`, `@deepseek-ai/dsh-experimental-tool-agent-team`, and `@deepseek-ai/dsh-experimental-client-ui-agent-team` with `@deepseek-ai/dsh-agent-team`, `@deepseek-ai/dsh-tool-agent-team`, and `@deepseek-ai/dsh-client-ui-agent-team`.
+2. Toggle **Use Agent Teams** in the root conversation’s model and reasoning menu. The `/team on` and `/team off` commands are removed.
+3. Verify that enabling shows shared tasks in the root conversation below the Subagent tree in the same panel and exposes four task tools. Reload the Session to confirm the saved selection. Re-enabling after disabling restores the existing tasks.
+
+Client plugin consumers replace `TeamActionProps` with `TeamBoardProps`; task content registers in `conversation.session.header.actions.subagent.footer` instead of the header actions slot.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/session-team-mode/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Agent Teams 在新 Session 中默认关闭，并使用按 Session 保存的选择。"
+---
+
+# 按 Session 选择智能体团队
+
+[English](guide.md) | 中文
+
+## 变更
+
+Agent Teams 随基于 base 的 profile 提供；新 Session 默认关闭。插件页不再提供独立的智能体团队开关。根 Session 的选择控制整棵子代理树中的任务工具和 Team 提示词。模型与推理等级菜单提供**使用智能体团队**开关，开启后通过根会话的 Subagent 页头入口，在同一面板中查看上方成员与下方共享任务。子会话保留导航，不显示共享任务板。
+
+关闭 Team 保留任务和子代理。已经进入执行的任务操作继续完成；排队中的操作在开始时检查当前模式。选择在重启后仍有效。没有保存选择的历史任务板保持开启。必读事件 `team/mode` 记录选择；旧读取器会拒绝该未知事件。参见[持久化变更确认](../../../persistence-changes/2026-10-19-session-team-mode.zh.md)。
+
+## 迁移
+
+1. 启动每个已有 profile 一次。加载时会移除已停用的 `@deepseek-ai/dsh-experimental-agent-team-profile` 组合选项；base 与 Web 组合提供对应插件。保留 `agent-team`、`tool-agent-team` 与 `ui-agent-team` 行覆盖。自定义组合将包名 `@deepseek-ai/dsh-experimental-agent-team`、`@deepseek-ai/dsh-experimental-tool-agent-team`、`@deepseek-ai/dsh-experimental-client-ui-agent-team` 分别替换为 `@deepseek-ai/dsh-agent-team`、`@deepseek-ai/dsh-tool-agent-team`、`@deepseek-ai/dsh-client-ui-agent-team`。
+2. 在根会话的模型与推理等级菜单中切换**使用智能体团队**。`/team on` 与 `/team off` 命令已移除。
+3. 在根会话中确认开启后通过 Subagent 入口在树下方查看共享任务板，并提供四个任务工具。重新加载 Session，确认选择已保存。关闭后再开启会恢复已有任务。
+
+Client 插件消费者将 `TeamActionProps` 替换为 `TeamBoardProps`；任务内容注册到 `conversation.session.header.actions.subagent.footer`，而非页头操作插槽。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-activation-options/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "SubagentActivationSpec accepts task options directly instead of a nested request object."
+---
+
+# Subagent activation options
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Plugin code calling `ctx.subagents.startActivation()` must pass `prompt`, `parent`, and optional execution settings directly on `SubagentActivationSpec`. The nested `request` field is removed. Type names, provider requests, cancellation, and result delivery are unchanged.
+
+## Migration
+
+1. In each `startActivation()` call, move the fields from `request` to the outer object. For an existing task object, replace `request: task` with `...task`; keep the activation's `label` and `signal` after the spread so they take precedence.
+2. Replace reads such as `spec.request.prompt` with `spec.prompt`. Keep backend `SubagentStartRequest` implementations unchanged.
+3. Typecheck the plugin and run its delegation tests to verify the updated calls.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-activation-options/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "SubagentActivationSpec 直接接受任务选项，不再使用嵌套的 request 对象。"
+---
+
+# 子代理 activation 选项
+
+[English](guide.md) | 中文
+
+## 变更
+
+调用 `ctx.subagents.startActivation()` 的插件代码必须将 `prompt`、`parent` 和可选执行设置直接放在 `SubagentActivationSpec` 上。嵌套的 `request` 字段已移除。类型名称、提供方请求、取消和结果投递保持不变。
+
+## 迁移
+
+1. 在每个 `startActivation()` 调用中，将 `request` 内的字段移到外层对象。已有任务对象时，将 `request: task` 替换为 `...task`；将 activation 的 `label` 和 `signal` 放在展开操作之后，以确保它们优先生效。
+2. 将 `spec.request.prompt` 等读取替换为 `spec.prompt`。保持后端的 `SubagentStartRequest` 实现不变。
+3. 对插件运行类型检查和委派测试，验证更新后的调用。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-service-methods/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The subagent service removes drainChildren, listChildren, and list."
+---
+
+# Subagent service method removal
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ctx.subagents` removes `drainChildren(parent, childIds)`, `listChildren(parentSessionId, signal?)`, and `list()`. This affects plugins that release resident children by id, read direct-child catalogs through the service, or enumerate registered provider names.
+
+## Migration
+
+1. Retain the activation returned by `startActivation()` and await its `dispose()` to release that exact execution. An old activation cannot release a later execution of the same Session. There is no replacement for releasing the current resident child by id; use `drainDescendants([root])` only when closing the entire tree. `interrupt()` stops current work but preserves a local Activation.
+2. For direct-child entries, use `ctx.sessionQuery.observeSession(parentSessionId, { signal })`, read `observation.projections?.values.subagentCatalog`, and dispose the observation with `using`. Load Session Query and the subagent service, and treat a missing catalog projection as unavailable. Keep `listDescendants()` for recursive discovery; its rows differ from direct catalog entries.
+3. Use `getProvider(name)` to check known provider names. The service no longer enumerates all registered names.
+4. Rebuild plugins against the updated service declarations. Verify registration and unload checks, exact-activation disposal, and catalog observation cleanup.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-service-methods/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "子代理服务移除 drainChildren、listChildren 和 list。"
+---
+
+# 子代理服务方法移除
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ctx.subagents` 移除 `drainChildren(parent, childIds)`、`listChildren(parentSessionId, signal?)` 和 `list()`。这会影响按 id 释放驻留子代理、通过服务读取直接子级目录或枚举已注册 provider 名称的插件。
+
+## 迁移
+
+1. 保留 `startActivation()` 返回的 activation，并等待其 `dispose()` 完成以释放那一次执行。旧 activation 不能释放同一 Session 后来恢复的执行。按 id 释放当前驻留子代理没有替代方法；仅在关闭整棵树时使用 `drainDescendants([root])`。`interrupt()` 停止当前工作，但保留本地 Activation。
+2. 读取直接子级条目时，使用 `ctx.sessionQuery.observeSession(parentSessionId, { signal })`，读取 `observation.projections?.values.subagentCatalog`，并通过 `using` 释放观察对象。加载 Session Query 和子代理服务，并将缺失的目录投影视为不可用。递归发现继续使用 `listDescendants()`；它返回的行与直接目录条目不同。
+3. 使用 `getProvider(name)` 检查已知 provider 名称。服务不再枚举全部已注册名称。
+4. 根据更新后的服务声明重新构建插件，验证注册和卸载检查、指定 activation 的释放以及目录观察对象的清理。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "Subagent user controls address only the target Session, rename the interrupt endpoint, and require target Session permissions instead of global permissions."
+---
+
+# Subagent user controls address the target Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Browser and custom Remote callers send subagent prompts without `parentSessionId` or `mode`. `subagents/interruptByParent(childSessionId, parentSessionId, mode)` is replaced by `subagents/interruptByUser(childSessionId)`. Creation ancestry, history addresses, completion recipients, and persisted Session data are unchanged.
+
+Both operations name the child as a `session` access resource. Non-owner policies must grant the corresponding action on that Session; a `global` binding or a binding on its parent does not grant access. Owner behavior is unchanged. Model messages remain limited to one subagent tree, and model interruption remains ancestor-only.
+
+The same-process `SubagentInterruptAuthority` user variant is `{ kind: 'user' }`. The published `@deepseek-ai/dsh-subagent/internal` entry point is removed, including its host prompt adapters and tool identity markers. Remote authorization is performed by the Gateway.
+
+Old prompt payloads with extra fields inside `request` can decode on the new Host, subject to its new access rules. Old interrupt calls fail because the endpoint is removed. New callers require the new Host. Upgrade custom clients and hosts together; the bundled Web client is delivered with its Host.
+
+## Migration
+
+1. Remove `parentSessionId` and `mode` from subagent prompt requests. Keep `childSessionId`, `requestId`, `delivery`, `content`, and optional `clientTimeZone`.
+2. Replace calls to `interruptByParent(childId, parentId, 'continuable')` with `interruptByUser(childId)`.
+3. Update non-owner policies to grant `subagents/prompt` and/or `subagents/interruptByUser` on `{ kind: 'session', id: childId }`. Parent-to-child grants remain an explicit policy decision.
+4. Remove `parentSessionId` from `{ kind: 'user' }` interrupt authorities. Replace imports from `@deepseek-ai/dsh-subagent/internal`: authenticated user prompts use `subagents/prompt`; model-authored messages use `ctx.subagents.sendMessage()`. There is no public arbitrary-source host prompt adapter. Custom tools own their instructions through tool descriptions and `systemPrompt.context()`, without identity markers. Keep parent ids in history addresses and creation records.
+5. Verify that a target-authorized user can send and interrupt, while a user authorized only for the parent or global resource is refused before any input or cancellation is admitted.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/subagent-user-controls/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "子代理用户控制仅按目标 Session 寻址，重命名中断端点，并以目标 Session 权限替代 global 权限。"
+---
+
+# 子代理用户控制按目标 Session 寻址
+
+[English](guide.md) | 中文
+
+## 变更
+
+浏览器和自定义 Remote 调用方发送子代理提示词时，不再提供 `parentSessionId` 或 `mode`。`subagents/interruptByParent(childSessionId, parentSessionId, mode)` 替换为 `subagents/interruptByUser(childSessionId)`。创建祖先、历史地址、完成通知接收者和持久化 Session 数据保持不变。
+
+两个操作都将子会话声明为 `session` 访问资源。非 owner 策略必须授予该 Session 上对应操作的权限；`global` 绑定或父会话上的绑定不授予访问权。owner 行为保持不变。模型消息仍限于同一棵子代理树，模型中断仍仅允许祖先发起。
+
+同进程 `SubagentInterruptAuthority` 的用户分支为 `{ kind: 'user' }`。已发布的 `@deepseek-ai/dsh-subagent/internal` 入口已删除，包括宿主 prompt 适配器和工具身份标记。远程授权由 Gateway 执行。
+
+旧提示词载荷在 `request` 内多带字段时，可以在新 Host 上解码，但须满足新的访问规则。旧中断调用因端点已移除而失败。新调用方要求新 Host。自定义客户端和宿主应一起升级；内置 Web 客户端随 Host 一起交付。
+
+## 迁移
+
+1. 从子代理提示词请求中移除 `parentSessionId` 和 `mode`。保留 `childSessionId`、`requestId`、`delivery`、`content` 和可选的 `clientTimeZone`。
+2. 将 `interruptByParent(childId, parentId, 'continuable')` 调用替换为 `interruptByUser(childId)`。
+3. 更新非 owner 策略，在 `{ kind: 'session', id: childId }` 上授予 `subagents/prompt` 和／或 `subagents/interruptByUser` 权限。父会话到子会话的授权仍由策略显式决定。
+4. 从 `{ kind: 'user' }` 中断授权中移除 `parentSessionId`。替换 `@deepseek-ai/dsh-subagent/internal` 的导入：经过认证的用户 prompt 使用 `subagents/prompt`；模型编写的消息使用 `ctx.subagents.sendMessage()`。不再提供允许任意来源的公开宿主 prompt 适配器。自定义工具通过工具描述和 `systemPrompt.context()` 提供说明，无需身份标记。历史地址和创建记录仍保留父级 id。
+5. 验证获准操作目标的用户能够发送和中断，而仅获准操作父会话或 global 资源的用户在输入或取消被接纳前遭到拒绝。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/tool-executor-plugins/guide.md

@@ -0,0 +1,35 @@
+---
+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 rejects the removed `mode` and `maxParallelSubCalls` configuration fields at load time. 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. Enabled `tool-executor-native` and `tool-executor-ptc` rows are required at startup; invalid executor configuration now stops startup. Web, headless, and SDK no longer read `DSH_TOOLS_MODE`; all inherit native execution from base.
+
+## 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 and mount a compatible `ctx.ptcRuntime` provider. The executor declares this service as a required injection; a missing runtime stops startup, and unloading the runtime withdraws the executor. `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 shared dispatch events and the `ptc-mode` message-source declaration from `@deepseek-ai/dsh-tool-executor-ptc/types`; Client code uses its `/client` re-export. Host policy extensions use `import type` from `@deepseek-ai/dsh-tool-executor-ptc` for `PtcDispatchLog` and `tools/ptc-dispatch-log`.
+
+7. Remove `DSH_TOOLS_MODE` from launch environments. For PTC, save the following as `ptc.yml` and pass it with `--patch`; native execution needs no overlay. The same patch works with `--profile web` and `--profile sdk`; TypeScript and Python SDK clients pass its path through `patches`. Confirm that the model receives only `run_code` in PTC mode.
+
+```yaml
+- id: tool-executor-native
+  disabled: true
+
+- id: tool-executor-ptc
+  disabled: false
+```
+
+```bash
+dsh --profile headless --patch ./ptc.yml "task"
+```