@maxiaochao/pi-toolkit 0.10.4 → 0.10.6

package/packages/todo/extensions/todo.ts

@@ -1,279 +0,0 @@
-/**
- * Branch-local execution-plan extension with tool-result snapshot persistence.
- *
- * The model sees only the current plan. The widget mirrors that plan, while
- * `/todos` shows the complete history for the active conversation branch.
- */
-
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { matchesKey, Text, truncateToWidth } from "@earendil-works/pi-tui";
-import { Type } from "typebox";
-import {
-	activeTodoRows,
-	applyTodoAction,
-	countTodoStatuses,
-	formatCurrentPlan,
-	normalizeTodo,
-	restoreTodoState,
-	type StoredTodo,
-	type Todo,
-	type TodoAction,
-	type TodoActionInput,
-	type TodoState,
-	type TodoStatus,
-} from "../src/todo-state.ts";
-
-interface TodoDetails {
-	action: TodoAction;
-	todos: StoredTodo[];
-	nextId: number;
-	error?: string;
-}
-
-const TodoParams = Type.Object({
-	action: StringEnum(["plan", "add_step", "complete_current", "cancel_current", "list"] as const, {
-		description: "plan creates or replaces the current plan; add_step appends; complete_current or cancel_current advances one expected current step; list reads the current plan",
-	}),
-	items: Type.Optional(Type.Array(Type.String(), {
-		description: "Ordered executable steps for plan; an empty array cancels all unfinished work",
-	})),
-	text: Type.Optional(Type.String({ description: "Step text for add_step" })),
-	expected_current_id: Type.Optional(Type.Integer({
-		minimum: 1,
-		description: "Stable ID of the sole current doing step; required by complete_current and cancel_current",
-	})),
-});
-
-const WIDGET_KEY = "todo-list";
-
-function sortedTodos(todos: Todo[]): Todo[] {
-	return [...todos].sort((a, b) => a.id - b.id);
-}
-
-function statusMarker(status: TodoStatus): string {
-	if (status === "doing") return "◼";
-	if (status === "done") return "✔";
-	if (status === "cancelled") return "✖";
-	return "◻";
-}
-
-function themedStatus(theme: Theme, status: TodoStatus, text: string): string {
-	if (status === "doing") return theme.fg("warning", text);
-	if (status === "done") return theme.fg("success", text);
-	if (status === "cancelled") return theme.fg("error", text);
-	return theme.fg("dim", text);
-}
-
-function historySummary(todos: Todo[]): string {
-	const counts = countTodoStatuses(todos);
-	return `${todos.length} steps · ${counts.done} done · ${counts.cancelled} cancelled · ${counts.doing + counts.todo} current`;
-}
-
-function currentSummary(todos: Todo[]): string {
-	const rows = activeTodoRows(todos);
-	return `${rows.length} current step${rows.length === 1 ? "" : "s"}`;
-}
-
-function renderHistoryLine(theme: Theme, todo: Todo): string {
-	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
-	if (todo.status === "done" || todo.status === "cancelled") {
-		return `${icon} \x1b[9m${theme.fg("dim", `#${todo.id} ${todo.text}`)}\x1b[29m`;
-	}
-	return `${icon} ${theme.fg("accent", `#${todo.id}`)} ${theme.fg("text", todo.text)}`;
-}
-
-function renderCurrentLine(theme: Theme, todo: Todo, position: number): string {
-	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
-	return `${icon} ${theme.fg("accent", `${position}.`)} ${theme.fg("text", todo.text)}`;
-}
-
-export class CurrentPlanWidget {
-	private cachedWidth?: number;
-	private cachedLines?: string[];
-	private readonly getTodos: () => Todo[];
-	private readonly theme: Theme;
-
-	constructor(getTodos: () => Todo[], theme: Theme) {
-		this.getTodos = getTodos;
-		this.theme = theme;
-	}
-
-	render(width: number): string[] {
-		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
-		const todos = this.getTodos();
-		const rows = activeTodoRows(todos);
-		this.cachedLines = [
-			truncateToWidth(`${this.theme.fg("accent", "●")} ${this.theme.fg("muted", currentSummary(todos))}`, width),
-			...rows.map(({ position, todo }) => truncateToWidth(`  ${renderCurrentLine(this.theme, todo, position)}`, width)),
-		];
-		this.cachedWidth = width;
-		return this.cachedLines;
-	}
-
-	invalidate(): void {
-		this.cachedWidth = undefined;
-		this.cachedLines = undefined;
-	}
-}
-
-class TodoListComponent {
-	private cachedWidth?: number;
-	private cachedLines?: string[];
-	private readonly todos: Todo[];
-	private readonly theme: Theme;
-	private readonly onClose: () => void;
-
-	constructor(todos: Todo[], theme: Theme, onClose: () => void) {
-		this.todos = todos;
-		this.theme = theme;
-		this.onClose = onClose;
-	}
-
-	handleInput(data: string): void {
-		if (matchesKey(data, "escape") || matchesKey(data, "ctrl+c")) this.onClose();
-	}
-
-	render(width: number): string[] {
-		if (this.cachedLines && this.cachedWidth === width) return this.cachedLines;
-
-		const border = this.theme.fg("borderMuted", "-".repeat(Math.max(0, width - 10)));
-		const lines = ["", truncateToWidth(`${this.theme.fg("borderMuted", "---")}${this.theme.fg("accent", " Todos ")}${border}`, width), ""];
-		if (this.todos.length === 0) {
-			lines.push(truncateToWidth(`  ${this.theme.fg("dim", "No todo history on this branch")}`, width));
-		} else {
-			lines.push(truncateToWidth(`${this.theme.fg("accent", "●")} ${this.theme.fg("muted", historySummary(this.todos))}`, width), "");
-			for (const todo of sortedTodos(this.todos)) lines.push(truncateToWidth(`  ${renderHistoryLine(this.theme, todo)}`, width));
-		}
-		lines.push("", truncateToWidth(`  ${this.theme.fg("dim", "Press Escape to close")}`, width), "");
-		this.cachedWidth = width;
-		this.cachedLines = lines;
-		return lines;
-	}
-
-	invalidate(): void {
-		this.cachedWidth = undefined;
-		this.cachedLines = undefined;
-	}
-}
-
-interface MountedWidget {
-	component: CurrentPlanWidget;
-	tui: { requestRender(): void };
-}
-
-export default function (pi: ExtensionAPI) {
-	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1") return;
-
-	let state: TodoState = { todos: [], nextId: 1 };
-	let mountedWidget: MountedWidget | undefined;
-	let actionQueue = Promise.resolve();
-	const snapshot = (): StoredTodo[] => state.todos.map((todo) => ({ ...todo }));
-
-	const refreshUI = (ctx: ExtensionContext) => {
-		if (!ctx.hasUI) return;
-		const hasCurrentPlan = activeTodoRows(state.todos).length > 0;
-		if (!hasCurrentPlan) {
-			if (mountedWidget) {
-				mountedWidget.component.invalidate();
-				ctx.ui.setWidget(WIDGET_KEY, undefined);
-				mountedWidget.tui.requestRender();
-				mountedWidget = undefined;
-			}
-			return;
-		}
-
-		if (mountedWidget) {
-			mountedWidget.component.invalidate();
-			mountedWidget.tui.requestRender();
-			return;
-		}
-
-		ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
-			const component = new CurrentPlanWidget(() => state.todos, theme);
-			mountedWidget = { component, tui };
-			component.invalidate();
-			tui.requestRender();
-			return component;
-		});
-	};
-
-	const reconstructState = (ctx: ExtensionContext) => {
-		state = { todos: [], nextId: 1 };
-		for (const entry of ctx.sessionManager.getBranch()) {
-			if (entry.type !== "message") continue;
-			const message = entry.message;
-			if (message.role !== "toolResult" || message.toolName !== "todo") continue;
-			const details = message.details as TodoDetails | undefined;
-			if (!details || !Array.isArray(details.todos) || typeof details.nextId !== "number") continue;
-			state = restoreTodoState(details.todos, details.nextId);
-		}
-		refreshUI(ctx);
-	};
-
-	pi.on("session_start", async (_event, ctx) => reconstructState(ctx));
-	pi.on("session_tree", async (_event, ctx) => reconstructState(ctx));
-	pi.on("session_shutdown", async (_event, ctx) => {
-		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
-		mountedWidget = undefined;
-	});
-
-	pi.registerTool({
-		name: "todo",
-		label: "Todo",
-		description: "Maintain a branch-local, user-visible CURRENT execution plan. Use plan only for explicit multi-step work, genuinely multi-stage work, or cross-model handoff—not simple one-step tasks. Preserve user intent and order. Complete only work actually done; blocked-but-needed work stays current. cancel_current means the current step is no longer needed while later steps remain valid; changed direction uses plan. Each completion/cancellation must name expected_current_id and advances exactly one step.",
-		parameters: TodoParams,
-		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const run = actionQueue.then(() => {
-				const result = applyTodoAction(state, params as TodoActionInput);
-				state = { todos: result.todos, nextId: result.nextId };
-				refreshUI(ctx);
-				return {
-					content: [{
-						type: "text" as const,
-						text: result.error ? `Error: ${result.error}\n\n${formatCurrentPlan(state.todos)}` : formatCurrentPlan(state.todos),
-					}],
-					details: {
-						action: params.action,
-						todos: snapshot(),
-						nextId: state.nextId,
-						...(result.error ? { error: result.error } : {}),
-					} as TodoDetails,
-					...(result.error ? { isError: true } : {}),
-				};
-			});
-			actionQueue = run.then(() => undefined, () => undefined);
-			return run;
-		},
-
-		renderCall(args, theme) {
-			let text = theme.fg("toolTitle", theme.bold("todo ")) + theme.fg("muted", args.action);
-			if (args.items) text += ` ${theme.fg("dim", `${args.items.length} steps`)}`;
-			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
-			if (args.expected_current_id !== undefined) text += ` ${theme.fg("accent", `#${args.expected_current_id}`)}`;
-			return new Text(text, 0, 0);
-		},
-
-		renderResult(result, _options, theme) {
-			const item = result.content[0];
-			const text = item?.type === "text" ? item.text : "";
-			const details = result.details as TodoDetails | undefined;
-			return new Text(details?.error ? theme.fg("error", text) : theme.fg("muted", text), 0, 0);
-		},
-	});
-
-	pi.registerCommand("todos", {
-		description: "Show full Todo history on the current branch",
-		handler: async (_args, ctx) => {
-			if (ctx.mode !== "tui") {
-				ctx.ui.notify("/todos requires interactive mode", "error");
-				return;
-			}
-			await ctx.ui.custom<void>((_tui, theme, _keybindings, done) =>
-				new TodoListComponent(snapshot().map(normalizeTodo), theme, () => done()),
-			);
-		},
-	});
-}

package/packages/todo/package.json

@@ -1,25 +0,0 @@
-{
-  "name": "@maxiaochao/pi-todo",
-  "version": "0.1.0",
-  "description": "Branch-local execution-plan lifecycle and history extension for Pi.",
-  "type": "module",
-  "keywords": ["pi-package", "pi-extension", "todo"],
-  "files": ["extensions", "src", "docs", "README.md", "TESTING.md", "CHANGELOG.md"],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/chaochaoxiaochao/pi-toolkit.git",
-    "directory": "packages/todo"
-  },
-  "pi": { "extensions": ["./extensions/todo.ts"] },
-  "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*",
-    "typebox": "*"
-  },
-  "scripts": {
-    "test": "node --experimental-strip-types tests/todo-state.mjs && node --experimental-strip-types tests/todo-extension.mjs",
-    "load-test": "pi -ne -e ./extensions/todo.ts"
-  },
-  "publishConfig": { "access": "public" }
-}

package/packages/todo/src/todo-state.ts

@@ -1,159 +0,0 @@
-export type TodoStatus = "todo" | "doing" | "done" | "cancelled";
-export type TodoAction = "plan" | "add_step" | "complete_current" | "cancel_current" | "list";
-
-export interface Todo {
-	id: number;
-	text: string;
-	status: TodoStatus;
-}
-
-export interface StoredTodo {
-	id: number;
-	text: string;
-	status?: TodoStatus;
-	done?: boolean;
-}
-
-export interface TodoState {
-	todos: Todo[];
-	nextId: number;
-}
-
-export interface ActiveTodoRow {
-	position: number;
-	todo: Todo;
-}
-
-export interface TodoActionInput {
-	action: TodoAction;
-	items?: string[];
-	text?: string;
-	expected_current_id?: number;
-}
-
-export interface TodoActionResult extends TodoState {
-	message: string;
-	error?: string;
-}
-
-export type TodoCounts = Record<TodoStatus, number>;
-
-export function normalizeTodo(todo: StoredTodo): Todo {
-	const status = todo.status === "todo" || todo.status === "doing" || todo.status === "done" || todo.status === "cancelled"
-		? todo.status
-		: todo.done
-			? "done"
-			: "todo";
-	return { id: todo.id, text: todo.text, status };
-}
-
-export function normalizeTodoFlow(todos: Todo[]): void {
-	const active = todos.filter((todo) => todo.status === "doing");
-	for (const todo of active.slice(1)) todo.status = "todo";
-	if (active.length > 0) return;
-
-	const next = todos.find((todo) => todo.status === "todo");
-	if (next) next.status = "doing";
-}
-
-export function restoreTodoState(stored: StoredTodo[], nextId?: number): TodoState {
-	const todos = stored.map(normalizeTodo).sort((a, b) => a.id - b.id);
-	normalizeTodoFlow(todos);
-	const minimumNextId = todos.reduce((max, todo) => Math.max(max, todo.id + 1), 1);
-	return { todos, nextId: Math.max(nextId ?? 1, minimumNextId) };
-}
-
-export function countTodoStatuses(todos: Todo[]): TodoCounts {
-	return todos.reduce<TodoCounts>(
-		(counts, todo) => {
-			counts[todo.status] += 1;
-			return counts;
-		},
-		{ todo: 0, doing: 0, done: 0, cancelled: 0 },
-	);
-}
-
-export function activeTodos(todos: Todo[]): Todo[] {
-	return [
-		...todos.filter((todo) => todo.status === "doing"),
-		...todos.filter((todo) => todo.status === "todo"),
-	];
-}
-
-export function activeTodoRows(todos: Todo[]): ActiveTodoRow[] {
-	return activeTodos(todos).map((todo, index) => ({ position: index + 1, todo }));
-}
-
-export function currentTodo(todos: Todo[]): Todo | undefined {
-	return todos.find((todo) => todo.status === "doing");
-}
-
-export function formatCurrentPlan(todos: Todo[]): string {
-	const current = activeTodos(todos);
-	if (current.length === 0) return "CURRENT plan: none";
-	return ["CURRENT plan", ...current.map((todo) => `#${todo.id} [${todo.status}] ${todo.text}`)].join("\n");
-}
-
-function cloneState(state: TodoState): TodoState {
-	return { todos: state.todos.map((todo) => ({ ...todo })), nextId: state.nextId };
-}
-
-function fail(state: TodoState, error: string): TodoActionResult {
-	return { ...cloneState(state), message: `Error: ${error}`, error };
-}
-
-function cleanText(text: string | undefined): string | undefined {
-	const cleaned = text?.trim();
-	return cleaned ? cleaned : undefined;
-}
-
-function closeCurrentAndAdvance(next: TodoState, expectedId: number | undefined, status: "done" | "cancelled"): TodoActionResult {
-	const current = next.todos.filter((todo) => todo.status === "doing");
-	if (expectedId === undefined) return fail(next, "expected_current_id is required");
-	if (current.length !== 1 || current[0].id !== expectedId) {
-		const actual = current.length === 1 ? `#${current[0].id}` : "none";
-		return fail(next, `expected current #${expectedId}, but current is ${actual}`);
-	}
-
-	current[0].status = status;
-	const following = next.todos.find((todo) => todo.status === "todo");
-	if (following) following.status = "doing";
-	return { ...next, message: `${status === "done" ? "Completed" : "Cancelled"} current step #${expectedId}` };
-}
-
-export function applyTodoAction(state: TodoState, input: TodoActionInput): TodoActionResult {
-	const next = cloneState(state);
-
-	switch (input.action) {
-		case "list":
-			return { ...next, message: "Listed current plan" };
-
-		case "plan": {
-			if (!input.items) return fail(state, "items is required for plan");
-			const items = input.items.map(cleanText);
-			if (items.some((item) => item === undefined)) return fail(state, "plan items must not be empty");
-			for (const todo of next.todos) {
-				if (todo.status === "doing" || todo.status === "todo") todo.status = "cancelled";
-			}
-			const texts = items as string[];
-			for (const [index, text] of texts.entries()) {
-				next.todos.push({ id: next.nextId++, text, status: index === 0 ? "doing" : "todo" });
-			}
-			return { ...next, message: texts.length === 0 ? "Cancelled all unfinished work" : `Planned ${texts.length} steps` };
-		}
-
-		case "add_step": {
-			const text = cleanText(input.text);
-			if (!text) return fail(state, "text is required for add_step");
-			const todo: Todo = { id: next.nextId++, text, status: currentTodo(next.todos) ? "todo" : "doing" };
-			next.todos.push(todo);
-			return { ...next, message: `Added step #${todo.id}` };
-		}
-
-		case "complete_current":
-			return closeCurrentAndAdvance(next, input.expected_current_id, "done");
-
-		case "cancel_current":
-			return closeCurrentAndAdvance(next, input.expected_current_id, "cancelled");
-	}
-}

package/packages/todo/tests/todo-extension.mjs

@@ -1,134 +0,0 @@
-import assert from "node:assert/strict";
-import registerTodo from "../extensions/todo.ts";
-
-const theme = {
-	fg(_color, text) { return text; },
-	bold(text) { return text; },
-};
-
-function createHarness(branch = [], hasUI = true) {
-	const handlers = new Map();
-	const commands = new Map();
-	let tool;
-	let currentBranch = branch;
-	let widget;
-	let historyComponent;
-	let renderRequests = 0;
-	const tui = { requestRender() { renderRequests += 1; } };
-	const ui = {
-		setWidget(_key, value) {
-			if (value === undefined) {
-				widget = undefined;
-				return;
-			}
-			widget = value(tui, theme);
-		},
-		notify() {},
-		async custom(factory) {
-			historyComponent = factory(tui, theme, {}, () => {});
-		},
-	};
-	const pi = {
-		on(name, handler) { handlers.set(name, handler); },
-		registerTool(definition) { tool = definition; },
-		registerCommand(name, definition) { commands.set(name, definition); },
-	};
-	const childGuard = process.env.PI_HERDR_SUBAGENTS_CHILD;
-	delete process.env.PI_HERDR_SUBAGENTS_CHILD;
-	try {
-		registerTodo(pi);
-	} finally {
-		if (childGuard === undefined) delete process.env.PI_HERDR_SUBAGENTS_CHILD;
-		else process.env.PI_HERDR_SUBAGENTS_CHILD = childGuard;
-	}
-	const context = {
-		hasUI,
-		mode: hasUI ? "tui" : "print",
-		ui,
-		sessionManager: { getBranch: () => currentBranch },
-	};
-	return {
-		handlers,
-		commands,
-		context,
-		get tool() { return tool; },
-		get widget() { return widget; },
-		get historyComponent() { return historyComponent; },
-		get renderRequests() { return renderRequests; },
-		setBranch(value) { currentBranch = value; },
-	};
-}
-
-function toolResult(todos, nextId) {
-	return {
-		type: "message",
-		message: {
-			role: "toolResult",
-			toolName: "todo",
-			details: { action: "list", todos, nextId },
-		},
-	};
-}
-
-const branch = [toolResult([
-	{ id: 1, text: "Closed history", status: "done" },
-	{ id: 2, text: "Current work", status: "doing" },
-	{ id: 3, text: "Later work", status: "todo" },
-], 4)];
-const harness = createHarness(branch);
-await harness.handlers.get("session_start")({}, harness.context);
-assert.ok(harness.tool, "Todo tool is registered");
-assert.deepEqual(harness.tool.parameters.properties.action.enum, ["plan", "add_step", "complete_current", "cancel_current", "list"]);
-assert.equal(harness.renderRequests, 1, "mounting the widget explicitly requests a TUI render");
-const mountedWidget = harness.widget;
-const initialWidget = mountedWidget.render(100).join("\n");
-assert.match(initialWidget, /1\. Current work/);
-assert.match(initialWidget, /2\. Later work/);
-assert.doesNotMatch(initialWidget, /#2|#3|Closed history|done|cancelled/, "widget hides IDs and closed history");
-
-const completed = await harness.tool.execute("complete", {
-	action: "complete_current",
-	expected_current_id: 2,
-}, undefined, undefined, harness.context);
-assert.equal(harness.widget, mountedWidget, "live updates keep the mounted widget component");
-assert.ok(harness.renderRequests >= 2, "state change invalidates the widget and requests another render");
-const updatedWidget = mountedWidget.render(100).join("\n");
-assert.match(updatedWidget, /1\. Later work/);
-assert.doesNotMatch(updatedWidget, /Current work/, "mounted widget reads current state instead of a captured row snapshot");
-assert.equal(completed.content[0].text, "CURRENT plan\n#3 [doing] Later work");
-
-await harness.commands.get("todos").handler("", harness.context);
-const history = harness.historyComponent.render(100).join("\n");
-assert.match(history, /#1 Closed history/);
-assert.match(history, /#2 Current work/);
-assert.match(history, /#3 Later work/, "/todos alone exposes complete branch history");
-
-await harness.tool.execute("empty", { action: "plan", items: [] }, undefined, undefined, harness.context);
-assert.equal(harness.widget, undefined, "widget disappears when the current plan is done or cancelled");
-assert.ok(harness.renderRequests >= 3, "unmounting the widget requests a render");
-
-harness.setBranch([toolResult([
-	{ id: 10, text: "Selected branch only", status: "doing" },
-	{ id: 11, text: "Selected branch next", status: "todo" },
-], 12)]);
-await harness.handlers.get("session_tree")({}, harness.context);
-const branchList = await harness.tool.execute("branch-list", { action: "list" }, undefined, undefined, harness.context);
-assert.equal(branchList.content[0].text, "CURRENT plan\n#10 [doing] Selected branch only\n#11 [todo] Selected branch next");
-assert.doesNotMatch(branchList.content[0].text, /Closed history|Later work/, "tree navigation reconstructs only getBranch snapshots");
-
-const serialized = createHarness([], false);
-await serialized.handlers.get("session_start")({}, serialized.context);
-const [planned, firstCompletion, repeatedCompletion] = await Promise.all([
-	serialized.tool.execute("plan", { action: "plan", items: ["First", "Second", "Third"] }, undefined, undefined, serialized.context),
-	serialized.tool.execute("complete-one", { action: "complete_current", expected_current_id: 1 }, undefined, undefined, serialized.context),
-	serialized.tool.execute("complete-repeat", { action: "complete_current", expected_current_id: 1 }, undefined, undefined, serialized.context),
-]);
-assert.equal(planned.content[0].text, "CURRENT plan\n#1 [doing] First\n#2 [todo] Second\n#3 [todo] Third");
-assert.equal(firstCompletion.content[0].text, "CURRENT plan\n#2 [doing] Second\n#3 [todo] Third");
-assert.equal(repeatedCompletion.isError, true, "same-turn repeated completion fails after the first queued call advances");
-assert.match(repeatedCompletion.content[0].text, /expected current #1, but current is #2/);
-assert.match(repeatedCompletion.content[0].text, /#2 \[doing\] Second/);
-const afterConcurrentCalls = await serialized.tool.execute("list", { action: "list" }, undefined, undefined, serialized.context);
-assert.equal(afterConcurrentCalls.content[0].text, "CURRENT plan\n#2 [doing] Second\n#3 [todo] Third");
-
-console.log("Todo extension integration tests passed");