dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-inspect-output/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.2-rc.1/ptc-inspect-output/guide.md
+/:
+  en: aa6195ec0952307e
+  zh: 1d80177284309ac6
+/explicit-output-in-typescript-ptc-programs:
+  en: 064ec0081b5c2946
+  zh: 4b67a513ea949220
+/explicit-output-in-typescript-ptc-programs/change:
+  en: a4b3d449a4eedd9f
+  zh: ae9b0ba7f9f4acbd
+/explicit-output-in-typescript-ptc-programs/migration:
+  en: 0953d3ac2f2f01e3
+  zh: b3614bf85d3d2fcf

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-inspect-output/guide.md

@@ -0,0 +1,48 @@
+---
+kind: upgrade-guide
+description: "TypeScript PTC programs display selected values through inspect and return ordered text and image output."
+---
+
+# Explicit output in TypeScript PTC programs
+
+English | [中文](guide.zh.md)
+
+## Change
+
+TypeScript `run_code` programs display selected values through `inspect(...values)`. Function return values and final expressions previously appeared in the result; they are now omitted. Each inspected argument is rendered independently: strings appear directly, and other values use Node's object formatting without depth, array-length or string-length preview limits. Undefined properties, Error objects and circular references remain visible.
+
+CUA observations previously produced output automatically. `getCapabilities()`, `listApps()`, `findApps(query)`, `getState()`, `app.getWindows()` and app or window `getAccessibilityTree()` now return their results to the program. Use `inspect` to display the values you need.
+
+Only CUA screenshots and `read_image` return ordinary `Image` values in TypeScript programs. Their `path` points to an attachment file readable in the execution environment; `width` and `height` describe its stored pixels. Pass selected images to `inspect` alongside explanatory text, including images in arrays, Map entries, Set values and enumerable object properties. Nested image selection follows Node's custom formatting. Read CUA window IDs from the window object’s `windowId`.
+
+Other image-producing tools retain their declared program values and automatically attach their pictures to the model context. Image adaptation requires a readable attachment path in the program filesystem. `fs-ssh` does not provide this mapping, so `read_image` and CUA screenshot bindings fail in that composition. Use a local filesystem composition for program Images.
+
+Formatting selected values can require more memory than the retained output; see the [Node formatting memory limit](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#known-limitations-and-deferred-work).
+
+## Migration
+
+1. Update programs that rely on completion values to explicitly inspect the values they need:
+
+   ```js
+   const result = await tools.bash({ command: 'pwd', description: 'Show current directory' })
+   inspect(result)
+   ```
+
+2. Remove output callbacks from `connectCua` and `createCuaApi`, the `emit` observation option and the unused `disableDiffing` AX option. Pass observations you want to display to `inspect`, for example `inspect(await app.getWindows())`. A custom dispatcher must return a program Image for screenshot operations.
+
+   ```js
+   const { connectCua } = await import("<host-provided bridge file URL>")
+   const cua = connectCua(() => tools.cua)
+   const app = await cua.getApp("TextEdit")
+   const windows = await app.getWindows()
+   const win = await app.getWindow(windows[0].windowId)
+   const before = await win.getScreenshot()
+   await app.pressKey("Tab")
+   const after = await win.getScreenshot()
+   inspect("before", { windowId: win.windowId }, before, "after", after)
+   ```
+
+3. Direct runtime consumers can set `discardCompletion: true` to select the same explicit-output behavior.
+4. Third-party `PtcRuntime` providers replace returned `logs` arrays with `output: PtcOutput[]`; direct runtime consumers read `result.output`. Text entries are `{ type: 'text', text }`, image entries are `{ type: 'image', attachment }`, and array order is display order. Preserve emitted line breaks and concatenate adjacent text entries without separators.
+5. For custom `launch.bootstrapPath` deployments, follow the [Node PTC bootstrap upgrade guide](../ptc-bootstrap-protocol/guide.md).
+6. Run an updated program and verify that inspected values appear once and its final expression adds no output.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-inspect-output/guide.zh.md

@@ -0,0 +1,48 @@
+---
+kind: upgrade-guide
+description: "TypeScript PTC 程序通过 inspect 展示选定的值，并返回有序的文本与图片输出。"
+---
+
+# TypeScript PTC 程序的显式输出
+
+[English](guide.md) | 中文
+
+## 变更
+
+TypeScript `run_code` 程序通过 `inspect(...values)` 展示选定的值。此前函数返回值和末尾表达式的值会进入结果，现在会被省略。各个 inspect 参数独立渲染：字符串直接展示，其他值使用 Node 的对象格式，不限制预览深度、数组项数或字符串长度。undefined 属性、Error 对象和循环引用均会展示。
+
+此前，CUA 观察方法默认会输出结果。现在，`getCapabilities()`、`listApps()`、`findApps(query)`、`getState()`、`app.getWindows()` 以及应用或窗口的 `getAccessibilityTree()` 都将结果返回给程序。需要展示哪些值，就把它们传给 `inspect`。
+
+只有 CUA 截图与 `read_image` 在 TypeScript 程序中返回普通 `Image`，其 `path` 指向执行环境可读取的附件文件，`width` 与 `height` 为该文件的像素尺寸。使用 `inspect` 将选中的图片与说明一起展示；图片可嵌入数组、Map 条目、Set 的值以及可枚举的对象属性。嵌套图片的选择遵循 Node 的自定义格式化。CUA 窗口 ID 从窗口对象的 `windowId` 读取。
+
+其他图片工具保留其声明的程序返回值，并将图片自动附加到模型上下文。图片适配要求附件在程序文件系统中有可读路径。`fs-ssh` 未提供这项映射，因此该组合中的 `read_image` 与 CUA 截图绑定会失败。需要程序 Image 时，使用本地文件系统组合。
+
+格式化选定的值所需内存可能大于保留的输出；参见 [Node 格式化的内存限制](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#known-limitations-and-deferred-work)。
+
+## 迁移
+
+1. 将依赖完成值的程序，改为显式 inspect 所需的值：
+
+   ```js
+   const result = await tools.bash({ command: 'pwd', description: 'Show current directory' })
+   inspect(result)
+   ```
+
+2. 删除 `connectCua` 和 `createCuaApi` 的输出回调、观察选项 `emit` 和已无作用的 AX 选项 `disableDiffing`。将要展示的观察结果传给 `inspect`，例如 `inspect(await app.getWindows())`。自定义分派器须为截图操作直接返回程序可用的 `Image`。
+
+   ```js
+   const { connectCua } = await import("<host-provided bridge file URL>")
+   const cua = connectCua(() => tools.cua)
+   const app = await cua.getApp("TextEdit")
+   const windows = await app.getWindows()
+   const win = await app.getWindow(windows[0].windowId)
+   const before = await win.getScreenshot()
+   await app.pressKey("Tab")
+   const after = await win.getScreenshot()
+   inspect("before", { windowId: win.windowId }, before, "after", after)
+   ```
+
+3. 直接调用运行时的消费方可设置 `discardCompletion: true`，选择相同的显式输出行为。
+4. 第三方 `PtcRuntime` 提供方将返回的 `logs` 数组替换为 `output: PtcOutput[]`；直接消费运行时结果的调用方改为读取 `result.output`。文本条目为 `{ type: 'text', text }`，图片条目为 `{ type: 'image', attachment }`，数组顺序就是展示顺序。保留实际输出的换行，相邻文本条目直接拼接，不额外插入分隔符。
+5. 使用自定义 `launch.bootstrapPath` 的部署，请按 [Node PTC bootstrap 升级指南](../ptc-bootstrap-protocol/guide.zh.md)更新。
+6. 运行更新后的程序，确认 inspect 的值只出现一次，且末尾表达式不额外输出。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-scoped-repl-default/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.2-rc.1/ptc-scoped-repl-default/guide.md
+/:
+  en: cff145a993d30f0a
+  zh: 784a2ce78146a563
+/retained-node-ptc-runs-the-scoped-repl-by-default:
+  en: 60119ea304ce7bad
+  zh: c0724f1da0e4590c
+/retained-node-ptc-runs-the-scoped-repl-by-default/change:
+  en: 1ca349eed9a54b9b
+  zh: 5dc5ba17ec953f0e
+/retained-node-ptc-runs-the-scoped-repl-by-default/migration:
+  en: 5d1e1f1bf7ce7821
+  zh: aafa439b6080acb4

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-scoped-repl-default/guide.md

@@ -0,0 +1,45 @@
+---
+kind: upgrade-guide
+description: "Node PTC persistent-in-memory execution runs the scoped REPL unless replScoped is false."
+---
+
+# Retained Node PTC runs the scoped REPL by default
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-ptc-runtime-node` previously ran `executionMode: persistent-in-memory` programs in Node's REPL evaluator when `replScoped` was omitted. It now runs them as scoped REPL statements and reports program format `scoped-repl`. Each call is a separate strict-mode script that starts with copies of the top-level bindings left by earlier calls, so a later call may declare a `let`, `const`, or `class` name again. `require`, `_`, `_error`, and globals created by assigning an undeclared name are unavailable. The model guidance describes this behavior; the package README lists its [known limitations](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#known-limitations-and-deferred-work).
+
+This affects:
+
+- profiles whose `ptc-runtime` entry sets `executionMode: persistent-in-memory` without `replScoped`, including workflow-ptc scripts that run on that runtime;
+- persistent PTC enabled from the Computer Use detail page, which now writes `replScoped: true`;
+- the Computer Use `cua_run_code` tool, whose dedicated runtime omits `replScoped` unless `standaloneRunCode.runtime.replScoped` is set;
+- profile editors that merge `resolvePersistentExecution` from `@deepseek-ai/dsh-ptc-runtime-node/configuration`, which now returns `replScoped: true` for function bodies and REPL statements.
+
+`per-call` and `vm-script` execution, including the default profile, are unchanged, and entries that set `replScoped: false` keep Node's REPL evaluator.
+
+## Migration
+
+1. To keep the scoped REPL, replace REPL-only code: use `await import(...)` instead of `require`, assign `globalThis.name` for an intentional global, and use a new name instead of reading a name's earlier value in its own `let` or `const` initializer.
+2. To restore Node's REPL evaluator, set `replScoped: false` in `$DSH_HOME/profiles/<profile>/cordis.patch.yml`; to move an entry that sets `false` to the scoped REPL, delete the key or set `true`. Each patch below replaces that entry's whole `config`, so copy the entry's existing fields into it, for the `cua` entry including `agentPreset`, `allowedApps`, and the other `standaloneRunCode` fields:
+
+   ```yaml
+   - id: ptc-runtime
+     config:
+       executionMode: persistent-in-memory
+       replScoped: false
+   ```
+
+   For `cua_run_code`, set it on the Computer Use provider entry:
+
+   ```yaml
+   - id: cua
+     config:
+       standaloneRunCode:
+         runtime:
+           replScoped: false
+   ```
+
+3. Restart the profile and run `const probe = 1` in two consecutive calls. The scoped REPL accepts both calls; Node's REPL evaluator reports that `probe` has already been declared in the second.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/ptc-scoped-repl-default/guide.zh.md

@@ -0,0 +1,45 @@
+---
+kind: upgrade-guide
+description: "Node PTC 的 persistent-in-memory 执行默认使用 scoped REPL，replScoped 为 false 时除外。"
+---
+
+# 保留状态的 Node PTC 默认使用 scoped REPL
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-ptc-runtime-node` 在 `executionMode: persistent-in-memory` 下省略 `replScoped` 时，原先用 Node 的 REPL 求值器运行程序；现在按 scoped REPL 语句运行，并报告程序格式 `scoped-repl`。每次调用是独立的严格模式脚本，开始时拿到之前调用留下的顶层绑定的拷贝，因此之后的调用可以再次声明同名的 `let`、`const` 或 `class`。`require`、`_`、`_error`，以及给未声明的名字赋值而产生的全局变量都不可用。模型说明描述了这些行为；包 README 列出了它的[已知限制](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#known-limitations-and-deferred-work)。
+
+受影响的有：
+
+- `ptc-runtime` 条目设置了 `executionMode: persistent-in-memory` 但没写 `replScoped` 的 profile，包括在该运行时上运行的 workflow-ptc 脚本；
+- 在 Computer Use 详情页打开的持久化 PTC，现在会写入 `replScoped: true`；
+- Computer Use 的 `cua_run_code` 工具，其专用运行时在没有设置 `standaloneRunCode.runtime.replScoped` 时省略 `replScoped`；
+- 合并 `@deepseek-ai/dsh-ptc-runtime-node/configuration` 中 `resolvePersistentExecution` 结果的 profile 编辑器，该函数现在对函数体和 REPL 语句返回 `replScoped: true`。
+
+`per-call` 和 `vm-script` 执行（包括默认 profile）不变，设置了 `replScoped: false` 的条目继续使用 Node 的 REPL 求值器。
+
+## 迁移
+
+1. 如果保留 scoped REPL，替换只在 REPL 下可用的代码：用 `await import(...)` 代替 `require`，有意的全局变量赋给 `globalThis.name`，不要在 `let` 或 `const` 的初始化表达式里读取同名的旧值，改用新名字。
+2. 如果要恢复 Node 的 REPL 求值器，在 `$DSH_HOME/profiles/<profile>/cordis.patch.yml` 里设置 `replScoped: false`；要让设为 `false` 的条目改用 scoped REPL，删除这个键或改为 `true`。下面每个 patch 都会替换该条目的整个 `config`，所以要把条目已有的字段一并写进去，`cua` 条目还包括 `agentPreset`、`allowedApps` 和 `standaloneRunCode` 的其他字段：
+
+   ```yaml
+   - id: ptc-runtime
+     config:
+       executionMode: persistent-in-memory
+       replScoped: false
+   ```
+
+   对 `cua_run_code`，在 Computer Use 提供方条目上设置：
+
+   ```yaml
+   - id: cua
+     config:
+       standaloneRunCode:
+         runtime:
+           replScoped: false
+   ```
+
+3. 重启 profile，在连续两次调用里运行 `const probe = 1`。scoped REPL 两次都接受；Node 的 REPL 求值器在第二次报告 `probe` 已经声明过。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/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.2-rc.1/runtime-context-reminders/guide.md
+/:
+  en: 9420cefcafb5ca18
+  zh: 68b86eac2f0df9ca
+/runtime-context-reminder-records:
+  en: 24314b42a810c1c9
+  zh: caa0d211650dd3a8
+/runtime-context-reminder-records/change:
+  en: ccbbcf44f91bfdac
+  zh: 0ffa950b9ac802bf
+/runtime-context-reminder-records/migration:
+  en: f1dfb64843da4574
+  zh: b7d12032c4e411d8

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Runtime-context log text gains reminder framing, and clear markers record empty snapshot sections."
+---
+
+# Runtime-context reminder records
+
+English | [中文](guide.zh.md)
+
+## Change
+
+New `user/message` records with `source.kind: 'runtime-context'` wrap their text in `<system-reminder>`. The first snapshot introduces the current session without asserting that it replaces earlier context; later snapshots explicitly replace context retained in conversation summaries. Clear reminders now carry `form: 'snapshot'` and `sections: []`.
+
+A retained legacy snapshot or clear marker without `source.sections` is refreshed once on the next admitted request. This adds a message without rewriting the existing request prefix. A legacy snapshot with unchanged recorded sections is not refreshed solely for its wording. Session format and the public `renderContextSnapshot()` and `joinContextSections()` helpers remain unchanged.
+
+## Migration
+
+1. Update consumers that match runtime-context text literally to recognize the reminder wrapper and the initial/update introductions. Prefer `source.kind` and available `source.sections` when identifying or inspecting these records.
+2. Treat empty sections as cleared context, and retain support for older records without structured sections. Verify both an initial snapshot and a clear reminder in resumed-session output; existing Session files need no rewrite.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/runtime-context-reminders/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "运行时上下文日志文本增加提醒包装，清空标记记录空的快照条目。"
+---
+
+# 运行时上下文提醒记录
+
+[English](guide.md) | 中文
+
+## 变更
+
+新写入且 `source.kind: 'runtime-context'` 的 `user/message` 记录会将文本包在 `<system-reminder>` 内。首份快照介绍当前会话，不宣称覆盖更早的上下文；后续快照明确覆盖对话摘要保留的上下文。清空提醒现在携带 `form: 'snapshot'` 和 `sections: []`。
+
+保留的旧快照或清空标记若没有 `source.sections`，会在下一次获准请求时刷新一次。这会增加一条消息，但不改写现有请求前缀。若旧快照的已记录条目未变，则不会仅因文案而刷新。Session 格式及公开的 `renderContextSnapshot()`、`joinContextSections()` 辅助方法保持不变。
+
+## 迁移
+
+1. 更新按字面匹配运行时上下文文本的消费方，使其识别提醒包装和首次／后续引导语。识别或检查记录时，优先使用 `source.kind` 及可用的 `source.sections`。
+2. 将空条目视为上下文已清空，并继续支持不带结构化条目的旧记录。检查恢复会话输出中的首次快照和清空提醒；现有 Session 文件无需改写。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/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.2-rc.1/session-append-overloads/guide.md
+/:
+  en: 0c7dd958bce09e16
+  zh: 3b3c85a2152294ec
+/update-replacements-for-session-append:
+  en: 5cc8a72cf2203e52
+  zh: 22976024cf5453eb
+/update-replacements-for-session-append/change:
+  en: 51fbd9ed1cd50cdf
+  zh: 103d3ac9b631414e
+/update-replacements-for-session-append/migration:
+  en: 19c39d4582b09f41
+  zh: 4345d25a52dec57e

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "Code that replaces Session.append must implement both the single-event and array overloads."
+---
+
+# Update replacements for `Session.append`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In v0.2.2-rc.1, `Session.append` had a single call signature. It now accepts either one typed event call or an array of event tuples. Ordinary single-event calls still compile. Test doubles and wrappers assigned to `Session['append']` must support both overloads.
+
+## Migration
+
+1. For a wrapper around `Session.append`, preserve both overloads by wrapping the original function with a `Proxy` and forwarding from its `apply` trap with `Reflect.apply`. For a test double that only accepts one event, type the single-event helper separately and call it from the relevant test.
+2. Typecheck assignments to `Session['append']`. Call replacements with both `append('turn/start', { turn: 1 })` and `append([['turn/start', { turn: 1 }]])` and verify the first returns one event and the second an array.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/session-append-overloads/guide.zh.md

@@ -0,0 +1,17 @@
+---
+kind: upgrade-guide
+description: "替换 Session.append 的代码必须实现单事件和数组两种重载。"
+---
+
+# 更新 `Session.append` 的替代实现
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 v0.2.2-rc.1 中，`Session.append` 只有一个调用签名。现在它可接收一个带类型的事件调用，也可接收事件元组数组。普通单事件调用仍可编译。赋值给 `Session['append']` 的测试替身和包装函数必须支持两种重载。
+
+## 迁移
+
+1. 包装 `Session.append` 时，用 `Proxy` 包装原函数，在 `apply` 拦截器内用 `Reflect.apply` 转发，以保留两种重载。若测试替身只接收单个事件，给该辅助函数单独声明类型并在相应测试中调用。
+2. 检查赋值给 `Session['append']` 的代码能通过类型检查。分别以 `append('turn/start', { turn: 1 })` 和 `append([['turn/start', { turn: 1 }]])` 调用替代实现，验证前者返回一个事件，后者返回数组。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/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.2-rc.1/subagent-interrupt-default/guide.md
+/:
+  en: fda192f58c50cd90
+  zh: 2ebe5d7389eb9689
+/built-in-configurations-disable-agent-interruption:
+  en: c253388db5ba6f5a
+  zh: af138bbc7bfd31b4
+/built-in-configurations-disable-agent-interruption/change:
+  en: 76b23fa746332e06
+  zh: d30315eab3aa53bd
+/built-in-configurations-disable-agent-interruption/migration:
+  en: 0f5bd67305b455dc
+  zh: a98770b64686d612

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "Built-in configurations disable interrupt_agent for subagents and Team mode."
+---
+
+# Built-in configurations disable agent interruption
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The base bundle and the Web `standard`, `cordis`, and `ptc` presets now set `config.interrupt: false` on their `tool-subagent-control` rows. Models using these configurations no longer receive `interrupt_agent`, including in Team mode. Messaging, discovery, inbox waiting, and the subagent service interruption API remain available. The plugin's own default remains `true`; independent compositions that omit the setting retain interruption.
+
+## Migration
+
+Keep `interrupt: false` to retain the built-in behavior. To restore interruption:
+
+1. Edit `$DSH_HOME/profiles/<profile>/cordis.patch.yml`. For base-backed profiles such as `headless`, `sdk`, and `acp`, append:
+
+   ```yaml
+   - id: tool-subagent-control
+     config:
+       interrupt: true
+   ```
+
+2. For `web` or `desktop`, instead override each required declaration: `preset-standard`, `preset-cordis`, or `preset-ptc`. Copy that declaration's complete `config` from the installed `@deepseek-ai/dsh-web-app` bundle's `presets/<name>.patch.yml` (source: [standard](../../../../packages/bundle/web-app/presets/standard.patch.yml), [cordis](../../../../packages/bundle/web-app/presets/cordis.patch.yml), [ptc](../../../../packages/bundle/web-app/presets/ptc.patch.yml)). If your profile already overrides the declaration, edit that override to preserve your customizations. A patch replaces the whole `config`: retain `id`, `order`, and the entire `plugins` list, including the `delegation` group. Within that group's `config`, change the `tool-subagent-control` row's `config.interrupt` to `true`. Use the declaration's outer ID as the patch target, following [Change a shipped preset](../../../../packages/preset/agent-preset/skills/dsh-doc/references/compositions.md#change-a-shipped-preset). A top-level patch targeting `tool-subagent-control` does not reach the preset's child row; it only changes the disabled Host row. Leave that Host row disabled.
+3. Restart the profile and create a new Session using the changed preset; existing Sessions retain their preset revision. Confirm that the model's tool definitions include `interrupt_agent`, `send_message`, `list_agents`, and `wait_agent`.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/subagent-interrupt-default/guide.zh.md

@@ -0,0 +1,27 @@
+---
+kind: upgrade-guide
+description: "内置配置关闭普通 subagent 和 Team 模式的 interrupt_agent。"
+---
+
+# 内置配置关闭 agent 中断
+
+[English](guide.md) | 中文
+
+## 变更
+
+base 组合包及 Web 的 `standard`、`cordis`、`ptc` preset 现在为各自的 `tool-subagent-control` 行设置 `config.interrupt: false`。使用这些配置的模型不再获得 `interrupt_agent`，也包括 Team 模式。消息、发现、收件箱等待和 subagent 服务的中断 API 仍然可用。插件自身的默认值仍为 `true`；省略该设置的独立组合仍提供中断工具。
+
+## 迁移
+
+保留 `interrupt: false` 可维持内置行为。如需恢复中断工具：
+
+1. 编辑 `$DSH_HOME/profiles/<profile>/cordis.patch.yml`。对于 `headless`、`sdk`、`acp` 等基于 base 的 profile，追加：
+
+   ```yaml
+   - id: tool-subagent-control
+     config:
+       interrupt: true
+   ```
+
+2. 对于 `web` 或 `desktop`，改为覆盖需要启用的声明行：`preset-standard`、`preset-cordis` 或 `preset-ptc`。从已安装的 `@deepseek-ai/dsh-web-app` 组合包的 `presets/<name>.patch.yml` 中复制该声明的完整 `config`（源码：[standard](../../../../packages/bundle/web-app/presets/standard.patch.yml)、[cordis](../../../../packages/bundle/web-app/presets/cordis.patch.yml)、[ptc](../../../../packages/bundle/web-app/presets/ptc.patch.yml)）。如果 profile 已经覆盖该声明，编辑已有覆盖以保留自定义配置。patch 会替换整个 `config`：保留 `id`、`order` 和完整的 `plugins` 列表，包括 `delegation` 组。在该组的 `config` 内，将 `tool-subagent-control` 行的 `config.interrupt` 改为 `true`。以声明的外层 ID 为 patch 目标，写法参见[修改内置 preset](../../../../packages/preset/agent-preset/skills/dsh-doc/references/compositions.md#change-a-shipped-preset)。顶层以 `tool-subagent-control` 为目标的 patch 无法修改 preset 内的子行，只会修改已禁用的 Host 行。保持该 Host 行禁用。
+3. 重启 profile，并使用修改后的 preset 创建新 Session；已有 Session 保留原 preset 修订。确认模型的工具定义包含 `interrupt_agent`、`send_message`、`list_agents` 和 `wait_agent`。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/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.2-rc.1/terminal-backend-cleanup-error/guide.md
+/:
+  en: 91597636f5a71894
+  zh: 02d2517952d86cfd
+/terminalbackendcleanuperror-extends-terminalerror:
+  en: cb11df977825904b
+  zh: 080f157e78942a9d
+/terminalbackendcleanuperror-extends-terminalerror/change:
+  en: bf3bd46faf910ff0
+  zh: fd47d6e58f467a1e
+/terminalbackendcleanuperror-extends-terminalerror/migration:
+  en: 85fe7dd354cf8657
+  zh: e39dc4ce137aeb13

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "TerminalBackendCleanupError extends TerminalError instead of AggregateError and carries the CLEANUP_FAILED code."
+---
+
+# `TerminalBackendCleanupError` extends `TerminalError`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-terminal` exports `TerminalBackendCleanupError`, which a PTY backend throws when startup failed and cleaning its partial resources also failed. It previously extended `AggregateError`. It now extends `TerminalError`, so it is a `HarnessError` with code `CLEANUP_FAILED`, and a tool result that carries it records `error.name` `TerminalBackendCleanupError` and `error.code` `CLEANUP_FAILED`. The constructor, the `name`, `spawnError`, `cleanupError`, and the `errors` list in that order are unchanged; `errors` is typed `readonly unknown[]` instead of `any[]`. `cause` is a new `AggregateError` of the same two failures. `error instanceof AggregateError` is now `false`.
+
+Backends and consumers that only construct the error, read `spawnError` or `cleanupError`, or test `instanceof TerminalBackendCleanupError` are unaffected.
+
+## Migration
+
+1. Replace `error instanceof AggregateError` checks meant for this error with `error instanceof TerminalBackendCleanupError`, or with `error.code === 'CLEANUP_FAILED'` on a `TerminalError`.
+2. Where TypeScript code reads members of `error.errors` without narrowing, narrow each `unknown` element before use, or read `spawnError` and `cleanupError`.
+3. Confirm with `pnpm exec tsc --noEmit` in the consuming project, and check that a startup cleanup failure still reaches the handling path.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-backend-cleanup-error/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "TerminalBackendCleanupError 改为继承 TerminalError 而非 AggregateError，并带 CLEANUP_FAILED 错误码。"
+---
+
+# `TerminalBackendCleanupError` 改为继承 `TerminalError`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-terminal` 导出的 `TerminalBackendCleanupError` 由 PTY 后端在启动失败且清理部分资源也失败时抛出。它原先继承 `AggregateError`，现在继承 `TerminalError`，因此是带 code `CLEANUP_FAILED` 的 `HarnessError`，携带它的工具结果会记录 `error.name` `TerminalBackendCleanupError` 和 `error.code` `CLEANUP_FAILED`。构造函数、`name`、`spawnError`、`cleanupError` 以及按原顺序排列的 `errors` 列表不变；`errors` 的类型由 `any[]` 改为 `readonly unknown[]`。`cause` 新增为同样两个失败组成的 `AggregateError`。`error instanceof AggregateError` 现在为 `false`。
+
+只构造该错误、读取 `spawnError` 或 `cleanupError`、或检查 `instanceof TerminalBackendCleanupError` 的后端与消费方不受影响。
+
+## 迁移
+
+1. 把针对该错误的 `error instanceof AggregateError` 检查改为 `error instanceof TerminalBackendCleanupError`，或对 `TerminalError` 检查 `error.code === 'CLEANUP_FAILED'`。
+2. TypeScript 代码未经收窄就读取 `error.errors` 元素成员时，先收窄每个 `unknown` 元素，或改为读取 `spawnError` 与 `cleanupError`。
+3. 在消费项目中运行 `pnpm exec tsc --noEmit` 确认通过，并检查启动清理失败仍会进入原有的处理路径。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/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.2-rc.1/terminal-bundle-sidebar-backend/guide.md
+/:
+  en: 785e5093e3550fe6
+  zh: 1d83c93daacf9b2e
+/persistent-terminals-open-in-the-web-sidebar:
+  en: f2ce8bce4d8fb13e
+  zh: c7270e6a1480b0cb
+/persistent-terminals-open-in-the-web-sidebar/change:
+  en: 05818c97f3e32442
+  zh: 249a6ce6f6b80f0d
+/persistent-terminals-open-in-the-web-sidebar/migration:
+  en: 1fe14dab0b4e5056
+  zh: 4afffad398f7a18b

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "The experimental terminal bundle opens Agent terminals in the Web sidebar and replaces its optional-terminal-bash and optional-terminal-pwsh rows with optional-terminal-panel."
+---
+# Persistent terminals open in the Web sidebar
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The **Persistent terminals** bundle (`@deepseek-ai/dsh-experimental-terminal-bundle`) used to run Agent terminals through `@deepseek-ai/dsh-terminal-bash`: a profile-free Bash on POSIX and PowerShell on Windows, invisible to the person, with sandbox-mode changes refused while one was open. Its `optional-persistent-terminals` group now mounts [`@deepseek-ai/dsh-terminal-panel`](../../../../packages/experimental/terminal-panel/README.md) instead. Each `terminal_open` becomes a sidebar tab running the execution environment's default shell with the person's startup files, or `pwsh` then `powershell` on Windows; the person can type into it and take it over. The bundle also registers `user_terminal_list` and `user_terminal_read`, and it requires the Web or Desktop composition, which mounts the terminal controller.
+
+Profile patches that target the removed `optional-terminal-bash` or `optional-terminal-pwsh` rows, or that configure `@deepseek-ai/dsh-terminal-bash` options such as `pollIntervalMs` through them, no longer apply. Headless or other compositions without the terminal controller no longer get a working `shell` backend from this bundle.
+
+## Migration
+
+1. In your profile patch (`cordis.patch.yml`), remove entries for the ids `optional-terminal-bash` and `optional-terminal-pwsh`. To tune the new backend, target `optional-terminal-panel` with [its configuration fields](../../../../packages/experimental/terminal-panel/README.md#use-this-package), for example `config: { timeoutMs: 60000 }` or `config: { readUserTerminals: false }`.
+2. For headless use, mount `@deepseek-ai/dsh-terminal`, `@deepseek-ai/dsh-terminal-bash` and `@deepseek-ai/dsh-tool-terminal` in your own patch instead of enabling the bundle.
+3. Confirm the migration by keeping `@deepseek-ai/dsh-experimental-terminal-bundle` in `dsh.profile.bundles` of `$DSH_HOME/profiles/<name>/package.json`, restarting that profile, and asking the Agent to open a terminal: a tab with an **Agent** badge appears in the sidebar.

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/terminal-bundle-sidebar-backend/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "实验终端 bundle 改为在 Web 侧栏打开 Agent 终端，并用 optional-terminal-panel 行替换 optional-terminal-bash 和 optional-terminal-pwsh 行。"
+---
+# 持久终端改为在 Web 侧栏打开
+
+[English](guide.md) | 中文
+
+## 变更
+
+**持久终端** bundle（`@deepseek-ai/dsh-experimental-terminal-bundle`）原先通过 `@deepseek-ai/dsh-terminal-bash` 运行 Agent 终端：POSIX 上是不加载配置文件的 Bash，Windows 上是 PowerShell，人看不到这些终端，而且有终端打开时会拒绝切换沙箱模式。现在它的 `optional-persistent-terminals` 分组改为挂载 [`@deepseek-ai/dsh-terminal-panel`](../../../../packages/experimental/terminal-panel/README.zh.md)。每次 `terminal_open` 都会成为一个侧栏标签页，运行执行环境的默认 shell 并加载人的启动文件，Windows 上依次优先 `pwsh` 和 `powershell`；人可以在其中输入并接管。该 bundle 还会注册 `user_terminal_list` 和 `user_terminal_read`，并且需要挂载终端控制器的 Web 或 Desktop 组合。
+
+针对已移除的 `optional-terminal-bash` 或 `optional-terminal-pwsh` 行的 profile patch，以及借这些行配置 `@deepseek-ai/dsh-terminal-bash` 选项（例如 `pollIntervalMs`）的 patch，都不再生效。没有终端控制器的 headless 或其他组合，不再能从这个 bundle 得到可用的 `shell` 后端。
+
+## 迁移
+
+1. 在 profile patch（`cordis.patch.yml`）中删除针对 id `optional-terminal-bash` 和 `optional-terminal-pwsh` 的条目。如需调整新后端，请以 `optional-terminal-panel` 为目标，使用[它的配置字段](../../../../packages/experimental/terminal-panel/README.zh.md#use-this-package)，例如 `config: { timeoutMs: 60000 }` 或 `config: { readUserTerminals: false }`。
+2. 在 headless 中使用时，不要启用该 bundle，而是在自己的 patch 中挂载 `@deepseek-ai/dsh-terminal`、`@deepseek-ai/dsh-terminal-bash` 和 `@deepseek-ai/dsh-tool-terminal`。
+3. 确认 `$DSH_HOME/profiles/<name>/package.json` 的 `dsh.profile.bundles` 中保留 `@deepseek-ai/dsh-experimental-terminal-bundle`，重启该 profile，再让 Agent 打开一个终端，侧栏中出现带 **Agent** 徽标的标签页，即说明迁移完成。

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/web-search-billing/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.2-rc.1/web-search-billing/guide.md
+/:
+  en: d5f047c8126e2039
+  zh: 921852a96d5fdaf2
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing:
+  en: 5b4ad8a6553f2017
+  zh: 33d0dbee4bbadad8
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing/change:
+  en: c479258a05c03e30
+  zh: 9479ed43eebd03c2
+/deepseek-web-search-and-fetch-choose-their-credential-by-billing/migration:
+  en: f02650a1b0730ecf
+  zh: e6ddb011af754005

package/references/official-docs/docs/upgrade-guide/v0.2.2-rc.1/web-search-billing/guide.md

@@ -0,0 +1,41 @@
+---
+kind: upgrade-guide
+description: "DeepSeek Search and Fetch add per-capability billing and replace provider authentication fields with ordered credential sources."
+---
+
+# DeepSeek web search and fetch choose their credential by billing
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The DeepSeek Search and Fetch APIs (`web-deepseek-api`) previously used the signed-in account only in `deepseek-account` conversations; other conversations required an API key. New `searchBilling` and `fetchBilling` settings accept `auto` (default), `account`, or `api-key`. With `auto`, DeepSeek model routes behave as before; other conversations and operations outside a Session now use the signed-in account when no key exists. `account` uses only the account; `api-key` only the key. Non-empty `*BaseURL` or `*ApiKeyEnv` settings still take precedence. Other providers, including local HTTP fetch, are unaffected.
+
+In TypeScript, `DeepSeekSearchApiOptions` and `DeepSeekFetchApiOptions` lose their top-level `baseURL`. Their `auth` becomes `{ sources, missingCredentialMessage? }`. Each account or API-key source carries its own address; list order replaces the implicit account-first order. Direct provider constructors must migrate.
+
+With an `AbortSignal`, credential-read errors now retain the original `Error` as `cause` and its name in the diagnostic without an extra `Error:` wrapper. A resolver throwing a DOMException named `AbortError` now yields `WEB_ABORTED`, not `WEB_PROVIDER_ERROR`, even when that signal is not aborted. The no-signal path already behaves this way.
+
+## Migration
+
+1. To disable the new account fallback, set both capabilities to `api-key` on the `web-deepseek-api` row, or choose **DeepSeek API key** under **Plugins > Built-in plugin settings > Web search and fetch** when each DeepSeek API is selected:
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-web-deepseek-api'
+     config:
+       searchBilling: api-key
+       fetchBilling: api-key
+   ```
+
+   This also disables account billing in account conversations; it does not fully restore the old route-dependent behavior.
+2. Migrate direct `DeepSeekSearchApiProvider` and `DeepSeekFetchApiProvider` constructors. The table describes TypeScript options, not YAML settings:
+
+   | Old option | Replacement |
+   |---|---|
+   | `baseURL: base`, `auth.apiKey: key` | `auth.sources: [{ kind: 'api-key', baseURL: base, key }]` |
+   | `auth.resolveApiKey`, `auth.apiKeyEnv` | An API-key source with `key: { ref, configured, resolve }`. Keep the reference (`DEEPSEEK_API_KEY` when omitted); `configured()` checks presence without reading the value, and `resolve()` reads it. |
+   | `auth.account` | `{ kind: 'account', ...account }`; preserve its address and callbacks. Place it before the Key source to retain account-first behavior. |
+   | `auth.missingKeyMessage` | `auth.missingCredentialMessage` |
+   | `auth.invalidRoute` | `{ kind: 'misconfigured', message }` at the position of the invalid source; it fails only when reached. |
+
+3. Update error handling to recognize resolver `AbortError` as cancellation. Do not depend on the extra error wrapper or its diagnostic prefix.
+4. Confirm migrated constructors type-check. With the DeepSeek APIs selected and `api-key` billing, missing keys withhold their tools; configured keys allow requests. Local HTTP fetch remains unaffected.