Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine

# Conflicts:
#	packages/context/workspace-context/README.md
#	packages/llm/llm-retry/README.md
#	packages/session-persistence/session-checkpoint-policy/README.md
#	scripts/type-equiv.manifest.json

packages/todo/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: 1e5ae9a1583b9e9d3913fcd1dca7ef11a5f391fe
+README.zh.md: 0048940424f71c5709714d88346433fcfbf1554f

packages/todo/README.md

@@ -1,5 +1,7 @@
 # todo/ — todo / planning capability family
 
+English | [中文](README.zh.md)
+
 The model-facing todo tool. A single **product** package — there is no interface/implementation seam here, because the list is single-owner session state (one agent session owns its own list), not a swappable capability.
 
 | Package | Role | ctx key |

packages/todo/README.zh.md

@@ -0,0 +1,11 @@
+# todo/：todo／规划能力系列
+
+[English](README.md) | 中文
+
+面向模型的 todo 工具。它是单一 **产品** 包（package）：这里没有接口／实现 seam，因为该列表是由单一所有者管理的会话状态（每个 agent（智能体）会话拥有自己的列表），而非可替换能力。
+
+| 包 | 职责 | ctx 键 |
+|---|---|---|
+| `tool-todo/` | 面向模型的 `todo_write` 工具；将完整列表写入会话日志（`todo/write`） | （注册到 `ctx.tools`） |
+
+列表存在于事件溯源会话日志中（`SessionEventMap['todo/write']`，由 [`dsh-session`](../core/session) 拥有）；本包是追加快照的轻量消费方。[TUI 应用](../examples/tui-demo)等 UI 以及宿主／客户端运行时会根据会话事件渲染该持久列表。

packages/todo/tool-todo/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+README.md: db6bbf6970c73767c8e9df1148f98d23047d19b7
+README.zh.md: 6a9b817cb5af2c43b8e66100333e46665359eba8

packages/todo/tool-todo/README.md

@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-tool-todo
 
+English | [中文](README.zh.md)
+
 The model-facing `todo_write` tool: the agent's whole task list, replaced wholesale on each call.
 
 ## What it does

packages/todo/tool-todo/README.zh.md

@@ -0,0 +1,63 @@
+# @deepseek-ai/dsh-tool-todo
+
+[English](README.md) | 中文
+
+面向模型的 `todo_write` 工具：agent（智能体）的完整任务列表，每次调用都会整体替换。
+
+## 功能
+
+注册一个工具 `todo_write(todos: [{ content, status }])` 到 `ctx.tools`。模型每次调用都会发送完整列表，不存在部分更新或单项编辑。每次调用都会向调用 agent 的会话日志追加 `todo/write` 事件（完整列表快照），具体调用 `agent.session.append('todo/write', { todos })`；当前列表是最新的该类事件（回放时后写者胜）。
+
+`status` 是 `pending`、`in_progress` 或 `completed` 之一。
+
+## 单一所有者
+
+该列表属于调用工具的唯一 agent 会话。不存在 subagent／共享／swarm scope：非 agent 调用方（没有 `exec.agent`）无处写入列表，因此会被拒绝。这是有意设置的 scope 限制，详见 Agent Note。
+
+## 验证
+
+除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`，以及同时存在多个 `in_progress` 任务的情况（连贯计划最多只有一个活跃任务）。顺序与保持列表最新的纪律由模型根据工具描述负责。
+
+## 渲染
+
+规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久列表；[TUI 应用](../../examples/tui-demo)将其显示为持久计划。
+
+## 导出形状
+
+函数／命名空间插件：导出 `name`/`inject`/`apply`，不提供默认导出。意外的 `export default` 会通过 Loader 的 `unwrapExports` 折叠模块并丢弃 `inject`（参见 [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)）。
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型所见内容
+
+模型会看到生成的 [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo)。
+
+#### Token 影响
+
+工具可见的每个请求都有固定 schema 成本。
+
+#### KV Cache 影响
+
+只要定义和可见性不变，前缀就保持稳定。插件生命周期或 scope 限制可能会使此 schema 之后的复用失效。
+
+### 工具调用历史与结果
+
+#### 模型所见内容
+
+每个 assistant 工具调用都会在参数中保留整个替换列表。成功时精确返回 `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.`。稳定失败文本为 ``Error: invalid todo: `content` must be a non-empty string``、`Error: invalid todos: duplicate content "<content>"`、`Error: invalid todos: at most one task may be in_progress, got <count>` 和 `Error: todo_write requires an owning agent session`。完整 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
+
+#### Token 影响
+
+Token 增长与模型每次提交的完整列表成比例，且这些调用参数会保留到压缩（compaction）。结果本身很小，且形状固定。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与延后工作
+
+- **仅单一所有者 scope**：列表属于唯一调用 agent 会话；subagent／共享／swarm scope 是有意裁减（参见「单一所有者」一节），非 agent 调用方会被拒绝。
+- **项目形状有意保持最小**：`content` 加三态 `status`；整表替换不需要稳定 id、优先级或 active-form 字段。
+- **整表替换是唯一操作**：没有部分更新，也没有回读工具；模型每次调用都必须重新发送完整列表。