@hydraharness/harness-tool-todo 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @hydraharness/harness-tool-todo
+
+The model-facing `todo_write` tool: the agent's whole task list, replaced wholesale on each call.
+
+The todo projection follows the selected transcript version and refolds on version creation or selection.
+
+## 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`, `completed`, `blocked`, `failed`, or `cancelled`. Completion requires a verified outcome. Blocked work lacks a prerequisite, failed work has an unsuccessful attempt, and cancelled work is abandoned; the content states the reason. Unfinished work must agree with result files and the final answer. The [evidence decision](../../../.agents/notes/implemented/bug-fix/2026-10-01-browser-evidence-and-result-validation.md) owns these distinctions.
+
+## 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, blocked, failed, cancelled } }`; 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)). Non-completion outcomes have distinct text labels and never contribute to the completed count.
+
+## Session projection
+
+When [`ctx.sessionProjections`](../../session/session-projection/README.md) is mounted, an injected child registers `todos` with `stateVersion:3` and an identity view. The initial value is `null`; each `todo/write` replaces the list and each `turn/start` clears it. `turn/end` keeps the checklist, and other events retain the same reference. This package merges the key into `SessionProjectionMap` through the Service Definition's `/types` export. The framework serves it on the history tail page and `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#hydraharness-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 `Updated todo list: <pending> pending, <inProgress> in progress, <completed> completed.` When unfinished outcomes exist, it appends `, <blocked> blocked, <failed> failed, <cancelled> cancelled` before the period. 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.
+- **Completion verification is model guidance** — the tool records statuses without proving arbitrary task outcomes. 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/lib/index.js

@@ -0,0 +1,213 @@
+import z from "@hydraharness/schemastery";
+import { z as z$1 } from "zod";
+import { defineTool } from "@hydraharness/harness-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 @hydraharness/harness-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",
+	"blocked",
+	"failed",
+	"cancelled"
+];
+/** Schemastery configuration for the todo tool consumer. */
+const Config = z.object({ allowParallelInProgress: z.boolean().required() });
+const DESCRIPTION_HEAD = "Replace the current task list with the ENTIRE todos array on each call. Plan concrete steps before multi-step work; skip trivial tasks. ";
+const DESCRIPTION_PARALLEL = "While work can proceed, mark active tasks `in_progress`; several only for concurrent work. ";
+const DESCRIPTION_SINGLE = "While work can proceed, keep exactly one todo `in_progress`. ";
+const DESCRIPTION_TAIL = "Mark `completed` only after verifying the outcome. Use `blocked` for missing prerequisites, `failed` for unsuccessful attempts, `cancelled` for abandoned work; put the reason in content. Keep statuses consistent with deliverables and the final answer.";
+/**
+* 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.enum(STATUSES)
+})), 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",
+			history: "active-version",
+			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: 4
+		});
+	});
+	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 (verified done) | blocked (missing prerequisite) | failed (unsuccessful) | cancelled (abandoned)."
+					}
+				}
+			}
+		} },
+		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
+							},
+							blocked: {
+								type: "integer",
+								required: true
+							},
+							failed: {
+								type: "integer",
+								required: true
+							},
+							cancelled: {
+								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` + (value.counts.blocked + value.counts.failed + value.counts.cancelled > 0 ? `, ${value.counts.blocked} blocked, ${value.counts.failed} failed, ${value.counts.cancelled} cancelled.` : ".")
+			}]
+		},
+		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"),
+					blocked: count("blocked"),
+					failed: count("failed"),
+					cancelled: count("cancelled")
+				}
+			});
+		},
+		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,57 @@
+//#region lib/types/invariant.js
+/** Package-owned durable todo-snapshot invariants. @module @hydraharness/harness-tool-todo/invariant */
+const PACKAGE_NAME = "@hydraharness/harness-tool-todo";
+const TODO_STATUSES = new Set([
+	"pending",
+	"in_progress",
+	"completed",
+	"blocked",
+	"failed",
+	"cancelled"
+]);
+/** 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 @hydraharness/harness-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 @hydraharness/harness-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 @hydraharness/harness-tool-todo
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/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,193 @@
+/**
+ * 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 @hydraharness/harness-tool-todo
+ */
+import z from '@hydraharness/schemastery';
+import { z as zod } from 'zod';
+import { defineTool } from '@hydraharness/harness-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', 'blocked', 'failed', 'cancelled'];
+/** Schemastery configuration for the todo tool consumer. */
+export const Config = z.object({
+    allowParallelInProgress: z.boolean().required(),
+});
+const DESCRIPTION_HEAD = 'Replace the current task list with the ENTIRE todos array on each call. '
+    + 'Plan concrete steps before multi-step work; skip trivial tasks. ';
+const DESCRIPTION_PARALLEL = 'While work can proceed, mark active tasks `in_progress`; several only for concurrent work. ';
+const DESCRIPTION_SINGLE = 'While work can proceed, keep exactly one todo `in_progress`. ';
+const DESCRIPTION_TAIL = 'Mark `completed` only after verifying the outcome. Use `blocked` for missing prerequisites, '
+    + '`failed` for unsuccessful attempts, `cancelled` for abandoned work; put the reason in content. '
+    + 'Keep statuses consistent with deliverables and the final answer.';
+/**
+ * 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.enum(STATUSES),
+    })),
+    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',
+            history: 'active-version',
+            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: 4,
+        });
+    });
+    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 (verified done) | blocked (missing prerequisite) | failed (unsuccessful) | cancelled (abandoned).',
+                        },
+                    },
+                },
+            },
+        },
+        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 },
+                            blocked: { type: 'integer', required: true },
+                            failed: { type: 'integer', required: true },
+                            cancelled: { 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`
+                        + (value.counts.blocked + value.counts.failed + value.counts.cancelled > 0
+                            ? `, ${value.counts.blocked} blocked, ${value.counts.failed} failed, ${value.counts.cancelled} cancelled.` : '.'),
+                }],
+        },
+        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'),
+                    blocked: count('blocked'),
+                    failed: count('failed'),
+                    cancelled: count('cancelled'),
+                },
+            });
+        },
+        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 @hydraharness/harness-tool-todo/invariant */
+import type { Context } from '@hydraharness/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 @hydraharness/harness-tool-todo/invariant */
+const PACKAGE_NAME = '@hydraharness/harness-tool-todo';
+const TODO_STATUSES = new Set(['pending', 'in_progress', 'completed', 'blocked', 'failed', 'cancelled']);
+/** 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,25 @@
+/**
+ * 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 (@hydraharness/harness-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 @hydraharness/harness-tool-todo/types
+ */
+import type { TodoItem } from '@hydraharness/harness-session/types';
+export type { TodoItem } from '@hydraharness/harness-session/types';
+declare module '@hydraharness/harness-session-projection/types' {
+    interface SessionProjectionStateMap {
+        todos: TodoItem[] | null;
+    }
+    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 (@hydraharness/harness-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 @hydraharness/harness-tool-todo/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@hydraharness/harness-tool-todo",
+  "description": "Model-facing todo_write tool over the Hydra harness event-sourced session log",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent maintain a visible task list within the conversation."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-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": "MIT",
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6"
+  },
+  "devDependencies": {
+    "@hydraharness/cordis-plugin-include": "^1.0.7",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop-testkit": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent-loop": "^0.1.1-rc.6",
+    "@hydraharness/harness-host-apiproxy": "^0.1.1-rc.6",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session-projection": "^0.1.1-rc.6",
+    "@hydraharness/harness-system-prompt": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/harness-user-questions": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}