@xynogen/pix-core 0.1.0

package/src/tool/todo/todo.ts

@@ -0,0 +1,194 @@
+/**
+ * todo.ts — durable execution checklist tool
+ *
+ * Extracted from the plan extension: the checklist is BUILD-phase execution
+ * state that survives context compaction and session restore (persisted via
+ * appendEntry("todo-state")). It is universal — other tools and workflow
+ * extensions (like plan) drive it — so it lives in pix-core and registers the
+ * `todo` tool. State, persistence, and restore are owned end to end here; the
+ * checklist is seeded by the model via the tool's `set` action.
+ */
+
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export type TodoStatus = "pending" | "in_progress" | "done" | "blocked";
+
+export interface TodoItem {
+	id: number;
+	text: string;
+	status: TodoStatus;
+}
+
+const TODO_GLYPH: Record<TodoStatus, string> = {
+	pending: "○",
+	in_progress: "◐",
+	done: "●",
+	blocked: "⊘",
+};
+
+const parseItems = (raw: string): string[] =>
+	raw
+		.split("\n")
+		.map((l) => l.replace(/^\s*(?:\d+[.)]|[-*•])\s*/, "").trim())
+		.filter(Boolean);
+
+export default function registerTodo(pi: ExtensionAPI): void {
+	let todos: TodoItem[] = [];
+	let nextTodoId = 1;
+
+	function persistTodos() {
+		pi.appendEntry("todo-state", { todos, nextTodoId });
+	}
+
+	function todoSummary(): string {
+		if (!todos.length) return "(no todos)";
+		const done = todos.filter((t) => t.status === "done").length;
+		const lines = todos.map((t) => `${TODO_GLYPH[t.status]} ${t.id}. ${t.text}`);
+		return `Todos ${done}/${todos.length} done:\n${lines.join("\n")}`;
+	}
+
+	// Durable execution checklist for BUILD mode. Survives context compaction
+	// and session restore. Workflows like plan instruct the model to seed it
+	// from a plan's "Implementation Phases" so it stays anchored to plan.md.
+	pi.registerTool({
+		name: "todo",
+		label: "Todo",
+		description:
+			"Track BUILD-phase execution progress. Durable across context compaction. Actions: list, set (replace all items from newline/numbered text), add, update (change one item's status), clear.",
+		promptSnippet:
+			"todo(action, items?, id?, status?, text?) — action: list|set|add|update|clear. Use to track implementation progress, especially when executing a plan.",
+		promptGuidelines: [
+			"When you start executing a multi-step plan in BUILD mode, seed the todo list with `todo(action:'set', items: <plan Implementation Phases>)`.",
+			"Mark each item in_progress before working it and done when finished via `todo(action:'update', id, status)`.",
+			"Call `todo(action:'list')` to recover your place after long runs or context compaction.",
+		],
+		parameters: Type.Object({
+			action: Type.Union(
+				[
+					Type.Literal("list"),
+					Type.Literal("set"),
+					Type.Literal("add"),
+					Type.Literal("update"),
+					Type.Literal("clear"),
+				],
+				{ description: "Operation to perform" },
+			),
+			items: Type.Optional(
+				Type.String({
+					description:
+						"For set/add: newline-separated or numbered list of todo texts.",
+				}),
+			),
+			id: Type.Optional(
+				Type.Number({ description: "For update: target todo id." }),
+			),
+			status: Type.Optional(
+				Type.Union(
+					[
+						Type.Literal("pending"),
+						Type.Literal("in_progress"),
+						Type.Literal("done"),
+						Type.Literal("blocked"),
+					],
+					{ description: "For update: new status." },
+				),
+			),
+			text: Type.Optional(
+				Type.String({
+					description: "For update: replacement text (optional).",
+				}),
+			),
+		}),
+		async execute(_id, params) {
+			switch (params.action) {
+				case "list":
+					return { content: [{ type: "text", text: todoSummary() }] };
+
+				case "set": {
+					const texts = parseItems(params.items ?? "");
+					if (!texts.length)
+						return {
+							content: [
+								{ type: "text", text: "set requires non-empty `items`." },
+							],
+							isError: true,
+						};
+					nextTodoId = 1;
+					todos = texts.map((text) => ({
+						id: nextTodoId++,
+						text,
+						status: "pending" as TodoStatus,
+					}));
+					persistTodos();
+					return { content: [{ type: "text", text: todoSummary() }] };
+				}
+
+				case "add": {
+					const texts = parseItems(params.items ?? "");
+					if (!texts.length)
+						return {
+							content: [
+								{ type: "text", text: "add requires non-empty `items`." },
+							],
+							isError: true,
+						};
+					for (const text of texts)
+						todos.push({ id: nextTodoId++, text, status: "pending" });
+					persistTodos();
+					return { content: [{ type: "text", text: todoSummary() }] };
+				}
+
+				case "update": {
+					const t = todos.find((x) => x.id === params.id);
+					if (!t)
+						return {
+							content: [
+								{ type: "text", text: `No todo with id ${params.id}.` },
+							],
+							isError: true,
+						};
+					if (params.status) t.status = params.status;
+					if (params.text) t.text = params.text;
+					persistTodos();
+					return { content: [{ type: "text", text: todoSummary() }] };
+				}
+
+				case "clear":
+					todos = [];
+					nextTodoId = 1;
+					persistTodos();
+					return { content: [{ type: "text", text: "Todos cleared." }] };
+
+				default:
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Unknown action: ${String(params.action)}`,
+							},
+						],
+						isError: true,
+					};
+			}
+		},
+	});
+
+	// Restore the checklist from session entries so it survives restart.
+	pi.on("session_start", async (_event, ctx) => {
+		const entries = ctx.sessionManager.getEntries() as Array<{
+			type: string;
+			customType?: string;
+			data?: { todos?: TodoItem[]; nextTodoId?: number };
+		}>;
+		const lastTodo = entries
+			.filter((e) => e.type === "custom" && e.customType === "todo-state")
+			.pop();
+		if (Array.isArray(lastTodo?.data?.todos)) {
+			todos = lastTodo.data.todos;
+			nextTodoId =
+				lastTodo.data.nextTodoId ??
+				todos.reduce((m, t) => Math.max(m, t.id + 1), 1);
+		}
+	});
+}

package/src/tool/toolbox/toolbox.test.ts

@@ -0,0 +1,312 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import registerToolbox, {
+	buildRows,
+	parseTargets,
+	renderList,
+	toggleTool,
+	type ToolRow,
+	type ToggleOps,
+} from "./toolbox.ts";
+
+// ─── Fixtures ───────────────────────────────────────────────────────────────
+
+const toolInfo = (name: string, source = "builtin") =>
+	({
+		name,
+		description: `${name} does things.`,
+		parameters: {},
+		sourceInfo: { source, path: "", scope: "user", origin: "package" },
+	}) as never;
+
+const mcpToolInfo = (name: string) => toolInfo(name, "mcp:context7");
+
+// ─── buildRows ──────────────────────────────────────────────────────────────
+
+describe("buildRows", () => {
+	test("excludes core tools (bash, edit, read, write)", () => {
+		const rows = buildRows([
+			toolInfo("bash"),
+			toolInfo("edit"),
+			toolInfo("read"),
+			toolInfo("write"),
+			toolInfo("grep"),
+			toolInfo("ls"),
+		]);
+		expect(rows.map((r) => r.name)).toEqual(["grep", "ls"]);
+		expect(rows.every((r) => !r.mcp)).toBe(true);
+	});
+
+	test("flags MCP tools", () => {
+		const rows = buildRows([mcpToolInfo("ctx_search")]);
+		expect(rows[0].mcp).toBe(true);
+	});
+
+	test("empty input returns empty", () => {
+		expect(buildRows([])).toEqual([]);
+	});
+});
+
+// ─── parseTargets ───────────────────────────────────────────────────────────
+
+describe("parseTargets", () => {
+	test("splits on commas, spaces, newlines", () => {
+		expect(parseTargets("ls, find  grep\nfetch")).toEqual([
+			"ls",
+			"find",
+			"grep",
+			"fetch",
+		]);
+	});
+
+	test("dedupes", () => {
+		expect(parseTargets("ls, ls")).toEqual(["ls"]);
+	});
+
+	test("empty yields empty", () => {
+		expect(parseTargets("")).toEqual([]);
+		expect(parseTargets("  , ")).toEqual([]);
+	});
+});
+
+// ─── renderList ─────────────────────────────────────────────────────────────
+
+describe("renderList", () => {
+	const rows: ToolRow[] = [
+		{ name: "read", description: "Read files.", mcp: false },
+		{ name: "grep", description: "Search files.", mcp: false },
+		{ name: "ctx", description: "MCP search.", mcp: true },
+	];
+	const isActive = (n: string) => n === "read";
+
+	test("shows status for each tool", () => {
+		const out = renderList(rows, isActive);
+		expect(out).toContain("✓ active  read");
+		expect(out).toContain("# gated  grep");
+		expect(out).toContain("# gated  ctx");
+		expect(out).toContain("[MCP]");
+	});
+
+	test("filters by query", () => {
+		const out = renderList(rows, isActive, "grep");
+		expect(out).toContain("grep");
+		expect(out).not.toContain("read");
+	});
+
+	test("no match message", () => {
+		const out = renderList(rows, isActive, "zzz");
+		expect(out).toContain('No tools matched "zzz"');
+	});
+
+	test("empty rows", () => {
+		expect(renderList([], isActive)).toContain("No tools registered");
+	});
+});
+
+// ─── toggleTool ─────────────────────────────────────────────────────────────
+
+describe("toggleTool", () => {
+	const rows: ToolRow[] = [
+		{ name: "read", description: "Read.", mcp: false },
+		{ name: "grep", description: "Search.", mcp: false },
+	];
+
+	test("enable calls onActivate", () => {
+		let called = "";
+		const ops: ToggleOps = {
+			onActivate: (n) => {
+				called = n;
+				return true;
+			},
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		const msg = toggleTool("enable", "grep", rows, ops);
+		expect(called).toBe("grep");
+		expect(msg).toContain("Enabled grep");
+	});
+
+	test("disable calls onDeactivate", () => {
+		let called = "";
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: (n) => {
+				called = n;
+				return true;
+			},
+			isActive: () => true,
+		};
+		const msg = toggleTool("disable", "read", rows, ops);
+		expect(called).toBe("read");
+		expect(msg).toContain("Disabled read");
+	});
+
+	test("unknown tool returns error", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		expect(toggleTool("enable", "nope", rows, ops)).toContain("Unknown");
+	});
+
+	test("already active returns already message", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => true,
+		};
+		expect(toggleTool("enable", "read", rows, ops)).toContain("already");
+	});
+
+	test("already gated returns already message", () => {
+		const ops: ToggleOps = {
+			onActivate: () => false,
+			onDeactivate: () => false,
+			isActive: () => false,
+		};
+		expect(toggleTool("disable", "read", rows, ops)).toContain("already");
+	});
+});
+
+// ─── Integration: /toolbox command ──────────────────────────────────────────
+
+// Isolate from real ~/.pi/agent/toolbox.json on disk
+let tmpAgentDir: string;
+beforeAll(() => {
+	tmpAgentDir = mkdtempSync(join(tmpdir(), "toolbox-test-"));
+	process.env.PI_CODING_AGENT_DIR = tmpAgentDir;
+});
+afterAll(() => {
+	delete process.env.PI_CODING_AGENT_DIR;
+	try {
+		rmSync(tmpAgentDir, { recursive: true });
+	} catch {}
+});
+
+function makeHost(toolNames: string[]) {
+	const handlers: Record<string, Array<(p: unknown) => unknown>> = {};
+	let active: string[] = [...toolNames];
+	const commands: Array<{ name: string; handler: Function }> = [];
+	const pi = {
+		on(ev: string, fn: (p: unknown) => unknown) {
+			(handlers[ev] ??= []).push(fn);
+		},
+		emit(ev: string, payload: unknown, ctx?: unknown) {
+			return Promise.all(
+				(handlers[ev] ?? []).map((f) => (f as Function)(payload, ctx)),
+			);
+		},
+		getAllTools() {
+			return toolNames.map((name) => ({
+				name,
+				description: `${name} does things.`,
+				parameters: {},
+				sourceInfo: { source: "builtin" },
+			}));
+		},
+		getActiveTools() {
+			return active;
+		},
+		setActiveTools(names: string[]) {
+			active = [...names];
+		},
+		getCommands() {
+			return [];
+		},
+		appendEntry() {},
+		registerTool() {},
+		registerCommand(name: string, def: { handler: Function }) {
+			commands.push({ name, handler: def.handler });
+		},
+	} as never;
+	const emit = (ev: string, payload: unknown, ctx?: unknown) =>
+		Promise.all((handlers[ev] ?? []).map((f) => (f as Function)(payload, ctx)));
+	return {
+		pi,
+		emit,
+		getActive: () => active,
+		command: (name: string) => commands.find((c) => c.name === name),
+	};
+}
+
+function makeCtx() {
+	const notes: Array<{ text: string; level?: string }> = [];
+	const ctx = {
+		ui: {
+			notify(text: string, level?: string) {
+				notes.push({ text, level });
+			},
+		},
+	} as never;
+	return { ctx, notes };
+}
+
+describe("/toolbox command", () => {
+	const ALL = ["read", "write", "bash", "grep", "ast_grep_search"];
+
+	async function boot() {
+		const host = makeHost(ALL);
+		registerToolbox(host.pi);
+		// session_start triggers init
+		await host.emit("session_start", {}, {});
+		return host;
+	}
+
+	test("registers a /toolbox command", async () => {
+		const host = await boot();
+		expect(host.command("toolbox")).toBeDefined();
+	});
+
+	test("bare /toolbox falls back to listing when no custom UI", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("", ctx);
+		expect(notes.length).toBe(1);
+		// only non-core tools shown, all start active
+		expect(notes[0].text).toContain("✓ active  grep");
+		expect(notes[0].text).toContain("✓ active  ast_grep_search");
+		// core tools excluded from toolbox
+		expect(notes[0].text).not.toContain("  read");
+		expect(notes[0].text).not.toContain("  bash");
+	});
+
+	test("/toolbox list shows non-core tools with status", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("list", ctx);
+		expect(notes[0].text).toContain("grep");
+		expect(notes[0].text).toContain("ast_grep_search");
+		expect(notes[0].text).not.toContain("  bash");
+	});
+
+	test("/toolbox list <query> filters", async () => {
+		const host = await boot();
+		const { ctx, notes } = makeCtx();
+		await host.command("toolbox")?.handler("list ast", ctx);
+		expect(notes[0].text).toContain("ast_grep_search");
+		expect(notes[0].text).not.toContain("✓ active  read");
+	});
+
+	test("opens interactive picker when ctx.ui.custom exists", async () => {
+		const host = await boot();
+		let customCalled = 0;
+		const notes: Array<{ text: string; level?: string }> = [];
+		const ctx = {
+			ui: {
+				notify(text: string, level?: string) {
+					notes.push({ text, level });
+				},
+				async custom() {
+					customCalled++;
+					return null;
+				},
+			},
+		} as never;
+		await host.command("toolbox")?.handler("", ctx);
+		expect(customCalled).toBe(1);
+		expect(notes.length).toBe(0);
+	});
+});