@deepseek-ai/dsh-tool-todo 0.1.1-rc.1 → 0.1.2-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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 packages/todo/tool-todo/README.md
-README.md: 4848758dd8f2049221901744e5d09cef2dd31591
-README.zh.md: 3c79ca6bba9bb0ffd7e1960dae7000bdb525bdfb
+README.md: 144f3476c36cb9054b7a21df11e78e3a70a1aed2
+README.zh.md: 0ebda11ac08a245f4b07eda32c69d062cb79d0a9

package/README.md

@@ -1,52 +1,137 @@
+---
+description: "The model-facing todo_write tool over the DeepSeek Harness session log: whole-list replacement, per-session ownership, and the todos projection, for users and maintainers choosing, configuring, or debugging the tool."
+kind: "package-reference"
+---
+
 # @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.
+## Summary
+
+`dsh-tool-todo` gives the agent a structured task list to plan with: break multi-step work into concrete tasks, mark the task you are working on, and check tasks off as they finish. The list survives across turns and reopened sessions, so the agent and the UI always see the latest plan. One configuration flag decides whether several tasks may be in progress at once, for agents that run work in parallel. Use it wherever an agent should keep a visible task list; each update replaces the whole list, and only the owning agent session can change it.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Use this package when you want the agent to maintain a visible task list while it works: plan multi-step work, show what is active, and record completion. Mounting it with the parallelism flag is the only setup; the agent then updates the list through its own planning tool whenever the plan changes.
+
+### When to choose it
+
+Choose it when one agent session should own the task list and whole-list updates are fine — the common shape for planning tools. Avoid it when several agents must share one list or when you need per-item edits: the list belongs to one agent and every update replaces the whole list. It needs an agent session to exist at all; automation-only surfaces that never run an agent cannot use it.
+
+### Minimal configuration
+
+`allowParallelInProgress` is required with no default: a composition that omits it fails at load, and a non-boolean value is rejected. Set `true` for agents that may run work concurrently (subagents, background commands, workflow fan-out) and `false` for the single-active discipline.
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `allowParallelInProgress` | required | Whether several todos may be `in_progress` at once; also selects the active-status clause of the model description |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-todo) is the exhaustive source for the accepted field.
+
+### What each call does
+
+The agent sends the ENTIRE list on every update; the new list replaces the previous one, so there are no partial updates or per-item edits. Each item is a short task description plus a status of `pending`, `in_progress`, or `completed`. A successful update returns the new counts — `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` — and the UI shows the new plan. Updates fail visibly when a task description is empty or duplicated, when an item carries fields beyond the description and status, or — when parallel work is disabled — when more than one task is marked in progress.
+
+### Single owner
+
+The task list belongs to the one agent session that created it — subagents and other agents each keep their own list, and there is no way to share a list between agents. A call from outside an agent session is rejected, so the agent learns the update failed instead of silently writing nowhere. If you need a list shared across agents, this package does not provide it.
 
-## What it does
+-----
 
-Registers one tool, `todo_write(todos: [{ content, status }])`, on `ctx.tools`. The model sends the ENTIRE list every call — there are no partial updates or per-item edits. Each call appends a `todo/write` event (the full list snapshot) to the calling agent's session log via `agent.session.append('todo/write', { todos })`; the current list is the most recent such event (last-write-wins on replay).
+<a id="understand-the-implementation"></a>
+## Understand the implementation
 
-`status` is one of `pending`, `in_progress`, or `completed`.
+<details>
+<summary>Implementation internals — click to expand</summary>
 
-## Single owner
+This section explains the design decisions behind the tool and points at the code that realizes them; the observable behavior is fully covered in [Use this package](#use-this-package).
 
-The list belongs to the ONE agent session that called the tool. There is no subagent/shared/swarm scope: a non-agent caller (no `exec.agent`) has nowhere to write the list and is rejected. This is a deliberate scope limit — see the Agent Note.
+### Design philosophy
 
-## Configuration
+The tool is built on four commitments:
 
-`allowParallelInProgress` is required: every composition must choose whether several todos may be `in_progress` at once. It is a deployment choice, not a fixed rule: whether concurrent active tasks are legitimate depends on runtime concurrency the tool cannot observe. Use `true` for agents that may fan out work and `false` to enforce the single-active discipline.
+- **Whole-list replace, log-backed state.** The model resends the entire list; the `todo/write` snapshot lives on the event-sourced session log, so durability, replay, and resume reconstruction come from the log rather than a service.
+- **Single owner.** The list belongs to the calling agent session; there is no shared or swarm scope, and non-agent callers are rejected.
+- **Deployment policy, not a coded rule.** `allowParallelInProgress` is a required composition choice because the tool cannot observe runtime concurrency; the durable-log invariant deliberately stays silent on the active count so a log written under one policy still replays under another.
+- **Validation keeps the logged snapshot honest.** Schema-level rejection of unknown keys and `execute`-level rejection of empty or duplicate content keep the durable snapshot equal to what the model believes it wrote.
 
-The flag moves the model-facing instruction and the accepted input together — `true` asks the model to mark every actively worked task and accepts any number, `false` asks for exactly one and rejects a call marking more with `Error: invalid todos: at most one task may be in_progress (got <n>)`. The durable-log invariant does NOT follow it: a log written while parallel work was allowed must still replay after a deployment tightens the policy, so the invariant stays silent on the active count.
+The [todo_write tool Agent Note](../../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md) records the original design and alternatives; the [parallel in-progress Agent Note](../../../.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md) records the policy decision.
 
-## Validation
+### Source map
 
-Beyond the schema's type/required/enum checks, `execute` rejects an empty or duplicate `content`, and any item key beyond `content`/`status` — an extended item shape (ids, nesting) fails loud instead of silently flattening, keeping the logged snapshot equal to what the model believes it wrote. How many tasks may be `in_progress` at once is the deployment's call (§ Configuration): a composition that chooses `true` permits parallel work (concurrent subagents, background commands) to mark several tasks simultaneously. Ordering and the discipline of keeping the list current are left to the model via the tool description.
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, tool registration, `todos` projection unit |
+| [`src/types.ts`](src/types.ts) | The one home of the `todos` projection-key declaration and its payload types |
+| [`src/client.ts`](src/client.ts) | Client-namespace re-export of the types outlet |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion: validates durable whole-list snapshots and open-turn ownership |
 
-## Rendering
+### Export shape
 
-The canonical result is `{ todos, counts: { pending, inProgress, completed } }`; its Native renderer returns the compact update acknowledgement. The tool also writes the full `todo/write` session event. UIs subscribe to the event stream and render that durable list themselves: the [web client](../../client/ui-conversation) shows a plan strip plus a dedicated tool row off the standing plan — latest `todo/write` with no later `turn/start` ([display](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.md), [lifetime](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)).
+The plugin is a function/namespace plugin: it exports `name` / `inject` / `apply` and no default export. A stray `export default` would make the Loader's `unwrapExports` collapse the module and drop `inject` (see [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).
 
-## Session projection
+### Session projection
 
-When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` projection unit under an injected child: `init` = `null` (no write yet), `apply` = take the whole list from each `todo/write` and clear to `null` on each `turn/start` (standing plan; `turn/end` keeps the finished checklist; every other event returns the same state reference), `view` = identity, `stateVersion` = 2. The key merges into `SessionProjectionMap` here (via the Service Definition package's `/types` outlet); the framework drives the unit and carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected. Lifetime rationale: [todo plan clears on next turn](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
+When the composition mounts `ctx.sessionProjections` ([`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.md)), this package registers the `todos` unit on an injected child: the projection is the standing plan — the latest whole `todo/write` list, `null` before the first write, cleared when the next turn starts while `turn/end` keeps the finished checklist visible. The key merges into `SessionProjectionMap` here; carriers serve the value on the history tail page and the `session/projection` push frame. Compositions without the registry are unaffected; see [src/index.ts](src/index.ts) for the unit registration. The lifetime rationale lives in the [todo plan clears on next turn Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md).
 
-## Export shape
+### Durable-log invariant
 
-A function/namespace plugin: it exports `name` / `inject` / `apply` and NO default. A stray `export default` would collapse the module via the Loader's `unwrapExports` and drop `inject` (see [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)).
+The invariant companion registers on `ctx.invariants`, validates existing and newly announced sessions once, and then advances a committed per-session turn trace for live appends. It rejects malformed entries, empty or duplicated content, unknown statuses, and any durable `todo/write` outside an open turn; core session treats declaration-merged events generically, while this producing package owns todo-specific rules. It deliberately says nothing about how many items are `in_progress`, because that is the tool's per-deployment policy, not a durable-data rule ([event ownership](../../../.agents/notes/implemented/architecture/2026-07-20-todo-event-ownership.md)).
 
+### Call mechanics
+
+Each call validates the submitted list against the schema, rejects incoherent input, and on success appends the full snapshot as a `todo/write` session event and returns the new counts; the current list is always the most recent `todo/write` in the log (last-write-wins on replay). See [src/index.ts](src/index.ts) for the exact validation and append steps.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the session subsystem to the generated catalogs and the decision records behind the tool.
+
+- [Todo subsystem](../../../docs/subsystems/todo.md) — the `todo/write` event payload, ownership rules, and `TodoItem`.
+- [todo group map](../README.md) — the sibling group page and its package table.
+- [Generated tool catalog](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo) — the `todo_write` schema the model receives.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-tool-todo) — every accepted config field and its source declaration.
+- [todo_write tool Agent Note](../../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.md) — the original design, alternatives, and dropped fields.
+- [parallel in-progress Agent Note](../../../.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.md) — why the active-count cap is a deployment policy.
+- [todo plan clears on next turn Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md) — the projection's standing-plan lifetime.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
 ### Tool schema
 
 #### What the model sees
 
-The model sees the generated [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo).
+The model sees the generated [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo): an object with one required `todos` array of `{ content, status }` items, where `status` is `pending`, `in_progress`, or `completed`. The description is the composed whole-list instruction whose active-status clause follows `allowParallelInProgress`.
 
 #### Token effect
 
-Fixed schema cost on every request where the tool is visible.
+Fixed schema cost on every request where the tool is visible; the description and schema are stable for a given configuration.
 
 #### KV Cache effect
 
@@ -68,6 +153,25 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 ## Known Limitations and Deferred Work
 
-- **Single-owner scope only** — the list belongs to the one calling agent session; subagent/shared/swarm scopes are a deliberate cut (see § Single owner), and a non-agent caller is rejected.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the tool is a poor fit. They are current package constraints, not a task backlog.
+
+- **Single-owner scope only** — the list belongs to the one calling agent session; subagent, shared, and swarm scopes are a deliberate cut, and a non-agent caller is rejected.
 - **The item shape is deliberately minimal** — `content` plus three-state `status`; whole-list replacement needs no stable id, priority, or active-form fields.
-- **Whole-list replacement is the only operation** — no partial updates, no read-back tool; the model must resend the entire list each call.
+- **Whole-list replacement is the only operation** — no partial updates, no read-back tool, and no per-item edits; the model must resend the entire list each call.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
+
+#### Future: cross-agent and shared lists
+
+The single-owner scope is a deliberate cut, and cross-agent or shared lists remain a separate future design: they would need per-item log deltas and explicit scope selection, and would change the model-visible contract. No design exists yet.
+
+</details>

package/README.zh.md

@@ -1,73 +1,177 @@
+---
+description: "面向 DeepSeek Harness 会话日志的模型侧 todo_write 工具：整表替换、单一会话归属与 todos 投影，供选择、配置或排查该工具的用户与维护者阅读。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-tool-todo
 
 [English](README.md) | 中文
 
-面向模型的 `todo_write` 工具：agent（智能体）的完整任务列表，每次调用都会整体替换。
+## 概述
+
+`dsh-tool-todo` 为 agent 提供一份可用于规划的结构化任务列表：把多步工作拆成具体任务、标记正在进行的任务、完成后逐项勾掉。列表跨轮次、跨重新打开的会话持续存在，agent 与 UI 始终看到最新计划。一个配置开关决定是否允许多个任务同时处于进行中，适用于并行开展工作的 agent。凡是希望 agent 维护可见任务列表的场景都可以使用它；每次更新整体替换列表，只有拥有该列表的 agent 会话才能修改。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当你希望 agent 在工作时维护一份可见的任务列表时使用本包：规划多步工作、展示当前进行中的任务、记录完成情况。挂载它并设置并行开关是唯一的配置步骤；此后每次计划变化，agent 都会通过它自己的规划工具更新列表。
+
+### 何时选择
+
+当某个 agent 会话应当拥有任务列表、且整表更新即可满足需求时选择它——这是规划工具的常见形态。当多个 agent 必须共享同一份列表、或需要逐项编辑时，请避开：列表只属于一个 agent，每次更新都会替换整个列表。它要求环境中确实存在 agent 会话；从不运行 agent 的纯自动化表面无法使用它。
+
+### 最小配置
+
+`allowParallelInProgress` 是必填项、没有默认值：省略它的组合会在加载时失败，非布尔值也会被拒绝。可能并发运行工作的 agent（subagent、后台命令、workflow 扇出）设为 `true`，需要单活跃项纪律的设为 `false`。
+
+```yaml
+- name: '@deepseek-ai/dsh-tool-todo'
+  config:
+    allowParallelInProgress: true
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `allowParallelInProgress` | 必填 | 是否允许多个 todo 同时处于 `in_progress`；同时选择模型描述中的活跃状态条款 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-todo)是每个受支持字段的穷尽式真源。
+
+### 每次调用做什么
+
+agent 每次更新都发送完整列表；新列表替换旧列表，因此没有部分更新或逐项编辑。每个条目是一句简短的任务描述，外加 `pending`、`in_progress` 或 `completed` 状态。成功的更新会返回新的计数——`Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.`——UI 随即展示新计划。任务描述为空或重复、条目带有描述与状态之外的字段、或（禁用并行时）多个任务被标记为进行中，这些情况下更新都会明确失败。
+
+### 单一所有者
+
+任务列表属于创建它的那一个 agent 会话——subagent 与其他 agent 各自维护自己的列表，不存在跨 agent 共享列表的方式。来自 agent 会话之外的调用会被拒绝，因此 agent 会得知更新失败，而不是被静默丢弃。如果你需要多个 agent 共享同一份列表，本包不提供该能力。
 
-## 功能
+-----
 
-注册一个工具 `todo_write(todos: [{ content, status }])` 到 `ctx.tools`。模型每次调用都会发送完整列表，不存在部分更新或单项编辑。每次调用都会向调用 agent 的会话日志追加 `todo/write` 事件（完整列表快照），具体调用 `agent.session.append('todo/write', { todos })`；当前列表是最新的该类事件（回放时后写覆盖先写）。
+<a id="understand-the-implementation"></a>
+## 理解实现
 
-`status` 是 `pending`、`in_progress` 或 `completed` 之一。
+<details>
+<summary>实现细节——点击展开</summary>
 
-## 单一所有者
+本节解释工具背后的设计决策，并指出实现它们的代码位置；可观察行为已在[使用本包](#use-this-package)中完整说明。
 
-该列表属于调用工具的唯一 agent 会话。不存在 subagent／共享／swarm scope：非 agent 调用方（没有 `exec.agent`）无处写入列表，因此会被拒绝。这是有意设置的 scope 限制，详见 Agent Note。
+### 设计理念
 
-## 配置
+本工具建立在四项承诺之上：
 
-`allowParallelInProgress` 是必填项：每个组合都必须选择是否允许多个 todo 同时处于 `in_progress`。这是部署层的选择而非固定规则：并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况。可能并行展开工作的 agent 使用 `true`，`false` 则强制执行单活跃项纪律。
+- **整表替换、日志承载状态。** 模型重新发送整个列表；`todo/write` 快照存放在事件溯源的会话日志上，持久性、回放与恢复重建都来自日志而非服务。
+- **单一所有者。** 列表属于调用 agent 会话；不存在共享或 swarm 作用域，非 agent 调用方会被拒绝。
+- **部署策略，而非编码规则。** `allowParallelInProgress` 是必填组合选择，因为工具无法观测运行时并发；持久日志不变式刻意不跟随它，因此一种策略下写入的日志在部署收紧另一种策略后仍可回放。
+- **校验让落库快照保持诚实。** schema 层拒绝未知键、`execute` 层拒绝空或重复 content，使持久快照与模型自认为写入的内容一致。
 
-该开关会同时改变面向模型的指令与接受的输入——`true` 要求模型标记每个正在推进的任务并接受任意数量；`false` 要求恰好一个，并以 `Error: invalid todos: at most one task may be in_progress (got <n>)` 拒绝标记更多的调用。持久日志不变式**不**跟随它：在允许并行时写下的日志，在部署收紧策略之后仍必须可回放，因此不变式对活跃数量保持沉默。
+[todo_write 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md) 记录原始设计与备选方案；[并行 in-progress Agent Note](../../../.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md) 记录该策略决策。
 
-## 验证
+### 源码地图
 
-除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`，以及 `content`/`status` 之外的任何条目键——扩展条目形状（id、嵌套）会明确报错而不是被静默压平，保证落日志的快照与模型自认为写入的内容一致。同时可以有多少任务处于 `in_progress` 由部署决定（见 § 配置）：选择 `true` 的组合允许并行工作（并发 subagent、后台命令）同时将多个任务标记为 `in_progress`。列表的顺序及及时更新由模型依照工具描述负责。
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`Config` schema、工具注册、`todos` 投影单元 |
+| [`src/types.ts`](src/types.ts) | `todos` 投影键声明及其载荷类型的唯一归属地 |
+| [`src/client.ts`](src/client.ts) | 客户端命名空间对类型出口的再导出 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件：校验持久整表快照与开放轮次归属 |
 
-## 渲染
+### 导出形状
 
-规范结果为 `{ todos, counts: { pending, inProgress, completed } }`；其 Native 渲染器返回精简的更新确认。工具还会写入完整 `todo/write` 会话事件。UI 订阅事件流，并自行渲染该持久化列表：[web 客户端](../../client/ui-conversation)基于当前有效计划（其后没有更晚 `turn/start` 的最近一次 `todo/write`）显示计划条和专属工具行（[展示](../../../.agents/notes/implemented/feature/2026-07-23-web-todo-display.zh.md)、[生命周期](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md)）。
+本插件是函数／命名空间插件：导出 `name` / `inject` / `apply`，没有默认导出。多余的 `export default` 会让 Loader 的 `unwrapExports` 折叠模块并丢弃 `inject`（参见 [postmortem 0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.zh.md)）。
 
-## 会话投影
+### 会话投影
 
-当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.zh.md)）时，本包在一个注入的子插件中注册 `todos` 投影单元：`init` = `null`（尚无写入）、`apply` = 从每个 `todo/write` 取整表，并在每个 `turn/start` 清为 `null`（当前有效计划；`turn/end` 保留刚完成的清单；其余事件都返回同一个状态引用）、`view` = 恒等、`stateVersion` = 2。该键在本包中合并进 `SessionProjectionMap`（经 Service Definition 包的 `/types` 出口）；框架驱动该单元，载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响。生命周期理由见 [在下一轮次清空 todo 计划](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md)。
+当组合挂载 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.zh.md)）时，本包在注入的子插件中注册 `todos` 单元：投影即有效计划——最新的整份 `todo/write` 列表，首次写入前为 `null`，下一轮次开始时清空，而 `turn/end` 保留刚完成的清单。该键在此处合并进 `SessionProjectionMap`；载体通过历史尾页与 `session/projection` 推送帧提供该值。未挂载注册表的组合不受影响；单元注册见 [src/index.ts](src/index.ts)。生命周期理由见 [todo 计划在下一轮次清空 Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md)。
 
-## 导出形状
+### 持久日志不变式
 
-函数／命名空间插件：导出 `name`/`inject`/`apply`，不提供默认导出。意外的 `export default` 会被 Loader 的 `unwrapExports` 折叠为默认导出，并导致 `inject` 丢失（参见 [docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.zh.md)）。
+不变式伴生插件注册到 `ctx.invariants`，先分别校验既有会话与新公布会话一次，再为实时追加推进按会话提交的轮次轨迹。它会拒绝畸形条目、空或重复 content、未知状态，以及开放轮次之外的持久 `todo/write`；核心 session 通用处理声明合并事件，而本生产包拥有 todo 专用规则。它刻意不约束有多少条目处于 `in_progress`，因为那是工具按部署制定的策略，而非持久数据规则（见[事件归属](../../../.agents/notes/implemented/architecture/2026-07-20-todo-event-ownership.zh.md)）。
 
+### 调用机制
+
+每次调用都会先校验提交的列表是否符合 schema，拒绝不一致的输入，成功后把完整快照作为 `todo/write` 会话事件追加并返回新的计数；当前列表始终是日志中最近一次 `todo/write`（回放时后写覆盖先写）。确切的校验与追加步骤见 [src/index.ts](src/index.ts)。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从会话子系统逐步进入生成的目录，以及工具背后的决策记录。
+
+- [Todo 子系统](../../../docs/subsystems/todo.zh.md)——`todo/write` 事件载荷、归属规则与 `TodoItem`。
+- [todo 组映射](../README.zh.md)——同级组页面及其包表格。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-todo)——模型接收的 `todo_write` schema。
+- [生成的配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-tool-todo)——每个受支持配置字段及其源声明。
+- [todo_write 工具 Agent Note](../../../.agents/notes/implemented/feature/2026-06-29-todo-write-tool.zh.md)——原始设计、备选方案与砍掉的字段。
+- [并行 in-progress Agent Note](../../../.agents/notes/implemented/feature/2026-07-26-todo-parallel-in-progress.zh.md)——为何活跃计数上限成为部署策略。
+- [todo 计划在下一轮次清空 Agent Note](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.zh.md)——投影的有效计划生命周期。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
 ### 工具 schema
 
-#### 模型看到的内容
+#### 模型看到什么
 
-模型会看到生成的 [`todo_write` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-todo)。
+模型会看到生成的 [`todo_write` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-todo)：一个对象，含一个必填的 `todos` 数组，元素为 `{ content, status }`，其中 `status` 为 `pending`、`in_progress` 或 `completed`。描述是组合后的整表指令，其活跃状态条款跟随 `allowParallelInProgress`。
 
 #### Token 影响
 
-工具可见的每个请求都有固定的 schema token 开销。
+工具可见的每个请求都有固定 schema 开销；在给定配置下描述与 schema 保持稳定。
 
 #### KV Cache 影响
 
-只要定义和可见性不变，前缀就保持稳定。插件生命周期或 scope 限制可能会使从此 schema 起的缓存复用失效。
+定义与可见性不变时前缀保持稳定。插件生命周期或作用域限制可能使从此 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: todo_write requires an owning agent session`，以及——仅在部署设置了 `allowParallelInProgress: false` 时——`Error: invalid todos: at most one task may be in_progress (got <n>)`。完整 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
+每次 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: todo_write requires an owning agent session`，以及——仅在部署设置 `allowParallelInProgress: false` 时——`Error: invalid todos: at most one task may be in_progress (got <n>)`。完整的 `todo/write` 会话事件是 UI 与回放状态，而非第二条模型消息。
 
 #### Token 影响
 
-token 用量会随模型每次提交的完整列表增长，且这些调用参数会保留到压缩（compaction）。结果本身很小，且形状固定。
+token 用量随模型每次提交的完整列表增长，这些调用参数会保留到压缩（compaction）。结果本身很小且形状固定。
 
 #### KV Cache 影响
 
-仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+仅追加；新可见内容位于可复用请求前缀之后，不会使既有 KV-cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明工具何时不合适。它们是当前包约束，不是任务积压。
+
+- **仅单一所有者作用域**——列表属于唯一调用 agent 会话；subagent、共享与 swarm 作用域是有意砍掉的部分，非 agent 调用方会被拒绝。
+- **条目形状刻意保持最小**——`content` 加三态 `status`；整表替换不需要稳定 id、优先级或 active-form 字段。
+- **整表替换是唯一操作**——没有部分更新、没有回读工具、没有逐项编辑；模型每次调用都必须重新发送完整列表。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：未决问题与尚未决定的方向。它明确不具权威性——已交付行为、限制与既定理由以上文、包代码和相关 Agent Note 为准。
+
+#### 未来：跨 agent 与共享列表
 
-## 已知限制与暂缓事项
+单一所有者作用域是有意砍掉的部分，跨 agent 或共享列表仍是独立的未来设计：它们需要逐项日志增量与显式作用域选择，并会改变模型可见约定。目前尚不存在设计。
 
-- **仅单一所有者 scope**：列表属于唯一调用 agent 会话；subagent／共享／swarm scope 是有意设置的限制（参见「单一所有者」一节），非 agent 调用方会被拒绝。
-- **条目形状有意保持最小**：`content` 加三态 `status`；整表替换不需要稳定 id、优先级或 active-form 字段。
-- **整表替换是唯一操作**：没有部分更新，也没有回读工具；模型每次调用都必须重新发送完整列表。
+</details>

package/lib/index.js

@@ -9,7 +9,7 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 * @module @deepseek-ai/dsh-tool-todo
 */
 const name = "tool-todo";
-const inject = ["tools"];
+const inject = ["tools", "sessionProjections"];
 /** The valid {@link TodoItem} statuses, as a runtime set for input narrowing. */
 const STATUSES = [
 	"pending",
@@ -70,29 +70,27 @@ const todosProjectionSchema = z$1.union([z$1.array(z$1.object({
 	])
 })), z$1.null()]);
 /**
-* Register the `todo_write` tool on `ctx.tools` and, when the session-projection seam is composed,
-* the `todos` unit.
-* @param ctx - registrant context carrying the tool registry.
+* Register the `todo_write` tool on `ctx.tools` and the `todos` unit on
+* `ctx.sessionProjections`.
+* @param ctx - registrant context carrying the tool and session-projection registries.
 * @param config - deployment's explicit todo policy.
 */
 function apply(ctx, config) {
 	const allowParallel = config.allowParallelInProgress;
-	ctx.inject(["sessionProjections"], (projectionCtx) => {
-		projectionCtx.sessionProjections.register({
-			key: "todos",
-			stateSchema: todosProjectionSchema,
-			init: () => null,
-			apply: (state, event) => {
-				if (event.type === "todo/write") return event.data.todos;
-				if (event.type === "turn/start") return null;
-				return state;
-			},
-			wire: {
-				viewSchema: todosProjectionSchema,
-				view: (state) => state
-			},
-			stateVersion: 2
-		});
+	ctx.sessionProjections.register({
+		key: "todos",
+		stateSchema: todosProjectionSchema,
+		init: () => null,
+		apply: (state, event) => {
+			if (event.type === "todo/write") return event.data.todos;
+			if (event.type === "turn/start") return null;
+			return state;
+		},
+		wire: {
+			viewSchema: todosProjectionSchema,
+			view: (state) => state
+		},
+		stateVersion: 2
 	});
 	ctx.tools.register(defineTool({
 		name: "todo_write",

package/lib/invariant.js

@@ -31,17 +31,51 @@ function validateTodos(value, fail) {
 		if (typeof status !== "string" || !TODO_STATUSES.has(status)) fail(`todo/write carries unknown status ${JSON.stringify(status)}`);
 	}
 }
-/** Validate the package-owned event fields and ignore unrelated events. */
-function validateEvent(event, fail) {
-	if (event.type === "todo/write") validateTodos(event.data.todos, fail);
+/** Advance the trace after one event has committed. */
+function advanceTrace(trace, event) {
+	if (event.type === "turn/start") trace.open = true;
+	if (event.type === "turn/end") trace.open = false;
+}
+/** Validate one package-owned event against the preceding committed trace. */
+function validateEvent(event, trace, fail) {
+	if (event.type !== "todo/write") return;
+	validateTodos(event.data.todos, fail);
+	if (!trace.open) fail("todo/write appended outside any open turn");
+}
+/** Validate one existing log in a single pass and return its tail trace. */
+function seedTrace(session, fail) {
+	const trace = { open: false };
+	for (const event of session.events) {
+		validateEvent(event, trace, fail);
+		advanceTrace(trace, event);
+	}
+	return trace;
 }
 /** Install validation for loaded and newly appended whole-list todo snapshots. */
 const install = Object.assign((ctx, fail) => {
-	for (const session of ctx.sessions.list()) for (const event of session.events) validateEvent(event, fail);
+	const traces = /* @__PURE__ */ new WeakMap();
+	const seed = (session) => {
+		traces.set(session, seedTrace(session, fail));
+	};
+	const traceFor = (session) => {
+		let trace = traces.get(session);
+		if (trace === void 0) {
+			trace = seedTrace(session, fail);
+			traces.set(session, trace);
+		}
+		return trace;
+	};
+	for (const session of ctx.sessions.list()) seed(session);
+	ctx.on("session/created", (session) => {
+		seed(session);
+	}, { global: true });
 	ctx.on("internal/dispatch", (_mode, eventName, args) => {
 		if (eventName !== "session/event") return;
-		const event = args[1];
-		validateEvent(event, fail);
+		const [session, event] = args;
+		validateEvent(event, traceFor(session), fail);
+	}, { global: true });
+	ctx.on("session/event", (session, event) => {
+		advanceTrace(traceFor(session), event);
 	}, { global: true });
 }, { inject: ["sessions"] });
 /**

package/lib/types/index.d.ts

@@ -23,9 +23,9 @@ export interface Config {
 /** Schemastery configuration for the todo tool consumer. */
 export declare const Config: z<Config>;
 /**
- * Register the `todo_write` tool on `ctx.tools` and, when the session-projection seam is composed,
- * the `todos` unit.
- * @param ctx - registrant context carrying the tool registry.
+ * Register the `todo_write` tool on `ctx.tools` and the `todos` unit on
+ * `ctx.sessionProjections`.
+ * @param ctx - registrant context carrying the tool and session-projection registries.
  * @param config - deployment's explicit todo policy.
  */
 export declare function apply(ctx: Context, config: Config): void;

package/lib/types/index.js

@@ -8,7 +8,7 @@ import z from '@deepseek-ai/schemastery';
 import { z as zod } from 'zod';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 export const name = 'tool-todo';
-export const inject = ['tools'];
+export const inject = ['tools', 'sessionProjections'];
 /** The valid {@link TodoItem} statuses, as a runtime set for input narrowing. */
 const STATUSES = ['pending', 'in_progress', 'completed'];
 /** Schemastery configuration for the todo tool consumer. */
@@ -83,33 +83,30 @@ const todosProjectionSchema = zod.union([
     zod.null(),
 ]);
 /**
- * Register the `todo_write` tool on `ctx.tools` and, when the session-projection seam is composed,
- * the `todos` unit.
- * @param ctx - registrant context carrying the tool registry.
+ * Register the `todo_write` tool on `ctx.tools` and the `todos` unit on
+ * `ctx.sessionProjections`.
+ * @param ctx - registrant context carrying the tool and session-projection registries.
  * @param config - deployment's explicit todo policy.
  */
 export function apply(ctx, config) {
     const allowParallel = config.allowParallelInProgress;
-    // The unit child activates only when a projection registry is composed
-    // (headless assemblies without the seam stay unaffected). Standing-plan fold:
-    // latest whole todo/write list, cleared by the next turn/start (turn/end keeps
-    // the finished checklist visible); null before the first write or after a
-    // later turn begins; every other event returns the same state reference.
-    ctx.inject(['sessionProjections'], (projectionCtx) => {
-        projectionCtx.sessionProjections.register({
-            key: 'todos',
-            stateSchema: todosProjectionSchema,
-            init: () => null,
-            apply: (state, event) => {
-                if (event.type === 'todo/write')
-                    return event.data.todos;
-                if (event.type === 'turn/start')
-                    return null;
-                return state;
-            },
-            wire: { viewSchema: todosProjectionSchema, view: state => state },
-            stateVersion: 2,
-        });
+    // Standing-plan fold: latest whole todo/write list, cleared by the next
+    // turn/start (turn/end keeps the finished checklist visible); null before the
+    // first write or after a later turn begins; every other event returns the
+    // same state reference.
+    ctx.sessionProjections.register({
+        key: 'todos',
+        stateSchema: todosProjectionSchema,
+        init: () => null,
+        apply: (state, event) => {
+            if (event.type === 'todo/write')
+                return event.data.todos;
+            if (event.type === 'turn/start')
+                return null;
+            return state;
+        },
+        wire: { viewSchema: todosProjectionSchema, view: state => state },
+        stateVersion: 2,
     });
     ctx.tools.register(defineTool({
         name: 'todo_write',

package/lib/types/invariant.js

@@ -33,23 +33,55 @@ function validateTodos(value, fail) {
         }
     }
 }
-/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
-/** Validate the package-owned event fields and ignore unrelated events. */
-function validateEvent(event, fail) {
-    if (event.type === 'todo/write')
-        validateTodos(event.data.todos, fail);
+/** Advance the trace after one event has committed. */
+function advanceTrace(trace, event) {
+    if (event.type === 'turn/start')
+        trace.open = true;
+    if (event.type === 'turn/end')
+        trace.open = false;
+}
+/** Validate one package-owned event against the preceding committed trace. */
+function validateEvent(event, trace, fail) {
+    if (event.type !== 'todo/write')
+        return;
+    validateTodos(event.data.todos, fail);
+    if (!trace.open)
+        fail('todo/write appended outside any open turn');
+}
+/** Validate one existing log in a single pass and return its tail trace. */
+function seedTrace(session, fail) {
+    const trace = { open: false };
+    for (const event of session.events) {
+        validateEvent(event, trace, fail);
+        advanceTrace(trace, event);
+    }
+    return trace;
 }
 /** Install validation for loaded and newly appended whole-list todo snapshots. */
 const install = Object.assign((ctx, fail) => {
-    for (const session of ctx.sessions.list()) {
-        for (const event of session.events)
-            validateEvent(event, fail);
-    }
+    const traces = new WeakMap();
+    const seed = (session) => {
+        traces.set(session, seedTrace(session, fail));
+    };
+    const traceFor = (session) => {
+        let trace = traces.get(session);
+        if (trace === undefined) {
+            trace = seedTrace(session, fail);
+            traces.set(session, trace);
+        }
+        return trace;
+    };
+    for (const session of ctx.sessions.list())
+        seed(session);
+    ctx.on('session/created', (session) => { seed(session); }, { global: true });
     ctx.on('internal/dispatch', (_mode, eventName, args) => {
         if (eventName !== 'session/event')
             return;
-        const event = args[1];
-        validateEvent(event, fail);
+        const [session, event] = args;
+        validateEvent(event, traceFor(session), fail);
+    }, { global: true });
+    ctx.on('session/event', (session, event) => {
+        advanceTrace(traceFor(session), event);
     }, { global: true });
 }, { inject: ['sessions'] });
 /* jscpd:ignore-end */

package/lib/types/types.d.ts

@@ -7,8 +7,30 @@
  *
  * @module @deepseek-ai/dsh-tool-todo/types
  */
-import type { TodoItem } from '@deepseek-ai/dsh-session/types';
-export type { TodoItem } from '@deepseek-ai/dsh-session/types';
+/**
+ * One entry in an agent's todo list — the unit of the `todo/write`
+ * whole-list snapshot declared by this package.
+ *
+ * Deliberately minimal: a human-readable `content` line and a three-state
+ * `status`. No id, priority, or `activeForm` — the list is replaced wholesale
+ * on every write (last-write-wins), so entries need no stable identity. The
+ * three statuses describe the complete portable lifecycle needed by model and
+ * UI consumers.
+ */
+export interface TodoItem {
+    /** What this task is — a short imperative line shown in the UI. */
+    content: string;
+    /** Lifecycle state. `in_progress` marks a task being worked now; parallel work may mark several. */
+    status: 'pending' | 'in_progress' | 'completed';
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** Whole-list snapshot; latest write wins on replay. Log-only UI state; never derived history. */
+        'todo/write': {
+            todos: TodoItem[];
+        };
+    }
+}
 declare module '@deepseek-ai/dsh-session-projection/types' {
     interface SessionProjectionStateMap {
         todos: TodoItem[] | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-todo",
   "description": "Model-facing todo_write tool over the DeepSeek Harness event-sourced session log",
-  "version": "0.1.1-rc.1",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,30 +38,29 @@
   "license": "MIT",
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.1"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-host-apiproxy": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
-    "@deepseek-ai/dsh-user-questions": "^0.1.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-user-questions": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }