dsh-plugin-dev-kb 1.6.0 → 1.8.0

package/kb/extra/upgrade-guide/v0.2.1-alpha.2/plugin-manager-view-fields/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "@deepseek-ai/dsh-plugin-manager/operations 的 viewProfilePackage 需要传入它打印的清单字段。"
+---
+
+# `viewProfilePackage` 接收它打印的字段
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-plugin-manager/operations` 的 `viewProfilePackage(dir, spec, options)` 原先打印固定的字段列表：`name`、`version`、`description` 与 `dsh`。`PackageViewOptions` 现在要求 `fields`，即 `pnpm view` 打印的清单或注册表字段，使同一查询可以读取版本列表和各版本的 peer。直接调用 `viewProfilePackage` 的代码缺少 `fields` 时无法通过类型检查，省略它的 JavaScript 调用方会让 `pnpm view` 不带字段运行。
+
+## 迁移
+
+1. 传入调用原先打印的字段：
+
+   ```ts
+   import { viewProfilePackage } from '@deepseek-ai/dsh-plugin-manager/operations'
+
+   declare const dir: string, spec: string, timeoutMs: number
+   await viewProfilePackage(dir, spec, { fields: ['name', 'version', 'description', 'dsh'], timeoutMs })
+   ```
+
+2. 运行类型检查；缺少 `fields` 属性的每处调用都会被报告。

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/model-switch-compaction/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "Automatic model switches require a valid destination pressure budget and successful compaction."
+---
+
+# Model switches check destination context pressure
+
+English | [中文](guide.zh.md)
+
+## Change
+
+With `compaction-basic` automatic mode enabled, a provider/model switch now checks destination pressure before recording the new request header. Previously, proactive pressure checks used the last committed route and warned on configuration or summary failure. A switch now fails with `MODEL_SWITCH_COMPACTION_FAILED` when destination capacity cannot be resolved, its pressure budget is invalid, or compaction cannot reduce history below its threshold. This also affects short conversations with invalid destination budgets. Completed pruning and earlier checkpoints remain; the previous request header is preserved.
+
+## Migration
+
+1. Ensure every selectable route has a registered adapter whose `resolveModelInfo()` declares `context.contextWindow`. For middleware-owned routes without this metadata, expose the capacity through an adapter or use `auto: false` for manual-only compaction; this also disables automatic pressure and overflow recovery.
+
+2. For small windows, configure `headroomTokens` in `cordis.yml` under the exact provider/model policy. The default is 65,536 tokens and must fit alongside the routed request's output reservation. For a 65,536-token window with a 4,096-token request output cap, this policy leaves a positive pressure budget:
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-compaction-basic'
+     config:
+       modelPolicies:
+         - provider: local
+           model: small-context
+           headroomTokens: 4096
+           maxTokens: 4096
+   ```
+
+3. Replace `local` and `small-context` with the registered route. The policy's `maxTokens` caps summary output; the destination request's own output cap is separate. Keep the resolved retained budget below the trigger. Switch once with short history to verify configuration, then with long history to verify condensation. If the switch fails, correct the reported cause and retry, or choose a larger model. See the [package configuration reference](../../../../packages/compaction/compaction-basic/README.md#use-this-package).

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/model-switch-compaction/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "自动模型切换要求有效的目标压力预算与成功的压缩。"
+---
+
+# 模型切换检查目标上下文压力
+
+[English](guide.md) | 中文
+
+## 变更
+
+启用 `compaction-basic` 自动模式时，提供方／模型切换会在记录新请求 header 前检查目标压力。此前，主动压力检查使用上次已提交路由，并对配置或摘要失败记录警告。现在，无法解析目标容量、压力预算无效或压缩无法将历史降至阈值以下时，切换会以 `MODEL_SWITCH_COMPACTION_FAILED` 失败。这也影响目标预算无效的短会话。已完成的剪枝与之前的检查点仍保留；先前请求 header 也保持不变。
+
+## 迁移
+
+1. 确保每个可选路由都有已注册的适配器，且其 `resolveModelInfo()` 声明了 `context.contextWindow`。对于缺少此元数据的中间件路由，通过适配器暴露容量，或设置 `auto: false` 仅使用手动压缩；这也会关闭自动压力压缩与溢出恢复。
+
+2. 对于小窗口，在 `cordis.yml` 的精确提供方／模型策略下配置 `headroomTokens`。默认值为 65,536 token，必须与路由请求的输出预留共同适配窗口。对于 65,536 token 窗口与 4,096 token 的请求输出上限，下列策略会留下正数压力预算：
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-compaction-basic'
+     config:
+       modelPolicies:
+         - provider: local
+           model: small-context
+           headroomTokens: 4096
+           maxTokens: 4096
+   ```
+
+3. 将 `local` 与 `small-context` 替换为已注册路由。策略的 `maxTokens` 限制摘要输出；目标请求自身的输出上限单独设置。解析后的保留预算必须低于触发阈值。先用短历史切换一次以验证配置，再用长历史验证压缩。切换失败时，修正所报原因后重试，或选择更大的模型。详见[包配置参考](../../../../packages/compaction/compaction-basic/README.zh.md#use-this-package)。

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/session-model-selection/guide.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Session model choices are fixed at step preparation, and projection types move to their owning package."
+---
+
+# Session model selection applies at the next step
+
+English | [中文](guide.zh.md)
+
+## Change
+
+ACP model and reasoning changes take effect at the next model step, including a tool continuation in the current turn. Previously, ACP pinned the selection for the complete prompt turn. A prepared step and its retries retain their captured selection. Image admission checks the route selected when admission begins; a later option change can select a different route before the step starts.
+
+`AgentLoop` owns the durable `modelSelection` projection and constructs an `AgentModel` instance on each Agent’s `model` property. The API Session controller no longer registers it. Programmatic resume restores recorded choices, including unused selections, before falling back to `AgentOptions`. Configured Agent-loop resumes, headless adoption, and SDK resume record their deployment route; an omitted effort preserves saved explicit effort only for the same route.
+
+Plugins must select provider, model, and optional explicit reasoning effort before prompt assembly. `agent/request` is deprecated. Existing listeners still run on each main-loop request attempt and can adjust other controls, but cannot change provider or model, or add, change, or clear reasoning effort. Absent effort still resolves through adapter defaults on each attempt. Auxiliary calls such as compaction do not dispatch this event. `installModelSelection` now installs only the switch-notice listener; its selection argument and `ModelSelectionRef` are removed.
+
+The client projection and Host state types move to `dsh-agent/types`; the API package no longer exports them.
+
+## Migration
+
+1. In custom Cordis compositions, mount `dsh-session-projection` with `dsh-agent-loop`. The loop constructs `agent.model`; consumers need no separate model-selection service.
+2. Replace mutable references and selection hooks with `agent.model.select(selection)` after validation. Read with `current()`. Keep `installModelSelection(agentCtx)` in Agent setup for switch notices and remove its old selection argument. Do not add `agent/request` listeners.
+3. Set the output cap through `AgentOptions.maxTokens`. Other per-request control overrides have no replacement API; retain an existing listener where that behavior is still required.
+4. To override a saved route during programmatic resume, merge the configured selection with the saved explicit effort only when the route is unchanged and the configuration omits effort, then call `agent.model.select(selection)` in the Agent setup callback. Supplying `agentOptions` alone provides only a fallback for a Session without a selection or request.
+5. Pass the captured `Readonly<ModelSelection>` in `agent/pre-step.modelSelection`, including explicit effort when selected; `AssembleContext.modelSelection` carries the same selection. Direct `SessionReferenceResolver.prepare()` callers pass the route as the fourth argument, before the optional signal.
+6. ACP controllers that require one model throughout a turn must wait for the active prompt to finish before changing its options. Verify that a mid-turn change is recorded as `model/selection`, the next step uses it, and resume retains an unused choice.
+7. Import `ModelSelectionProjection` from `@deepseek-ai/dsh-agent/types`, replacing API package aliases. `ModelSelection` remains in `dsh-agent/types`. Import `ModelSelectionProjectionState` from `@deepseek-ai/dsh-agent` only when implementing a driver; ordinary reads use `agent.model.current()`. Effort values use `ReasoningEffortId` from `dsh-llm/brand`.

package/kb/extra/upgrade-guide/v0.2.1-alpha.4/session-model-selection/guide.zh.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Session 模型选择在步骤准备时固定，投影类型移至其所属包。"
+---
+
+# Session 模型选择从下一个步骤开始生效
+
+[English](guide.md) | 中文
+
+## 变更
+
+ACP（Agent Client Protocol）的模型与推理强度变更从下一个模型步骤开始生效，包括当前轮次的工具后续步骤。此前，ACP 会在整个提示词轮次中固定选择。已准备的步骤及其重试保留捕获的选择。图片准入检查准入开始时选择的路由；后续选项变更可能在步骤开始前选中另一条路由。
+
+`AgentLoop` 拥有持久 `modelSelection` 投影，并为每个 Agent 的 `model` 属性构建一个 `AgentModel` 实例。API Session 控制器不再注册该投影。程序化恢复优先还原记录中的选择，包括尚未使用的选择，然后才回退到 `AgentOptions`。配置式 Agent-loop 恢复、headless 接管与 SDK 恢复会记录各自的部署路由；省略推理强度时，仅在路由相同的情况下保留已保存的显式强度。
+
+插件必须在提示词组装前选定提供方、模型及可选的显式推理强度。`agent/request` 已弃用。现有监听器仍在主循环的每次请求尝试中运行，可以调整其他控制参数，但不能改变提供方或模型，也不能添加、修改或清除推理强度。未指定的强度仍在每次尝试时通过适配器默认值解析。压缩等辅助调用不会分发该事件。`installModelSelection` 现在只安装切换提示监听器；其选择参数与 `ModelSelectionRef` 已移除。
+
+客户端投影与 Host 状态类型移至 `dsh-agent/types`；API 包不再导出这些类型。
+
+## 迁移
+
+1. 在自定义 Cordis 组合中将 `dsh-session-projection` 与 `dsh-agent-loop` 一起挂载。循环构建 `agent.model`；消费方不需要独立的模型选择服务。
+2. 将可变引用与选择 hook 替换为校验后的 `agent.model.select(selection)`，使用 `current()` 读取选择。在 Agent setup 中保留 `installModelSelection(agentCtx)` 以提供切换提示，并移除原来的选择参数。不要添加 `agent/request` 监听器。
+3. 通过 `AgentOptions.maxTokens` 设置输出上限。其他逐请求控制参数覆盖没有替代 API；仍需要该行为时，保留现有监听器。
+4. 要在程序化恢复时覆盖已保存路由，先形成配置选择，仅在路由不变且配置省略强度时保留已保存的显式强度，再在 Agent setup 回调中调用 `agent.model.select(selection)`。仅提供 `agentOptions` 时，它只为没有选择或请求记录的 Session 提供回退值。
+5. 通过 `agent/pre-step.modelSelection` 传入捕获的 `Readonly<ModelSelection>`，包含已选定的显式强度；`AssembleContext.modelSelection` 携带同一选择。直接调用 `SessionReferenceResolver.prepare()` 时，将路由作为第四个参数，放在可选信号之前。
+6. 要求整轮使用同一个模型的 ACP 控制器，必须等待活跃提示词完成后再更改选项。验证轮次中的变更被记录为 `model/selection`、下一个步骤使用该选择，且恢复保留尚未使用的选择。
+7. 从 `@deepseek-ai/dsh-agent/types` 导入 `ModelSelectionProjection`，替换 API 包别名。`ModelSelection` 仍位于 `dsh-agent/types`。仅在实现驱动器时从 `@deepseek-ai/dsh-agent` 导入 `ModelSelectionProjectionState`；普通读取使用 `agent.model.current()`。强度值使用 `dsh-llm/brand` 中的 `ReasoningEffortId`。

package/kb/extra/upgrade-guide/v0.2.1-rc.1/agent-instructions-chain-budgets/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "The maxBytes budget of @deepseek-ai/dsh-agent-instructions caps each instruction chain separately, so a baseline holding both chains can reach twice the configured size."
+---
+
+# Size `maxBytes` of `@deepseek-ai/dsh-agent-instructions` per instruction chain
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`maxBytes` of `@deepseek-ai/dsh-agent-instructions` bounded the complete workspace-instruction baseline and each reconciliation message. It now bounds the user-global chain (`$DSH_HOME/AGENTS.md` and the shared agents root) and the project chain separately, so a message holding both chains can reach twice the configured size. The exported `loadBaselineInstructions` and `renderAgentInstructions` follow the same bound. Deployments that sized `maxBytes` as a total prompt budget observe the larger maximum.
+
+## Migration
+
+1. When the old total must hold, halve `maxBytes` in the `@deepseek-ai/dsh-agent-instructions` row of the deployment's `cordis.yml` or patch; `dsh-base` keeps `65536`. `maxBytes` is part of the baseline identity, so every session resumed after the change receives one complete replacement baseline.
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-agent-instructions'
+     config:
+       maxBytes: 32768
+   ```
+
+2. Start a new session and read the first `user/message` whose `source.kind` is `agent-instructions` in its session log: its text stays within twice `maxBytes`, and a `Workspace instruction budget ...` line names every omitted or truncated file.

package/kb/extra/upgrade-guide/v0.2.1-rc.1/agent-instructions-chain-budgets/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "@deepseek-ai/dsh-agent-instructions 的 maxBytes 分别限制每条指令链，因此同时包含两条链的基线最多可达配置值的两倍。"
+---
+
+# 按指令链设定 `@deepseek-ai/dsh-agent-instructions` 的 `maxBytes`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-agent-instructions` 的 `maxBytes` 原先限制完整的工作区指令基线和每条对账消息。现在它分别限制用户全局指令链（`$DSH_HOME/AGENTS.md` 与共享 agents 根目录）和项目指令链，因此同时包含两条链的消息最多可达配置值的两倍。导出的 `loadBaselineInstructions` 与 `renderAgentInstructions` 遵循同一上限。把 `maxBytes` 当作总提示词预算设定的部署会看到更大的上限。
+
+## 迁移
+
+1. 若仍须遵守原来的总量，在部署的 `cordis.yml` 或 patch 中 `@deepseek-ai/dsh-agent-instructions` 配置行里把 `maxBytes` 减半；`dsh-base` 保持 `65536`。`maxBytes` 属于基线标识，因此修改后恢复的每个会话都会收到一次完整的替代基线。
+
+   ```yaml
+   - name: '@deepseek-ai/dsh-agent-instructions'
+     config:
+       maxBytes: 32768
+   ```
+
+2. 启动新会话，在其会话日志中读取第一条 `source.kind` 为 `agent-instructions` 的 `user/message`：其文本不超过 `maxBytes` 的两倍，且一行 `Workspace instruction budget ...` 会指名所有被省略或截断的文件。

package/kb/extra/upgrade-guide/v0.2.1-rc.1/subagent-control-tools/guide.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: Custom subagent compositions must update model-selection settings and register discovery through main entries.
+---
+
+# Update subagent model selection and control tools
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-tool-subagent` replaces `modelSelectionSettings` with `modelSelection`, which controls optional child route fields. Discovery requires `modelDiscovery: true` on one instance per tool scope. Both options default to false. The package has no `/list-models` plugin export. Shipped Web and Desktop presets enable both options on spawn and keep fork route fields disabled; custom fork tools may enable selection. Headless, SDK, and ACP defaults retain their tool sets.
+
+The Host `/model-selection-settings` service records authorization during Agent creation, including Sessions created before delegation tools are mounted. Child Sessions inherit the policy, restored Sessions preserve it, and later tool installation or settings edits do not resample existing Sessions. Without a recorded policy, discovery and explicit selection permit only the current parent route. Enabling the Host setting with an empty allowed-model list rejects every fresh top-level Session, even without delegation tools; the settings UI prevents saving that combination.
+
+`@deepseek-ai/dsh-tool-subagent-control` registers `send_message`, `interrupt_agent`, and `list_agents` together and requires `tools`, `subagents`, and `agents`. Its separate `/list-agents` export is removed. Model discovery follows its configured delegation-tool instance’s lifetime, independently of the delegation provider; unloading that instance removes discovery even if other instances remain. Discovery calls fail if `llm` is unavailable.
+
+## Migration
+
+1. In custom `cordis.yml`, patches, or direct plugin configuration, rename `modelSelectionSettings: true` to `modelSelection: true`. Set `modelDiscovery: true` on one delegation instance per tool scope that needs `list_subagent_models`; multiple discovery owners in one scope fail registration.
+2. Mount `@deepseek-ai/dsh-tool-subagent/model-selection-settings` in the Host before creating Agents when custom compositions need user-authorized alternative routes. Supply its required `sessions` and `sessionProjections` services. If its setting is enabled, supply a non-empty allowed-model list. Direct `apply(ctx, config)` callers no longer pass a Session argument.
+3. Replace `/list-agents` rows with one `@deepseek-ai/dsh-tool-subagent-control` row per tool scope, or remove them if that row already exists. Remove patches targeting the retired `tool-subagent-list-agents` row. Disabling the shared control row now disables all three tools; use tool restrictions to hide individual tools.
+4. Create a fresh Session and verify one definition of each requested tool. Discovery must return authorized routes when the preference is enabled, or only the parent route otherwise; explicit unauthorized delegation must fail. Unload the discovery-owning instance and verify that its discovery tool disappears.

package/kb/extra/upgrade-guide/v0.2.1-rc.1/subagent-control-tools/guide.zh.md

@@ -0,0 +1,23 @@
+---
+kind: upgrade-guide
+description: 自定义 subagent 组合必须更新模型选择配置，并通过主入口注册发现工具。
+---
+
+# 更新 subagent 模型选择与控制工具
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-tool-subagent` 将 `modelSelectionSettings` 替换为 `modelSelection`，用于控制可选子级路由字段。发现功能要求每个工具作用域的一个实例设置 `modelDiscovery: true`。两个选项均默认 false。该包不导出 `/list-models` 插件。随附 Web 与 Desktop preset 为 spawn 启用两个选项，并为 fork 保持路由字段关闭；自定义 fork 工具可以启用选择。headless、SDK 和 ACP 的默认工具集保持不变。
+
+Host 的 `/model-selection-settings` 服务在 Agent（智能体）创建时记录授权，包括在委派工具挂载前创建的 Session。子 Session 继承策略，恢复的 Session 保留策略，之后安装工具或编辑设置均不会重新采样已有 Session。没有已记录策略时，发现和显式选择只允许当前父级路由。Host 设置启用但允许模型列表为空时，会拒绝创建所有新的顶层 Session，即使未挂载委派工具；设置界面不允许保存这种组合。
+
+`@deepseek-ai/dsh-tool-subagent-control` 一起注册 `send_message`、`interrupt_agent` 和 `list_agents`，要求 `tools`、`subagents` 和 `agents`。独立的 `/list-agents` 导出已移除。模型发现随配置该选项的委派工具实例存续，与委派提供方无关；卸载该实例会移除发现，即使其他实例仍然存在。`llm` 不可用时，发现调用会失败。
+
+## 迁移
+
+1. 在自定义 `cordis.yml`、patch 或直接插件配置中，将 `modelSelectionSettings: true` 改为 `modelSelection: true`。在每个需要 `list_subagent_models` 的工具作用域中，为一个委派实例设置 `modelDiscovery: true`；同一作用域的多个发现工具所有者会注册失败。
+2. 自定义组合需要用户授权其他路由时，在创建 Agent 前将 `@deepseek-ai/dsh-tool-subagent/model-selection-settings` 挂载到 Host，并提供必需的 `sessions` 和 `sessionProjections` 服务。设置启用时，须提供非空的允许模型列表。直接调用 `apply(ctx, config)` 时不再传入 Session 参数。
+3. 将 `/list-agents` 配置行替换为每个工具作用域一条 `@deepseek-ai/dsh-tool-subagent-control`，已有该行时则删除它们。移除针对已停用的 `tool-subagent-list-agents` 行的 patch。禁用共享控制行现在会禁用全部三个工具；使用工具限制隐藏单个工具。
+4. 创建新 Session，确认所需工具各有一份定义。用户偏好启用时，发现必须返回授权路由，否则仅返回父级路由；显式选择未授权路由的委派必须失败。卸载负责发现的实例，确认其发现工具消失。

package/kb/extra/upgrade-guide/v0.2.1-rc.2/agent-runtime-owner/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Agent creation and resume options rename parentAgent to ownerAgent for runtime ownership."
+---
+
+# Agent runtime ownership uses `ownerAgent`
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`CreateAgentOptions` and `ResumeAgentOptions` in `@deepseek-ai/dsh-agent` replace `parentAgent` with `ownerAgent`. This affects plugins and custom factories calling `ctx.agents.create()` or `ctx.agents.resume()`. The field selects the live Agent that owns the runtime instance; omitting it creates a runtime root.
+
+Session creation lineage remains in `meta.parentSession`. For a nested subagent, the runtime owner can be the tree root while the direct creator is another descendant. Persisted Session fields and formats are unchanged.
+
+## Migration
+
+1. Rename the `parentAgent` option to `ownerAgent` in creation and resume calls, and update custom `AgentFactory` implementations that read or forward it. Pass the same Agent as before.
+2. Keep `meta.parentSession` and stored `parentSession` values unchanged. Do not substitute the runtime owner for the direct creator.
+3. Typecheck consumers against the updated package, then verify that `ctx.agents.isOwnedBy(id, owner)` and `ctx.agents.roots()` report the same runtime relationships after creation and resume.

package/kb/extra/upgrade-guide/v0.2.1-rc.2/agent-runtime-owner/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "Agent 创建和恢复选项将表示运行归属的 parentAgent 改名为 ownerAgent。"
+---
+
+# Agent 运行归属使用 `ownerAgent`
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-agent` 中的 `CreateAgentOptions` 和 `ResumeAgentOptions` 将 `parentAgent` 替换为 `ownerAgent`。这影响调用 `ctx.agents.create()` 或 `ctx.agents.resume()` 的插件与自定义工厂。该字段指定拥有运行实例的在线 Agent；省略时创建运行时根。
+
+Session 创建来源仍由 `meta.parentSession` 记录。嵌套子代理的运行归属者可以是树根，而直接创建者是另一个后代。持久化 Session 字段和格式保持不变。
+
+## 迁移
+
+1. 将创建和恢复调用中的 `parentAgent` 选项改名为 `ownerAgent`，并更新读取或透传该字段的自定义 `AgentFactory` 实现。继续传入原来的 Agent。
+2. 保持 `meta.parentSession` 和存储的 `parentSession` 值不变。不要用运行归属者替换直接创建者。
+3. 针对更新后的包对消费者运行类型检查，再验证创建和恢复后的 `ctx.agents.isOwnedBy(id, owner)` 与 `ctx.agents.roots()` 仍报告相同的运行归属关系。

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