pi-ui-extend 0.1.1

package/external/pi-tools-suite/src/todo/todo.ts

@@ -0,0 +1,487 @@
+/**
+ * todo tool + /todos command — thin registration shell.
+ *
+ * Tool/command identity, schema, types, reducer, store, replay, response
+ * envelope, selectors, and view formatters live in the layered modules under
+ * `tool/`, `state/`, and `view/`. This file is the package-root registration
+ * surface — it mirrors `packages/rpiv-ask-user-question/ask-user-question.ts`
+ * which keeps the tool registration at the package root.
+ *
+ * Public re-exports below preserve the pre-refactor import surface so that
+ * `index.ts` and the global `test/setup.ts` `beforeEach`
+ * continue to import from `./todo.js`.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { TODO_TOOL_DESCRIPTION } from "../tool-descriptions.js";
+import {
+	disablePersistence,
+	getTodoPlanPath,
+	loadPersistedPlan,
+	savePersistedPlan,
+	syncPersistedPlan,
+} from "./state/persistence.js";
+import { AUTO_CLEAR_COMPLETED_MESSAGE, autoClearCompletedTodos } from "./state/auto-clear.js";
+import { replayFromBranch } from "./state/replay.js";
+import { selectTasksByStatus, selectTodoCounts } from "./state/selectors.js";
+import { applyTaskMutation } from "./state/state-reducer.js";
+import { commitState, getState, replaceState } from "./state/store.js";
+import { buildToolResult, formatContent } from "./tool/response-envelope.js";
+import {
+	COMMAND_NAME,
+	ERR_REQUIRES_INTERACTIVE,
+	MSG_NO_TODOS,
+	type Task,
+	type TaskAction,
+	type TaskMutationParams,
+	type TaskPriority,
+	type TaskStatus,
+	TOOL_LABEL,
+	TOOL_NAME,
+	TodoParamsSchema,
+} from "./tool/types.js";
+import { formatCommandTaskLine } from "./view/format.js";
+import { formatStatusLabel } from "./view/labels.js";
+
+const SECTION_PENDING = "── Pending ──";
+const SECTION_IN_PROGRESS = "── In Progress ──";
+const SECTION_DEFERRED = "── Deferred ──";
+const SECTION_COMPLETED = "── Completed ──";
+const PERSIST_COMMAND_NAME = "todos-persist";
+const SCOPE_COMMAND_NAME = "todos-scope";
+export const TODO_STATE_EVENT = "pi-tools-suite:todo:state";
+
+type CommandCompletion = { value: string; label: string; description?: string };
+
+const TODOS_ARGUMENT_COMPLETIONS: CommandCompletion[] = [
+	{ value: "persist on", label: "persist on", description: "Enable project plan persistence" },
+	{ value: "persist status", label: "persist status", description: "Show project plan persistence status" },
+	{ value: "persist off", label: "persist off", description: "Disable persistence and remove the project plan file" },
+	{ value: "persist clear", label: "persist clear", description: "Alias for persist off" },
+	{ value: "scope ", label: "scope <id...>", description: "Keep selected items active and defer out-of-scope items" },
+	{ value: "--active", label: "--active", description: "Show pending/in_progress tasks" },
+	{ value: "--ready", label: "--ready", description: "Show pending tasks whose blockers are completed" },
+	{ value: "--blocked", label: "--blocked", description: "Show tasks with blockers" },
+	{ value: "--tree", label: "--tree", description: "Show parent/subtask tree" },
+	{ value: "--tag ", label: "--tag <tag>", description: "Filter by tag" },
+	{ value: "--priority ", label: "--priority <level>", description: "Filter by priority" },
+	{ value: "--status ", label: "--status <status>", description: "Filter by status" },
+	{ value: "--export markdown", label: "--export markdown", description: "Export visible todos as Markdown" },
+	{ value: "--export json", label: "--export json", description: "Export visible todos as JSON" },
+];
+
+const PERSIST_ARGUMENT_COMPLETIONS: CommandCompletion[] = [
+	{ value: "on", label: "on", description: "Enable project plan persistence" },
+	{ value: "status", label: "status", description: "Show persistence status" },
+	{ value: "off", label: "off", description: "Disable persistence and remove the plan file" },
+	{ value: "clear", label: "clear", description: "Alias for off" },
+];
+
+interface TodoToolHooks {
+	afterCommit?: (state: ReturnType<typeof getState>, ctx: ExtensionContext) => void | Promise<void>;
+}
+
+type TodoStateEventContext = { sessionManager?: { getSessionFile?: () => unknown } };
+type TodoStateEventEmitter = { events?: { emit?: (channel: string, data: unknown) => void } };
+
+interface TodosCommandOptions {
+	status?: TaskStatus;
+	priority?: TaskPriority;
+	tag?: string;
+	blockedOnly: boolean;
+	readyOnly: boolean;
+	activeOnly: boolean;
+	includeDeleted: boolean;
+	tree: boolean;
+	exportFormat?: "json" | "markdown";
+}
+
+function parseTodosArgs(args: unknown): TodosCommandOptions {
+	const text = typeof args === "string" ? args : Array.isArray(args) ? args.join(" ") : "";
+	const tokens = text.trim().split(/\s+/).filter(Boolean);
+	const options: TodosCommandOptions = {
+		blockedOnly: false,
+		readyOnly: false,
+		activeOnly: false,
+		includeDeleted: false,
+		tree: false,
+	};
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		const next = tokens[i + 1];
+		switch (token) {
+			case "--blocked":
+				options.blockedOnly = true;
+				break;
+			case "--ready":
+				options.readyOnly = true;
+				break;
+			case "--active":
+				options.activeOnly = true;
+				break;
+			case "--tree":
+				options.tree = true;
+				break;
+			case "--include-deleted":
+				options.includeDeleted = true;
+				break;
+			case "--tag":
+				if (next) options.tag = tokens[++i].replace(/^#/, "");
+				break;
+			case "--priority":
+				if (next === "low" || next === "medium" || next === "high" || next === "urgent") options.priority = tokens[++i] as TaskPriority;
+				break;
+			case "--status":
+				if (next === "pending" || next === "in_progress" || next === "deferred" || next === "completed" || next === "deleted") options.status = tokens[++i] as TaskStatus;
+				break;
+			case "--export":
+				options.exportFormat = next === "markdown" ? "markdown" : "json";
+				if (next === "json" || next === "markdown") i++;
+				break;
+		}
+	}
+	return options;
+}
+
+function getCommandText(args: unknown): string {
+	return typeof args === "string" ? args : Array.isArray(args) ? args.join(" ") : "";
+}
+
+function getCommandTokens(args: unknown): string[] {
+	return getCommandText(args).trim().split(/\s+/).filter(Boolean);
+}
+
+function completeCommandArguments(prefix: string, completions: readonly CommandCompletion[]): CommandCompletion[] {
+	const normalizedPrefix = prefix.trimStart();
+	return completions.filter((completion) => completion.value.startsWith(normalizedPrefix));
+}
+
+function parseScopeIds(tokens: readonly string[]): number[] {
+	const ids = tokens
+		.flatMap((token) => token.split(/[\s,]+/))
+		.map((token) => Number(token.replace(/^#/, "")))
+		.filter((id) => Number.isFinite(id) && id > 0);
+	return [...new Set(ids)];
+}
+
+function scopeStatus(task: Task, selected: ReadonlySet<number>): TaskStatus {
+	if (selected.has(task.id)) {
+		if (task.status === "deferred") return "pending";
+		return task.status;
+	}
+	if (task.status === "pending" || task.status === "in_progress") return "deferred";
+	return task.status;
+}
+
+type NotifyLevel = "info" | "warning" | "error";
+
+function notifyCommand(ctx: { hasUI?: boolean; ui?: { notify?: (message: string, level?: NotifyLevel) => void } }, message: string, level: NotifyLevel = "info"): void {
+	if (ctx.hasUI && ctx.ui?.notify) {
+		ctx.ui.notify(message, level);
+		return;
+	}
+	if (level === "error") console.error(message);
+	else console.log(message);
+}
+
+function sessionFileFromContext(ctx: unknown): string | undefined {
+	const sessionFile = (ctx as TodoStateEventContext | undefined)?.sessionManager?.getSessionFile?.();
+	return typeof sessionFile === "string" && sessionFile.trim() ? sessionFile : undefined;
+}
+
+export function publishTodoState(
+	pi: TodoStateEventEmitter,
+	ctx: unknown,
+	action: TaskAction = "list",
+	params: Record<string, unknown> = {},
+): void {
+	const state = getState();
+	const sessionFile = sessionFileFromContext(ctx);
+	pi.events?.emit?.(TODO_STATE_EVENT, {
+		version: 1,
+		details: {
+			action,
+			params,
+			tasks: state.tasks,
+			nextId: state.nextId,
+		},
+		...(sessionFile ? { sessionFile } : {}),
+		checkedAt: Date.now(),
+	});
+}
+
+function handlePersistCommand(args: unknown, ctx: { cwd?: string; hasUI?: boolean; ui?: { notify?: (message: string, level?: NotifyLevel) => void } }): boolean {
+	const [command, subcommand = "status"] = getCommandTokens(args);
+	if (command !== "persist") return false;
+
+	const cwd = ctx.cwd;
+	switch (subcommand) {
+		case "on": {
+			const path = savePersistedPlan(cwd, getState());
+			notifyCommand(ctx, `Todo persistence enabled: ${path}`);
+			return true;
+		}
+		case "off":
+		case "clear": {
+			const path = disablePersistence(cwd);
+			notifyCommand(ctx, `Todo persistence disabled and project plan removed: ${path}`);
+			return true;
+		}
+		case "status": {
+			const loaded = loadPersistedPlan(cwd);
+			if (!loaded) {
+				notifyCommand(ctx, `Todo persistence is off (${getTodoPlanPath(cwd)} not found)`);
+				return true;
+			}
+			const visible = loaded.state.tasks.filter((task) => task.status !== "deleted").length;
+			const active = loaded.state.tasks.filter((task) => task.status === "pending" || task.status === "in_progress").length;
+			notifyCommand(ctx, `Todo persistence is on: ${loaded.path}\n${visible} visible tasks, ${active} active.`);
+			return true;
+		}
+		default:
+			notifyCommand(ctx, "Usage: /todos persist on|off|clear|status", "error");
+			return true;
+	}
+}
+
+function handleScopeCommand(
+	args: unknown,
+	ctx: { cwd?: string; hasUI?: boolean; ui?: { notify?: (message: string, level?: NotifyLevel) => void } },
+	afterCommit?: () => void,
+): boolean {
+	const [command, ...rest] = getCommandTokens(args);
+	if (command !== "scope") return false;
+	const selectedIds = parseScopeIds(rest);
+	if (selectedIds.length === 0) {
+		notifyCommand(ctx, "Usage: /todos scope <id> [id...]", "error");
+		return true;
+	}
+
+	const selected = new Set(selectedIds);
+	let nextState = getState();
+	const changed: number[] = [];
+	for (const task of nextState.tasks) {
+		if (task.status === "deleted" || task.status === "completed") continue;
+		const nextStatus = scopeStatus(task, selected);
+		if (nextStatus === task.status) continue;
+		const result = applyTaskMutation(nextState, "update", { action: "update", id: task.id, status: nextStatus });
+		if (result.op.kind === "error") {
+			notifyCommand(ctx, result.op.message, "error");
+			return true;
+		}
+		nextState = result.state;
+		changed.push(task.id);
+	}
+	commitState(nextState);
+	afterCommit?.();
+	const sync = syncPersistedPlan(ctx.cwd, nextState);
+	const selectedText = selectedIds.map((id) => `#${id}`).join(", ");
+	const persistedText = sync ? `\nPersisted plan updated: ${sync.path}` : "";
+	notifyCommand(ctx, `Todo scope selected: ${selectedText}\nDeferred out-of-scope active tasks: ${changed.length}${persistedText}`);
+	return true;
+}
+
+function filterCommandTasks(tasks: readonly Task[], options: TodosCommandOptions): Task[] {
+	const byId = new Map(tasks.map((task) => [task.id, task]));
+	let view = [...tasks];
+	if (!options.includeDeleted) view = view.filter((task) => task.status !== "deleted");
+	if (options.activeOnly) view = view.filter((task) => task.status === "pending" || task.status === "in_progress");
+	if (options.readyOnly) {
+		view = view.filter(
+			(task) =>
+				task.status === "pending" &&
+				(task.blockedBy ?? []).every((id) => byId.get(id)?.status === "completed"),
+		);
+	}
+	if (options.status) view = view.filter((task) => task.status === options.status);
+	if (options.priority) view = view.filter((task) => task.priority === options.priority);
+	const tag = options.tag;
+	if (tag) view = view.filter((task) => task.tags?.includes(tag));
+	if (options.blockedOnly) view = view.filter((task) => (task.blockedBy?.length ?? 0) > 0);
+	return view;
+}
+
+function commandGlyph(status: TaskStatus): string {
+	switch (status) {
+		case "pending":
+			return "○";
+		case "in_progress":
+			return "◐";
+		case "deferred":
+			return "◌";
+		case "completed":
+			return "✓";
+		case "deleted":
+			return "⊘";
+	}
+}
+
+function formatCommandTree(tasks: readonly Task[]): string[] {
+	const byParent = new Map<number | undefined, Task[]>();
+	const ids = new Set(tasks.map((task) => task.id));
+	for (const task of tasks) {
+		const parent = task.parentId !== undefined && ids.has(task.parentId) ? task.parentId : undefined;
+		const siblings = byParent.get(parent) ?? [];
+		siblings.push(task);
+		byParent.set(parent, siblings);
+	}
+	const lines: string[] = [];
+	const seen = new Set<number>();
+	const visit = (task: Task, depth: number) => {
+		if (seen.has(task.id)) return;
+		seen.add(task.id);
+		lines.push(`${"  ".repeat(depth)}${formatCommandTaskLine(task, commandGlyph(task.status)).trimStart()}`);
+		for (const child of byParent.get(task.id) ?? []) visit(child, depth + 1);
+	};
+	for (const root of byParent.get(undefined) ?? []) visit(root, 0);
+	for (const task of tasks) visit(task, 0);
+	return lines;
+}
+
+// ---------------------------------------------------------------------------
+// Public re-exports — pre-refactor consumers (tests, index.ts) keep
+// importing from `./todo.js`. New code may opt into deeper imports.
+// ---------------------------------------------------------------------------
+
+export { isTransitionValid } from "./state/invariants.js";
+export { applyTaskMutation } from "./state/state-reducer.js";
+export { __resetState, getNextId, getTodos } from "./state/store.js";
+export { deriveBlocks, detectCycle } from "./state/task-graph.js";
+export type { Task, TaskAction, TaskDetails, TaskPriority, TaskStatus } from "./tool/types.js";
+export { TOOL_NAME } from "./tool/types.js";
+
+/**
+ * Backward-compat replay shim. Pre-refactor `reconstructTodoState(ctx)`
+ * mutated module state directly; the new replay seam (`state/replay.ts`)
+ * returns a `TaskState` and the caller commits via `replaceState`.
+ */
+export function reconstructTodoState(ctx: Parameters<typeof replayFromBranch>[0]): void {
+	replaceState(replayFromBranch(ctx));
+}
+
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_PROMPT_SNIPPET = TODO_TOOL_DESCRIPTION.promptSnippet ?? "";
+export const DEFAULT_PROMPT_GUIDELINES: string[] = TODO_TOOL_DESCRIPTION.promptGuidelines ?? [];
+
+export function registerTodoTool(pi: ExtensionAPI, hooks: TodoToolHooks = {}): void {
+	pi.registerTool({
+		...TODO_TOOL_DESCRIPTION,
+		name: TOOL_NAME,
+		label: TOOL_LABEL,
+		promptSnippet: DEFAULT_PROMPT_SNIPPET,
+		promptGuidelines: DEFAULT_PROMPT_GUIDELINES,
+		parameters: TodoParamsSchema,
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			const result = applyTaskMutation(getState(), params.action, params as TaskMutationParams);
+			if (result.op.kind === "error") {
+				throw new Error(result.op.message);
+			}
+			const autoClear = autoClearCompletedTodos(result.state);
+			commitState(autoClear.state);
+			publishTodoState(pi as TodoStateEventEmitter, _ctx, params.action, params as Record<string, unknown>);
+			await hooks.afterCommit?.(autoClear.state, _ctx as ExtensionContext);
+			const toolResult = buildToolResult(params.action, params as TaskMutationParams, autoClear.state, result.op);
+			if (!autoClear.cleared) return toolResult;
+			return {
+				...toolResult,
+				content: [{ type: "text" as const, text: `${toolResult.content[0]?.text ?? ""}\n${AUTO_CLEAR_COMPLETED_MESSAGE}`.trim() }],
+			};
+		},
+
+	});
+}
+
+// ---------------------------------------------------------------------------
+// /todos slash command
+// ---------------------------------------------------------------------------
+
+export function registerTodosCommand(pi: ExtensionAPI): void {
+	pi.registerCommand(COMMAND_NAME, {
+		description: "Show todos on the current branch. Flags: --active, --ready, --blocked, --tree, --tag <tag>, --priority <level>, --status <status>, --export [json|markdown]. Commands: persist on|off|clear|status, scope <id...>",
+		getArgumentCompletions: (prefix) => completeCommandArguments(String(prefix ?? ""), TODOS_ARGUMENT_COMPLETIONS),
+		handler: async (args, ctx) => {
+			if (handlePersistCommand(args, ctx)) return;
+			if (handleScopeCommand(args, ctx, () => publishTodoState(pi as TodoStateEventEmitter, ctx))) return;
+			if (!ctx.hasUI) {
+				console.error(ERR_REQUIRES_INTERACTIVE);
+				return;
+			}
+			const state = getState();
+			const options = parseTodosArgs(args);
+			if (options.exportFormat) {
+				const exportState = { tasks: filterCommandTasks(state.tasks, options), nextId: state.nextId };
+				const op = {
+					kind: "export" as const,
+					format: options.exportFormat,
+					includeDeleted: options.includeDeleted,
+					blockedOnly: options.blockedOnly,
+					...(options.status ? { statusFilter: options.status } : {}),
+					...(options.priority ? { priorityFilter: options.priority } : {}),
+					...(options.tag ? { tagFilter: options.tag } : {}),
+				};
+				ctx.ui.notify(formatContent(op, exportState), "info");
+				return;
+			}
+
+			const visible = filterCommandTasks(state.tasks, options);
+			if (visible.length === 0) {
+				ctx.ui.notify(MSG_NO_TODOS, "info");
+				return;
+			}
+			const filteredState = { tasks: visible, nextId: state.nextId };
+			const groups = selectTasksByStatus(filteredState);
+			const counts = selectTodoCounts(filteredState);
+
+			const header: string[] = [];
+			if (counts.completed > 0) header.push(`${counts.completed}/${counts.total} ${formatStatusLabel("completed")}`);
+			if (counts.inProgress > 0) header.push(`${counts.inProgress} ${formatStatusLabel("in_progress")}`);
+			if (counts.pending > 0) header.push(`${counts.pending} ${formatStatusLabel("pending")}`);
+			if (counts.deferred > 0) header.push(`${counts.deferred} ${formatStatusLabel("deferred")}`);
+
+			const lines: string[] = [header.join(" · ")];
+			if (options.tree) {
+				lines.push("── Tree ──");
+				lines.push(...formatCommandTree(visible));
+				ctx.ui.notify(lines.join("\n"), "info");
+				return;
+			}
+			if (groups.pending.length > 0) {
+				lines.push(SECTION_PENDING);
+				for (const task of groups.pending) lines.push(formatCommandTaskLine(task, "○"));
+			}
+			if (groups.inProgress.length > 0) {
+				lines.push(SECTION_IN_PROGRESS);
+				for (const task of groups.inProgress) lines.push(formatCommandTaskLine(task, "◐"));
+			}
+			if (groups.deferred.length > 0) {
+				lines.push(SECTION_DEFERRED);
+				for (const task of groups.deferred) lines.push(formatCommandTaskLine(task, "◌"));
+			}
+			if (groups.completed.length > 0) {
+				lines.push(SECTION_COMPLETED);
+				for (const task of groups.completed) lines.push(formatCommandTaskLine(task, "✓"));
+			}
+
+			ctx.ui.notify(lines.join("\n"), "info");
+		},
+	});
+
+	pi.registerCommand(PERSIST_COMMAND_NAME, {
+		description: "Enable, disable, clear, or inspect project todo persistence. Args: on|off|clear|status.",
+		getArgumentCompletions: (prefix) => completeCommandArguments(String(prefix ?? ""), PERSIST_ARGUMENT_COMPLETIONS),
+		handler: async (args, ctx) => {
+			handlePersistCommand(`persist ${getCommandText(args)}`, ctx);
+		},
+	});
+
+	pi.registerCommand(SCOPE_COMMAND_NAME, {
+		description: "Select todo ids to continue from a persisted plan; pending/in_progress items outside the scope become deferred.",
+		handler: async (args, ctx) => {
+			handleScopeCommand(`scope ${getCommandText(args)}`, ctx, () => publishTodoState(pi as TodoStateEventEmitter, ctx));
+		},
+	});
+}

package/external/pi-tools-suite/src/todo/tool/response-envelope.ts

@@ -0,0 +1,143 @@
+import type { TaskState } from "../state/state.js";
+import type { Op } from "../state/state-reducer.js";
+import { deriveBlocks } from "../state/task-graph.js";
+import type { Task, TaskAction, TaskDetails, TaskMutationParams } from "./types.js";
+
+/**
+ * Format a single task for the LLM-facing `list` response. The `/todos`
+ * command uses `view/format.ts` for its grouped text presentation.
+ */
+function formatListLine(t: Task): string {
+	const block = t.blockedBy?.length ? ` ⛓ ${t.blockedBy.map((id) => `#${id}`).join(",")}` : "";
+	const parent = t.parentId !== undefined ? ` ↳ #${t.parentId}` : "";
+	const priority = t.priority ? ` (${t.priority})` : "";
+	const tags = t.tags?.length ? ` ${t.tags.map((tag) => `#${tag}`).join(" ")}` : "";
+	const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+	return `[${t.status}] #${t.id} ${t.subject}${priority}${form}${parent}${block}${tags}`;
+}
+
+/**
+ * Multi-line presentation for the `get` action. Keep the most actionable task
+ * fields near the top, then dependency and ownership metadata.
+ */
+function formatGetLines(task: Task, state: TaskState): string {
+	const blocks = deriveBlocks(state.tasks).get(task.id) ?? [];
+	const lines = [`#${task.id} [${task.status}] ${task.subject}`];
+	if (task.description) lines.push(`  description: ${task.description}`);
+	if (task.activeForm) lines.push(`  activeForm: ${task.activeForm}`);
+	if (task.priority) lines.push(`  priority: ${task.priority}`);
+	if (task.parentId !== undefined) lines.push(`  parentId: #${task.parentId}`);
+	if (task.blockedBy?.length) {
+		lines.push(`  blockedBy: ${task.blockedBy.map((id) => `#${id}`).join(", ")}`);
+	}
+	if (blocks.length) {
+		lines.push(`  blocks: ${blocks.map((id) => `#${id}`).join(", ")}`);
+	}
+	if (task.tags?.length) lines.push(`  tags: ${task.tags.map((tag) => `#${tag}`).join(" ")}`);
+	if (task.owner) lines.push(`  owner: ${task.owner}`);
+	return lines.join("\n");
+}
+
+function filterTasks(op: Extract<Op, { kind: "list" | "export" }>, state: TaskState): Task[] {
+	let view = state.tasks;
+	if (!op.includeDeleted) view = view.filter((t) => t.status !== "deleted");
+	if (op.statusFilter) view = view.filter((t) => t.status === op.statusFilter);
+	if (op.priorityFilter) view = view.filter((t) => t.priority === op.priorityFilter);
+	const tagFilter = op.tagFilter;
+	if (tagFilter) view = view.filter((t) => t.tags?.includes(tagFilter));
+	if (op.blockedOnly) view = view.filter((t) => (t.blockedBy?.length ?? 0) > 0);
+	return view;
+}
+
+function formatMarkdownExport(tasks: readonly Task[]): string {
+	const byParent = new Map<number | undefined, Task[]>();
+	for (const task of tasks) {
+		const siblings = byParent.get(task.parentId) ?? [];
+		siblings.push(task);
+		byParent.set(task.parentId, siblings);
+	}
+	const lines: string[] = [];
+	const seen = new Set<number>();
+	const visit = (task: Task, depth: number) => {
+		if (seen.has(task.id)) return;
+		seen.add(task.id);
+		const checked = task.status === "completed" ? "x" : " ";
+		const priority = task.priority ? ` (${task.priority})` : "";
+		const status = task.status === "deferred" ? " {deferred}" : "";
+		const tags = task.tags?.length ? ` [${task.tags.map((tag) => `#${tag}`).join(" ")}]` : "";
+		const blocked = task.blockedBy?.length ? ` ⛓ ${task.blockedBy.map((id) => `#${id}`).join(",")}` : "";
+		lines.push(`${"  ".repeat(depth)}- [${checked}] #${task.id}${priority} ${task.subject}${status}${blocked}${tags}`);
+		for (const child of byParent.get(task.id) ?? []) visit(child, depth + 1);
+	};
+	for (const root of byParent.get(undefined) ?? []) visit(root, 0);
+	for (const task of tasks) visit(task, 0);
+	return lines.join("\n");
+}
+
+/**
+ * Pure formatter: `(op, state) → string`. Closed switch on `op.kind` —
+ * adding a new `Op` variant fails to compile here until a branch is added.
+ * The strings on each branch are byte-equivalent to pre-refactor `todo.ts`
+ * reducer output.
+ */
+export function formatContent(op: Op, state: TaskState): string {
+	switch (op.kind) {
+		case "create": {
+			const t = state.tasks.find((x) => x.id === op.taskId);
+			// Defensive — `op.taskId` always resolves on success path.
+			if (!t) return `Created #${op.taskId}`;
+			return `Created #${t.id}: ${t.subject} (pending)`;
+		}
+		case "update": {
+			const transition = op.fromStatus !== op.toStatus ? ` (${op.fromStatus} → ${op.toStatus})` : "";
+			return `Updated #${op.id}${transition}`;
+		}
+		case "batch_create":
+			return `Created ${op.ids.length} tasks: ${op.ids.map((id) => `#${id}`).join(", ")}`;
+		case "batch_update":
+			return `Updated ${op.ids.length} tasks: ${op.ids.map((id) => `#${id}`).join(", ")}`;
+		case "delete":
+			return `Deleted #${op.id}: ${op.subject}`;
+		case "clear":
+			return `Cleared ${op.count} tasks`;
+		case "list": {
+			const view = filterTasks(op, state);
+			return view.length === 0 ? "No tasks" : view.map(formatListLine).join("\n");
+		}
+		case "get":
+			return formatGetLines(op.task, state);
+		case "export": {
+			const tasks = filterTasks(op, state);
+			if (op.format === "markdown") return formatMarkdownExport(tasks);
+			return JSON.stringify({ tasks, nextId: state.nextId }, null, 2);
+		}
+		case "import":
+			return `Imported ${op.count} tasks${op.replaced ? " (replaced existing tasks)" : ""}`;
+		case "error":
+			return `Error: ${op.message}`;
+	}
+}
+
+/**
+ * Build the LLM-facing tool envelope after the store has committed the
+ * reducer's new state. `details` is the persistence + replay snapshot —
+ * `state/replay.ts` consumes this exact shape on session lifecycle events.
+ *
+ * Mirrors `packages/rpiv-ask-user-question/tool/response-envelope.ts:13-47`.
+ */
+export function buildToolResult(
+	action: TaskAction,
+	params: TaskMutationParams,
+	state: TaskState,
+	op: Op,
+): { content: Array<{ type: "text"; text: string }>; details: TaskDetails } {
+	const text = formatContent(op, state);
+	const details: TaskDetails = {
+		action,
+		params: params as Record<string, unknown>,
+		tasks: state.tasks,
+		nextId: state.nextId,
+		...(op.kind === "error" ? { error: op.message } : {}),
+	};
+	return { content: [{ type: "text", text }], details };
+}