@deepseek-ai/dsh-tool-todo 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/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 packages/todo/tool-todo/README.md
+README.md: 4848758dd8f2049221901744e5d09cef2dd31591
+README.zh.md: 39cb243d1cf59bf51e524a9a778f67e841ae16ff

package/README.md

@@ -0,0 +1,73 @@
+# @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
+
+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).
+
+`status` is one of `pending`, `in_progress`, or `completed`.
+
+## Single owner
+
+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.
+
+## Configuration
+
+`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.
+
+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.
+
+## Validation
+
+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.
+
+## Rendering
+
+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)).
+
+## 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).
+
+## Export shape
+
+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)).
+
+## Model Experience
+
+### Tool schema
+
+#### What the model sees
+
+The model sees the generated [`todo_write` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-todo).
+
+#### Token effect
+
+Fixed schema cost on every request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the definition and visibility are unchanged. Plugin lifecycle or scoped restrictions may invalidate reuse from this schema.
+
+### Tool-call history and result
+
+#### What the model sees
+
+Each assistant tool call retains the entire replacement list in its arguments. Success returns exactly `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` Stable failures are ``Error: invalid todo: `content` must be a non-empty string``, `Error: invalid todos: duplicate content "<content>"`, `Error: todo_write requires an owning agent session`, and — only where the deployment set `allowParallelInProgress: false` — `Error: invalid todos: at most one task may be in_progress (got <n>)`. The full `todo/write` session event is UI and replay state, not a second model message.
+
+#### Token effect
+
+Token growth scales with every full list the model submits, and those call arguments remain until compaction. The result itself is small and fixed-shape.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## 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.
+- **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.

package/README.zh.md

@@ -0,0 +1,73 @@
+# @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（agent 决策记录）。
+
+## 配置
+
+`allowParallelInProgress` 是必填项：每个组合都必须选择是否允许多个 todo 同时处于 `in_progress`。这是部署层的选择而非固定规则：并发的活跃任务是否合理，取决于工具无法观测的运行时并发情况。可能并行展开工作的 agent 使用 `true`，`false` 则强制执行单活跃项纪律。
+
+该开关会同时改变面向模型的指令与接受的输入——`true` 要求模型标记每个正在推进的任务并接受任意数量；`false` 要求恰好一个，并以 `Error: invalid todos: at most one task may be in_progress (got <n>)` 拒绝标记更多的调用。持久日志不变式**不**跟随它：在允许并行时写下的日志，在部署收紧策略之后仍必须可回放，因此不变式对活跃数量保持沉默。
+
+## 验证
+
+除 schema 的类型／必填／枚举检查外，`execute` 还会拒绝空或重复的 `content`，以及 `content`/`status` 之外的任何条目键——扩展条目形状（id、嵌套）会明确报错而不是被静默压平，保证落日志的快照与模型自认为写入的内容一致。同时可以有多少任务处于 `in_progress` 由部署决定（见 § 配置）：选择 `true` 的组合允许并行工作（并发 subagent、后台命令）同时将多个任务标记为 `in_progress`。列表的顺序及及时更新由模型依照工具描述负责。
+
+## 渲染
+
+规范结果为 `{ 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.md)、[生命周期](../../../.agents/notes/implemented/feature/2026-07-28-todo-plan-clears-on-next-turn.md)）。
+
+## 会话投影
+
+当组合挂载了 `ctx.sessionProjections`（[`@deepseek-ai/dsh-session-projection`](../../session/session-projection/README.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.md)。
+
+## 导出形状
+
+函数／命名空间插件：导出 `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 token 开销。
+
+#### 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: 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）。结果本身很小，且形状固定。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **仅单一所有者 scope**：列表属于唯一调用 agent 会话；subagent／共享／swarm scope 是有意设置的限制（参见「单一所有者」一节），非 agent 调用方会被拒绝。
+- **条目形状有意保持最小**：`content` 加三态 `status`；整表替换不需要稳定 id、优先级或 active-form 字段。
+- **整表替换是唯一操作**：没有部分更新，也没有回读工具；模型每次调用都必须重新发送完整列表。

package/lib/index.js

@@ -0,0 +1,195 @@
+import z from "@deepseek-ai/schemastery";
+import { z as z$1 } from "zod";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/**
+* Model-facing whole-list replacement. Each call appends a `todo/write` snapshot to the calling
+* agent's session; replay is last-write-wins, and UIs render from session events. A non-agent
+* caller has no owning list and is rejected. Named exports preserve loader injection metadata.
+* @module @deepseek-ai/dsh-tool-todo
+*/
+const name = "tool-todo";
+const inject = ["tools"];
+/** 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. */
+const Config = z.object({ allowParallelInProgress: z.boolean().required() });
+const DESCRIPTION_HEAD = "Record and update a structured task list for the current work. Send the ENTIRE list every call — it REPLACES the previous list (there are no partial updates, no per-item edits). Use it to plan multi-step work and show progress: add one todo per concrete step before you start. ";
+const DESCRIPTION_PARALLEL = "Mark every todo being actively worked on `in_progress` — several at once when work genuinely runs in parallel (e.g. concurrent subagents or background commands), one for sequential work; while work remains, at least one task should be `in_progress`. ";
+const DESCRIPTION_SINGLE = "Keep AT MOST ONE todo `in_progress` at a time; while work remains, exactly one active task should be `in_progress`. ";
+const DESCRIPTION_TAIL = "Mark a todo `completed` the moment it is done (do not batch completions), and allow no `in_progress` item only once all work is complete. Skip the list for trivial single-step tasks. Statuses: `pending` (not started), `in_progress` (being worked on now), `completed` (finished).";
+/**
+* The model-facing description for one activation. The active-status clause is the only part that
+* varies, because it is the only instruction the parallel policy changes.
+* @param allowParallel - whether several todos may be `in_progress` at once.
+* @returns the composed tool description.
+*/
+function describe(allowParallel) {
+	return DESCRIPTION_HEAD + (allowParallel ? DESCRIPTION_PARALLEL : DESCRIPTION_SINGLE) + DESCRIPTION_TAIL;
+}
+/**
+* Validate the value constraints the ParameterSchemaSpec can't express and build the canonical {@link
+* TodoItem}[]: trimmed non-empty unique content, and at most one `in_progress` item unless the
+* deployment allows parallel work. The registry has already enforced the status enum and rejected
+* unknown item keys (`additionalProperties: false` — the logged snapshot must equal what the model
+* believes it wrote, so a nested/extended item shape fails loud at the schema boundary instead of
+* silently flattening); the cast below records that guarantee.
+* @param raw - the model-supplied list, already schema-checked.
+* @param allowParallel - whether several items may be `in_progress` at once.
+* @returns the canonical list.
+*/
+function toTodoList(raw, allowParallel) {
+	const todos = [];
+	const seen = /* @__PURE__ */ new Set();
+	let active = 0;
+	for (const item of raw) {
+		const content = item.content.trim();
+		if (content.length === 0) throw new Error("invalid todo: `content` must be a non-empty string");
+		if (seen.has(content)) throw new Error(`invalid todos: duplicate content ${JSON.stringify(content)}`);
+		seen.add(content);
+		if (item.status === "in_progress") active++;
+		todos.push({
+			content,
+			status: item.status
+		});
+	}
+	if (!allowParallel && active > 1) throw new Error(`invalid todos: at most one task may be in_progress (got ${active})`);
+	return todos;
+}
+/** Wire payload schema of the `todos` projection (whole list or pre-first-write null). */
+const todosProjectionSchema = z$1.union([z$1.array(z$1.object({
+	content: z$1.string(),
+	status: z$1.union([
+		z$1.literal("pending"),
+		z$1.literal("in_progress"),
+		z$1.literal("completed")
+	])
+})), 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.
+* @param config - deployment's explicit todo policy.
+*/
+function apply(ctx, config) {
+	const allowParallel = config.allowParallelInProgress;
+	ctx.inject(["sessionProjections"], (projectionCtx) => {
+		projectionCtx.sessionProjections.register({
+			key: "todos",
+			schema: todosProjectionSchema,
+			init: () => null,
+			apply: (state, event) => {
+				if (event.type === "todo/write") return event.data.todos;
+				if (event.type === "turn/start") return null;
+				return state;
+			},
+			view: (state) => state,
+			stateVersion: 2
+		});
+	});
+	ctx.tools.register(defineTool({
+		name: "todo_write",
+		description: describe(allowParallel),
+		parameters: { todos: {
+			type: "array",
+			required: true,
+			description: "The COMPLETE task list, replacing any previous list.",
+			items: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					content: {
+						type: "string",
+						required: true,
+						description: "What the task is — a short imperative line."
+					},
+					status: {
+						type: "string",
+						required: true,
+						enum: [...STATUSES],
+						description: "pending (not started) | in_progress (now) | completed (done)."
+					}
+				}
+			}
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					todos: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								content: {
+									type: "string",
+									required: true
+								},
+								status: {
+									type: "string",
+									required: true,
+									enum: [...STATUSES]
+								}
+							}
+						}
+					},
+					counts: {
+						type: "object",
+						additionalProperties: false,
+						required: true,
+						properties: {
+							pending: {
+								type: "integer",
+								required: true
+							},
+							inProgress: {
+								type: "integer",
+								required: true
+							},
+							completed: {
+								type: "integer",
+								required: true
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Updated todo list: ${value.counts.pending} pending, ${value.counts.inProgress} in progress, ${value.counts.completed} completed.`
+			}]
+		},
+		execute(args, exec) {
+			const todos = toTodoList(args.todos, allowParallel);
+			if (!exec.agent) throw new Error("todo_write requires an owning agent session");
+			exec.agent.session.append("todo/write", { todos });
+			const count = (status) => todos.filter((t) => t.status === status).length;
+			return Promise.resolve({
+				todos: todos.map((todo) => ({
+					content: todo.content,
+					status: todo.status
+				})),
+				counts: {
+					pending: count("pending"),
+					inProgress: count("in_progress"),
+					completed: count("completed")
+				}
+			});
+		},
+		presentCall: (args) => ({
+			card: "generic",
+			title: "Update todo list",
+			kind: "other",
+			rawInput: args.todos
+		})
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,54 @@
+//#region lib/types/invariant.js
+/** Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant */
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-todo";
+const TODO_STATUSES = new Set([
+	"pending",
+	"in_progress",
+	"completed"
+]);
+/** Cordis companion plugin name. */
+const name = "tool-todo-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Validate one whole-list todo snapshot before it reaches the durable log.
+*
+* Deliberately silent on how many items are `in_progress`. That is the tool's
+* per-deployment policy (`Config.allowParallelInProgress`), not a durable-shape
+* rule: a log written while parallel work was allowed must still replay after a
+* deployment tightens the policy, so tying the invariant to the current config
+* would reject history that was valid when it was written.
+*/
+function validateTodos(value, fail) {
+	if (!Array.isArray(value)) fail("todo/write todos must be an array");
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) fail("todo/write entries must be objects");
+		const { content, status } = item;
+		if (typeof content !== "string" || content.length === 0 || content.trim() !== content) fail("todo/write content must be non-empty and already trimmed");
+		if (seen.has(content)) fail(`todo/write repeats content ${JSON.stringify(content)}`);
+		seen.add(content);
+		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);
+}
+/** 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);
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const event = args[1];
+		validateEvent(event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the todo invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/client.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the todo domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-tool-todo/client
+ */
+export type * from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,10 @@
+/**
+ * Client-namespace projection of the todo domain: a pure re-export of the package's
+ * types outlet. Client code imports ONLY the client namespace (repo
+ * discipline), so `./client` projects the same single-source content
+ * `./types` serves to host consumers — zero duplication.
+ *
+ * @module @deepseek-ai/dsh-tool-todo/client
+ */
+export {};
+//# sourceMappingURL=client.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Model-facing whole-list replacement. Each call appends a `todo/write` snapshot to the calling
+ * agent's session; replay is last-write-wins, and UIs render from session events. A non-agent
+ * caller has no owning list and is rejected. Named exports preserve loader injection metadata.
+ * @module @deepseek-ai/dsh-tool-todo
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export type * from './types.ts';
+export declare const name = "tool-todo";
+export declare const inject: string[];
+/** Model-facing todo tool configuration. */
+export interface Config {
+    /**
+     * Required deployment choice for whether several todos may be `in_progress` at once. True suits
+     * agents that run work concurrently — subagents, background commands, workflow fan-out — and the
+     * description then instructs the model to mark every actively worked task. False restores the
+     * single-active discipline: the description asks for exactly one, and a call marking more is
+     * rejected.
+     */
+    allowParallelInProgress: boolean;
+}
+/** 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.
+ * @param config - deployment's explicit todo policy.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,192 @@
+/**
+ * Model-facing whole-list replacement. Each call appends a `todo/write` snapshot to the calling
+ * agent's session; replay is last-write-wins, and UIs render from session events. A non-agent
+ * caller has no owning list and is rejected. Named exports preserve loader injection metadata.
+ * @module @deepseek-ai/dsh-tool-todo
+ */
+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'];
+/** 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. */
+export const Config = z.object({
+    allowParallelInProgress: z.boolean().required(),
+});
+const DESCRIPTION_HEAD = 'Record and update a structured task list for the current work. Send the ENTIRE '
+    + 'list every call — it REPLACES the previous list (there are no partial updates, '
+    + 'no per-item edits). Use it to plan multi-step work and show progress: add one '
+    + 'todo per concrete step before you start. ';
+const DESCRIPTION_PARALLEL = 'Mark every todo being actively worked '
+    + 'on `in_progress` — several at once when work genuinely runs in parallel (e.g. '
+    + 'concurrent subagents or background commands), one for sequential work; while '
+    + 'work remains, at least one task should be `in_progress`. ';
+const DESCRIPTION_SINGLE = 'Keep AT MOST ONE todo `in_progress` at a '
+    + 'time; while work remains, exactly one active task should be `in_progress`. ';
+const DESCRIPTION_TAIL = 'Mark a todo '
+    + '`completed` the moment it is done (do not batch completions), and allow no '
+    + '`in_progress` item only once all work is complete. Skip the list for trivial '
+    + 'single-step tasks. Statuses: `pending` (not started), `in_progress` (being '
+    + 'worked on now), `completed` (finished).';
+/**
+ * The model-facing description for one activation. The active-status clause is the only part that
+ * varies, because it is the only instruction the parallel policy changes.
+ * @param allowParallel - whether several todos may be `in_progress` at once.
+ * @returns the composed tool description.
+ */
+function describe(allowParallel) {
+    return DESCRIPTION_HEAD
+        + (allowParallel ? DESCRIPTION_PARALLEL : DESCRIPTION_SINGLE)
+        + DESCRIPTION_TAIL;
+}
+/**
+ * Validate the value constraints the ParameterSchemaSpec can't express and build the canonical {@link
+ * TodoItem}[]: trimmed non-empty unique content, and at most one `in_progress` item unless the
+ * deployment allows parallel work. The registry has already enforced the status enum and rejected
+ * unknown item keys (`additionalProperties: false` — the logged snapshot must equal what the model
+ * believes it wrote, so a nested/extended item shape fails loud at the schema boundary instead of
+ * silently flattening); the cast below records that guarantee.
+ * @param raw - the model-supplied list, already schema-checked.
+ * @param allowParallel - whether several items may be `in_progress` at once.
+ * @returns the canonical list.
+ */
+function toTodoList(raw, allowParallel) {
+    const todos = [];
+    const seen = new Set();
+    let active = 0;
+    for (const item of raw) {
+        const content = item.content.trim();
+        if (content.length === 0) {
+            throw new Error('invalid todo: `content` must be a non-empty string');
+        }
+        if (seen.has(content)) {
+            throw new Error(`invalid todos: duplicate content ${JSON.stringify(content)}`);
+        }
+        seen.add(content);
+        if (item.status === 'in_progress')
+            active++;
+        todos.push({ content, status: item.status });
+    }
+    if (!allowParallel && active > 1) {
+        throw new Error(`invalid todos: at most one task may be in_progress (got ${active})`);
+    }
+    return todos;
+}
+/** Wire payload schema of the `todos` projection (whole list or pre-first-write null). */
+const todosProjectionSchema = zod.union([
+    zod.array(zod.object({
+        content: zod.string(),
+        status: zod.union([zod.literal('pending'), zod.literal('in_progress'), zod.literal('completed')]),
+    })),
+    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.
+ * @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',
+            schema: todosProjectionSchema,
+            init: () => null,
+            apply: (state, event) => {
+                if (event.type === 'todo/write')
+                    return event.data.todos;
+                if (event.type === 'turn/start')
+                    return null;
+                return state;
+            },
+            view: state => state,
+            stateVersion: 2,
+        });
+    });
+    ctx.tools.register(defineTool({
+        name: 'todo_write',
+        description: describe(allowParallel),
+        parameters: {
+            todos: {
+                type: 'array',
+                required: true,
+                description: 'The COMPLETE task list, replacing any previous list.',
+                items: {
+                    type: 'object',
+                    additionalProperties: false,
+                    properties: {
+                        content: { type: 'string', required: true, description: 'What the task is — a short imperative line.' },
+                        status: {
+                            type: 'string',
+                            required: true,
+                            enum: [...STATUSES],
+                            description: 'pending (not started) | in_progress (now) | completed (done).',
+                        },
+                    },
+                },
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    todos: {
+                        type: 'array',
+                        required: true,
+                        items: {
+                            type: 'object',
+                            additionalProperties: false,
+                            properties: {
+                                content: { type: 'string', required: true },
+                                status: { type: 'string', required: true, enum: [...STATUSES] },
+                            },
+                        },
+                    },
+                    counts: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: true,
+                        properties: {
+                            pending: { type: 'integer', required: true },
+                            inProgress: { type: 'integer', required: true },
+                            completed: { type: 'integer', required: true },
+                        },
+                    },
+                },
+            },
+            render: (_args, value) => [{
+                    type: 'text',
+                    text: `Updated todo list: ${value.counts.pending} pending, ${value.counts.inProgress} in progress, ${value.counts.completed} completed.`,
+                }],
+        },
+        execute(args, exec) {
+            const todos = toTodoList(args.todos, allowParallel);
+            if (!exec.agent) {
+                // The list is per-agent-session state; a non-agent caller (no owning
+                // session) has nowhere to write it. Reject rather than silently no-op.
+                throw new Error('todo_write requires an owning agent session');
+            }
+            exec.agent.session.append('todo/write', { todos });
+            const count = (status) => todos.filter(t => t.status === status).length;
+            return Promise.resolve({
+                todos: todos.map(todo => ({ content: todo.content, status: todo.status })),
+                counts: {
+                    pending: count('pending'),
+                    inProgress: count('in_progress'),
+                    completed: count('completed'),
+                },
+            });
+        },
+        presentCall: args => ({ card: 'generic', title: 'Update todo list', kind: 'other', rawInput: args.todos }),
+    }));
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-todo-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the todo invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,62 @@
+/** Package-owned durable todo-snapshot invariants. @module @deepseek-ai/dsh-tool-todo/invariant */
+const PACKAGE_NAME = '@deepseek-ai/dsh-tool-todo';
+const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed']);
+/** Cordis companion plugin name. */
+export const name = 'tool-todo-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * Validate one whole-list todo snapshot before it reaches the durable log.
+ *
+ * Deliberately silent on how many items are `in_progress`. That is the tool's
+ * per-deployment policy (`Config.allowParallelInProgress`), not a durable-shape
+ * rule: a log written while parallel work was allowed must still replay after a
+ * deployment tightens the policy, so tying the invariant to the current config
+ * would reject history that was valid when it was written.
+ */
+function validateTodos(value, fail) {
+    if (!Array.isArray(value))
+        fail('todo/write todos must be an array');
+    const seen = new Set();
+    for (const item of value) {
+        if (typeof item !== 'object' || item === null)
+            fail('todo/write entries must be objects');
+        const { content, status } = item;
+        if (typeof content !== 'string' || content.length === 0 || content.trim() !== content) {
+            fail('todo/write content must be non-empty and already trimmed');
+        }
+        if (seen.has(content))
+            fail(`todo/write repeats content ${JSON.stringify(content)}`);
+        seen.add(content);
+        if (typeof status !== 'string' || !TODO_STATUSES.has(status)) {
+            fail(`todo/write carries unknown status ${JSON.stringify(status)}`);
+        }
+    }
+}
+/* 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);
+}
+/** 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);
+    }
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const event = args[1];
+        validateEvent(event, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * Register the todo invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure types of the todo domain: the ONE home of the `todos` projection-key
+ * declaration plus its payload types, free of this package's host-side value
+ * imports (dsh-tools, zod). Two namespace projections serve it — `./types`
+ * for host consumers, `./client/types` (the browser half-entry's re-export)
+ * for client aggregates — with zero content duplication.
+ *
+ * @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';
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /**
+         * The agent's current whole todo list (the latest `todo/write` snapshot),
+         * or `null` before the first write. Whole-value rule: every `todo/write`
+         * carries the complete replacement list, so the fold is last-wins.
+         */
+        todos: TodoItem[] | null;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,11 @@
+/**
+ * Pure types of the todo domain: the ONE home of the `todos` projection-key
+ * declaration plus its payload types, free of this package's host-side value
+ * imports (dsh-tools, zod). Two namespace projections serve it — `./types`
+ * for host consumers, `./client/types` (the browser half-entry's re-export)
+ * for client aggregates — with zero content duplication.
+ *
+ * @module @deepseek-ai/dsh-tool-todo/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@deepseek-ai/dsh-tool-todo",
+  "description": "Model-facing todo_write tool over the DeepSeek Harness event-sourced session log",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/todo/tool-todo"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "^1.0.5-rc.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session-projection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-user-interaction": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}