dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Agent Teams uses the standard subagent tools and Session ids; Team-specific creation, messaging, listing, interruption, and their configuration keys are removed."
+---
+
+# Agent Teams uses subagents and Session ids
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Descriptions label responsibilities; only Session ids identify recipients.
+
+- `spawn_teammate` and the Team-scoped `send_message`, `list_agents`, and `interrupt_agent` are removed. The standard control tools use `agent_id`, not `target`. Members of one root tree can message each other across branches by id; interruption remains ancestor-only.
+- `list_agents` takes no arguments and lists the entire tree. Remove scripted `scope` arguments. Rows use `kind: root`, `kind: child`, or `kind: diagnostic`; descendants include parent ids and root-relative depth.
+- Team supplies four task tools and policy; controls supply required identity. `wait_agent` moves to ordinary subagent controls and waits for the caller’s next-step inbox, including pending input. Status changes and unrelated inboxes do not wake it; `noProgress` is removed. Timeout bounds/default remain unchanged.
+- `agent-team` rejects `maxMembers`, `maxMessageBytes`, and `disposalTimeoutMs`; `tool-agent-team` rejects `interrupt`, `freshProvider`, and `forkProvider`.
+- `ctx.agentTeams` removes creation, messaging, interruption, roster, membership, and wait APIs. `TeamMembership`, `TeamMemberView`, spawn/send request/result types, and `TeamWaitResult` are removed. Task ownership uses `ownerId`, including the root’s Session id.
+- Runtime instances share root ownership without changing creation ancestry. Member settlement does not dispose descendants. Messages restore only their target. Hosts close the tree when its root closes; members obtain required results explicitly.
+- Cold resume uses saved presets and permissions, not the creator’s current generation. Missing presets fail restoration; historical targets without one use host composition plus descriptor overrides. Lifecycle dispatch uses the root scope while retaining the direct creator in `parentSessionId`. Browser continuation requires the root online; failure uses `subagent/delivery-unavailable`.
+- Historical Team roster and mailbox records remain readable. Historical names do not resolve message recipients or task owners. Subagent catalog payloads are unchanged.
+- The Web Team panel shows tasks only; subagent navigation owns member browsing. The wire `agentTeam.members` field and `TeamMemberProjection` are removed; persisted roster state still decodes. Task commits do not end waits, deliver messages, or start idle Agents. Message another Agent when it needs to act on task changes.
+
+## Migration
+
+1. Move `interrupt: false` from `tool-agent-team` to `tool-subagent-control`. Remove other obsolete keys and any patch rows that disable subagent tools solely for Team support.
+2. Replace `spawn_teammate({ name, description, prompt, context })` with `subagent({ description, prompt })`, or `subagent_fork` for inherited conversation history. Save the returned agent id.
+3. Use `send_message({ agent_id, message })` and `interrupt_agent({ agent_id })`. Discover all Team member ids with `list_agents`.
+4. Pass member Session ids to task `owner` fields and read `ownerId` in results. Use the Lead's Session id instead of the alias `lead`.
+5. Replace `spawnTeammate`, `sendMessage`, and `interrupt` with `ctx.subagents.startActivation`, `sendMessage`, and `interrupt`. Replace `membership`/`tryMembership` with `rootOf`, and `listMembers` with `listDescendants`. Replace `waitForChange` with `wait_agent`, then re-read tasks.
+6. SDK `session/resume` rejects subagent sessions. Resume the root Session instead. Verify navigation, nested task assignment, and that messages end inbox waits while task commits do not.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/guide.zh.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Agent Teams 使用标准 subagent 工具和 Session id；移除 Team 专属创建、消息、列举、中断操作及其配置键。"
+---
+
+# Agent Teams 使用子代理和 Session id
+
+[English](guide.md) | 中文
+
+## 变更
+
+描述标注职责；仅 Session id 标识接收者。
+
+- 移除 `spawn_teammate` 以及 Team 作用域的 `send_message`、`list_agents` 和 `interrupt_agent`。标准控制工具使用 `agent_id` 而非 `target`。同一根下的成员可以通过 id 跨分支互发消息；中断仍只允许祖先执行。
+- `list_agents` 不接受参数，列出整棵树。移除脚本中的 `scope` 参数。行使用 `kind: root`、`kind: child` 或 `kind: diagnostic`；后代包含父 id 和相对根的深度。
+- Team 提供四个任务工具和策略；控制工具提供必需身份。`wait_agent` 移至普通 subagent 控制工具，等待调用者的下一步收件箱，包括待处理输入。状态变化和其他收件箱不会唤醒它；移除 `noProgress`。超时范围和默认值不变。
+- `agent-team` 拒绝 `maxMembers`、`maxMessageBytes` 和 `disposalTimeoutMs`；`tool-agent-team` 拒绝 `interrupt`、`freshProvider` 和 `forkProvider`。
+- `ctx.agentTeams` 移除创建、通信、中断、名册、成员关系和等待 API。`TeamMembership`、`TeamMemberView`、spawn/send 请求和结果类型以及 `TeamWaitResult` 被移除。任务归属使用 `ownerId`，包括根的 Session id。
+- 运行时实例共享根所有权，不改变创建祖先关系。成员收尾不释放后代。消息仅恢复目标。根关闭时 host 关闭整棵树；成员显式获取所需结果。
+- 冷恢复使用已保存的 preset 和权限，而非创建者当前代次。缺失 preset 会导致恢复失败；历史目标没有保存 preset 时，使用 host 组合及描述符覆盖。生命周期分派使用根作用域，同时在 `parentSessionId` 中保留直接创建者。浏览器继续执行需要根在线；失败使用 `subagent/delivery-unavailable`。
+- 历史 Team 名册和邮箱记录仍可读取。其中的名字仅作为历史数据，不用于解析消息收件人或任务所有者。Subagent catalog 载荷不变。
+- Web Team 面板仅显示任务；subagent 导航负责浏览成员。线上 `agentTeam.members` 字段与 `TeamMemberProjection` 被移除；持久化成员状态仍可解码。任务提交不结束等待、不投递消息，也不启动空闲 Agent。需要另一个 Agent 处理任务变更时，应发送消息。
+
+## 迁移
+
+1. 将 `interrupt: false` 从 `tool-agent-team` 移到 `tool-subagent-control`。删除其余废弃键，以及仅为支持 Team 而禁用 subagent 工具的 patch 行。
+2. 将 `spawn_teammate({ name, description, prompt, context })` 替换为 `subagent({ description, prompt })`；继承对话历史时使用 `subagent_fork`。保存返回的 agent id。
+3. 使用 `send_message({ agent_id, message })` 和 `interrupt_agent({ agent_id })`。通过 `list_agents` 查询所有 Team 成员的 id。
+4. 任务的 `owner` 字段传入成员 Session id，结果读取 `ownerId`。以 Lead 的 Session id 取代 `lead` 别名。
+5. 将 `spawnTeammate`、`sendMessage` 和 `interrupt` 替换为 `ctx.subagents.startActivation`、`sendMessage` 和 `interrupt`。将 `membership`/`tryMembership` 替换为 `rootOf`，将 `listMembers` 替换为 `listDescendants`。将 `waitForChange` 替换为 `wait_agent`，随后重新读取任务。
+6. SDK `session/resume` 拒绝子代理会话。改为恢复根 Session。验证导航、嵌套任务分配，以及消息结束收件箱等待而任务提交不会。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/approval-projection-dependency/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/approval-projection-dependency/guide.md
+/:
+  en: 10a5bce762cfa31b
+  zh: eddf92b54eb31683
+/approval-requires-the-projection-registry:
+  en: 89b130eab1f61761
+  zh: f1382f60b6f8612f
+/approval-requires-the-projection-registry/change:
+  en: a338aa2a5279676c
+  zh: 8744d85c90437bfd
+/approval-requires-the-projection-registry/migration:
+  en: fd59212cd75f01a2
+  zh: a36f9f6c5101d733

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/approval-projection-dependency/guide.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "Custom ApprovalService compositions must provide sessionProjections and await service activation."
+---
+
+# Approval requires the Projection registry
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ApprovalService` requires `sessionProjections`. It waits for projection registration during activation instead of reading the event log when the registry is absent or pending. Custom compositions that mounted approval alone must add the registry. Shipped profiles already provide it.
+
+Approval outcomes, audit events, policy defaults, and synchronous business methods keep their existing behavior. Session logs and checkpoint formats do not change. The private registration handle is process-local; checkpoints contain only the policy override and turn state.
+
+## Migration
+
+1. In custom `cordis.yml` files, mount `@deepseek-ai/dsh-session-projection` before `@deepseek-ai/dsh-user-approval`. Avoid adding a duplicate registry to a shipped profile.
+2. In direct host compositions, use `ctx.plugin(ApprovalService)` and await activation before using `ctx.approval`. Do not construct the service with `new ApprovalService(...)`: that does not run `Service.init`.
+
+   ```ts
+   import { Context } from '@deepseek-ai/cordis'
+   import SessionStore from '@deepseek-ai/dsh-session'
+   import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+   import ApprovalService from '@deepseek-ai/dsh-user-approval'
+
+   const ctx = new Context()
+   await ctx.plugin(SessionStore)
+   await ctx.plugin(SessionProjectionRegistry)
+   await ctx.plugin(ApprovalService)
+   ```
+
+3. Let the host and registry complete Session recovery before exposing historical state to synchronous readers. Follow the [registry lifecycle](../../../../packages/session/session-projection/README.md); do not add history loading to approval getters or replay runtime hooks.
+4. Confirm activation completes and the existing approval tests still produce the same outcomes and audit records. Registration errors must fail activation instead of selecting a full-log fallback.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/approval-projection-dependency/guide.zh.md

@@ -0,0 +1,34 @@
+---
+kind: upgrade-guide
+description: "自定义 ApprovalService 组合必须提供 sessionProjections 并等待服务激活。"
+---
+
+# 审批服务要求 Projection 注册表
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ApprovalService` 要求 `sessionProjections`。它在激活时等待 Projection 注册，不再在注册表缺失或尚未就绪时读取事件日志。原先只挂载审批服务的自定义组合必须补上注册表。发布的配置已提供该服务。
+
+审批结果、审计事件、策略默认值和同步业务方法保持原有行为。会话日志和检查点格式不变。私有注册句柄仅在进程内有效；检查点只保存策略覆盖值和轮次状态。
+
+## 迁移
+
+1. 在自定义 `cordis.yml` 中，先挂载 `@deepseek-ai/dsh-session-projection`，再挂载 `@deepseek-ai/dsh-user-approval`。不要向发布的配置重复添加注册表。
+2. 在直接挂载服务的宿主中，使用 `ctx.plugin(ApprovalService)` 并等待激活完成，再使用 `ctx.approval`。不要用 `new ApprovalService(...)` 直接构造服务；这不会执行 `Service.init`。
+
+   ```ts
+   import { Context } from '@deepseek-ai/cordis'
+   import SessionStore from '@deepseek-ai/dsh-session'
+   import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+   import ApprovalService from '@deepseek-ai/dsh-user-approval'
+
+   const ctx = new Context()
+   await ctx.plugin(SessionStore)
+   await ctx.plugin(SessionProjectionRegistry)
+   await ctx.plugin(ApprovalService)
+   ```
+
+3. 由宿主和注册表完成会话恢复，再向同步读取方交付历史状态。遵循[注册表生命周期](../../../../packages/session/session-projection/README.zh.md)；不要在审批 getter 中加载历史，也不要在回放时触发运行时钩子。
+4. 确认激活完成，原有审批测试仍产生相同的结果和审计记录。注册错误必须使激活失败，不能切换到全日志回退路径。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-shutdown/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/auto-review-shutdown/guide.md
+/:
+  en: c0e64f8108b1a473
+  zh: 93b63b014611242d
+/reopen-auto-review-sessions-after-shutdown:
+  en: b72fca04b4e46f21
+  zh: 4e4e5a76fe6d0304
+/reopen-auto-review-sessions-after-shutdown/change:
+  en: 34ba91c7d8a85add
+  zh: d1adc66602607db6
+/reopen-auto-review-sessions-after-shutdown/migration:
+  en: 651e7d17139d0047
+  zh: 09205aca0a13390f

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-shutdown/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Auto review Sessions retain their permission preset when the application closes and require the integration when reopened."
+---
+
+# Reopen Auto review Sessions after shutdown
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Application shutdown previously could change a live Auto review Session to Full access, depending on disposal order. Shutdown now preserves Auto and its approval policy. Removing the Auto review plugin from a running application still changes its live Auto Sessions to Full access.
+
+A saved Auto Session requires the Auto review integration before it can reopen. This also applies when a headless invocation requests another permission preset: restore validates the saved selection before applying the new flag. Existing policy records are not rewritten.
+
+## Migration
+
+1. Keep the Auto review integration enabled in the profile that reopens the Session. If you loaded it through a one-off `--patch` overlay, pass that overlay again on resume.
+2. To change a saved Auto Session to another preset, first reopen it with the integration present, then select the new preset. Headless callers can supply `--session-id <id> --permission-mode <preset>` with the same Auto overlay.
+3. Close and reopen the Session with the integration present. Verify that its selected preset remains Auto unless you explicitly changed it.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-shutdown/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Auto review Session 在应用关闭时保留权限预设，重新打开时需要对应集成。"
+---
+
+# 关闭后重新打开 Auto review Session
+
+[English](guide.md) | 中文
+
+## 变更
+
+此前，应用关闭可能会将存活的 Auto review Session 改为 Full access，结果取决于资源释放顺序。现在关闭会保留 Auto 及其审批策略。在运行中的应用内移除 Auto review 插件，仍会将其存活的 Auto Session 改为 Full access。
+
+已保存的 Auto Session 必须在 Auto review 集成存在时才能重新打开。即使 headless 调用请求另一权限预设也一样：恢复会先验证已保存的选择，再应用新参数。既有策略记录不会被改写。
+
+## 迁移
+
+1. 在重新打开 Session 的 profile 中保持 Auto review 集成启用。如果通过一次性的 `--patch` overlay 加载集成，恢复时再次传入该 overlay。
+2. 要将已保存的 Auto Session 改为另一预设，先在集成存在时重新打开它，再选择新预设。Headless 调用方可以在传入同一 Auto overlay 时提供 `--session-id <id> --permission-mode <preset>`。
+3. 在集成存在时关闭并重新打开 Session。确认其所选预设仍为 Auto，除非你显式进行了更改。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-user-sources/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/auto-review-user-sources/guide.md
+/:
+  en: 5602b65244dc3b42
+  zh: a2d8b6485e75a097
+/auto-review-recognizes-user-sourced-instructions:
+  en: 3901da6e70cc6bc7
+  zh: 8b8963da4cd39d0f
+/auto-review-recognizes-user-sourced-instructions/change:
+  en: 4aa55907b4704194
+  zh: c5e4b94e2358a6ca
+/auto-review-recognizes-user-sourced-instructions/migration:
+  en: 5502daa0b833f046
+  zh: 2a7811dfd6d86004

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-user-sources/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Auto review recognizes user-sourced task instructions across input transports and existing history."
+---
+
+# Auto review recognizes user-sourced instructions
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Experimental Auto review recognizes text with `source.kind: 'user'` as task instructions without requiring a browser `rpcId`. This includes Headless, SDK, ACP, custom producers that submit as the user, and existing user-sourced history. An explicit instruction can authorize a medium-risk action within its stated scope. A child's own creation prompt and direct-parent messages retain their subordinate role; inherited and unverified creation prompts remain facts.
+
+## Migration
+
+1. Check custom calls to `createUserMessage`. Use the user source only for input submitted as the user's task. Give background or injected content its own producer-declared `MessageSourceMap` entry.
+2. Before resuming Auto, review existing user-sourced instructions that could authorize medium-risk actions. Explicitly replace any obsolete scope in the next task.
+3. Verify that injected content appears as `fact` or `constraint` in Auto's filtered history, while admitted user text appears as `user-instruction`. Files, tool results, and checkpoints cannot authorize actions.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/auto-review-user-sources/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Auto review 跨输入传输与已有历史识别 user-source 任务指令。"
+---
+
+# Auto review 识别 user-source 指令
+
+[English](guide.md) | 中文
+
+## 变更
+
+实验性 Auto review 将 `source.kind: 'user'` 的文本识别为任务指令，不再要求浏览器 `rpcId`。这包括 Headless、SDK、ACP、以用户身份提交内容的自定义生产者，以及已有的 user-source 历史。显式指令可在其声明范围内授权 medium 风险动作。Child 自身的创建 prompt 和直接父级消息保留从属角色；继承的创建 prompt 与无法验证的创建 prompt 仍是事实。
+
+## 迁移
+
+1. 检查自定义的 `createUserMessage` 调用。仅对作为用户任务提交的输入使用 user source。为后台或注入内容声明生产者自己的 `MessageSourceMap` 成员。
+2. 恢复 Auto 前，检查已有 user-source 指令中可能授权 medium 风险动作的内容。在下一个任务中明确替换已失效的范围。
+3. 验证 Auto 筛选历史将注入内容归为 `fact` 或 `constraint`，将接纳的用户文本归为 `user-instruction`。文件、工具结果和 checkpoint 不能授权动作。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/built-in-japanese/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/built-in-japanese/guide.md
+/:
+  en: cfd1ffd2cd268220
+  zh: 2ed03b1063f3319d
+/built-in-languages-replace-duplicate-language-packs:
+  en: 5855b69ac12a5f50
+  zh: a81de3239837f1c4
+/built-in-languages-replace-duplicate-language-packs/change:
+  en: 665e68d784661f15
+  zh: 2fff6fcfceea7994
+/built-in-languages-replace-duplicate-language-packs/migration:
+  en: 6f77e0b507e09ca7
+  zh: 59e0c71780f06e9e

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/built-in-japanese/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Built-in language registrations conflict with third-party language packs using the same ids."
+---
+
+# Built-in languages replace duplicate language packs
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The locale plugin registers `ja`, `es`, `fr`, `de`, `ru`, and `pt`, with dictionaries for `common`, `settings.locale`, and the built-in UI plugins. Third-party language packs using these ids now fail with an already-registered language or dictionary error, including packs based on the earlier Japanese or French README examples.
+
+## Migration
+
+1. In the language pack's client entry, remove `ctx.locale.addLanguage(...)` for these ids and dictionary registrations in namespaces supplied by built-in plugins. Keep translations for namespaces owned by your own plugins.
+2. If the pack represents a distinct language variant, register a separate BCP 47-style id, such as `fr-CA`, for both the definition and its dictionaries instead of the built-in id.
+3. Reload the application with the pack enabled. Confirm it starts without duplicate-registration errors and that selecting the intended language displays its translations.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/built-in-japanese/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "内置语言注册会与使用相同 id 的第三方语言包冲突。"
+---
+
+# 内置语言取代重复的语言包
+
+[English](guide.md) | 中文
+
+## 变更
+
+locale 插件注册 `ja`、`es`、`fr`、`de`、`ru` 和 `pt`，并提供 `common`、`settings.locale` 以及内置 UI 插件的字典。使用这些 id 的第三方语言包会因语言或字典已注册而加载失败，包括按此前 README 日语或法语示例编写的语言包。
+
+## 迁移
+
+1. 在语言包的 client 入口中，删除这些 id 的 `ctx.locale.addLanguage(...)`，以及内置插件已提供的命名空间下的字典注册。保留自己插件所拥有命名空间的翻译。
+2. 如果语言包代表不同的语言变体，为语言定义及其字典注册独立的 BCP 47 风格 id，例如 `fr-CA`，代替内置 id。
+3. 启用语言包并重新加载应用。确认启动时没有重复注册错误，且选择目标语言后显示对应译文。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/conditional-tools/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/conditional-tools/guide.md
+/:
+  en: 1dc343c5aa10de02
+  zh: 59ac1c2052255919
+/declare-conditional-tools-through-step-admission:
+  en: 4edb4c80b402de77
+  zh: 856160ec69c515ea
+/declare-conditional-tools-through-step-admission/change:
+  en: e140ab052beb78ed
+  zh: 9603c44ae7731ab8
+/declare-conditional-tools-through-step-admission/migration:
+  en: 364c2a62343a608b
+  zh: c00ab4611b1fc4e3

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/conditional-tools/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Tool declarations come only from step-admitted registrations: `system-prompt/assemble` no longer carries tools, conditional tools need a resolved step set, and `exit_plan_mode` is declared only after a Session first enters plan mode."
+---
+
+# Declare conditional tools through step admission
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`ctx.tools.register(definition, { when })` adds a synchronous or asynchronous condition. AgentLoop resolves conditions once per proposed step with `{ agent, modelSelection, signal }`, before prompt assembly and `agent/pre-step`, and uses the resulting `ResolvedToolSet` for tool declarations, Native dispatch, PTC bindings, and nested calls in that step and its retries. A false condition removes the tool from all of them; a thrown condition ends the turn with `TOOL_ACTIVATION_FAILED`.
+
+The `system-prompt/assemble` waterfall now receives sections, contexts, and variables (`PromptPresentation`) without a tool array, and a returned `tools` field is ignored. Plugins that removed or added tool declarations in that waterfall are affected; their removals no longer reach the request, and a listener that reads `assembly.tools` receives `undefined` and fails at runtime.
+
+Model tool calls run only through their step's admitted set. A call to a conditional tool without a resolved set, a call after the set is disposed, and a pending call whose registration was replaced or removed during the step return `UNKNOWN_TOOL` instead of running. Replacement applies to every tool, so a hot reload, MCP reconnect, or skill reload that re-registers a tool mid-step fails that step's unstarted calls of it. Callers that pass no set, such as the experimental `claude-code-mods` `$.tool.call`, cannot call conditional tools.
+
+`exit_plan_mode` is declared from the first step whose selected plan state is active and stays declared for the rest of the Session, so requests of a Session that never entered plan mode no longer list it. Existing Sessions require no format migration.
+
+## Migration
+
+1. Replace tool filtering and reads of `assembly.tools` in `system-prompt/assemble` listeners with a `when` condition on the registration; read the step's provider, model, and reasoning effort from the condition's `modelSelection`. Keep only section, context, and variable changes in the waterfall.
+2. Make tool guidance follow the same admission: section callbacks pass `context.toolSet` to `ctx.tools.get()` or `ctx.tools.schemas()`.
+3. For programmatic calls of conditional tools, call `ctx.tools.resolve({ agent, modelSelection, signal })`, pass the returned `toolSet` to `assemble()` and the `ctx.tools.execute()` batch, and dispose it after the batch settles. A custom executor that does not use the shared pipeline looks up each call with `ctx.tools.executable(name, agent, toolSet)`.
+4. Update expectations that listed `exit_plan_mode` before a Session entered plan mode. Verify that a disabled tool is absent from the request, that calling its name returns `UNKNOWN_TOOL` without reaching the implementation, and that a failing condition ends the turn with `TOOL_ACTIVATION_FAILED`.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/conditional-tools/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "工具声明只来自步骤准入的注册：`system-prompt/assemble` 不再携带工具，条件工具需要已解析的步骤集合，`exit_plan_mode` 只在会话首次进入计划模式后声明。"
+---
+
+# 通过步骤准入声明条件工具
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ctx.tools.register(definition, { when })` 可以附加同步或异步条件。AgentLoop 在提示词组装与 `agent/pre-step` 之前，以 `{ agent, modelSelection, signal }` 为每个拟议步骤计算一次条件，并在该步骤及其重试中用得到的 `ResolvedToolSet` 决定工具声明、原生分发、PTC 绑定和嵌套调用。条件返回 false 时，工具从以上所有位置移除；条件抛错时，轮次以 `TOOL_ACTIVATION_FAILED` 结束。
+
+`system-prompt/assemble` waterfall 现在接收不含工具数组的段落、上下文与变量（`PromptPresentation`），返回的 `tools` 字段会被忽略。在这个 waterfall 中删除或添加工具声明的插件会受到影响：它们做的删除不再进入请求；读取 `assembly.tools` 的监听器会拿到 `undefined`，并在运行时出错。
+
+模型的工具调用只通过所属步骤的准入集合执行。没有已解析集合的条件工具调用、集合释放之后的调用，以及注册在步骤内被替换或移除时尚未开始的调用，都会返回 `UNKNOWN_TOOL`，不会执行。替换规则适用于所有工具，因此在步骤中途重新注册工具的热重载、MCP 重连或 skill 重载会让该步骤里这个工具尚未开始的调用失败。不传集合的调用方（例如实验性 `claude-code-mods` 的 `$.tool.call`）无法调用条件工具。
+
+`exit_plan_mode` 从已选计划状态首次为激活的步骤起声明，并在会话剩余部分保持声明，因此从未进入计划模式的会话，其请求不再列出它。现有 Session 无需格式迁移。
+
+## 迁移
+
+1. 把 `system-prompt/assemble` 监听器中的工具过滤和对 `assembly.tools` 的读取改为注册时的 `when` 条件；从条件的 `modelSelection` 读取该步骤的提供方、模型与推理强度。waterfall 中只保留段落、上下文与变量的修改。
+2. 让工具指引跟随同一准入：段落回调把 `context.toolSet` 传给 `ctx.tools.get()` 或 `ctx.tools.schemas()`。
+3. 程序化调用条件工具时，调用 `ctx.tools.resolve({ agent, modelSelection, signal })`，把返回的 `toolSet` 传给 `assemble()` 与 `ctx.tools.execute()` 批次，并在批次结束后释放。不使用共享 pipeline 的自定义执行器用 `ctx.tools.executable(name, agent, toolSet)` 查找每次调用。
+4. 更新在会话进入计划模式之前仍列出 `exit_plan_mode` 的期望。验证被禁用的工具不出现在请求中，用其名称调用会返回 `UNKNOWN_TOOL` 且不进入实现，条件失败时轮次以 `TOOL_ACTIVATION_FAILED` 结束。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md
+/:
+  en: b0a44570cee3ac45
+  zh: f68438befed14c6e
+/context-menu-services-in-custom-client-compositions:
+  en: b2018bf0250be579
+  zh: 1d8a243d09f4128f
+/context-menu-services-in-custom-client-compositions/change:
+  en: 3eaef415166d076f
+  zh: 4040390d2572fc47
+/context-menu-services-in-custom-client-compositions/migration:
+  en: ebffe957534ac31b
+  zh: a33d2782f5ad0f5d

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Custom Client compositions must provide the context-menu and file-action services required by GUI plugins."
+---
+
+# Context menu services in custom Client compositions
+
+English | [中文](guide.zh.md)
+
+## Change
+
+GUI plugins now inject `contextMenus` to open shared object menus. The open-in-app plugin also injects `fileActions`, `sidebarRight`, `sidebarRightTabs`, and `remote.workspaceFiles`. Custom compositions that mount these GUI plugins without the new services cannot activate them. The shipped Web application bundle includes the providers; existing Session and tab menu Slot names remain available.
+
+## Migration
+
+1. In the package manifest that owns a custom composition, add dependencies on `@deepseek-ai/dsh-client-ui-context-menu` and `@deepseek-ai/dsh-client-ui-file-actions` at the same Harness version.
+2. Add both package names as plugin rows in the custom Client composition alongside the existing locale, slots, shortcuts, sidebar, and workspace-file providers. The default `@deepseek-ai/dsh-web-app` bundle already contains these rows.
+3. Rename `ctx.menus` to `ctx.contextMenus` and `MenuTargetMap` to `ContextMenuTargetMap`; neither old name has an alias. Mount the menu plugin so its `ctx.slots.provideRoot` contribution supplies `useContextMenu` to every Slot. Components call the hook once and spread `getTriggerProps(target, handlers?)` onto each element, including elements created in loops. See the [menu reference](../../../../packages/client/ui-context-menu/README.md) for handler composition and external action registration.
+4. Rebuild and launch the custom profile. Confirm that GUI plugins activate, right-clicking a background Session preserves selection, and existing Session/tab Slot contributions still appear.
+5. Custom Slot hosts must remove their declarations of `sidebar.workspaces.session.menu.item` and `sidebar.right.tab.menu.item`; the workspace and right-sidebar adapters now own these under `contextMenu.content`. Session rows retain the `[open, setOpen]` hook context, and tab rows receive `{ tab, dismiss }` within the clicked Session’s provider. A custom host replacing these adapters must declare the same children and supply those owners itself. Dockkit embedders using `getTabTriggerProps` own the popup and dismissal; `renderTabMenuItems` is used only by the kit popup. Supply reactive `tabMenuOpen` to suppress close-button tooltips while a custom menu prepares or remains open.
+
+6. Built-in Session menu items are data contributions. The legacy React Slot retains external entries together before Archive; Slot priority no longer shadows built-in actions. Use `ctx.contextMenus.register` for new actions and optional `commandId` to display an existing command’s current binding. Keep captured-target execution in `run`; no command dispatch is added.
+7. Menu contributions use `icon?: ReactNode`; replace `symbol` with a glyph element and wrap icon URLs in `<img>`. Obtain `useContextMenu` at each actual Slot entry. Plain children receive `getTriggerProps` or bound `contextMenuProps`; ToolRow uses `fileContextMenuProps` and `urlContextMenuProps`. Remove menu fields from Chat flow/node owners. The assistant entry supplies an ordinary file adapter to `forClosing()`, while Markdown adapts its target type at `MarkdownDelegateProvider.getTriggerProps`. Keep Session identity and gesture-time path resolution in the business registration. Remove imports of `contextMenuTrigger` and `menuPoint`; their independent utility package is removed. Do not add gesture exports to ui-primitives.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/context-menu-services/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "自定义 Client 组合必须提供 GUI 插件所需的右键菜单与文件动作服务。"
+---
+
+# 自定义 Client 组合中的右键菜单服务
+
+[English](guide.md) | 中文
+
+## 变更
+
+GUI 插件现在注入 `contextMenus` 以打开共享对象菜单。open-in-app 插件还注入 `fileActions`、`sidebarRight`、`sidebarRightTabs` 和 `remote.workspaceFiles`。自定义组合若挂载这些 GUI 插件却没有新服务，将无法激活它们。随附 Web 应用 bundle（插件包）已包含提供方；现有 Session 和标签页菜单 Slot 名称仍可使用。
+
+## 迁移
+
+1. 在自定义组合所属的包清单中，添加与 Harness 版本一致的 `@deepseek-ai/dsh-client-ui-context-menu` 和 `@deepseek-ai/dsh-client-ui-file-actions` 依赖。
+2. 在自定义 Client 组合中将两个包名添加为插件行，与已有 locale、slots、shortcuts、侧栏和工作区文件提供方并列。默认 `@deepseek-ai/dsh-web-app` bundle 已包含这些行。
+3. 将 `ctx.menus` 改为 `ctx.contextMenus`，将 `MenuTargetMap` 改为 `ContextMenuTargetMap`，旧名均无兼容别名。挂载菜单插件，由其 `ctx.slots.provideRoot` 贡献向每个 Slot 提供 `useContextMenu`。组件调用一次 hook，将 `getTriggerProps(target, handlers?)` 展开到每个元素，包括循环生成的元素。处理器组合和外部动作注册见[菜单参考](../../../../packages/client/ui-context-menu/README.zh.md)。
+4. 重新构建并启动自定义 profile（配置档）。确认 GUI 插件正常激活、右键后台 Session 不改变选择，且现有 Session/标签页 Slot 贡献仍然显示。
+5. 自定义 Slot 宿主应移除对 `sidebar.workspaces.session.menu.item` 和 `sidebar.right.tab.menu.item` 的声明；现在由工作区和右侧栏适配器在 `contextMenu.content` 下拥有它们。会话行继续接收 `[open, setOpen]` hook context，标签行在所点击会话的 provider 内接收 `{ tab, dismiss }`。替换这些适配器的自定义宿主须自行声明相同的子 Slot 并提供这些 owner。使用 `getTabTriggerProps` 的 Dockkit 嵌入方负责弹窗和关闭，`renderTabMenuItems` 仅供组件自身的弹窗使用。通过响应式 `tabMenuOpen` 在自定义菜单准备或显示时禁用关闭按钮的 Tooltip。
+
+6. 内置 Session 菜单项改为数据贡献。旧 React Slot 将外部条目集中显示在归档之前，Slot priority 不再覆盖内置动作。新增动作用 `ctx.contextMenus.register`，可通过 `commandId` 展示已有命令的当前绑定。针对捕获目标的执行仍放在 `run`，不增加命令调度。
+7. 菜单贡献使用 `icon?: ReactNode`：将 `symbol` 改为图标元素，并用 `<img>` 包装图标 URL。在每个实际 Slot 入口获取 `useContextMenu`。普通子组件接收 `getTriggerProps` 或绑定后的 `contextMenuProps`；ToolRow 使用 `fileContextMenuProps` 和 `urlContextMenuProps`。删除 Chat 消息流和节点 owner 的菜单字段。助手入口向 `forClosing()` 传入普通文件适配函数，Markdown 则在 `MarkdownDelegateProvider.getTriggerProps` 处适配目标类型。业务注册保留 Session 归属和触发时路径解析。删除 `contextMenuTrigger` 和 `menuPoint` 导入，其独立工具包已删除。不要向 ui-primitives 增加手势导出。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md
+/:
+  en: 131777d89cb23df3
+  zh: 44e50f8c09b2c4b9
+/computer-use-consent-storage:
+  en: fb837293708860f5
+  zh: 8ee31126d1faf7c7
+/computer-use-consent-storage/change:
+  en: 88150a92531212bf
+  zh: a0103c4d035a4af7
+/computer-use-consent-storage/migration:
+  en: c7a4989a79f4fbca
+  zh: 630fc23128ee0520

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Computer Use application consent moves from profile configuration to durable profile-scoped storage."
+---
+
+# Computer Use consent storage
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Computer Use stores application consent through `storageDomain`. With the default JSON backend, each canonical profile directory has its own `$DSH_HOME/storages/cua_permissions_<sha256>.json`. “Allow for this session” now follows the conversation ID across DSH restart and Computer Use disablement. It does not authorize another conversation. Unverifiable applications still require a matching native process identity; restarting that application may require new consent.
+
+`allowedApps` is a legacy import source. The first store access imports it once. Subsequent configuration edits do not grant or revoke access, and a revoked grant is not restored by reloading the old configuration. The permission page remains the authoring interface for grants and refusals. macOS privileges are unchanged.
+
+## Migration
+
+1. Keep the profile's existing storage services mounted. Shipped profiles already include `storageDomain` and the JSON backend; custom profiles need the same services. A profile without domain storage refuses authorization operations.
+2. Enable Computer Use and open its details to initialize storage. Confirm that the always-allowed applications appear.
+3. Remove `allowedApps` from the CUA entry in the profile configuration and other overlays after confirmation. Keep the remaining CUA configuration.
+4. Use the permission page to revoke applications or allow asking again. Existing conversation-only grants held by an older running process cannot be recovered; grant those once after upgrading. Newly granted conversation access then survives restart.
+5. Keep the storage file with that profile's state. Moving the profile to a different real directory selects a different store. File locks coordinate processes on one machine, not different machines sharing a network filesystem.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-consent-storage/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Computer Use 应用授权从 profile 配置迁移到按 profile 隔离的持久存储。"
+---
+
+# Computer Use 授权存储
+
+[English](guide.md) | 中文
+
+## 变更
+
+Computer Use 通过 `storageDomain` 保存应用授权。使用默认 JSON 后端时，每个 profile 的真实目录对应独立的 `$DSH_HOME/storages/cua_permissions_<sha256>.json`。“本会话允许”现在按对话 ID 跨 DSH 重启和 Computer Use 启停保留，不授权其他对话。无法验证签名的应用仍需匹配本机进程身份，应用重启后可能需要重新授权。
+
+`allowedApps` 作为旧数据来源，只在首次访问存储时导入一次。此后修改配置不会授予或撤销访问权限，重新加载旧配置也不会恢复已撤销的许可。权限页继续提供授权管理和清除拒绝的操作。macOS 系统权限保持原样。
+
+## 迁移
+
+1. 保留 profile 的现有存储服务。随附 profile 已包含 `storageDomain` 和 JSON 后端，自定义 profile 需要挂载相同服务。有 profile 但没有域存储时，授权操作会被拒绝。
+2. 启用 Computer Use 并打开详情页，初始化存储。确认始终允许的应用显示正确。
+3. 确认后，从 profile 配置及其他覆盖层的 CUA 条目中删除 `allowedApps`，保留其他 CUA 配置。
+4. 在权限页撤销应用授权或允许再次询问。旧进程内已有的会话许可无法恢复，升级后需要重新授予一次；新授予的会话许可随后可跨重启保留。
+5. 将存储文件作为该 profile 的状态保留。把 profile 移到另一个真实目录后会使用不同存储。文件锁协调同一电脑上的进程，不支持多台电脑共用网络文件系统。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.md
+/:
+  en: 36d6b79b48c08dd5
+  zh: 814caece159e9b0e
+/cua-defaults-to-ptc-session-scopes:
+  en: a53b6884785bdf56
+  zh: 7d27fc9b029e0e3e
+/cua-defaults-to-ptc-session-scopes/change:
+  en: dac96a29e3751249
+  zh: d48cb030f43c07e4
+/cua-defaults-to-ptc-session-scopes/migration:
+  en: f3d82fe45e41c712
+  zh: e55e424f5a2c096a

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Standalone native CUA compositions must explicitly select global tool registration."
+---
+
+# CUA defaults to PTC session scopes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The native CUA provider defaults `agentPreset` to `ptc`. It registers tools for existing and new PTC Agents, including when a saved application-grants configuration omits the new field. Custom compositions without an Agent preset registry no longer receive global CUA tools by default.
+
+## Migration
+
+1. For the standard Computer Use switch, keep the default; existing application grants remain usable.
+2. For a standalone composition that needs global tools, add `agentPreset: false` under the native CUA entry’s `config` in its profile patch or overlay. Preserve its other fields, including `allowedApps` and `helperPath`.
+3. Restart or let HMR apply the edit, then confirm that the intended Agent exposes `cua` in native mode or through the PTC SDK.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-preset-scope/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "独立原生 CUA 组合需要显式选择全局工具注册。"
+---
+
+# CUA 默认使用 PTC 会话作用域
+
+[English](guide.md) | 中文
+
+## 变更
+
+原生 CUA 提供方的 `agentPreset` 默认为 `ptc`。工具注册到已有和新建 PTC Agent，即使保存的应用授权配置没有这个新字段也会生效。不包含 Agent preset 注册表的自定义组合不再默认获得全局 CUA 工具。
+
+## 迁移
+
+1. 使用标准 Computer Use 开关时保持默认值，已有应用授权仍可使用。
+2. 独立组合若需要全局工具，在 profile patch 或 overlay 的原生 CUA 条目 `config` 下添加 `agentPreset: false`，保留 `allowedApps`、`helperPath` 等其他字段。
+3. 重启或等待 HMR 应用后，确认目标 Agent 能在原生模式或 PTC SDK 中使用 `cua`。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.i18n.yaml

@@ -0,0 +1,16 @@
+# Bilingual-pair consistency record for guide.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/upgrade-guide/v0.2.1-rc.2/cua-relative-coordinates/guide.md
+/:
+  en: ffbf3ccb8ac486ea
+  zh: 1712a76e8e3a664a
+/cua-relative-coordinates-use-0-999:
+  en: 1952d155be13e0d1
+  zh: 01b2f9f27499f033
+/cua-relative-coordinates-use-0-999/change:
+  en: 311311c2056c8e93
+  zh: 63f4dc87c9d22f99
+/cua-relative-coordinates-use-0-999/migration:
+  en: de5b600f1d9ae83c
+  zh: e2de8ebd5c7ca2bb