@asterxsk/kiln 0.1.0

package/agent/extensions/todo/package.json

@@ -0,0 +1,67 @@
+{
+	"name": "@juicesharp/rpiv-todo",
+	"version": "1.20.0",
+	"description": "Pi extension. A todo list for the model, rendered as a live overlay that survives /reload and conversation compaction.",
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"rpiv",
+		"todo"
+	],
+	"type": "module",
+	"license": "MIT",
+	"author": "juicesharp",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/juicesharp/rpiv-mono.git",
+		"directory": "packages/rpiv-todo"
+	},
+	"homepage": "https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo#readme",
+	"bugs": {
+		"url": "https://github.com/juicesharp/rpiv-mono/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"test": "vitest run"
+	},
+	"files": [
+		"config.ts",
+		"index.ts",
+		"locales/",
+		"todo.ts",
+		"todo-overlay.ts",
+		"LICENSE",
+		"README.md",
+		"state/invariants.ts",
+		"state/i18n-bridge.ts",
+		"state/replay.ts",
+		"state/selectors.ts",
+		"state/state-reducer.ts",
+		"state/state.ts",
+		"state/store.ts",
+		"state/task-graph.ts",
+		"tool/response-envelope.ts",
+		"tool/types.ts",
+		"view/format.ts"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@juicesharp/rpiv-i18n": "*",
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"peerDependenciesMeta": {
+		"@juicesharp/rpiv-i18n": {
+			"optional": true
+		}
+	},
+	"dependencies": {}
+}

package/agent/extensions/todo/state/i18n-bridge.ts

@@ -0,0 +1,64 @@
+/**
+ * i18n bridge for rpiv-todo — single thin import surface so every call site
+ * routes through one module. Backed by `@juicesharp/rpiv-i18n`'s SDK when
+ * available; degrades to canonical-English fallbacks when not.
+ *
+ * - `t(key, fallback)` is `scope("@juicesharp/rpiv-todo")` if the SDK is
+ *   installed (live `/languages` updates propagate). If the SDK is missing
+ *   (standalone install without rpiv-i18n), `t` is an identity passthrough
+ *   that returns the inline English fallback at every call site, so the
+ *   extension stays online with English UI.
+ * - `formatStatusLabel(status)` resolves a TaskStatus to its locale-aware
+ *   label via the canonical `status.*` namespace, with the English literal
+ *   as fallback so nothing renders blank if the namespace isn't registered.
+ *   This is the SINGLE point of localization for status words — overlay,
+ *   /todos header, /todos render-call all route through here.
+ *
+ * Strings are registered ONCE at extension load (see ../index.ts). Call sites
+ * MUST use this module at render time — never bake the result into a top-level
+ * `const X = formatStatusLabel(...)`.
+ */
+
+import type { TaskStatus } from "../tool/types.js";
+
+export const I18N_NAMESPACE = "@juicesharp/rpiv-todo";
+
+type ScopeFn = (key: string, fallback: string) => string;
+type I18nSDK = { scope: (namespace: string) => ScopeFn };
+
+// Prefer the live SDK if installed: closures it returns track the active
+// locale, so /languages picker propagates to our render call sites. If the
+// SDK isn't installed (standalone install of this extension without
+// rpiv-i18n), the dynamic import fails, every t(key, fallback) returns the
+// canonical English literal, and the extension stays online.
+//
+// Top-level await is required so a synchronous `t(...)` call from any
+// downstream module sees the resolved scope; ESM module loading awaits this
+// before evaluating any importer.
+let scopeImpl: ScopeFn;
+try {
+	const sdk = (await import("@juicesharp/rpiv-i18n")) as I18nSDK;
+	scopeImpl = sdk.scope(I18N_NAMESPACE);
+} catch {
+	scopeImpl = (_key, fallback) => fallback;
+}
+
+export const t: ScopeFn = scopeImpl;
+
+const STATUS_LABEL_PENDING = "pending";
+const STATUS_LABEL_IN_PROGRESS = "in progress";
+const STATUS_LABEL_COMPLETED = "completed";
+const STATUS_LABEL_DELETED = "deleted";
+
+export function formatStatusLabel(status: TaskStatus): string {
+	switch (status) {
+		case "pending":
+			return t("status.pending", STATUS_LABEL_PENDING);
+		case "in_progress":
+			return t("status.in_progress", STATUS_LABEL_IN_PROGRESS);
+		case "completed":
+			return t("status.completed", STATUS_LABEL_COMPLETED);
+		case "deleted":
+			return t("status.deleted", STATUS_LABEL_DELETED);
+	}
+}

package/agent/extensions/todo/state/invariants.ts

@@ -0,0 +1,20 @@
+import type { TaskStatus } from "../tool/types.js";
+
+/**
+ * Allowed forward transitions per source status. `completed` is one-way to
+ * `deleted` (never back to `in_progress`); `deleted` is terminal.
+ *
+ * Idempotent same→same is checked separately in `isTransitionValid` so this
+ * table only enumerates actual transitions.
+ */
+export const VALID_TRANSITIONS: Record<TaskStatus, ReadonlySet<TaskStatus>> = {
+	pending: new Set(["in_progress", "completed", "deleted"]),
+	in_progress: new Set(["pending", "completed", "deleted"]),
+	completed: new Set(["deleted"]),
+	deleted: new Set(),
+};
+
+export function isTransitionValid(from: TaskStatus, to: TaskStatus): boolean {
+	if (from === to) return true;
+	return VALID_TRANSITIONS[from].has(to);
+}

package/agent/extensions/todo/state/replay.ts

@@ -0,0 +1,38 @@
+import type { TaskDetails } from "../tool/types.js";
+import { EMPTY_STATE, type TaskState } from "./state.js";
+
+/**
+ * Discriminator for `details` envelopes that match the persisted `TaskDetails`
+ * shape. Defensive — branch entries from older or corrupt sessions are
+ * skipped silently.
+ */
+export function isTaskDetails(value: unknown): value is TaskDetails {
+	if (!value || typeof value !== "object") return false;
+	const v = value as Record<string, unknown>;
+	return Array.isArray(v.tasks) && typeof v.nextId === "number";
+}
+
+/**
+ * Walk the current branch in chronological order; the LAST `toolResult` whose
+ * `toolName === "todo"` and whose `details` shape matches `TaskDetails` wins
+ * (last-write-wins). When no matching entry exists, returns `EMPTY_STATE`.
+ *
+ * Pure of module state — `index.ts` writes the returned snapshot into the
+ * store after this returns. The function explicitly does NOT touch the store
+ * cell.
+ */
+export function replayFromBranch(ctx: { sessionManager: { getBranch(): Iterable<unknown> } }): TaskState {
+	let result: TaskState = { tasks: [...EMPTY_STATE.tasks], nextId: EMPTY_STATE.nextId };
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const e = entry as { type?: string; message?: { role?: string; toolName?: string; details?: unknown } };
+		if (e.type !== "message") continue;
+		const msg = e.message;
+		if (msg?.role !== "toolResult" || msg.toolName !== "todo") continue;
+		if (!isTaskDetails(msg.details)) continue;
+		result = {
+			tasks: msg.details.tasks.map((t) => ({ ...t })),
+			nextId: msg.details.nextId,
+		};
+	}
+	return result;
+}

package/agent/extensions/todo/state/selectors.ts

@@ -0,0 +1,107 @@
+import type { Task, TaskStatus } from "../tool/types.js";
+import type { TaskState } from "./state.js";
+
+/** Tasks excluding deleted tombstones — the canonical "what's visible". */
+export function selectVisibleTasks(state: TaskState): readonly Task[] {
+	return state.tasks.filter((t) => t.status !== "deleted");
+}
+
+/**
+ * Group visible tasks by status. Iteration order at the call site uses
+ * (`completed`, `inProgress`, `pending`) to match the `/todos` header part
+ * order pinned by `todo.command.test.ts`.
+ */
+export interface TasksByStatus {
+	pending: readonly Task[];
+	inProgress: readonly Task[];
+	completed: readonly Task[];
+}
+export function selectTasksByStatus(state: TaskState): TasksByStatus {
+	const visible = selectVisibleTasks(state);
+	return {
+		pending: visible.filter((t) => t.status === "pending"),
+		inProgress: visible.filter((t) => t.status === "in_progress"),
+		completed: visible.filter((t) => t.status === "completed"),
+	};
+}
+
+/** Total counts for the overlay heading (`Todos (n/m)`) and `/todos` header. */
+export interface TodoCounts {
+	total: number;
+	pending: number;
+	inProgress: number;
+	completed: number;
+}
+export function selectTodoCounts(state: TaskState): TodoCounts {
+	const groups = selectTasksByStatus(state);
+	return {
+		total: groups.pending.length + groups.inProgress.length + groups.completed.length,
+		pending: groups.pending.length,
+		inProgress: groups.inProgress.length,
+		completed: groups.completed.length,
+	};
+}
+
+/**
+ * Whether any visible task carries a `blockedBy` reference. The overlay uses
+ * this to gate the `#id` prefix on per-task rows — without at least one
+ * `⛓ #N` suffix, the per-row id has no anchor.
+ */
+export function selectShowTaskIds(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.blockedBy && t.blockedBy.length > 0);
+}
+
+/**
+ * Resolve a task's subject by id from the live state for renderCall's
+ * accent label. `undefined` when the id is unknown — caller falls back to
+ * `#id` plain rendering.
+ */
+export function selectTaskSubjectById(state: TaskState, id: number): string | undefined {
+	return state.tasks.find((t) => t.id === id)?.subject;
+}
+
+/**
+ * Overlay layout decision. Encapsulates the "drop completed first, then
+ * truncate non-completed tail" rule pre-refactor lived in
+ * `todo-overlay.ts:144-188`. `budget` is the body-slot count (caller passes
+ * `MAX_WIDGET_LINES - 1` to reserve the heading row); on overflow the
+ * selector reserves one more slot internally for the summary row. Returns
+ * the visible task slice plus the overflow summary parts.
+ */
+export interface OverlayLayout {
+	visible: readonly Task[];
+	hiddenCompleted: number;
+	truncatedTail: number;
+}
+export function selectOverlayLayout(state: TaskState, budget: number): OverlayLayout {
+	const all = selectVisibleTasks(state);
+	if (all.length <= budget) {
+		return { visible: all, hiddenCompleted: 0, truncatedTail: 0 };
+	}
+	const innerBudget = budget - 1;
+	const nonCompleted = all.filter((t) => t.status !== "completed");
+	const totalCompleted = all.length - nonCompleted.length;
+	if (nonCompleted.length <= innerBudget) {
+		const kept = new Set<Task>(nonCompleted);
+		for (const t of all) {
+			if (kept.size >= innerBudget) break;
+			if (t.status === "completed") kept.add(t);
+		}
+		const visible = all.filter((t) => kept.has(t));
+		const shownCompleted = visible.filter((t) => t.status === "completed").length;
+		return { visible, hiddenCompleted: totalCompleted - shownCompleted, truncatedTail: 0 };
+	}
+	const visible = nonCompleted.slice(0, innerBudget);
+	const truncatedTail = nonCompleted.length - innerBudget;
+	return { visible, hiddenCompleted: totalCompleted, truncatedTail };
+}
+
+/**
+ * Helper: whether any visible task is `pending` or `in_progress`. The overlay
+ * uses this to pick the heading icon (`accent`+`●` vs `dim`+`○`).
+ */
+export function selectHasActive(state: TaskState): boolean {
+	return selectVisibleTasks(state).some((t) => t.status === "in_progress" || t.status === "pending");
+}
+
+export const ACTIVE_STATUSES: ReadonlySet<TaskStatus> = new Set(["pending", "in_progress"]);

package/agent/extensions/todo/state/state-reducer.ts

@@ -0,0 +1,326 @@
+import type { Task, TaskAction, TaskMutationParams, TaskStatus } from "../tool/types.js";
+import { isTransitionValid } from "./invariants.js";
+import type { TaskState } from "./state.js";
+import { detectCycle } from "./task-graph.js";
+
+/**
+ * Reducer outcome. Closed tagged union — adding a new action requires extending
+ * this union AND the response-envelope's `formatContent` switch (compiler-
+ * enforced exhaustive). Mirrors the `Effect` pattern in
+ * `packages/rpiv-ask-user-question/state/state-reducer.ts:14-30`.
+ *
+ * `error` carries the message in-band so callers can pattern-match on
+ * `op.kind === "error"` without a side-channel boolean.
+ */
+export type Op =
+	| { kind: "create"; ids: number[] }
+	| { kind: "update"; results: Array<{ id: number; fromStatus: TaskStatus; toStatus: TaskStatus }> }
+	| { kind: "delete"; items: Array<{ id: number; subject: string }> }
+	| { kind: "list"; statusFilter?: TaskStatus; includeDeleted: boolean }
+	| { kind: "get"; tasks: Task[] }
+	| { kind: "clear"; count: number }
+	| { kind: "batch"; results: Array<{ index: number; op: Exclude<Op, { kind: "batch" }> }> }
+	| { kind: "error"; message: string };
+
+export interface ApplyResult {
+	state: TaskState;
+	op: Op;
+}
+
+function errorResult(state: TaskState, message: string): ApplyResult {
+	return { state, op: { kind: "error", message } };
+}
+
+/**
+ * Pure reducer: (state, action, params) → (state, op). Mirrors the
+ * `applyTaskMutation` of pre-refactor `todo.ts` minus content/details
+ * formatting; the response envelope (`tool/response-envelope.ts`) owns
+ * formatting, the store (`state/store.ts`) owns commit.
+ *
+ * Validation is in-line: structural guards (`subject required`, `id required`,
+ * `at least one mutable field`) plus state-aware checks (transition legality,
+ * dangling/deleted blockedBy, self-block, cycles). Decision: validation stays
+ * in-reducer — see Plan §Decisions §Decision 2.
+ */
+export function applyTaskMutation(state: TaskState, action: TaskAction, params: TaskMutationParams): ApplyResult {
+	switch (action) {
+		case "create": {
+			// Plural path: subjects[]
+			if (params.subjects?.length) {
+				const subjects = params.subjects.filter((s): s is string => typeof s === "string" && s.trim().length > 0);
+				if (subjects.length === 0) return errorResult(state, "subjects[] requires at least one non-empty subject");
+
+				const createdIds: number[] = [];
+				let cursor = state;
+				for (const subject of subjects) {
+					const subResult = applyTaskMutation(cursor, "create", {
+						...params,
+						subject,
+						subjects: undefined,
+					} as TaskMutationParams);
+					if (subResult.op.kind === "error") return subResult;
+					cursor = subResult.state;
+					if (subResult.op.kind === "create") createdIds.push(...subResult.op.ids);
+				}
+				return { state: cursor, op: { kind: "create", ids: createdIds } };
+			}
+			if (!params.subject?.trim()) {
+				return errorResult(state, "subject required for create");
+			}
+			if (params.blockedBy?.length) {
+				for (const dep of params.blockedBy) {
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `blockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `blockedBy: #${dep} is deleted`);
+				}
+			}
+			const newTask: Task = {
+				id: state.nextId,
+				subject: params.subject,
+				status: "pending",
+			};
+			if (params.description) newTask.description = params.description;
+			if (params.activeForm) newTask.activeForm = params.activeForm;
+			if (params.blockedBy?.length) newTask.blockedBy = [...params.blockedBy];
+			if (params.owner) newTask.owner = params.owner;
+			if (params.metadata) newTask.metadata = { ...params.metadata };
+
+			const newTasks = [...state.tasks, newTask];
+			return {
+				state: { tasks: newTasks, nextId: state.nextId + 1 },
+				op: { kind: "create", ids: [newTask.id] },
+			};
+		}
+
+		case "update": {
+			// Plural path: ids[]
+			if (params.ids?.length) {
+				const results: Array<{ id: number; fromStatus: TaskStatus; toStatus: TaskStatus }> = [];
+				let cursor = state;
+				for (const id of params.ids) {
+					const subResult = applyTaskMutation(cursor, "update", {
+						...params,
+						id,
+						ids: undefined,
+					} as TaskMutationParams);
+					if (subResult.op.kind === "error") return subResult;
+					cursor = subResult.state;
+					if (subResult.op.kind === "update") results.push(subResult.op.results[0]);
+				}
+				return { state: cursor, op: { kind: "update", results } };
+			}
+			if (params.id === undefined) return errorResult(state, "id required for update");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+
+			const hasMutation =
+				params.subject !== undefined ||
+				params.description !== undefined ||
+				params.activeForm !== undefined ||
+				params.status !== undefined ||
+				params.owner !== undefined ||
+				params.metadata !== undefined ||
+				(params.addBlockedBy && params.addBlockedBy.length > 0) ||
+				(params.removeBlockedBy && params.removeBlockedBy.length > 0);
+			if (!hasMutation) return errorResult(state, "update requires at least one mutable field");
+
+			let newStatus = current.status;
+			if (params.status !== undefined) {
+				if (!isTransitionValid(current.status, params.status)) {
+					return errorResult(state, `illegal transition ${current.status} → ${params.status}`);
+				}
+				newStatus = params.status;
+			}
+
+			let newBlockedBy = current.blockedBy ? [...current.blockedBy] : [];
+			if (params.removeBlockedBy?.length) {
+				const toRemove = new Set(params.removeBlockedBy);
+				newBlockedBy = newBlockedBy.filter((dep) => !toRemove.has(dep));
+			}
+			if (params.addBlockedBy?.length) {
+				for (const dep of params.addBlockedBy) {
+					if (dep === current.id) return errorResult(state, `cannot block #${current.id} on itself`);
+					const depTask = state.tasks.find((t) => t.id === dep);
+					if (!depTask) return errorResult(state, `addBlockedBy: #${dep} not found`);
+					if (depTask.status === "deleted") return errorResult(state, `addBlockedBy: #${dep} is deleted`);
+					if (!newBlockedBy.includes(dep)) newBlockedBy.push(dep);
+				}
+				if (detectCycle(state.tasks, current.id, newBlockedBy)) {
+					return errorResult(state, "addBlockedBy would create a cycle in the blockedBy graph");
+				}
+			}
+
+			let newMetadata = current.metadata;
+			if (params.metadata !== undefined) {
+				const merged: Record<string, unknown> = { ...(current.metadata ?? {}) };
+				for (const [k, v] of Object.entries(params.metadata)) {
+					if (v === null) delete merged[k];
+					else merged[k] = v;
+				}
+				newMetadata = Object.keys(merged).length ? merged : undefined;
+			}
+
+			const updated: Task = { ...current, status: newStatus };
+			if (params.subject !== undefined) updated.subject = params.subject;
+			if (params.description !== undefined) updated.description = params.description;
+			if (params.activeForm !== undefined) updated.activeForm = params.activeForm;
+			if (params.owner !== undefined) updated.owner = params.owner;
+			if (newBlockedBy.length) updated.blockedBy = newBlockedBy;
+			else delete updated.blockedBy;
+			if (newMetadata === undefined) delete updated.metadata;
+			else updated.metadata = newMetadata;
+
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: { kind: "update", results: [{ id: updated.id, fromStatus: current.status, toStatus: newStatus }] },
+			};
+		}
+
+		case "list": {
+			return {
+				state,
+				op: {
+					kind: "list",
+					includeDeleted: params.includeDeleted === true,
+					...(params.status !== undefined ? { statusFilter: params.status } : {}),
+				},
+			};
+		}
+
+		case "get": {
+			// Plural path: ids[]
+			if (params.ids?.length) {
+				const tasks: Task[] = [];
+				let cursor = state;
+				for (const id of params.ids) {
+					const subResult = applyTaskMutation(cursor, "get", {
+						...params,
+						id,
+						ids: undefined,
+					} as TaskMutationParams);
+					if (subResult.op.kind === "error") return subResult;
+					cursor = subResult.state;
+					if (subResult.op.kind === "get") tasks.push(subResult.op.tasks[0]);
+				}
+				return { state: cursor, op: { kind: "get", tasks } };
+			}
+			if (params.id === undefined) return errorResult(state, "id required for get");
+			const task = state.tasks.find((t) => t.id === params.id);
+			if (!task) return errorResult(state, `#${params.id} not found`);
+			return { state, op: { kind: "get", tasks: [task] } };
+		}
+
+		case "delete": {
+			// Plural path: ids[]
+			if (params.ids?.length) {
+				const items: Array<{ id: number; subject: string }> = [];
+				let cursor = state;
+				for (const id of params.ids) {
+					const subResult = applyTaskMutation(cursor, "delete", {
+						...params,
+						id,
+						ids: undefined,
+					} as TaskMutationParams);
+					if (subResult.op.kind === "error") return subResult;
+					cursor = subResult.state;
+					if (subResult.op.kind === "delete") items.push(subResult.op.items[0]);
+				}
+				return { state: cursor, op: { kind: "delete", items } };
+			}
+			if (params.id === undefined) return errorResult(state, "id required for delete");
+			const idx = state.tasks.findIndex((t) => t.id === params.id);
+			if (idx === -1) return errorResult(state, `#${params.id} not found`);
+			const current = state.tasks[idx];
+			if (current.status === "deleted") return errorResult(state, `#${current.id} is already deleted`);
+			const updated: Task = { ...current, status: "deleted" };
+			const newTasks = [...state.tasks];
+			newTasks[idx] = updated;
+			return {
+				state: { tasks: newTasks, nextId: state.nextId },
+				op: { kind: "delete", items: [{ id: updated.id, subject: updated.subject }] },
+			};
+		}
+
+		case "clear": {
+			const count = state.tasks.length;
+			return {
+				state: { tasks: [], nextId: 1 },
+				op: { kind: "clear", count },
+			};
+		}
+
+		case "batch": {
+			if (!params.items?.length) {
+				return errorResult(state, "batch requires at least one item in items[]");
+			}
+			type BatchOp = Exclude<Op, { kind: "batch" }>;
+			const results: Array<{ index: number; op: BatchOp }> = [];
+			let currentState = state;
+			const refRegistry = new Map<string, number>();
+
+			for (let i = 0; i < params.items.length; i++) {
+				const item = params.items[i];
+				const { action: itemAction, as: itemAs, refs: itemRefs, ...itemParams } = item;
+
+				// Validate "as" labels
+				if (itemAs?.length) {
+					if (itemAction !== "create") {
+						return errorResult(state, `batch item ${i}: "as" only valid for create actions`);
+					}
+					const taskCount = item.subjects?.length ?? 1;
+					if (itemAs.length !== taskCount) {
+						return errorResult(state, `batch item ${i}: "as" (${itemAs.length}) must match task count (${taskCount})`);
+					}
+					for (const label of itemAs) {
+						if (refRegistry.has(label)) {
+							return errorResult(state, `batch item ${i}: duplicate as label "${label}"`);
+						}
+					}
+				}
+
+				// Resolve "refs" → ids
+				if (itemRefs?.length) {
+					const resolvedIds: number[] = [];
+					for (const ref of itemRefs) {
+						const id = refRegistry.get(ref);
+						if (id === undefined) {
+							return errorResult(state, `batch item ${i}: ref "${ref}" not defined in earlier items`);
+						}
+						resolvedIds.push(id);
+					}
+					itemParams.ids = resolvedIds;
+				}
+
+				// Block list/get in batch (read-only ops)
+				if ((itemAction as string) === "list" || (itemAction as string) === "get") {
+					return errorResult(state, `batch item ${i}: action "${itemAction}" not allowed in batch (use list/get separately)`);
+				}
+
+				const sub = applyTaskMutation(currentState, itemAction, itemParams as TaskMutationParams);
+				if (sub.op.kind === "error") {
+					return errorResult(state, `batch item ${i} (${itemAction}): ${(sub.op as { kind: "error"; message: string }).message}`);
+				}
+				currentState = sub.state;
+
+				// Register "as" labels after successful create
+				if (itemAs?.length && sub.op.kind === "create") {
+					sub.op.ids.forEach((id, idx) => {
+						if (idx < itemAs.length) {
+							refRegistry.set(itemAs[idx], id);
+						}
+					});
+				}
+
+				results.push({ index: i, op: sub.op as BatchOp });
+			}
+
+			return {
+				state: currentState,
+				op: { kind: "batch", results },
+			};
+		}
+	}
+}

package/agent/extensions/todo/state/state.ts

@@ -0,0 +1,18 @@
+import type { Task } from "../tool/types.js";
+
+/**
+ * Canonical state for the todo tool. Single source of truth — both the reducer
+ * (`state/state-reducer.ts`) and the live store cell (`state/store.ts`) read
+ * this shape. Replay (`state/replay.ts`) returns a fresh `TaskState`; the
+ * lifecycle handlers in `index.ts` write it via `replaceState`.
+ *
+ * The shape is intentionally minimal — no derived caches or runtime cells.
+ * Selectors in `state/selectors.ts` are pure of `TaskState` and own all
+ * derivations (visible/grouped/counted/etc).
+ */
+export interface TaskState {
+	tasks: Task[];
+	nextId: number;
+}
+
+export const EMPTY_STATE: TaskState = { tasks: [], nextId: 1 };