dsh-primer 0.4.4 → 0.4.6

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Task-board changes no longer end wait_agent calls; send a message to request further work."
+---
+# Agent waits require inbox input
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`wait_agent` waits only for the calling Agent's next-step inbox. Task creation, assignment, completion, and other task updates no longer end an active wait. They do not add inbox messages or start idle Agents. Queued next-turn input and other Agents' status changes also leave the wait pending.
+
+Existing next-step input returns immediately; new messages, completion notifications, and user steering end the wait without consuming that input. Timeout and cancellation behavior remain unchanged.
+
+## Migration
+
+1. After changing a task, use `send_message` when its owner or another member needs to act on the update. Do not rely on a task mutation to release `wait_agent`.
+2. Read current task state before acting; a task update is not a message or an instruction to begin a new turn.
+3. Verify that a task update leaves an empty-inbox wait pending, then send a message and confirm that the wait returns with `timedOut: false`.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/inbox-only-agent-wait/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "任务板变更不再结束 wait_agent 调用；需要继续工作时发送消息。"
+---
+# Agent 等待需要收件箱输入
+
+[English](guide.md) | 中文
+
+## 变更
+
+`wait_agent` 仅等待调用 Agent 的下一步收件箱。任务创建、分配、完成和其他任务更新不再结束正在进行的等待，也不添加收件箱消息或启动空闲 Agent。排队的下一轮输入和其他 Agent 的状态变化同样不会结束等待。
+
+已有下一步输入时立即返回；新消息、完成通知和用户引导会结束等待，但不消费输入。超时和取消行为保持不变。
+
+## 迁移
+
+1. 修改任务后，需要任务所有者或其他成员处理更新时使用 `send_message`。不要依赖任务修改来结束 `wait_agent`。
+2. 行动前读取当前任务状态；任务更新不是消息，也不是开始新轮次的指令。
+3. 验证任务更新不会结束空收件箱上的等待，然后发送消息，确认等待返回 `timedOut: false`。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/independent-session-forks/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.3/independent-session-forks/guide.md
+/:
+  en: 68f919837577038b
+  zh: 6ae8223b1542c369
+/ordinary-forks-are-independent-sessions:
+  en: 4556d51bd8086cfe
+  zh: 8811b03db9225739
+/ordinary-forks-are-independent-sessions/change:
+  en: 0a2790279aec9e24
+  zh: 5cca673af988a228
+/ordinary-forks-are-independent-sessions/migration:
+  en: 53b586ad6498fdb8
+  zh: dfa70928e17478e2

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "Ordinary Session forks stop recording their source relationship and stop appearing as subagents."
+---
+
+# Ordinary forks are independent Sessions
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Ordinary forks copy the selected history and continue independently. They omit `SessionHeader.parentSession` and the Client's `parentSessionId`; no replacement source field is written. Subagents, including fork-backend subagents, retain their direct creator. Existing logs retain their recorded metadata.
+
+SDK `subagent.started` excludes ordinary forks, including historical ones carrying a parent id. ACP list/resume admits ordinary forks; headless adoption also accepts them when cwd and preset checks pass. Client lists no longer indent them or insert newly discovered forks before their sources; saved manual positions remain intact. Source-based trace queries, parent filters, telemetry, and remote logs cannot recover the source of new ordinary forks. Workspace binding, optional title increments, inherited history, and seed boundaries remain available.
+
+The Session format stays V4. Older V4 readers may reject a parentless fork containing inherited delivery acknowledgements as a corrupt log with `current-generation delivery marker names the wrong Session`. The tested readers refuse before granting a handle or truncating the file. They do not provide an upgrade-specific diagnostic. See the [compatibility decision](../../../../.agents/notes/implemented/architecture/2026-10-23-independent-session-forks.md).
+
+## Migration
+
+1. Upgrade every reader and writer sharing the Session directory before resuming newly created forks. Do not edit old headers or delete delivery records to bypass an older reader's rejection.
+2. Replace consumer checks that treat any `parentSession` as a subagent with `origin === 'subagent'`. Continuation still requires a valid descriptor from the Session's own event range; inherited descriptors do not establish its identity.
+3. Remove any ordinary-fork workflow that requires persistent source tracing. Keep source-dependent actions such as workspace selection within the fork operation.
+4. Confirm that an ordinary fork has no parent field, survives restart with inherited delivery records, and produces no `subagent.started`; confirm that real subagents retain their creator and notification.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/independent-session-forks/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: "普通 Session fork 停止记录来源关系，也不再显示为子代理。"
+---
+
+# 普通 fork 是独立 Session
+
+[English](guide.md) | 中文
+
+## 变更
+
+普通 fork 复制选定历史并独立继续运行。它们省略 `SessionHeader.parentSession` 及客户端的 `parentSessionId`，不写入替代来源字段。子代理（包括使用 fork backend 的子代理）保留直接创建者。已有日志保留记录中的元数据。
+
+SDK 的 `subagent.started` 排除普通 fork，包括携带父 ID 的历史会话。ACP 列表和恢复允许普通 fork；通过 cwd 和 preset 检查的普通 fork 也可由 headless 沿用。客户端列表不再将它们缩进，也不再把新发现的 fork 插到来源之前；已保存的手动位置保持不变。基于来源的追踪查询、父关系筛选、遥测和远端日志无法还原新普通 fork 的来源。工作区绑定、可选标题递增、继承历史和 seed 边界仍然可用。
+
+Session 格式保持 V4。旧 V4 reader 可能将包含继承投递确认的无父关系 fork 作为损坏日志拒绝，报错为 `current-generation delivery marker names the wrong Session`。已测试的 reader 在授予句柄或截断文件之前拒绝，不提供专门的升级诊断。参见[兼容性决策](../../../../.agents/notes/implemented/architecture/2026-10-23-independent-session-forks.zh.md)。
+
+## 迁移
+
+1. 在恢复新建 fork 之前，升级共享 Session 目录的全部 reader 和 writer。不要编辑旧 header 或删除投递记录来绕过旧 reader 的拒绝。
+2. 将消费方中把任意 `parentSession` 视为子代理的检查替换为 `origin === 'subagent'`。继续运行仍要求来自 Session 自身事件区间的有效 descriptor；继承的 descriptor 不建立其身份。
+3. 移除依赖持久化来源追踪的普通 fork 工作流。工作区选择等依赖来源的动作保留在 fork 操作期间。
+4. 确认普通 fork 不含父字段、携带继承投递记录也能在重启后恢复，且不产生 `subagent.started`；确认真正子代理保留创建者及通知。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/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.3/ptc-caller-cancellation/guide.md
+/:
+  en: 6deb73f8bd3b1b2a
+  zh: 8bafa6e8c6277923
+/ptc-caller-cancellation-uses-the-standard-tool-error-code:
+  en: c647ac85178ef0ea
+  zh: a6e5b76d53bbb6ef
+/ptc-caller-cancellation-uses-the-standard-tool-error-code/change:
+  en: 1a9a455bf55e6b81
+  zh: ec925abc44d7684f
+/ptc-caller-cancellation-uses-the-standard-tool-error-code/migration:
+  en: e3bbbebda24059c0
+  zh: 926e91f3ce5a8a72

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Caller-cancelled run_code results use ABORTED instead of CODE_RUN_FAILED."
+---
+
+# PTC caller cancellation uses the standard tool error code
+
+English | [中文](guide.zh.md)
+
+## Change
+
+When a running `run_code` call is cancelled by its caller and the runtime reports `abort`, its `tool/result` error changes from `CodeRunFailedError` / `CODE_RUN_FAILED` to `AbortError` / `ABORTED`. The result content is `Error: tool call aborted`, replacing the runtime diagnostic, captured output and sandbox summary. SDK clients and Session consumers that classify these results are affected.
+
+The Agent continues to record the specific cancellation cause in `turn/end`, including a hook's `reason`. Runtime failures such as timeout and cleanup failure, and runtime-local cancellation without caller cancellation, retain `CODE_RUN_FAILED`. Cancellation still waits for cleanup; it does not roll back completed tool effects, and retained runtime variables may be cleared.
+
+## Migration
+
+1. In consumers of new `tool/result` events, classify caller cancellation by `data.error.code === 'ABORTED'`. Read the Agent cancellation cause from the corresponding `turn/end` event's `data.reason.reason` when `data.reason.kind === 'aborted'`.
+2. Keep support for `CODE_RUN_FAILED` when reading historical PTC cancellation results. Existing Session logs are not rewritten.
+3. Cancel a running `run_code` call and confirm its result has code `ABORTED`, followed by a `turn/end` event containing the original Agent cancellation cause. Confirm ordinary runtime failures still report `CODE_RUN_FAILED`.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/ptc-caller-cancellation/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "调用方取消的 run_code 结果使用 ABORTED，取代 CODE_RUN_FAILED。"
+---
+
+# PTC 调用方取消使用标准工具错误码
+
+[English](guide.md) | 中文
+
+## 变更
+
+运行中的 `run_code` 被调用方取消且运行时报告 `abort` 时，其 `tool/result` 错误从 `CodeRunFailedError` / `CODE_RUN_FAILED` 变为 `AbortError` / `ABORTED`。结果内容为 `Error: tool call aborted`，取代运行时诊断、捕获输出和沙箱摘要。按这些结果分类的 SDK 客户端和 Session 消费方受到影响。
+
+Agent 继续在 `turn/end` 中记录具体取消原因，包括 hook 的 `reason`。超时、清理失败等运行时失败，以及没有调用方取消的运行时内部取消，保留 `CODE_RUN_FAILED`。取消仍等待清理完成；它不会回滚已完成的工具操作，保留的运行时变量可能被清空。
+
+## 迁移
+
+1. 在新 `tool/result` 事件的消费方中，通过 `data.error.code === 'ABORTED'` 识别调用方取消。当对应 `turn/end` 事件的 `data.reason.kind === 'aborted'` 时，从 `data.reason.reason` 读取 Agent 取消原因。
+2. 读取历史 PTC 取消结果时，继续支持 `CODE_RUN_FAILED`。已有 Session 日志不会被重写。
+3. 取消运行中的 `run_code`，确认其结果错误码为 `ABORTED`，随后的 `turn/end` 事件包含原始 Agent 取消原因。确认普通运行时失败仍报告 `CODE_RUN_FAILED`。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/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.3/session-follow-activation/guide.md
+/:
+  en: 789ee06aa8932a32
+  zh: d465eb26824f2b4b
+/request-activation-when-following-a-session:
+  en: 25bd54a8216b1c71
+  zh: edaa12b04713528a
+/request-activation-when-following-a-session/change:
+  en: d4021672fedcbfb7
+  zh: 35d5e76a69301e4a
+/request-activation-when-following-a-session/migration:
+  en: aa22d72ca3f91d38
+  zh: ebe991eca4bf74c2

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Session follow callers must explicitly request background Agent activation."
+---
+# Request activation when following a Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`session.follow` no longer automatically resumes a cold ordinary Agent when `activate` is omitted. It reads the opening snapshot and follows subsequent events without activation. This affects integrations that used opening a history stream to make an Agent available. The shipped Web Client sends `activate: true` explicitly and retains its opening behavior.
+
+With `activate: true`, activation starts once the opening snapshot is computed, before it is delivered; that snapshot does not acknowledge Agent readiness. Subagent Sessions still do not use ordinary Agent activation.
+
+## Migration
+
+1. Add `activate: true` to `session.follow` requests that must resume a cold ordinary Agent. Keep the existing `address` and history-window fields.
+2. For passive viewers, omit `activate` or set it to `false`.
+3. Verify that an activation-enabled stream still returns its opening snapshot, then check Agent availability separately. Do not treat receipt of the snapshot as completion of activation.
+
+See the [Session Controller reference](../../../../packages/api/session-controller/README.md) for history and state observation behavior.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/session-follow-activation/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: "Session follow 调用方必须显式请求后台 Agent 激活。"
+---
+# 跟随 Session 时显式请求激活
+
+[English](guide.md) | 中文
+
+## 变更
+
+`session.follow` 在省略 `activate` 时不再自动恢复冷普通 Agent。它只读取开场快照并跟随后续事件，不进行激活。这会影响通过打开历史流使 Agent 可用的集成。随产品提供的 Web Client 显式发送 `activate: true`，保留原有打开行为。
+
+设置 `activate: true` 时，激活在开场快照计算完成后、交付之前开始；该快照不确认 Agent 已就绪。子会话仍不走普通 Agent 激活。
+
+## 迁移
+
+1. 为需要恢复冷普通 Agent 的 `session.follow` 请求添加 `activate: true`，保留原有 `address` 和历史窗口字段。
+2. 被动查看器可以省略 `activate` 或设为 `false`。
+3. 确认启用激活的流仍返回开场快照，再单独检查 Agent 是否可用。不要把收到快照当作激活完成。
+
+历史与状态观察行为见 [Session Controller 参考](../../../../packages/api/session-controller/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/subagent-runtime-ownership/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.3/subagent-runtime-ownership/guide.md
+/:
+  en: 10f7c9b47f2b39f2
+  zh: 2c93aa4e6bef0f33
+/subagent-runtime-ownership:
+  en: 20c105e3d68b46ee
+  zh: 685c1ad4eef7eefb
+/subagent-runtime-ownership/change:
+  en: bacb015157610964
+  zh: 635055eab24394ac
+/subagent-runtime-ownership/migration:
+  en: 3fb0ce93ad94074f
+  zh: 49e2f520191d6c53

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/subagent-runtime-ownership/guide.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: Agent factory ownership parameters and registry tree queries are removed; subagent Activations own runtime tree membership.
+---
+
+# Subagent runtime ownership
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-agent` removes the create/resume runtime-owner parameter (`parentAgent` or `ownerAgent`), `AgentRegistry.isOwnedBy()`, `AgentRegistry.roots()`, and the owner argument of `enter()`. Direct factory creation no longer enrolls an Agent in a managed subagent tree. Custom factories no longer implement runtime tree ownership.
+
+The subagent service resolves runtime membership from its existing Activations through `rootOf(agent)`. The Session format and Cordis context ownership of handles are unchanged.
+
+## Migration
+
+1. Create delegated work through `ctx.subagents.startActivation()` with a registered provider. Remove ownership parameters from direct `ctx.agents.create()` and `resume()` calls; these operations create independent runtime instances.
+2. Use `ctx.agents.get(id)` and `list()` for live lookup. To select ordinary live Agents, filter `list()` by `agent.session.header.origin !== 'subagent'`; historical ordinary forks can still have `parentSession`.
+3. Query the live tree root with `ctx.subagents.rootOf(agent)` and compare Agent objects, not only ids. Ordinary live Agents resolve to themselves; unmanaged delegated or stale instances throw `SubagentError` with code `UNAUTHORIZED`. Read `session.header.parentSession` for the direct creator; use durable subagent catalogs when traversing offline creation ancestors.
+4. Update custom factory implementations to call `ctx.agents.enter(agent)` after setup. Retain caller-context disposal, initialization rollback, and exact-instance registration checks. Runtime tree membership is available after managed activation publication; `agent/created` runs before that point. Verify stale instances cannot reuse a disposed instance's ownership.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/subagent-runtime-ownership/guide.zh.md

@@ -0,0 +1,21 @@
+---
+kind: upgrade-guide
+description: Agent 工厂归属参数和注册表树查询已删除；subagent Activation 拥有运行时树成员关系。
+---
+
+# Subagent 运行时归属
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-agent` 删除 create/resume 的运行时归属参数（`parentAgent` 或 `ownerAgent`）、`AgentRegistry.isOwnedBy()`、`AgentRegistry.roots()` 以及 `enter()` 的 owner 参数。直接通过工厂创建 Agent 不再将其加入托管 subagent 树。自定义工厂不再实现运行时树归属。
+
+subagent 服务通过 `rootOf(agent)` 从已有 Activation 解析运行时成员关系。Session 格式和 Cordis 上下文对句柄的所有权不变。
+
+## 迁移
+
+1. 通过 `ctx.subagents.startActivation()` 和已注册提供方创建委派工作。删除直接调用 `ctx.agents.create()` 与 `resume()` 时的归属参数；这些操作创建独立的运行时实例。
+2. 通过 `ctx.agents.get(id)` 与 `list()` 查询存活实例。筛选普通存活 Agent 时，用 `agent.session.header.origin !== 'subagent'` 过滤 `list()`；历史普通 fork 仍可能包含 `parentSession`。
+3. 通过 `ctx.subagents.rootOf(agent)` 查询存活树根，并比较 Agent 对象，而非仅比较 id。普通存活 Agent 返回自身；非托管的委派实例或失效实例抛出代码为 `UNAUTHORIZED` 的 `SubagentError`。直接创建者读取 `session.header.parentSession`；遍历离线创建祖先时使用持久化 subagent 目录。
+4. 更新自定义工厂，在 setup 后调用 `ctx.agents.enter(agent)`。保留调用方上下文释放、初始化回滚和确切实例注册检查。运行时树成员关系在托管 activation 发布后可用；`agent/created` 早于该时点。验证失效实例不能复用已释放实例的归属。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-mode-menu/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.3/team-mode-menu/guide.md
+/:
+  en: 1c39dada6c6162a7
+  zh: ab2f5e2824bfbf0c
+/select-team-mode-from-the-conversation-menu:
+  en: d570d0f970f6a77a
+  zh: 7a722461f27bc620
+/select-team-mode-from-the-conversation-menu/change:
+  en: 37b569a98d41587d
+  zh: ce9c8ee4c35ac634
+/select-team-mode-from-the-conversation-menu/migration:
+  en: d548bbca6276ed74
+  zh: 2468a89bd342b3ff

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-mode-menu/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The Team mode slash command is removed; use the root conversation menu."
+---
+
+# Select Team mode from the conversation menu
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`/team on` and `/team off` are no longer registered. The root conversation’s **Use Agent Teams** switch calls `remote.agentTeams.setEnabled` directly. Saved selections, task retention, and root-only authorization are unchanged.
+
+## Migration
+
+1. Enable or disable **Use Agent Teams** in the root conversation’s model and reasoning menu.
+2. Plugins that execute the command should call `ctx.agentTeams.setEnabled(rootAgent, enabled)` instead; browser clients call `remote.agentTeams.setEnabled(rootSessionId, enabled)`.
+3. Confirm the switch reflects the saved selection after reloading the Session.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-mode-menu/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "Team 模式斜杠命令已移除，请使用根会话菜单。"
+---
+
+# 从会话菜单选择 Team 模式
+
+[English](guide.md) | 中文
+
+## 变更
+
+`/team on` 和 `/team off` 不再注册。根会话的**使用智能体团队**开关直接调用 `remote.agentTeams.setEnabled`。保存的选择、任务保留以及仅允许根会话修改的授权规则不变。
+
+## 迁移
+
+1. 在根会话的模型与推理等级菜单中打开或关闭**使用智能体团队**。
+2. 执行该命令的插件改为调用 `ctx.agentTeams.setEnabled(rootAgent, enabled)`；浏览器客户端调用 `remote.agentTeams.setEnabled(rootSessionId, enabled)`。
+3. 重新加载 Session，确认开关反映已保存的选择。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-projection/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.3/team-projection/guide.md
+/:
+  en: 185304d86b229610
+  zh: b98e40567653a55f
+/team-projection-retains-tasks-and-mode:
+  en: c20510084cf9d412
+  zh: ee26f2365ab5d216
+/team-projection-retains-tasks-and-mode/change:
+  en: 5b92baca861b7281
+  zh: 57b4162fb425163c
+/team-projection-retains-tasks-and-mode/migration:
+  en: 6c30148dea17af5e
+  zh: 81b7fa72cc118252

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-projection/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Team projection stops restoring historical teammates and mailbox state while retaining tasks and saved mode."
+---
+
+# Team projection retains tasks and mode
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `agentTeam` projection no longer restores `members`, `messages`, or `delivered` from historical `team/member` and `team/message/*` events. It ignores their payloads, so historical roster or mailbox validation failures no longer block task reads or writes. Historical teammates are not restored and queued mail is not delivered.
+
+Task revisions, task owners, deleted-task records, and the saved Team mode remain supported. Ordinary subagent discovery and messaging are unchanged. The Session format and committed log files do not change; projection checkpoint version 7 rebuilds older cached state from the log.
+
+## Migration
+
+1. No data conversion or configuration change is required. Open the Session normally to rebuild incompatible projection checkpoints.
+2. Use `list_agents` and `send_message` for current teammates. Read historical roster or mailbox events from the original Session log if you need an archive; the Team projection no longer supplies these collections.
+3. Confirm that the task board and saved Team mode are restored. Historical roster and mailbox records do not grant task-assignment authority.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/team-projection/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Team 投影停止恢复历史队友与邮箱状态，同时保留任务和保存的模式。"
+---
+
+# Team 投影保留任务与模式
+
+[English](guide.md) | 中文
+
+## 变更
+
+`agentTeam` 投影不再从历史 `team/member` 和 `team/message/*` 事件恢复 `members`、`messages` 或 `delivered`。投影忽略这些载荷，因此历史名册或邮箱校验失败不再阻止任务读写。不恢复历史队友，也不投递排队邮件。
+
+任务修订、任务所有者、已删除任务记录和保存的 Team 模式仍受支持。普通子代理发现与通信保持不变。Session 格式和已提交日志文件不变；投影检查点版本 7 从日志重建旧缓存状态。
+
+## 迁移
+
+1. 无需转换数据或修改配置。正常打开 Session 即可重建不兼容的投影检查点。
+2. 使用 `list_agents` 和 `send_message` 与当前队友协作。需要归档信息时，从原始 Session 日志读取历史名册或邮箱事件；Team 投影不再提供这些集合。
+3. 确认任务板和保存的 Team 模式已恢复。历史名册与邮箱记录不授予任务分配权限。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/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.3/web-file-downloads/guide.md
+/:
+  en: 25674d6a93c97ca5
+  zh: ac1563eccab1b284
+/file-downloads-on-web:
+  en: d8fac1a37dede04d
+  zh: 8f132360f0553b64
+/file-downloads-on-web/change:
+  en: d76c6132a5e5fc9d
+  zh: 691b2264a37a526f
+/file-downloads-on-web/migration:
+  en: a4365e73ae4e2de4
+  zh: 8988bc1703fc5b8d

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "Custom file-action menus must offer save-as only on Desktop and browser downloads on Web."
+---
+
+# File downloads on Web
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The Web file-action service no longer offers save-as through a browser file picker. `canSaveAs` is always false on Web, and `save(source, 'saveAs')` rejects before reading the source. Built-in Web file and image menus offer Download and omit Save as. Desktop still offers both actions; successful saves return the absolute destination `path` instead of an opaque file ID.
+
+## Migration
+
+1. Custom Client menus should include Save as only when `ctx.fileActions.canSaveAs` is true.
+2. On Web, call `ctx.fileActions.save(source, 'download')`. The browser handles the original content and suggested filename; a `requested` result means download started, not completed. Do not report a saved local path.
+3. Replace `savedFile(url)` and `reveal(id)` calls with an action on the completed `saved` result, using its `path` with `session.openWorkspacePath`. Keep original-file context-menu reveal independent of saved destinations.
+4. Verify that Web file and image menus expose Download without Save as, including browsers that support `showSaveFilePicker`. Verify that Desktop image menus retain both actions. See the [file-action reference](../../../../packages/client/ui-file-actions/README.md) for save results and feedback ownership.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-file-downloads/guide.zh.md

@@ -0,0 +1,19 @@
+---
+kind: upgrade-guide
+description: "自定义文件动作菜单应仅在 Desktop 提供另存为，在 Web 使用浏览器下载。"
+---
+
+# Web 文件下载
+
+[English](guide.md) | 中文
+
+## 变更
+
+Web 文件动作服务不再通过浏览器文件选择器提供另存为。Web 的 `canSaveAs` 始终为 false，`save(source, 'saveAs')` 会在读取来源前拒绝。内置 Web 文件和图片菜单提供「下载」，不显示「另存为」。Desktop 仍提供两种操作；保存成功后返回目标绝对路径 `path`，不再返回不透明文件 ID。
+
+## 迁移
+
+1. 自定义 Client 菜单仅在 `ctx.fileActions.canSaveAs` 为 true 时添加「另存为」。
+2. Web 端调用 `ctx.fileActions.save(source, 'download')`。浏览器处理原始内容和建议文件名；`requested` 结果仅表示下载已开始，不代表完成。不要报告本机保存路径。
+3. 将 `savedFile(url)` 和 `reveal(id)` 调用替换为完成后 `saved` 结果上的操作，使用其中的 `path` 调用 `session.openWorkspacePath`。原文件右键定位应独立于保存目标。
+4. 验证 Web 文件和图片菜单只有「下载」而没有「另存为」，包括支持 `showSaveFilePicker` 的浏览器；验证 Desktop 图片菜单保留两种操作。保存结果与提示的归属参见[文件动作参考](../../../../packages/client/ui-file-actions/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-search-defaults/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.3/web-search-defaults/guide.md
+/:
+  en: 0bac687ed0a7a944
+  zh: 0dade41ad394e9ed
+/web-search-defaults:
+  en: a8cdc03730cb149c
+  zh: 9ddab73784ab6241
+/web-search-defaults/change:
+  en: bb2364852099c2f0
+  zh: 2ff6e8911af96569
+/web-search-defaults/migration:
+  en: dd501144b0f64744
+  zh: 6940e5842fc140db

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-search-defaults/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "One web_search call accepts 10 queries and returns 10 sources by default, and the DeepSeek Search API provider paces its requests."
+---
+
+# Web search defaults
+
+English | [中文](guide.zh.md)
+
+## Change
+
+In `dsh-tool-web`, the `searchMaxQueries` default rises from 4 to 10 and the `searchMaxResults` default rises from 8 to 10. The `web_search` schema now advertises `1–10 search queries`, so a call with 5–10 queries runs instead of failing validation, and each call can return up to 10 sources. A call can therefore start more provider searches and add more source text to the context. With the shipped Messages search provider, each query is one auxiliary model request. `dsh-web-deepseek-api` adds `searchRequestsPerSecond`, default 5: its Search provider sends at most that many requests in any one-second window, so the second five queries of a 10-query call start one second after the first instead of exceeding the account's 5 QPS limit. Values that a deployment already sets are kept.
+
+## Migration
+
+1. To keep the previous limits, set `searchMaxQueries: 4` and `searchMaxResults: 8` in the `tool-web` entry's `config` in `cordis.patch.yml`.
+2. If several processes share one DeepSeek account through the Search API, lower `searchRequestsPerSecond` in the `web-deepseek-api` entry so that their combined rate stays at or below 5.
+3. Confirm the result by running a task that sends 10 queries in one `web_search` call: it returns results instead of `Error: queries must contain at most 4 queries`. See the [tool-web configuration](../../../../packages/web/tool-web/README.md).

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.3/web-search-defaults/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "一次 web_search 调用默认接受 10 个查询并返回 10 个来源，DeepSeek Search API 提供方会为请求限速。"
+---
+
+# Web 搜索默认值
+
+[English](guide.md) | 中文
+
+## 变更
+
+在 `dsh-tool-web` 中，`searchMaxQueries` 默认值从 4 提高到 10，`searchMaxResults` 默认值从 8 提高到 10。`web_search` 的 schema 现在公布 `1–10 search queries`，因此含 5–10 个查询的调用会执行，而不是校验失败；每次调用最多返回 10 个来源。因此一次调用可能发起更多提供方搜索，并向上下文加入更多来源文本。使用内置的 Messages 搜索提供方时，每个查询都是一次辅助模型请求。`dsh-web-deepseek-api` 新增 `searchRequestsPerSecond`，默认 5：其 Search 提供方在任意一秒窗口内最多发送这么多请求，因此 10 个查询的调用中后五个查询比前五个晚一秒开始，而不会超过账号的 5 QPS 限制。部署已设置的值保持不变。
+
+## 迁移
+
+1. 如需保留原上限，在 `cordis.patch.yml` 的 `tool-web` 条目 `config` 中设置 `searchMaxQueries: 4` 和 `searchMaxResults: 8`。
+2. 如果多个进程通过 Search API 共享同一个 DeepSeek 账号，在 `web-deepseek-api` 条目中调低 `searchRequestsPerSecond`，使它们的合计速率不超过 5。
+3. 运行一个在一次 `web_search` 调用中发送 10 个查询的任务来确认：调用返回结果，而不是 `Error: queries must contain at most 4 queries`。参见 [tool-web 配置](../../../../packages/web/tool-web/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/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.4/model-listing-refresh/guide.md
+/:
+  en: 87b8371f353630ce
+  zh: 545cd66ec2055405
+/model-listings-refresh-automatically:
+  en: f4613eb3beef2045
+  zh: 7c1301d90456a6c2
+/model-listings-refresh-automatically/change:
+  en: 6ed436b9f0a93aef
+  zh: 16a09e92ba786d89
+/model-listings-refresh-automatically/migration:
+  en: e479027c4c4811df
+  zh: 7cc7cde8aa4e0135

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "DeepSeek model listings refresh automatically after first use, and custom listing-cache owners must supply live settings and change notifications."
+---
+# Model listings refresh automatically
+
+English | [中文](guide.zh.md)
+
+## Change
+
+DeepSeek account and API-key routes refresh their model listing automatically after first use, including while idle. `modelsMaxAgeMs` keeps its ten-minute default and now schedules background requests instead of waiting for another access. Failed refreshes retain the last successful listing, including badges. Successful refreshes replace badge metadata, including omission or `null`, and notify open Web selectors.
+
+`ModelListingCache` consumers must supply `settings` and `changed` callbacks. Its `dispose()` now returns a promise that settles after active loads and automatic credential lookups finish. `ListedCatalog` also requires a `badges` map, and `ModelSelectInjected` requires a `resolveText` callback.
+
+## Migration
+
+1. Keep existing `modelsMaxAgeMs` values to use the same interval for automatic refresh. Use `0` only when each access should refresh and no automatic timer should run.
+2. Custom `ModelListingCache` owners must provide `settings: () => ListingSettings | undefined` for the latest route configuration and `changed: () => void` to notify catalog consumers. Return `undefined` from `settings` when the route stops following a listing.
+3. Return or await `cache.dispose()` from the owning plugin's cleanup.
+4. Code that constructs `ListedCatalog` must include `badges: new Map()` when it has no badges, or a map from model id to `LlmModelBadge`. Prefer `resolveListedCatalog` to construct this result from decoded listing entries.
+5. Code that constructs `ModelSelectInjected` must provide `resolveText: text => ctx.locale.resolveText(text)` from its owning locale service. Test doubles can use `text => typeof text === 'string' ? text : text.en` when they intentionally render English.
+6. After the next refresh, confirm that an already-open model selector displays the current badge without reloading the page. Remove the badge field or set it to `null` to clear it.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/model-listing-refresh/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "DeepSeek 模型列表首次使用后自动刷新，自定义列表缓存的持有者必须提供实时配置与变化通知。"
+---
+# 模型列表自动刷新
+
+[English](guide.md) | 中文
+
+## 变更
+
+DeepSeek 账号与 API key 路由首次使用模型列表后会自动刷新，空闲时也会刷新。`modelsMaxAgeMs` 保留十分钟默认值，现在会安排后台请求，无需等待下一次访问。刷新失败时保留上次成功加载的列表及其角标。刷新成功时替换角标元数据，省略或 `null` 也会生效，并通知已打开的 Web 选择器。
+
+`ModelListingCache` 的消费方必须提供 `settings` 与 `changed` 回调。其 `dispose()` 现在返回一个 promise，等待进行中的加载与自动凭据查询结束后才完成。`ListedCatalog` 还要求提供 `badges` 映射，`ModelSelectInjected` 要求提供 `resolveText` 回调。
+
+## 迁移
+
+1. 保留现有 `modelsMaxAgeMs` 值即可按相同间隔自动刷新。只有需要每次访问都刷新、且不运行自动定时器时，才使用 `0`。
+2. 自定义 `ModelListingCache` 持有者必须提供 `settings: () => ListingSettings | undefined` 以读取最新路由配置，并通过 `changed: () => void` 通知目录消费方。路由停止跟随列表时，`settings` 返回 `undefined`。
+3. 在持有该缓存的插件清理函数中返回或等待 `cache.dispose()`。
+4. 构造 `ListedCatalog` 的代码在没有角标时必须提供 `badges: new Map()`，否则提供模型 id 到 `LlmModelBadge` 的映射。优先使用 `resolveListedCatalog` 从已解码的列表条目构造该结果。
+5. 构造 `ModelSelectInjected` 的代码必须通过所属的 locale 服务提供 `resolveText: text => ctx.locale.resolveText(text)`。明确使用英语渲染的测试替身可以使用 `text => typeof text === 'string' ? text : text.en`。
+6. 下一次刷新后，确认已打开的模型选择器无需重新加载页面就显示当前角标。移除角标字段或将其设为 `null` 即可清除角标。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.4/reasoning-body-props/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.4/reasoning-body-props/guide.md
+/:
+  en: ec5a417eaedb6661
+  zh: b5adde6bf6c32fd0
+/reasoning-body-slot-text-fields:
+  en: ea09fc75b8c4467e
+  zh: 64d548cbdb42792a
+/reasoning-body-slot-text-fields/change:
+  en: ff40c45f886d47f5
+  zh: 18d7bb5456b048e6
+/reasoning-body-slot-text-fields/migration:
+  en: 49cd6281b4aef73a
+  zh: 6bdf66c3f82bfa8b