dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ForgeProvider.diff and ctx.forge.diff take the head commit to read, ForgeFailure gains the stale code, and ChangeRequestSnapshot gains threadsTruncated."
+---
+
+# Forge diffs read one head commit
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ForgeProvider.diff(ref, signal)` becomes `diff(ref, headSha, signal)`, and `ctx.forge.diff(ref, signal)` becomes `ctx.forge.diff(ref, headSha, signal)`. A provider returns a patch only when it describes `headSha`; when the change request's head is another commit, it resolves to a `ForgeFailure` whose code is the new `stale`. `ctx.forge.diff` then polls the change request again at once when it is watched. The GitHub provider reads the head and base commits in one GraphQL query, returns `stale` when the head is another commit, and otherwise reads the patch through the compare API between those two commits instead of `gh pr diff`. A GitHub pull request over 300 files, which `gh pr diff` refused as too large, now shows its complete diff; only output over `maxOutputBytes` or GitHub's own refusal remains `too-large`.
+
+`ForgeFailure['code']` gains `stale`. `ChangeRequestSnapshot` gains the required `threadsTruncated: boolean`, which marks `unresolvedThreads` as a lower bound when the provider counted only some review threads.
+
+The `forgePanel.changeRequestDiff` Remote rejects with `forgePanel/stale-head` instead of returning a patch read at another head.
+
+This affects third-party `ForgeProvider` implementations registered with `ctx.forge.register`, code that calls `ctx.forge.diff` or `forgePanel.changeRequestDiff`, code that builds `ChangeRequestSnapshot` values, and code that switches exhaustively over `ForgeFailure['code']`. All types come from `@deepseek-ai/dsh-experimental-forge`.
+
+## Migration
+
+1. In a `ForgeProvider`, add the `headSha: string` parameter to `diff` before `signal`. Return the patch only when the host computed it at `headSha`; otherwise return `{ code: 'stale', message }`. [`GitHubProvider.diff`](../../../../packages/experimental/forge-github/src/provider.ts) reads the current head first and then a diff addressed by commit.
+2. Pass the head commit to every `ctx.forge.diff` call, usually `ctx.forge.latest(ref)`'s `snapshot.headSha`. On `stale`, wait for a later status and read again at its head; do not cache the result under the old head.
+3. Set `threadsTruncated` in every `ChangeRequestSnapshot` a provider builds: `false` when `unresolvedThreads` counts every review thread.
+4. Handle `stale` wherever code switches exhaustively over `ForgeFailure['code']`, and `forgePanel/stale-head` wherever a caller of `forgePanel.changeRequestDiff` distinguishes Remote error codes.
+5. Run your type check; it succeeds when every `diff` implementation and call passes a head commit, every snapshot sets `threadsTruncated`, and no `ForgeFailure` code is unhandled.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-pinned-diff/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: "ForgeProvider.diff 与 ctx.forge.diff 需要传入要读取的 head 提交，ForgeFailure 新增 stale 代码，ChangeRequestSnapshot 新增 threadsTruncated。"
+---
+
+# Forge diff 读取指定的 head 提交
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ForgeProvider.diff(ref, signal)` 改为 `diff(ref, headSha, signal)`，`ctx.forge.diff(ref, signal)` 改为 `ctx.forge.diff(ref, headSha, signal)`。提供方只在补丁描述 `headSha` 时返回补丁；变更请求的 head 已是其他提交时，resolve 为代码为新增 `stale` 的 `ForgeFailure`。此时若该变更请求正被 watch，`ctx.forge.diff` 会立即重新轮询它。GitHub 提供方在一次 GraphQL 查询中读取 head 与基准提交，head 是其他提交时返回 `stale`，否则不再使用 `gh pr diff`，改经 compare API 读取这两个提交之间的补丁。超过 300 个文件、此前被 `gh pr diff` 判为过大的 GitHub pull request 现在显示完整 diff；只有输出超过 `maxOutputBytes` 或 GitHub 自身拒绝时才仍为 `too-large`。
+
+`ForgeFailure['code']` 新增 `stale`。`ChangeRequestSnapshot` 新增必填字段 `threadsTruncated: boolean`；提供方只统计了部分评审讨论时，它表示 `unresolvedThreads` 只是下限。
+
+`forgePanel.changeRequestDiff` Remote 以 `forgePanel/stale-head` 拒绝，不再返回在其他 head 读到的补丁。
+
+受影响的是用 `ctx.forge.register` 注册的第三方 `ForgeProvider` 实现、调用 `ctx.forge.diff` 或 `forgePanel.changeRequestDiff` 的代码、构造 `ChangeRequestSnapshot` 的代码，以及对 `ForgeFailure['code']` 做穷尽分支的代码。这些类型都来自 `@deepseek-ai/dsh-experimental-forge`。
+
+## 迁移
+
+1. 在 `ForgeProvider` 的 `diff` 中，于 `signal` 之前加入 `headSha: string` 参数。只有托管平台在 `headSha` 处计算出补丁时才返回补丁，否则返回 `{ code: 'stale', message }`。[`GitHubProvider.diff`](../../../../packages/experimental/forge-github/src/provider.ts) 先读取当前 head，再读取按提交寻址的 diff。
+2. 每次调用 `ctx.forge.diff` 都传入 head 提交，通常是 `ctx.forge.latest(ref)` 的 `snapshot.headSha`。收到 `stale` 时，等待更新的状态并按其 head 重新读取；不要把结果缓存在旧 head 下。
+3. 提供方构造的每个 `ChangeRequestSnapshot` 都要设置 `threadsTruncated`：`unresolvedThreads` 统计了全部评审讨论时为 `false`。
+4. 凡对 `ForgeFailure['code']` 做穷尽分支的地方都处理 `stale`；凡区分 `forgePanel.changeRequestDiff` Remote 错误代码的调用方都处理 `forgePanel/stale-head`。
+5. 运行类型检查；所有 `diff` 实现与调用都传入 head 提交、所有快照都设置 `threadsTruncated`、没有未处理的 `ForgeFailure` 代码时，检查通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "ForgeFailure gains the unsupported code, which ctx.forge.readReview returns for a provider without review reads."
+---
+
+# Forge failures report unsupported reads
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ForgeFailure['code']` gains `unsupported`. `ctx.forge.readReview(ref, headSha, signal)`, new beside the optional `ForgeProvider.readReview`, returns it when the provider of the change request does not read review threads. Other reads keep their codes: a provider without `fetchChecks` still makes `ctx.forge.fetchChecks` return `unavailable`.
+
+This affects code that switches exhaustively over `ForgeFailure['code']`, such as a `Record<ForgeFailure['code'], …>` lookup or a `switch` that ends in `assertNever`. All types come from `@deepseek-ai/dsh-experimental-forge`. Providers need no change: `readReview` is optional.
+
+## Migration
+
+1. Handle `unsupported` wherever code switches exhaustively over `ForgeFailure['code']`; treat it as a capability the provider lacks, not as a failed read to retry.
+2. Run your type check; it succeeds when no `ForgeFailure` code is unhandled.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/forge-review-reads/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "ForgeFailure 新增 unsupported 代码；提供方不支持读取评审讨论时，ctx.forge.readReview 返回它。"
+---
+
+# Forge 失败代码报告不支持的读取
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ForgeFailure['code']` 新增 `unsupported`。新增的 `ctx.forge.readReview(ref, headSha, signal)` 对应可选的 `ForgeProvider.readReview`；变更请求的提供方不支持读取评审讨论时，它返回 `unsupported`。其他读取的代码不变：提供方未实现 `fetchChecks` 时，`ctx.forge.fetchChecks` 仍返回 `unavailable`。
+
+受影响的是对 `ForgeFailure['code']` 做穷举的代码，例如 `Record<ForgeFailure['code'], …>` 查表，或以 `assertNever` 结尾的 `switch`。所有类型都来自 `@deepseek-ai/dsh-experimental-forge`。提供方无需修改：`readReview` 是可选方法。
+
+## 迁移
+
+1. 在所有对 `ForgeFailure['code']` 做穷举的地方处理 `unsupported`，把它当作提供方缺少的能力，而不是需要重试的读取失败。
+2. 运行类型检查；没有未处理的 `ForgeFailure` 代码时即通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/package-export-cleanup/guide.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: Internal helper values are removed from three published plugin-root entries.
+---
+
+# Replace internal plugin-root imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+After upgrading from v0.2.2-rc.1, the following plugin-root values are no longer exported. Their implementations remain inside the packages. Consumers importing these values from a package root must change their imports or use the owning service.
+
+| Package suffix (`@deepseek-ai/dsh-`) | Removed root helpers |
+|---|---|
+| `file-reference-local` | `DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES`, `DEFAULT_FILE_SEARCH_MAX_ENTRIES`, `DEFAULT_FILE_SEARCH_MAX_RESULTS`, `WorkspaceFileSearch`, `FILE_REFERENCE_PROMPT`, `activeAtToken`, `formatFileMention` |
+| `llm-pi-ai` | `recordKeyFor` |
+| `lsp-stdio` | `LspConnection`, `LspInstance`, `MessageDecoder`, `canonicalizeWorkspace`, `encodeMessage`, `negotiatePositionEncoding`, `normalizeHover`, `normalizeLocations`, `readHostSource`, `requestMethod`, `supportsOperation`, `supportsTransientOpen` |
+
+Brand constructors, package subpaths, persisted values and Session formats are unchanged.
+
+## Migration
+
+1. Stop importing the listed helper values from plugin roots. Package-owned tests can use relative imports from the corresponding internal modules.
+2. Application code should use the injected `fileReferences` or `lsp` service instead of provider implementation classes or protocol helpers. File-reference grammar remains at `@deepseek-ai/dsh-file-reference/grammar`; `FILE_REFERENCE_PROMPT` remains at `@deepseek-ai/dsh-file-reference`. `recordKeyFor` has no replacement public entry.
+3. Compile the application and run its tests. Load any plain-JavaScript consumers under Node as well: TypeScript checking alone does not cover missing ESM named exports in `.mjs` files.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/package-export-cleanup/guide.zh.md

@@ -0,0 +1,26 @@
+---
+kind: upgrade-guide
+description: 三个已发布插件的根入口移除内部辅助实体的值导出。
+---
+
+# 替换内部插件根导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 v0.2.2-rc.1 升级后，以下插件根入口不再导出这些值。对应实现在包内保留。从包根入口导入这些值的消费方需要更改导入或改用所属服务。
+
+| 包名后缀（`@deepseek-ai/dsh-`） | 移除的根辅助实体 |
+|---|---|
+| `file-reference-local` | `DEFAULT_FILE_SEARCH_EXCLUDED_DIRECTORIES`、`DEFAULT_FILE_SEARCH_MAX_ENTRIES`、`DEFAULT_FILE_SEARCH_MAX_RESULTS`、`WorkspaceFileSearch`、`FILE_REFERENCE_PROMPT`、`activeAtToken`、`formatFileMention` |
+| `llm-pi-ai` | `recordKeyFor` |
+| `lsp-stdio` | `LspConnection`、`LspInstance`、`MessageDecoder`、`canonicalizeWorkspace`、`encodeMessage`、`negotiatePositionEncoding`、`normalizeHover`、`normalizeLocations`、`readHostSource`、`requestMethod`、`supportsOperation`、`supportsTransientOpen` |
+
+品牌构造器、包子路径、持久化值和 Session 格式不变。
+
+## 迁移
+
+1. 停止从插件根入口导入上表的辅助实体值。包内测试可以相对导入对应内部模块。
+2. 应用代码应使用注入的 `fileReferences` 或 `lsp` 服务，而不是提供方的实现类或协议辅助函数。文件引用语法仍在 `@deepseek-ai/dsh-file-reference/grammar`；`FILE_REFERENCE_PROMPT` 仍在 `@deepseek-ai/dsh-file-reference`。`recordKeyFor` 没有替代的公开入口。
+3. 编译应用并运行其测试，同时用 Node 加载纯 JavaScript 消费方：仅检查 TypeScript 无法覆盖 `.mjs` 文件中缺少 ESM 命名导出的错误。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "BundleInfo.updatable is replaced by BundleInfo.update, and ManagementError gains the unexpected-package code."
+---
+
+# `BundleInfo.update` replaces `BundleInfo.updatable`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`pluginManager.listBundles()` no longer returns `BundleInfo.updatable: boolean`. It returns the optional `BundleInfo.update`, which is `'registry'` for a bundle whose newer versions `listVersions` reads, `'git'` for a bundle installed from a Git spec pinned to a full commit, and absent for a bundle `updateBundle` cannot replace. A bundle that `updatable: true` marked before is now `update: 'registry'`. `updateBundle` also accepts a `'git'` bundle when `options.spec` names a newer commit of the same repository directory.
+
+`ManagementError['code']` gains `unexpected-package`: an installation run with `InstallBundleOptions.expected`, which `updateBundle` always passes, fails with it when the spec installs another package or version.
+
+This affects code that reads `listBundles()` through the Host API, `@deepseek-ai/dsh-plugin-manager/types`, or the remote client in `@deepseek-ai/dsh-api-remotes/client`, and code that switches exhaustively over `ManagementError['code']`. The `plugin_manager` tool never returned the field and is unchanged.
+
+## Migration
+
+1. Replace each read of `updatable`. To decide whether `listVersions` can list a bundle's versions, test `bundle.update === 'registry'`; to decide whether `updateBundle` can replace it at all, test `bundle.update !== undefined`.
+2. If code switches exhaustively over `ManagementError['code']`, handle `unexpected-package`.
+3. Run your type check; it succeeds when no `updatable` read and no unhandled `ManagementError` code remains.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/plugin-update-method/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "BundleInfo.updatable 由 BundleInfo.update 取代，ManagementError 新增 unexpected-package 错误码。"
+---
+
+# `BundleInfo.update` 取代 `BundleInfo.updatable`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`pluginManager.listBundles()` 不再返回 `BundleInfo.updatable: boolean`，改为返回可选的 `BundleInfo.update`：`listVersions` 能读取其较新版本的组合包为 `'registry'`，从固定到完整提交的 Git spec 安装的组合包为 `'git'`，`updateBundle` 无法替换的组合包不含此字段。此前标记为 `updatable: true` 的组合包现在为 `update: 'registry'`。当 `options.spec` 指向同一仓库目录的较新提交时，`updateBundle` 也接受 `'git'` 组合包。
+
+`ManagementError['code']` 新增 `unexpected-package`：带 `InstallBundleOptions.expected` 运行的安装（`updateBundle` 总会传入该选项）在 spec 安装了其他包或其他版本时以此错误码失败。
+
+受影响的代码包括：通过 Host API、`@deepseek-ai/dsh-plugin-manager/types` 或 `@deepseek-ai/dsh-api-remotes/client` 中的远端客户端读取 `listBundles()` 的代码，以及对 `ManagementError['code']` 做穷尽 switch 的代码。`plugin_manager` 工具从未返回该字段，保持不变。
+
+## 迁移
+
+1. 替换每一处对 `updatable` 的读取。要判断 `listVersions` 能否列出组合包的版本，检查 `bundle.update === 'registry'`；要判断 `updateBundle` 是否能以任何方式替换它，检查 `bundle.update !== undefined`。
+2. 如果代码对 `ManagementError['code']` 做穷尽 switch，需要处理 `unexpected-package`。
+3. 运行类型检查；当不再有对 `updatable` 的读取，也没有未处理的 `ManagementError` 错误码时，类型检查通过。

package/kb/extra/upgrade-guide/v0.2.2-rc.1/ptc-bootstrap-protocol/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Update custom Node PTC bootstraps to protocol version 3 before running them with the upgraded Host, and handle the new scoped-repl program format."
+---
+
+# Node PTC bootstrap protocol version 3 and the scoped-repl format
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Node PTC Host requires bootstrap protocol version 3 instead of version 2. It rejects an older bootstrap before dispatching a program, with `bootstrap protocol mismatch; upgrade launch.bootstrapPath with the host`. This affects custom `launch.bootstrapPath` deployments in every execution mode, including `@deepseek-ai/dsh-ssh` hosts with a `node-script` launch that set `launch.bootstrapPath` and `launch.bootstrapHash`. The bootstrap bundled with DSH updates with the Host and needs no configuration change.
+
+Version 3 carries optional `ProgramBootData.initialization` source for each new environment. The bootstrap evaluates it separately after installing current bindings, then awaits the Host's `initialized()` RPC acceptance and rechecks cancellation before running the model program. Initialization failure discards the environment and prevents model execution. The Node provider supports initializer registration only in `persistent-in-memory` mode.
+
+Version 3 also carries `ProgramBootData.discardCompletion` to discard completion values before JSON validation and serialization. The bootstrap provides `inspect` and sends selected images through `HostMethods.image(id)` in output order. Custom bootstraps must support these fields and methods alongside environment initialization.
+
+Version 3 also adds the `scoped-repl` program format. `PtcProgramFormat` in `@deepseek-ai/dsh-ptc-runtime` now includes `'scoped-repl'`, which `@deepseek-ai/dsh-ptc-runtime-node` reports as `PtcRuntime.programFormat` when `replScoped: true` is set with `executionMode: persistent-in-memory`. Code that matches the union exhaustively stops compiling until it handles the new value.
+
+## Migration
+
+1. If your Node PTC configuration sets `launch.bootstrapPath`, deploy the matching version of `@deepseek-ai/dsh-ptc-runtime-node` in its execution environment. Use the package's built `lib/process.js` or REPL-default `lib/persistent-process.js` with its dependencies. Keep the Host and bootstrap versions aligned; changing only the advertised version is insufficient.
+2. Update `launch.bootstrapPath` to the matching entry and restart the provider. For `@deepseek-ai/dsh-ssh` with a `node-script` launch, copy the new bootstrap to the remote `launch.bootstrapPath` and set `launch.bootstrapHash` to its lowercase SHA-256, for example from `sha256sum`. For local deployments that need no custom bootstrap, remove that override to use the installed default. The [Node runtime documentation](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#persistent-repl) describes retained execution and remote launch.
+3. Handle `'scoped-repl'` wherever code switches over `PtcProgramFormat` or keys a record by it. A `scoped-repl` program is REPL statements whose final expression is the result; top-level `return` is not supported, and a final Promise is not awaited.
+4. Run a program in each configured execution mode and confirm that it completes without the protocol error. Consumers using `registerEnvironmentInitializer(program)` must also verify that initialization runs once per new environment and that an initialization error prevents the model program's effects. Typecheck the code that uses `PtcProgramFormat`.

package/kb/extra/upgrade-guide/v0.2.2-rc.1/ptc-bootstrap-protocol/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "自定义 Node PTC bootstrap 必须升级到协议版本 3，才能与新版 Host 一起运行；还要处理新增的 scoped-repl 程序格式。"
+---
+
+# Node PTC bootstrap 协议版本 3 与 scoped-repl 格式
+
+[English](guide.md) | 中文
+
+## 变更
+
+Node PTC Host 要求 bootstrap 协议版本从 2 升至 3。它会在派发程序前拒绝旧 bootstrap，并报告 `bootstrap protocol mismatch; upgrade launch.bootstrapPath with the host`。这影响所有执行模式下自定义 `launch.bootstrapPath` 的部署，包括使用 `node-script` 启动、设置了 `launch.bootstrapPath` 和 `launch.bootstrapHash` 的 `@deepseek-ai/dsh-ssh` 宿主。DSH 内置 bootstrap 随 Host 更新，无需修改配置。
+
+版本 3 为每个新环境携带可选的 `ProgramBootData.initialization` 源码。bootstrap 安装本次绑定后独立执行初始化，随后等待 Host 对 `initialized()` RPC 的确认，再次检查取消状态后才执行模型程序。初始化失败会丢弃环境并阻止模型代码执行。Node 提供方仅在 `persistent-in-memory` 模式下支持注册初始化程序。
+
+版本 3 还携带 `ProgramBootData.discardCompletion`，用于在 JSON 校验和序列化前丢弃完成值。bootstrap 提供 `inspect`，并通过 `HostMethods.image(id)` 按输出顺序发送选中的图片。自定义 bootstrap 必须同时支持这些字段、方法和环境初始化。
+
+版本 3 还新增了 `scoped-repl` 程序格式。`@deepseek-ai/dsh-ptc-runtime` 的 `PtcProgramFormat` 新增 `'scoped-repl'`；`@deepseek-ai/dsh-ptc-runtime-node` 在 `executionMode: persistent-in-memory` 下设置 `replScoped: true` 时，`PtcRuntime.programFormat` 报告这个值。对这个联合类型做穷尽匹配的代码，处理新值之前无法通过编译。
+
+## 迁移
+
+1. 如果 Node PTC 配置设置了 `launch.bootstrapPath`，请在其执行环境中部署匹配版本的 `@deepseek-ai/dsh-ptc-runtime-node`。使用包内构建产物 `lib/process.js`，或默认采用 REPL 的 `lib/persistent-process.js`，并保留其依赖。Host 与 bootstrap 版本必须匹配；只修改声明的版本号并不够。
+2. 将 `launch.bootstrapPath` 指向匹配的入口并重启提供方。使用 `node-script` 启动的 `@deepseek-ai/dsh-ssh`：把新的 bootstrap 复制到远端的 `launch.bootstrapPath`，并把 `launch.bootstrapHash` 设为它的小写 SHA-256，例如用 `sha256sum` 计算。本地部署若不需要自定义 bootstrap，可以移除此覆盖项以使用安装默认值。[Node 运行时文档](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#persistent-repl)说明状态保留和远程启动方式。
+3. 在按 `PtcProgramFormat` 分支或以它为键的地方处理 `'scoped-repl'`。`scoped-repl` 程序是 REPL 语句，最后一条表达式就是结果；不支持顶层 `return`，末尾的 Promise 不会被等待。
+4. 在每种已配置的执行模式中运行一个程序，确认正常完成且没有协议错误。使用 `registerEnvironmentInitializer(program)` 的消费方还须验证：初始化在每个新环境中只执行一次，且初始化出错时模型程序不会产生效果。再对使用 `PtcProgramFormat` 的代码做类型检查。

package/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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/kb/extra/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.