dsh-primer 0.4.3 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/cordis-timer-wrappers/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Timer wrappers return void in TypeScript and ignore calls after disposal."
+---
+
+# Timer wrapper return types and disposal
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The functions returned by `ctx.throttle()` and `ctx.debounce()` now declare a `void` return type. They previously inherited the callback's return type, although they already returned `undefined` at runtime. TypeScript code that uses the wrapper's return value or assigns it to the callback's type may need updating. Host and browser use the same `TimerService` implementation.
+
+Calling `.dispose()` or disposing the owning fiber cancels pending work and makes later wrapper calls inert. A disposed throttle wrapper previously could still execute a leading call; debounce wrappers already ignored calls after disposal.
+
+The `@deepseek-ai/dsh-cordis-client-runner/client` entry no longer exports `ClientTimerService`. The runner installs the shared `TimerService` from `@deepseek-ai/cordis-plugin-timer`.
+
+## Migration
+
+1. Let TypeScript infer the wrapper type, or declare its call signature with a `void` return type while retaining `.dispose()` where needed.
+2. Consume callback results inside the callback. Awaiting the wrapper does not wait for an asynchronous callback to finish.
+3. Move required work before disposal, or create a new wrapper in an active plugin.
+4. Remove imports of `ClientTimerService` from the runner. Consumer plugins declare `inject: ['timer']` and use `ctx.timer`; code that installs the service imports `TimerService` from `@deepseek-ai/cordis-plugin-timer`.
+5. Run your extension's type check and verify that calls after disposal neither invoke the callback nor schedule work.

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/cordis-timer-wrappers/guide.zh.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Timer 包装函数的 TypeScript 返回类型为 void，释放后忽略后续调用。"
+---
+
+# Timer 包装函数的返回类型与资源释放
+
+[English](guide.md) | 中文
+
+## 变更
+
+`ctx.throttle()` 和 `ctx.debounce()` 返回的函数现在声明 `void` 返回类型。此前这些函数继承回调的返回类型，但运行时已经返回 `undefined`。使用包装函数返回值或将包装函数赋给回调类型的 TypeScript 代码可能需要更新。Host 与浏览器使用同一份 `TimerService` 实现。
+
+调用 `.dispose()` 或释放所属 fiber 会取消待执行的工作，并使后续包装函数调用不再执行。此前已释放的 throttle 包装函数仍可能执行前沿调用；debounce 包装函数在释放后已经会忽略调用。
+
+`@deepseek-ai/dsh-cordis-client-runner/client` 入口不再导出 `ClientTimerService`。runner 安装的是 `@deepseek-ai/cordis-plugin-timer` 中的共享 `TimerService`。
+
+## 迁移
+
+1. 让 TypeScript 推断包装函数的类型，或将其调用签名声明为返回 `void`，并按需保留 `.dispose()`。
+2. 在回调内部使用回调结果。对包装函数使用 await 不会等待异步回调完成。
+3. 将必须执行的工作移到资源释放之前，或在活动插件中创建新的包装函数。
+4. 移除从 runner 导入 `ClientTimerService` 的代码。消费插件声明 `inject: ['timer']` 并使用 `ctx.timer`；负责安装服务的代码从 `@deepseek-ai/cordis-plugin-timer` 导入 `TimerService`。
+5. 运行扩展的类型检查，并验证释放后的调用既不会执行回调，也不会安排工作。

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/plugin-manager-view-fields/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-alpha.2/plugin-manager-view-fields/guide.md
+/:
+  en: ce2254ec04c7e121
+  zh: d41be1b049886b05
+/viewprofilepackage-takes-the-fields-it-prints:
+  en: 2b42139fb8291351
+  zh: 142078b83eec688c
+/viewprofilepackage-takes-the-fields-it-prints/change:
+  en: 72177a0fbf9d18de
+  zh: 0e689154933a6174
+/viewprofilepackage-takes-the-fields-it-prints/migration:
+  en: 7107ae7573558a60
+  zh: 17c4428c0e83a842

package/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.2/plugin-manager-view-fields/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "viewProfilePackage from @deepseek-ai/dsh-plugin-manager/operations requires the manifest fields it prints."
+---
+
+# `viewProfilePackage` takes the fields it prints
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`viewProfilePackage(dir, spec, options)` from `@deepseek-ai/dsh-plugin-manager/operations` used to print a fixed field list: `name`, `version`, `description`, and `dsh`. `PackageViewOptions` now requires `fields`, the manifest or registry fields `pnpm view` prints, so the same lookup reads version lists and per-version peers. Code that calls `viewProfilePackage` directly no longer type-checks without `fields`, and a JavaScript caller that omits it runs `pnpm view` with no fields.
+
+## Migration
+
+1. Pass the fields the call used to print:
+
+   ```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. Run your type checker; a missing `fields` property is reported at each call.

package/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/model-switch-compaction/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-alpha.4/model-switch-compaction/guide.md
+/:
+  en: 830f003296555f6f
+  zh: a83508af05b217ff
+/model-switches-check-destination-context-pressure:
+  en: 7d11a333984b08b7
+  zh: 93f0d5f2c309253d
+/model-switches-check-destination-context-pressure/change:
+  en: 613c81a294809de3
+  zh: 6a8747f2f326c390
+/model-switches-check-destination-context-pressure/migration:
+  en: c17dc3c452145b02
+  zh: 9a905067e047e275

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-alpha.4/session-model-selection/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-alpha.4/session-model-selection/guide.md
+/:
+  en: 3890f393c1af5500
+  zh: 64fce473a9f35fae
+/session-model-selection-applies-at-the-next-step:
+  en: ac99540fa45af789
+  zh: 68b33ea8d0063615
+/session-model-selection-applies-at-the-next-step/change:
+  en: 5ab837106ca3bd0c
+  zh: 5a6d2e65f3cdb191
+/session-model-selection-applies-at-the-next-step/migration:
+  en: bf4f6d902cfe5a78
+  zh: f19cb24e45d50dc4

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.1/agent-instructions-chain-budgets/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.1/agent-instructions-chain-budgets/guide.md
+/:
+  en: a4f7c0355dfc799f
+  zh: 7fba904f2c771d26
+/size-maxbytes-of-deepseek-ai-dsh-agent-instructions-per-instruction-chain:
+  en: 32a1e5663b3ddc28
+  zh: 2f2bdb9dbc72449a
+/size-maxbytes-of-deepseek-ai-dsh-agent-instructions-per-instruction-chain/change:
+  en: 852972af8ae3b10b
+  zh: 984774781a0233bc
+/size-maxbytes-of-deepseek-ai-dsh-agent-instructions-per-instruction-chain/migration:
+  en: 45737c7f5e7534ea
+  zh: 46ac35baa76b850a

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.1/subagent-control-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.1/subagent-control-tools/guide.md
+/:
+  en: d97a8cf3403991bf
+  zh: 7ef3622f752de926
+/update-subagent-model-selection-and-control-tools:
+  en: 94241cbd81231955
+  zh: 0e1b5032ce228b57
+/update-subagent-model-selection-and-control-tools/change:
+  en: 365ba74eca3f90da
+  zh: 177b74ef9933cee4
+/update-subagent-model-selection-and-control-tools/migration:
+  en: a249dd8e8f91c5e4
+  zh: 88b2a33be42ad258

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/agent-runtime-owner/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/agent-runtime-owner/guide.md
+/:
+  en: ced4d23952f772d5
+  zh: f8e7e8c069266fa1
+/agent-runtime-ownership-uses-owneragent:
+  en: 8a1164f53b3627da
+  zh: 19fae50e43c4dca4
+/agent-runtime-ownership-uses-owneragent/change:
+  en: 88457ac32ffc2c7d
+  zh: 05ea7db957db119b
+/agent-runtime-ownership-uses-owneragent/migration:
+  en: d25ad901f4601369
+  zh: 96b556991249635b

package/references/official-docs/docs/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/references/official-docs/docs/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/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/agent-team-subagents/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/agent-team-subagents/guide.md
+/:
+  en: 1f073189776760d8
+  zh: cfbb0403aea96f84
+/agent-teams-uses-subagents-and-session-ids:
+  en: 703c7766dd80e1d1
+  zh: 157c67164c1cbc7d
+/agent-teams-uses-subagents-and-session-ids/change:
+  en: d387c95a87d1bd6a
+  zh: 69dd000fbff0b6fa
+/agent-teams-uses-subagents-and-session-ids/migration:
+  en: dcc698d29a4677f0
+  zh: 2af5cea905ad4371