dsh-primer 0.4.4 → 0.4.5

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-model-catalog/guide.zh.md

@@ -0,0 +1,53 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 目录移除了部分模型 ID，并降低了部分模型容量。"
+---
+
+# pi-ai 1.3.0 模型目录变更
+
+[English](guide.md) | 中文
+
+## 变更
+
+pi-ai 依赖从 1.1.0 升级到 1.3.0。以下聊天模型 ID 不再包含在目录中。已保存的 `modelOverrides` 会报告目录条目缺失诊断；新的覆盖配置会被拒绝。显式 `models` 条目会失去目录默认值。
+
+| 提供商 | 已移除的模型 ID |
+|---|---|
+| `google-vertex` | `gemini-flash-latest`, `gemini-flash-lite-latest` |
+| `nvidia` | `moonshotai/kimi-k3`, `nvidia/nemotron-3-super-120b-a12b` |
+| `opencode` | `exo-free`, `fledge-alpha-free`, `ling-3.0-flash-fin-free`, `ling-3.1-flash-free` |
+| `opencode-go` | `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`, `grok-4.6`, `minimax-m2.7` |
+| `openrouter` | `anthropic/claude-sonnet-4`, `apodex/apodex-1.1-mini:free`, `inclusionai/ling-3.0-flash-fin`, `inclusionai/ling-3.0-flash-sante:free`, `qwen/qwen-plus-2025-07-28`, `qwen/qwen3-235b-a22b`, `qwen/qwen3-30b-a3b-thinking-2507`, `qwen/qwen3-8b`, `qwen/qwen3-coder-plus`, `qwen/qwen3-max`, `qwen/qwen3-max-thinking`, `qwen/qwen3-vl-235b-a22b-thinking`, `qwen/qwen3-vl-32b-instruct`, `qwen/qwen3-vl-8b-thinking`, `qwen/qwen3.6-max-preview`, `sao10k/l3.1-euryale-70b`, `unbiased/pareto`, `unbiased/pareto-26.10-preview` |
+| `vercel-ai-gateway` | `alibaba/qwen-3.6-max-preview`, `alibaba/qwen3-235b-a22b-thinking`, `alibaba/qwen3-coder-plus`, `alibaba/qwen3-max`, `alibaba/qwen3-max-preview`, `alibaba/qwen3-vl-235b-a22b-instruct`, `alibaba/qwen3-vl-thinking`, `anthropic/claude-3-haiku`, `anthropic/claude-opus-4`, `inclusionai/ling-3.1-flash-free` |
+
+以下目录限制降低。数值以 token 为单位；`—` 表示该限制未降低。显式覆盖值仍然优先。`maxTokens` 描述模型容量，不是隐式的请求限制。
+
+| 提供商/模型 | 新 contextWindow / maxTokens |
+|---|---|
+| `anthropic/claude-sonnet-4-5` | 200000 / — |
+| `anthropic/claude-sonnet-4-5-20250929` | 200000 / — |
+| `openrouter/deepseek/deepseek-v4-flash` | 1048575 / 943717 |
+| `openrouter/inclusionai/ling-3.0-flash-vl` | 131072 / — |
+| `openrouter/meta-llama/llama-4-scout` | 131072 / — |
+| `openrouter/minimax/minimax-m2` | — / 131072 |
+| `openrouter/minimax/minimax-m2.5` | 198000 / 32768 |
+| `openrouter/minimax/minimax-m2.7` | — / 131072 |
+| `openrouter/moonshotai/kimi-k2-thinking` | — / 98304 |
+| `openrouter/nvidia/nemotron-3-ultra-550b-a55b` | 202800 / — |
+| `openrouter/openai/gpt-oss-120b` | — / 65536 |
+| `openrouter/qwen/qwen3-235b-a22b-thinking-2507` | 128000 / 16384 |
+| `openrouter/qwen/qwen3.5-35b-a3b` | 256000 / 16384 |
+| `openrouter/qwen/qwen3.8-2.4t-a95b` | 1000000 / — |
+| `openrouter/qwen/qwen3.8-27b` | 262144 / — |
+| `openrouter/~z-ai/glm-latest` | — / 131072 |
+| `radius/claude-sonnet-4-5` | 200000 / — |
+| `vercel-ai-gateway/alibaba/qwen3-coder` | — / 32768 |
+| `vercel-ai-gateway/deepseek/deepseek-v4.1-flash-fast` | — / 32768 |
+
+`vercel-ai-gateway` 的 `alibaba/qwen-3-235b` 模型现在被声明为非推理模型。协议与推理强度变更见[单独的指南](../pi-ai-protocol-replay/guide.zh.md)。
+
+## 迁移
+
+1. 在“设置 → 模型”中，将已移除的 ID 替换为受支持的模型。检查端点、能力和价格；ID 没有自动替代项。
+2. 更新 `cordis.patch.yml`、preset patch 和受影响 Session 中的模型选择。移除过时的 `providers.<provider>.modelOverrides.<id>` 条目，并替换 `providers.<provider>.models` 列表中已移除的 ID。参见[配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。
+3. 根据端点支持的值检查容量与推理覆盖配置。启动 profile，确认模型没有配置诊断，再发送一个简短提示。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-protocol-replay/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/pi-ai-protocol-replay/guide.md
+/:
+  en: 1e2bdc1e7e35ea20
+  zh: 503fcf05bceec218
+/pi-ai-1-3-0-protocol-and-replay-changes:
+  en: c59f3b45f3ab51cd
+  zh: 34363c450eb55190
+/pi-ai-1-3-0-protocol-and-replay-changes/change:
+  en: 308406476f8470f0
+  zh: ecb22ad91d460769
+/pi-ai-1-3-0-protocol-and-replay-changes/migration:
+  en: 24c50a0f234a7ee8
+  zh: 6ac8b31f88d22c37

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-protocol-replay/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 changes provider protocols, reasoning choices, history replay, and invalid tool-argument handling."
+---
+
+# pi-ai 1.3.0 protocol and replay changes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The pi-ai upgrade from 1.1.0 to 1.3.0 changes these defaults. Explicit profile overrides still win.
+
+| Route or behavior | New behavior |
+|---|---|
+| `kimi-coding` | Uses `openai-completions` at `https://api.kimi.com/coding/v1` instead of `anthropic-messages` at `/coding` |
+| `opencode`, `opencode-go` | Endpoints replace `/zen` with `/inference`; `/go` and `/v1` suffixes remain model-specific |
+| Xiaomi MiMo catalogs, including token-plan routes | Offer only `off` and `high` reasoning |
+| `kimi-coding/kimi-for-coding-highspeed` | Does not offer reasoning `off` |
+| Assistant reasoning history | Outgoing requests omit thinking from another provider, API, or model instead of converting it to text; degraded replay without native metadata also omits thinking |
+| Invalid completed tool arguments | The attempt fails with `MALFORMED_RESPONSE`; it executes no tools and publishes no successful replay state. The default normal retry policy excludes this code |
+
+Stored history is retained. Returning to the original model restores its valid native replay metadata. Output truncated by the token limit still drops incomplete tool calls and can continue normally. Credentials do not require migration.
+
+## Migration
+
+1. Review `providers.<provider>.baseURL`, `api`, and `compat` overrides in `cordis.patch.yml`. For overrides that follow the upstream Kimi Coding endpoint, use the Completions protocol and `/v1` path. Custom gateways must explicitly retain their actual protocol and path. Update OpenCode URLs to `/inference` where applicable. Omit overrides when catalog defaults are intended.
+2. Replace unsupported reasoning selections in profiles, presets, and Sessions with a level shown by the current model metadata.
+3. Put facts needed across model changes in user messages or normal assistant replies; do not rely on prior private reasoning becoming visible text.
+4. For `MALFORMED_RESPONSE`, inspect the reported invalid arguments and correct the model or gateway output. Verify the affected route with a short prompt and a tool call. See the [configuration reference](../../../../packages/llm/llm-pi-ai/README.md).

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/pi-ai-protocol-replay/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "pi-ai 1.3.0 改变了提供方协议、推理选项、历史回放以及无效工具参数的处理方式。"
+---
+
+# pi-ai 1.3.0 协议与回放变更
+
+[English](guide.md) | 中文
+
+## 变更
+
+pi-ai 从 1.1.0 升级到 1.3.0 时改变了以下默认行为。显式 profile 覆盖值仍然优先。
+
+| 路由或行为 | 新行为 |
+|---|---|
+| `kimi-coding` | 使用 `https://api.kimi.com/coding/v1` 上的 `openai-completions`，替代 `/coding` 上的 `anthropic-messages` |
+| `opencode`、`opencode-go` | 端点将 `/zen` 替换为 `/inference`；`/go` 和 `/v1` 后缀仍由模型决定 |
+| Xiaomi MiMo 目录，包括 token-plan 路由 | 只提供 `off` 和 `high` 推理选项 |
+| `kimi-coding/kimi-for-coding-highspeed` | 不提供推理 `off` 选项 |
+| assistant 推理历史 | 发出的请求会省略来自另一提供方、API 或模型的思考，而不再将其转换为文本；缺少原生元数据的降级回放也会省略思考 |
+| 已完成调用的工具参数无效 | 本次尝试以 `MALFORMED_RESPONSE` 失败，不执行任何工具，也不发布成功的回放状态。默认的普通重试策略不重试此错误码 |
+
+存储的历史保持不变。切回原模型时会恢复其有效的原生回放元数据。达到 token 限制而截断的输出仍会丢弃未完成的工具调用，并可正常续写。凭据无需迁移。
+
+## 迁移
+
+1. 检查 `cordis.patch.yml` 中的 `providers.<provider>.baseURL`、`api` 和 `compat` 覆盖配置。对于跟随上游 Kimi Coding 端点的覆盖配置，使用 Completions 协议和 `/v1` 路径。自定义网关必须显式保留其实际协议和路径。按需将 OpenCode URL 更新为 `/inference`。若希望使用目录默认值，请省略覆盖配置。
+2. 将 profile、preset 和 Session 中不受支持的推理选项替换为当前模型元数据列出的级别。
+3. 将切换模型后仍需要的事实放入用户消息或普通 assistant 回复；不要依赖先前的私有推理转换为可见文本。
+4. 出现 `MALFORMED_RESPONSE` 时，检查诊断中的无效参数，并修正模型或网关输出。用一个简短提示和一次工具调用验证受影响的路由。参见[配置参考](../../../../packages/llm/llm-pi-ai/README.zh.md)。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/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/ptc-script-format/guide.md
+/:
+  en: 2503e2027c918185
+  zh: ffd1bf229fdfbb7d
+/handle-script-programs-and-explicit-state-retention:
+  en: 484afb11caae52a3
+  zh: e2c5e8a365845828
+/handle-script-programs-and-explicit-state-retention/change:
+  en: e8631aefd51606cd
+  zh: 39cffa3d535b903e
+/handle-script-programs-and-explicit-state-retention/migration:
+  en: 2f9132751d5be30e
+  zh: c6bc98904eff22ce

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "PTC programFormat includes Script syntax, and consumers read retainsState for cross-call memory."
+---
+
+# Handle Script programs and explicit state retention
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The published `@deepseek-ai/dsh-ptc-runtime` service widens `PtcRuntime.programFormat` from `'function-body' | 'repl'` to include `'script'`. External consumers that exhaustively match the old union must handle the new value. `retainsState` reports whether a provider preserves memory for a `stateOwner`; its base implementation returns `false`, so custom retained providers must override it.
+
+Node keeps `per-call` as its default. The opt-in `executionMode: vm-script` accepts Script statements and top-level await, with `scriptPersistence` selecting cross-call memory independently. Existing Node function-body and REPL configurations remain valid.
+
+## Migration
+
+1. Import the exported `PtcProgramFormat` from `@deepseek-ai/dsh-ptc-runtime` instead of copying its union literals. Update `programFormat` switches in custom tool or workflow adapters. Handle `'script'` using statements or a final expression, without top-level `return`; consult the [Node syntax reference](../../../../packages/ptc-runtime/ptc-runtime-node/README.md#use-this-package).
+2. Replace checks that infer memory retention from `programFormat === 'repl'` with `runtime.retainsState`. If a custom `PtcRuntime` provider retains owner-scoped memory, override `retainsState` to return `true` and continue implementing `release(owner)`.
+3. Rebuild external consumers against the new package declarations. Confirm that each supported format compiles and that persistence controls follow `retainsState` for both REPL and Script providers.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/ptc-script-format/guide.zh.md

@@ -0,0 +1,20 @@
+---
+kind: upgrade-guide
+description: "PTC programFormat 新增 Script 语法，消费者通过 retainsState 判断跨调用内存保留。"
+---
+
+# 处理 Script 程序与显式状态保留
+
+[English](guide.md) | 中文
+
+## 变更
+
+已发布的 `@deepseek-ai/dsh-ptc-runtime` 服务将 `PtcRuntime.programFormat` 从 `'function-body' | 'repl'` 扩展为包含 `'script'`。对旧联合类型做穷举匹配的外部消费者必须处理新值。`retainsState` 表示提供方是否为 `stateOwner` 保留内存；基类实现返回 `false`，因此自定义保留状态的提供方必须覆盖该 getter。
+
+Node 仍默认使用 `per-call`。显式启用的 `executionMode: vm-script` 接受 Script 语句和顶层 await，`scriptPersistence` 独立选择是否跨调用保留内存。已有 Node 函数体和 REPL 配置仍然有效。
+
+## 迁移
+
+1. 从 `@deepseek-ai/dsh-ptc-runtime` 导入已导出的 `PtcProgramFormat`，不复制其联合类型字面量。更新自定义工具或工作流适配器中的 `programFormat` 分支。使用语句或末尾表达式处理 `'script'`，不使用顶层 `return`；参见 [Node 语法参考](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md#use-this-package)。
+2. 将通过 `programFormat === 'repl'` 推断内存保留的检查改为读取 `runtime.retainsState`。自定义 `PtcRuntime` 提供方若按所有者保留内存，应覆盖 `retainsState` 并返回 `true`，同时继续实现 `release(owner)`。
+3. 使用新的包声明重新构建外部消费者。确认所有支持的格式均可编译，并且持久化控制对 REPL 和 Script 提供方都按 `retainsState` 判断。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/sdk-desktop-context/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/sdk-desktop-context/guide.md
+/:
+  en: d3cffa64b9c50498
+  zh: 515c03ce9ae6d031
+/sdk-desktop-tools-and-context:
+  en: d202616bf6e03fa4
+  zh: cc276adda4b952be
+/sdk-desktop-tools-and-context/change:
+  en: ef89799953ecb457
+  zh: 86fdb487b9a15a6f
+/sdk-desktop-tools-and-context/migration:
+  en: 9caef4f8b153622a
+  zh: 1b4901f5b18b72fd

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/sdk-desktop-context/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: The existing SDK profile includes native desktop tools and model context.
+---
+
+# SDK desktop tools and context
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The existing `sdk` profile now includes `present`, `ask_user_question`, schedule tools, file-reference guidance and time context. It does not start a Web server. Native tool execution remains the default; select PTC through an [executor overlay](../tool-executor-plugins/guide.md). `sdk-minimal` is unchanged.
+
+## Migration
+
+1. Keep selecting `sdk`. Provide `onUserQuestion` (TypeScript) or `on_user_question` (Python) to answer built-in questions over the native protocol, or retain an in-process `user-questions/request` answerer; without one, the tool reports `NO_PROVIDER`.
+2. Working directory and model still come from SDK initialization. The SDK profile does not mount the Web-specific checkout and GUI development context.
+3. Custom compositions that need the previous model-visible tool/context roster can disable the `present`, `tool-ask-user`, `tool-schedule`, `file-reference-local`, `deliverable-file-references`, and `time-context` rows. Review any pinned prompts and tool schemas before upgrading.

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

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: 现有 SDK profile 包含原生桌面工具和模型上下文。
+---
+
+# SDK 桌面工具与上下文
+
+[English](guide.md) | 中文
+
+## 变更
+
+现有 `sdk` profile 现在包含 `present`、`ask_user_question`、定时任务工具、文件引用说明和时间上下文。它不启动 Web server。默认仍使用原生工具执行；通过[执行器 overlay](../tool-executor-plugins/guide.zh.md) 选择 PTC。`sdk-minimal` 保持不变。
+
+## 迁移
+
+1. 继续选择 `sdk`。通过 `onUserQuestion`（TypeScript）或 `on_user_question`（Python）使用原生协议回答内建问题，或保留进程内的 `user-questions/request` 回答方；没有回答方时，工具报告 `NO_PROVIDER`。
+2. 工作目录和模型仍来自 SDK 初始化。SDK profile 不挂载 Web 专用的 checkout 和 GUI 开发上下文。
+3. 需要保留之前模型可见工具/上下文组合的自定义配置，可以禁用 `present`、`tool-ask-user`、`tool-schedule`、`file-reference-local`、`deliverable-file-references` 和 `time-context` 配置项。升级前请检查固定的提示词和工具 schema。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/sdk-minimal-checkpoints/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/sdk-minimal-checkpoints/guide.md
+/:
+  en: c81d35a7d1605742
+  zh: 49a149c848fdbb35
+/sdk-minimal-requires-durable-checkpoints:
+  en: a238e25e459a20cd
+  zh: 871ee52936d06b24
+/sdk-minimal-requires-durable-checkpoints/change:
+  en: 3ba980ee74955e34
+  zh: 495fe6c0dd9001bf
+/sdk-minimal-requires-durable-checkpoints/migration:
+  en: 43c3d55a0fa7a562
+  zh: f2b087fb1387b517

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/sdk-minimal-checkpoints/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "The sdk-minimal profile now stops model and tool dispatch when session persistence cannot complete a checkpoint."
+---
+
+# SDK-minimal requires durable checkpoints
+
+English | [中文](guide.zh.md)
+
+## Change
+
+The `sdk-minimal` profile enables `session-checkpoint-policy`. It waits for session history to flush before model requests, top-level tool execution, and agent steps. Previously these operations could proceed while JSONL writes were buffered; persistence errors could remain background warnings. A checkpoint failure now stops the dependent operation. First-use file-lock initialization is paid before the first model request, and checkpoint writes contribute to request latency. This does not change the Session format or guarantee that forced termination preserves the final unflushed response.
+
+## Migration
+
+1. Keep the selected `dsh_home` writable and allow request deadlines to cover storage initialization and checkpoint writes. A longer shutdown timeout alone does not affect a pre-request checkpoint.
+2. Check profile and invocation patches for overrides of `session-checkpoint-policy`. To receive the durability policy, retain its enabled default alongside `sessions`.
+3. Run a short SDK turn, close normally, and use `resume_session()` with the same home and session ID to verify restoration. Investigate checkpoint failures before retrying model or tool work; the operation does not run until the checkpoint succeeds.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/sdk-minimal-checkpoints/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "sdk-minimal profile 现在会在会话持久化无法完成检查点时停止模型和工具调度。"
+---
+
+# SDK-minimal 要求持久化检查点
+
+[English](guide.md) | 中文
+
+## 变更
+
+`sdk-minimal` profile 启用 `session-checkpoint-policy`，在模型请求、顶层工具执行和 agent step 之前等待会话历史刷盘。此前，JSONL 写入尚在缓冲时这些操作也可以继续，持久化错误可能只记录为后台警告。现在，检查点失败会停止依赖它的操作。首次文件锁初始化发生在第一次模型请求之前，检查点写入也计入请求延迟。此变更不修改 Session 格式，也不保证强制终止时保留最后尚未刷盘的回复。
+
+## 迁移
+
+1. 确保选定的 `dsh_home` 可写，并让请求超时覆盖存储初始化和检查点写入。仅延长关闭超时不会影响请求前的检查点。
+2. 检查 profile 和调用级 patch 是否覆盖了 `session-checkpoint-policy`。要使用此持久化策略，应在 `sessions` 旁保留其默认启用状态。
+3. 运行一轮 SDK 短对话，正常关闭，再使用相同 home 和会话 ID 调用 `resume_session()` 验证恢复。重试模型或工具操作前，先排查检查点失败；只有检查点成功后，操作才会执行。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-projection-handles/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/session-projection-handles/guide.md
+/:
+  en: a7c158942ce2a575
+  zh: 7103da2fa7ca494a
+/session-projection-registration-handles:
+  en: 08af78abac6d3bcd
+  zh: 85ede5596cac9d5e
+/session-projection-registration-handles/change:
+  en: d5e6ea606de638a0
+  zh: a041eee1ffd48ac3
+/session-projection-registration-handles/migration:
+  en: 9c7d73f9f50c4bdd
+  zh: b1c597c63d52b444

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-projection-handles/guide.md

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Session projection registration resolves asynchronously to a retained reader; the callable result and registry-level state reads are deprecated."
+---
+# Session projection registration handles
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-session-projection` changes `SessionProjectionRegistry.register(definition)` from a synchronous disposer to `Promise<ProjectionHandle<S>>`. The definition installs synchronously; awaiting the result yields a handle with `stateOf(session)` and `dispose()`, and registration errors reject it. The runtime value is a callable thenable, not a native Promise: calling it still releases the registration, but that call is deprecated. `typeof registration` is `"function"` and `registration instanceof Promise` is false, so code that branches on those checks or treats functions as callbacks is affected; Vitest's `.rejects` calls it instead of observing the rejection.
+
+Registry-level `stateOf(session, key): unknown` is deprecated. It returns `undefined` whenever no plugin currently registers the key: its owner is not composed, has not reached registration, or has released its last registration. `SessionProjectionStateMap` is removed; host state types stay local to `ProjectionDefinition<K, S>` and are inferred from `stateSchema`. After the last registration is disposed, the unit leaves snapshots, checkpoints, and live notifications, but retained handles still fold Session events on demand. [Runtime compatibility](../../../../packages/session/session-projection/README.md#deprecated-plugin-compatibility) details the deprecated calls.
+
+`@deepseek-ai/dsh-agent` and `@deepseek-ai/dsh-subagent` require `sessionProjections`. AgentRegistry owns turn and step state and provides `ctx.agents.turnBoundaryOf(session)`; `@deepseek-ai/dsh-agent-loop` no longer exports `turnBoundaryProjectionDefinition`. Turn-state consumers, including the Claude Code mods bridge, require `agents`. Preset and context-pressure reads use `ctx.agentPresets.presetForSession(session)` and `ctx.tokenMeter.contextPressure(session)`. The API controller and mods bridge no longer register those definitions independently; their optional-service behavior applies when the owning service is absent. `@deepseek-ai/dsh-api-session-controller` removes `installModelSelectionProjection`.
+
+## Migration
+
+1. Mount `SessionProjectionRegistry` before `AgentRegistry`, `SubagentRuntime`, and other projection owners in custom compositions. Include `@deepseek-ai/dsh-agent` wherever a plugin requires `agents`.
+2. For a plugin's own definitions, await `ctx.sessionProjections.register(definition)` in asynchronous `apply()` or `[Service.init]()` and retain the handle before publishing dependent operations. Remove `SessionProjectionStateMap` augmentations and pass the state type as the second `ProjectionDefinition<K, S>` argument. Keep client-value declarations in `SessionProjectionMap`.
+3. Replace `registry.stateOf(session, key)` with the owning service's method, such as `ctx.agents.turnBoundaryOf(session)`, or `handle.stateOf(session)` inside the owner; until then, handle its `undefined` result. Replace calls to the registration result with an awaited `handle.dispose()`; fiber disposal still releases registrations automatically.
+4. Where a native Promise is required, pass `Promise.resolve(registration)`, including `await expect(Promise.resolve(registration)).rejects.toThrow(...)` in Vitest. Replace `typeof` or `instanceof Promise` checks on the result with awaiting.
+5. Replace `installModelSelectionProjection(ctx)` with `await ctx.sessionProjections.register(modelSelectionProjection)`, importing the definition from `@deepseek-ai/dsh-api-session-controller/src/model-selection-projection.ts`.
+6. Typecheck custom plugins, then verify activation, a Session state read, a rejected registration, and owner disposal.

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

@@ -0,0 +1,24 @@
+---
+kind: upgrade-guide
+description: "Session 投影注册异步解析为保留读取能力的句柄；可调用的注册结果与注册表级状态读取已弃用。"
+---
+# Session 投影注册句柄
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-session-projection` 的 `SessionProjectionRegistry.register(definition)` 从同步释放函数改为 `Promise<ProjectionHandle<S>>`。定义同步安装；等待结果得到带 `stateOf(session)` 与 `dispose()` 的句柄，注册错误使结果拒绝。运行时返回值是可调用的 thenable，而非原生 Promise：调用它仍会释放注册，但该调用已弃用。`typeof registration` 为 `"function"`，`registration instanceof Promise` 为 false，因此按这些检查分支或把函数视为回调的代码会受影响；Vitest 的 `.rejects` 会调用它，而不是观察拒绝。
+
+注册表级 `stateOf(session, key): unknown` 已弃用。当前没有任何插件注册该 key 时它返回 `undefined`：所属插件未组合、尚未执行到注册，或已释放最后一次注册。`SessionProjectionStateMap` 已移除；宿主状态类型保留在各自的 `ProjectionDefinition<K, S>` 中，并从 `stateSchema` 推导。最后一次注册释放后，该投影单元不再参与快照、检查点和实时通知，但保留的句柄仍可按需折叠 Session 事件。[运行时兼容说明](../../../../packages/session/session-projection/README.zh.md#deprecated-plugin-compatibility)详述这些已弃用调用。
+
+`@deepseek-ai/dsh-agent` 与 `@deepseek-ai/dsh-subagent` 依赖 `sessionProjections`。AgentRegistry 持有轮次和步骤状态，并提供 `ctx.agents.turnBoundaryOf(session)`；`@deepseek-ai/dsh-agent-loop` 不再导出 `turnBoundaryProjectionDefinition`。包括 Claude Code mods 桥接在内的轮次状态消费方依赖 `agents`。预设与上下文压力分别通过 `ctx.agentPresets.presetForSession(session)` 和 `ctx.tokenMeter.contextPressure(session)` 读取。API 控制器与 mods 桥接不再独立注册这些定义；所属服务缺席时采用各自的可选服务行为。`@deepseek-ai/dsh-api-session-controller` 移除了 `installModelSelectionProjection`。
+
+## 迁移
+
+1. 在自定义组合中，先挂载 `SessionProjectionRegistry`，再挂载 `AgentRegistry`、`SubagentRuntime` 及其他投影所有者。组合中的插件依赖 `agents` 时，加入 `@deepseek-ai/dsh-agent`。
+2. 对插件自己的定义，在异步 `apply()` 或 `[Service.init]()` 中等待 `ctx.sessionProjections.register(definition)`，并在提供依赖操作前保存句柄。删除 `SessionProjectionStateMap` 的声明合并，将状态类型作为 `ProjectionDefinition<K, S>` 的第二个类型参数。保留 `SessionProjectionMap` 中的客户端值声明。
+3. 将 `registry.stateOf(session, key)` 替换为所属服务的方法（例如 `ctx.agents.turnBoundaryOf(session)`），或所有者内部的 `handle.stateOf(session)`；替换之前须处理其 `undefined` 结果。将对注册结果的调用替换为等待 `handle.dispose()`；fiber 释放仍会自动释放注册。
+4. 需要原生 Promise 时传入 `Promise.resolve(registration)`，包括在 Vitest 中写 `await expect(Promise.resolve(registration)).rejects.toThrow(...)`。将对结果的 `typeof` 或 `instanceof Promise` 检查改为直接等待。
+5. 将 `installModelSelectionProjection(ctx)` 替换为 `await ctx.sessionProjections.register(modelSelectionProjection)`，从 `@deepseek-ai/dsh-api-session-controller/src/model-selection-projection.ts` 导入该定义。
+6. 对自定义插件执行类型检查，再验证激活、Session 状态读取、注册被拒绝以及 owner 释放。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-store-writes/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/session-store-writes/guide.md
+/:
+  en: 9f4269869ddedadc
+  zh: 1727a99e307a0748
+/store-owned-session-writes-follow-publication:
+  en: 084471869eed95ac
+  zh: f85b7855bab7868e
+/store-owned-session-writes-follow-publication/change:
+  en: be28a83cfa73d844
+  zh: 5c380f0e25c3f6ca
+/store-owned-session-writes-follow-publication/migration:
+  en: ebfc3e7cdf09ddda
+  zh: 8f53f5500fbe1958

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-store-writes/guide.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Store-owned Sessions reject writes before creation announcement completes and after removal."
+---
+# Store-owned Session writes follow publication
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`Session.append()` and `appendPluginRecord()` on store-owned instances reject writes until the instance enters a `SessionStore` and its synchronous `session/created` dispatch completes, and after it leaves. Store ownership starts at `prepare()` or `enter()`. Creation listeners cannot append; a failed announcement leaves writes disabled. Independent `Session.create()` and `Session.fromRestore()` instances remain writable without notifying store observers. Constructor, restore, and fork history still load normally. The Agent factory completes `session/created` before invoking setup; `agent/created` still follows setup. During `session/created`, `ctx.agents.get(session.id)` now returns `undefined`. Listeners registered inside setup miss their own Session’s creation announcement. Setup events now reach live Session subscribers as well as persisted history.
+
+A failed setup retains constructor history and setup events already written to persistence. A failed seeded creation, including a fork, can therefore leave a stored Session; its identity is no longer available for a new creation.
+
+Permission defaults are initialized during `agent/created`, so creating a bare Session no longer pins them. `dsh-permission-presets` now requires the `agents` service as well as its existing dependencies.
+
+## Migration
+
+1. Use `ctx.sessions.create()` for a writable Session owned by the calling fiber. For explicit lifecycle ownership, call `prepare()`, `enter()`, and `announce()` before appending; retain the returned disposer until all closing events finish.
+2. Keep `Session.create()` and `Session.fromRestore()` for independent log construction. Build history before handing the instance to `enter()`, or pass it as the seed to `prepare()`. Removal does not restore independent write access. Cold durable writes use the persistence write handle.
+3. Move writes and Agent-dependent work out of `session/created` listeners. Use setup or `agent/created` for writes; use the supplied Agent in setup and the `agent/created` payload instead of looking up an Agent during Session announcement.
+4. Replace setup-installed observers of their own `session/created` with `agent/created` listeners. Keep Session creation observers in a scope installed before factory creation starts.
+5. After failed creation with persisted history, retry with `ctx.agents.resume({ resumeSessionId })` instead of `create()` on the same id. Retain the stored history for recovery.
+6. Custom profiles mounting `dsh-permission-presets` must also mount `dsh-agent`, the provider of `agents`, and await permission plugin activation before creating Agents.
+7. Verify that creation observers see the expected registry state, permission initialization completes, failed creation can resume its stored history, and rejected appends leave history unchanged.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-store-writes/guide.zh.md

@@ -0,0 +1,25 @@
+---
+kind: upgrade-guide
+description: "Store 接管的 Session 拒绝创建宣告完成前和移除后的写入。"
+---
+# Store 接管的 Session 在发布后开放写入
+
+[English](guide.md) | 中文
+
+## 变更
+
+Store 接管的实例仅在进入 `SessionStore` 且同步 `session/created` 分发完成后，才能通过 `Session.append()` 和 `appendPluginRecord()` 写入，离开 Store 后再次拒绝写入。Store 从 `prepare()` 或 `enter()` 开始接管实例。创建监听器不能追加，宣告失败后仍不能写入。独立的 `Session.create()` 和 `Session.fromRestore()` 实例仍可写入，且不通知 Store 观察者。构造、恢复和 fork 历史仍可正常加载。Agent 工厂在调用 setup 前完成 `session/created`，`agent/created` 仍在 setup 后执行。在 `session/created` 期间，`ctx.agents.get(session.id)` 现在返回 `undefined`。setup 内注册的监听器会错过其所属 Session 的创建宣告。setup 事件现在除了进入持久化历史，也会传递给 Session 的实时订阅方。
+
+setup 失败后会保留已经写入持久化存储的构造历史和 setup 事件。因此，带 seed 的创建（包括 fork）失败后可能留下已存储的 Session，其标识不能再用于新建。
+
+权限默认值在 `agent/created` 中初始化，因此只创建 Session 不再固定这些默认值。`dsh-permission-presets` 除既有依赖外，现在还要求 `agents` 服务。
+
+## 迁移
+
+1. 使用 `ctx.sessions.create()` 创建由调用方 fiber 拥有的可写 Session。若显式拥有生命周期，依次调用 `prepare()`、`enter()` 和 `announce()` 后再追加；保留返回的 disposer，直到所有收尾事件完成。
+2. 独立日志构造继续使用 `Session.create()` 和 `Session.fromRestore()`。在把实例交给 `enter()` 前构造历史，或把历史作为 seed 传给 `prepare()`。移除不会恢复独立写入权限。冷日志的持久化写入使用持久化写句柄。
+3. 将写入和依赖 Agent 的工作移出 `session/created` 监听器。在 setup 或 `agent/created` 中写入；使用 setup 提供的 Agent 或 `agent/created` 载荷，不要在 Session 宣告期间查找 Agent。
+4. 将 setup 内监听所属 Session 的 `session/created` 的代码改为监听 `agent/created`。需要观察 Session 创建时，应在工厂创建开始前安装监听作用域。
+5. 创建失败但已持久化历史时，使用 `ctx.agents.resume({ resumeSessionId })` 重试，不要对同一 id 再次调用 `create()`；保留存储历史用于恢复。
+6. 挂载 `dsh-permission-presets` 的自定义 profile 也必须挂载提供 `agents` 的 `dsh-agent`，并等待权限插件激活后再创建 Agent。
+7. 验证创建观察者看到预期的注册表状态、权限完成初始化、创建失败后能恢复存储历史，以及被拒绝的追加不会改变历史。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-team-mode/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/session-team-mode/guide.md
+/:
+  en: 2b713df685f8b593
+  zh: 4e185e636a3b5d99
+/select-agent-teams-per-session:
+  en: 9e82418f46f6275b
+  zh: d1282eec79b37b59
+/select-agent-teams-per-session/change:
+  en: 3ba5920179726841
+  zh: 940e0d956a523dbc
+/select-agent-teams-per-session/migration:
+  en: 7b6dc660602d9c3b
+  zh: 8f8459198300aa46

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/session-team-mode/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Agent Teams defaults off for new Sessions and uses a saved per-Session selection."
+---
+
+# Select Agent Teams per Session
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Agent Teams ships with base-backed profiles; new Sessions default to off. The Plugins page has no separate Agent Teams switch. The root Session’s selection controls task tools and Team guidance throughout its subagent tree. The model and reasoning menu offers **Use Agent Teams**, and the root conversation’s Subagent header control opens members above shared tasks in one panel while enabled. Child conversations retain navigation without a shared task board.
+
+Disabling Team retains tasks and subagents. Admitted task operations finish; queued operations check the current mode when they start. The selection survives restart. A historical task board without a saved selection remains enabled. The required `team/mode` event records selections; older readers reject this unfamiliar event. See the [persistence acknowledgement](../../../persistence-changes/2026-10-19-session-team-mode.md).
+
+## Migration
+
+1. Start each existing profile once. Profile loading removes the retired `@deepseek-ai/dsh-experimental-agent-team-profile` bundle selection; the base and Web bundles supply its plugins. Keep `agent-team`, `tool-agent-team`, and `ui-agent-team` row overrides. Custom compositions replace package names `@deepseek-ai/dsh-experimental-agent-team`, `@deepseek-ai/dsh-experimental-tool-agent-team`, and `@deepseek-ai/dsh-experimental-client-ui-agent-team` with `@deepseek-ai/dsh-agent-team`, `@deepseek-ai/dsh-tool-agent-team`, and `@deepseek-ai/dsh-client-ui-agent-team`.
+2. Toggle **Use Agent Teams** in the root conversation’s model and reasoning menu. The `/team on` and `/team off` commands are removed.
+3. Verify that enabling shows shared tasks in the root conversation below the Subagent tree in the same panel and exposes four task tools. Reload the Session to confirm the saved selection. Re-enabling after disabling restores the existing tasks.
+
+Client plugin consumers replace `TeamActionProps` with `TeamBoardProps`; task content registers in `conversation.session.header.actions.subagent.footer` instead of the header actions slot.

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

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Agent Teams 在新 Session 中默认关闭，并使用按 Session 保存的选择。"
+---
+
+# 按 Session 选择智能体团队
+
+[English](guide.md) | 中文
+
+## 变更
+
+Agent Teams 随基于 base 的 profile 提供；新 Session 默认关闭。插件页不再提供独立的智能体团队开关。根 Session 的选择控制整棵子代理树中的任务工具和 Team 提示词。模型与推理等级菜单提供**使用智能体团队**开关，开启后通过根会话的 Subagent 页头入口，在同一面板中查看上方成员与下方共享任务。子会话保留导航，不显示共享任务板。
+
+关闭 Team 保留任务和子代理。已经进入执行的任务操作继续完成；排队中的操作在开始时检查当前模式。选择在重启后仍有效。没有保存选择的历史任务板保持开启。必读事件 `team/mode` 记录选择；旧读取器会拒绝该未知事件。参见[持久化变更确认](../../../persistence-changes/2026-10-19-session-team-mode.zh.md)。
+
+## 迁移
+
+1. 启动每个已有 profile 一次。加载时会移除已停用的 `@deepseek-ai/dsh-experimental-agent-team-profile` 组合选项；base 与 Web 组合提供对应插件。保留 `agent-team`、`tool-agent-team` 与 `ui-agent-team` 行覆盖。自定义组合将包名 `@deepseek-ai/dsh-experimental-agent-team`、`@deepseek-ai/dsh-experimental-tool-agent-team`、`@deepseek-ai/dsh-experimental-client-ui-agent-team` 分别替换为 `@deepseek-ai/dsh-agent-team`、`@deepseek-ai/dsh-tool-agent-team`、`@deepseek-ai/dsh-client-ui-agent-team`。
+2. 在根会话的模型与推理等级菜单中切换**使用智能体团队**。`/team on` 与 `/team off` 命令已移除。
+3. 在根会话中确认开启后通过 Subagent 入口在树下方查看共享任务板，并提供四个任务工具。重新加载 Session，确认选择已保存。关闭后再开启会恢复已有任务。
+
+Client 插件消费者将 `TeamActionProps` 替换为 `TeamBoardProps`；任务内容注册到 `conversation.session.header.actions.subagent.footer`，而非页头操作插槽。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-activation-options/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/subagent-activation-options/guide.md
+/:
+  en: b087162d9a24f772
+  zh: a32f167c3529fb1c
+/subagent-activation-options:
+  en: 20a5b01ef11bff72
+  zh: 919de21bc865ee9e
+/subagent-activation-options/change:
+  en: 7cc2554992e98c53
+  zh: 434540bcd037d1f5
+/subagent-activation-options/migration:
+  en: 2243d08661eb457c
+  zh: a928a8e7fb3515ff

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-activation-options/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "SubagentActivationSpec accepts task options directly instead of a nested request object."
+---
+
+# Subagent activation options
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Plugin code calling `ctx.subagents.startActivation()` must pass `prompt`, `parent`, and optional execution settings directly on `SubagentActivationSpec`. The nested `request` field is removed. Type names, provider requests, cancellation, and result delivery are unchanged.
+
+## Migration
+
+1. In each `startActivation()` call, move the fields from `request` to the outer object. For an existing task object, replace `request: task` with `...task`; keep the activation's `label` and `signal` after the spread so they take precedence.
+2. Replace reads such as `spec.request.prompt` with `spec.prompt`. Keep backend `SubagentStartRequest` implementations unchanged.
+3. Typecheck the plugin and run its delegation tests to verify the updated calls.

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-activation-options/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "SubagentActivationSpec 直接接受任务选项，不再使用嵌套的 request 对象。"
+---
+
+# 子代理 activation 选项
+
+[English](guide.md) | 中文
+
+## 变更
+
+调用 `ctx.subagents.startActivation()` 的插件代码必须将 `prompt`、`parent` 和可选执行设置直接放在 `SubagentActivationSpec` 上。嵌套的 `request` 字段已移除。类型名称、提供方请求、取消和结果投递保持不变。
+
+## 迁移
+
+1. 在每个 `startActivation()` 调用中，将 `request` 内的字段移到外层对象。已有任务对象时，将 `request: task` 替换为 `...task`；将 activation 的 `label` 和 `signal` 放在展开操作之后，以确保它们优先生效。
+2. 将 `spec.request.prompt` 等读取替换为 `spec.prompt`。保持后端的 `SubagentStartRequest` 实现不变。
+3. 对插件运行类型检查和委派测试，验证更新后的调用。

package/references/official-docs/docs/upgrade-guide/v0.2.1-rc.2/subagent-service-methods/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/subagent-service-methods/guide.md
+/:
+  en: 6955b11d6f698e4c
+  zh: 8a8d4d6edd5dea0c
+/subagent-service-method-removal:
+  en: 102f43348f7c8eb0
+  zh: be09ff117c31ada1
+/subagent-service-method-removal/change:
+  en: 8cd7f93df401c417
+  zh: 27313127c2059e6b
+/subagent-service-method-removal/migration:
+  en: f0f0f921f284efec
+  zh: 8b9e88e9412282c2