@maxiaochao/pi-toolkit 0.8.2 → 0.9.1

package/extensions/todo-state.ts

@@ -0,0 +1,151 @@
+export type TodoStatus = "todo" | "doing" | "done" | "cancelled";
+export type TodoAction = "list" | "replace" | "add" | "update" | "remove" | "clear";
+
+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 TodoActionInput {
+	action: TodoAction;
+	text?: string;
+	items?: string[];
+	id?: number;
+	status?: TodoStatus;
+}
+
+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" || todo.status === "todo");
+}
+
+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 hasActiveDuplicate(todos: Todo[], text: string): boolean {
+	return todos.some((todo) => (todo.status === "todo" || todo.status === "doing") && todo.text === text);
+}
+
+export function applyTodoAction(state: TodoState, input: TodoActionInput): TodoActionResult {
+	const next = cloneState(state);
+
+	switch (input.action) {
+		case "list":
+			return { ...next, message: next.todos.length ? "Listed todos" : "No todos" };
+
+		case "replace": {
+			if (!input.items?.length) return fail(state, "items required for replace");
+			const items = input.items.map(cleanText);
+			if (items.some((item) => item === undefined)) return fail(state, "replace items must not be empty");
+			const texts = items as string[];
+			if (new Set(texts).size !== texts.length) return fail(state, "replace items must be unique");
+			const firstId = next.nextId;
+			next.todos = texts.map((text, index) => ({ id: firstId + index, text, status: index === 0 ? "doing" : "todo" }));
+			next.nextId += next.todos.length;
+			return { ...next, message: `Replaced plan with ${next.todos.length} tasks` };
+		}
+
+		case "add": {
+			const text = cleanText(input.text);
+			if (!text) return fail(state, "text required for add");
+			if (hasActiveDuplicate(next.todos, text)) return fail(state, `active task already exists: ${text}`);
+			if (input.status === "doing") {
+				for (const todo of next.todos) if (todo.status === "doing") todo.status = "todo";
+			}
+			const todo: Todo = { id: next.nextId++, text, status: input.status ?? "todo" };
+			next.todos.push(todo);
+			normalizeTodoFlow(next.todos);
+			return { ...next, message: `Added todo #${todo.id} [${todo.status}]: ${todo.text}` };
+		}
+
+		case "update": {
+			if (input.id === undefined || input.status === undefined) return fail(state, "id and status required for update");
+			const todo = next.todos.find((item) => item.id === input.id);
+			if (!todo) return fail(state, `#${input.id} not found`);
+			if (input.status === "doing") {
+				for (const item of next.todos) if (item.status === "doing") item.status = "todo";
+			}
+			todo.status = input.status;
+			normalizeTodoFlow(next.todos);
+			return { ...next, message: `Todo #${todo.id} is now ${todo.status}` };
+		}
+
+		case "remove": {
+			if (input.id === undefined) return fail(state, "id required for remove");
+			const index = next.todos.findIndex((item) => item.id === input.id);
+			if (index < 0) return fail(state, `#${input.id} not found`);
+			const [removed] = next.todos.splice(index, 1);
+			normalizeTodoFlow(next.todos);
+			return { ...next, message: `Removed todo #${removed.id}: ${removed.text}` };
+		}
+
+		case "clear": {
+			const count = next.todos.length;
+			return { todos: [], nextId: 1, message: `Cleared ${count} todos` };
+		}
+	}
+}

package/extensions/todo.ts

@@ -1,30 +1,25 @@
 /**
- * Lightweight todo extension with branch-aware session persistence.
+ * Session-scoped todo extension with branch-aware persistence.
  *
- * Provides one `todo` tool, a `/todos` dialog, a persistent below-editor
- * widget, and footer counts. It has no subagent integration or prompt hooks.
+ * Provides the `todo` tool, a compact active-work widget, and `/todos` current-plan view.
  */
 
 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";
-
-type TodoStatus = "todo" | "doing" | "done";
-type TodoAction = "list" | "add" | "update" | "toggle" | "clear";
-
-interface Todo {
-	id: number;
-	text: string;
-	status: TodoStatus;
-}
-
-interface StoredTodo {
-	id: number;
-	text: string;
-	status?: TodoStatus;
-	done?: boolean;
-}
+import {
+	activeTodos,
+	applyTodoAction,
+	countTodoStatuses,
+	normalizeTodo,
+	restoreTodoState,
+	type StoredTodo,
+	type Todo,
+	type TodoAction,
+	type TodoState,
+	type TodoStatus,
+} from "./todo-state.ts";
 
 interface TodoDetails {
 	action: TodoAction;
@@ -34,37 +29,22 @@ interface TodoDetails {
 }
 
 const TodoParams = Type.Object({
-	action: StringEnum(["list", "add", "update", "toggle", "clear"] as const, {
-		description: "Operation to perform. Prefer update over toggle when setting an explicit status.",
+	action: StringEnum(["list", "replace", "add", "update", "remove", "clear"] as const, {
+		description: "list current tasks; replace the plan; add one; update status; remove one; or clear all",
 	}),
-	text: Type.Optional(Type.String({ description: "Specific, outcome-oriented task text. Required for add." })),
-	id: Type.Optional(Type.Number({ description: "Todo ID. Required for update and toggle." })),
-	status: Type.Optional(StringEnum(["todo", "doing", "done"] as const, {
-		description: "Explicit task state. Required for update; optional for add (defaults to todo).",
+	items: Type.Optional(Type.Array(Type.String(), {
+		minItems: 1,
+		description: "Complete ordered task texts for replace",
+	})),
+	text: Type.Optional(Type.String({ description: "Task text for add" })),
+	id: Type.Optional(Type.Integer({ minimum: 1, description: "Task ID for update or remove" })),
+	status: Type.Optional(StringEnum(["todo", "doing", "done", "cancelled"] as const, {
+		description: "New status for update; optional initial status for add",
 	})),
 });
 
 const WIDGET_KEY = "todo-list";
 
-function normalizeTodo(todo: StoredTodo): Todo {
-	const status = todo.status === "todo" || todo.status === "doing" || todo.status === "done"
-		? todo.status
-		: todo.done
-			? "done"
-			: "todo";
-	return { id: todo.id, text: todo.text, status };
-}
-
-function countStatuses(todos: Todo[]): Record<TodoStatus, number> {
-	return todos.reduce<Record<TodoStatus, number>>(
-		(counts, todo) => {
-			counts[todo.status] += 1;
-			return counts;
-		},
-		{ todo: 0, doing: 0, done: 0 },
-	);
-}
-
 function sortedTodos(todos: Todo[]): Todo[] {
 	return [...todos].sort((a, b) => a.id - b.id);
 }
@@ -72,24 +52,29 @@ function sortedTodos(todos: Todo[]): Todo[] {
 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 taskSummary(todos: Todo[]): string {
-	const counts = countStatuses(todos);
-	const noun = todos.length === 1 ? "task" : "tasks";
-	return `${todos.length} ${noun} (${counts.done} done, ${counts.doing} in progress, ${counts.todo} open)`;
+	const counts = countTodoStatuses(todos);
+	const active = counts.todo + counts.doing;
+	const parts = [`${active} active (${counts.doing} doing, ${counts.todo} queued)`];
+	if (counts.done > 0) parts.push(`${counts.done} done`);
+	if (counts.cancelled > 0) parts.push(`${counts.cancelled} cancelled`);
+	return parts.join(" · ");
 }
 
 function renderTodoLine(theme: Theme, todo: Todo): string {
 	const icon = themedStatus(theme, todo.status, statusMarker(todo.status));
-	if (todo.status === "done") {
+	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)}`;
@@ -143,14 +128,14 @@ class TodoListComponent {
 export default function (pi: ExtensionAPI) {
 	if (process.env.PI_SUBAGENT_CHILD === "1") return;
 
-	let todos: Todo[] = [];
-	let nextId = 1;
+	let state: TodoState = { todos: [], nextId: 1 };
 
-	const snapshot = (): StoredTodo[] => todos.map((todo) => ({ ...todo }));
+	const snapshot = (): StoredTodo[] => state.todos.map((todo) => ({ ...todo }));
 
 	const refreshUI = (ctx: ExtensionContext) => {
 		if (!ctx.hasUI) return;
-		if (todos.length === 0) {
+		const visible = activeTodos(state.todos);
+		if (visible.length === 0) {
 			ctx.ui.setWidget(WIDGET_KEY, undefined);
 			return;
 		}
@@ -160,8 +145,8 @@ export default function (pi: ExtensionAPI) {
 			(_tui, theme) => ({
 				render(width: number): string[] {
 					return [
-						truncateToWidth(`${theme.fg("accent", "●")} ${theme.fg("muted", taskSummary(todos))}`, width),
-						...sortedTodos(todos).map((todo) => truncateToWidth(`  ${renderTodoLine(theme, todo)}`, width)),
+						truncateToWidth(`${theme.fg("accent", "●")} ${theme.fg("muted", taskSummary(state.todos))}`, width),
+						...sortedTodos(visible).map((todo) => truncateToWidth(`  ${renderTodoLine(theme, todo)}`, width)),
 					];
 				},
 				invalidate() {},
@@ -170,16 +155,14 @@ export default function (pi: ExtensionAPI) {
 	};
 
 	const reconstructState = (ctx: ExtensionContext) => {
-		todos = [];
-		nextId = 1;
+		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;
-			todos = details.todos.map(normalizeTodo);
-			nextId = details.nextId;
+			state = restoreTodoState(details.todos, details.nextId);
 		}
 		refreshUI(ctx);
 	};
@@ -187,116 +170,39 @@ export default function (pi: ExtensionAPI) {
 	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) return;
-		ctx.ui.setWidget(WIDGET_KEY, undefined);
+		if (ctx.hasUI) ctx.ui.setWidget(WIDGET_KEY, undefined);
 	});
 
 	pi.registerTool({
 		name: "todo",
 		label: "Todo",
-		description: `Maintain a visible, session-scoped task list with explicit todo, doing, and done states.
-
-Use this tool when:
-- The user asks for a checklist, plan, or progress tracking.
-- Work has multiple concrete steps whose progress should remain visible.
-- A task starts, finishes, becomes pending again, or the current state must be inspected.
-
-Do not create a list for a single trivial action unless the user explicitly requests one. Keep task text specific and outcome-oriented. Avoid duplicate tasks.
-
-States:
-- todo: Planned but not started, or intentionally returned to the queue.
-- doing: Actively being worked on now. Set this immediately before starting the task.
-- done: Fully completed and, when applicable, verified. Never mark partial or failed work done.
-
-Actions:
-- list: Read the complete current list. Use before updating when IDs or current states are uncertain, and when reporting progress.
-- add: Create one task using text. It defaults to todo; pass status only when the task is already active or completed.
-- update: Set an exact state using id and status. This is the preferred way to move tasks between todo, doing, and done.
-- toggle: Cycle one task todo -> doing -> done -> todo. Use only for quick manual-style transitions when the current state is already known; otherwise use update.
-- clear: Remove the entire list and reset IDs. Use only when the user requests a reset or the whole list is obsolete.
-
-Execution discipline:
-- Move a task to doing before performing it.
-- Move it to done immediately after successful completion and verification.
-- Leave failed, blocked, or incomplete work as doing, or move it back to todo when it is no longer active.
-- Keep only genuinely active work in doing; sequential workflows normally have one doing task at a time.`,
+		description: "Track explicit checklists and non-trivial multi-step work. Replace the plan when instructions change. The tool keeps one task doing and advances automatically; mark obsolete work cancelled and verified work done.",
 		parameters: TodoParams,
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			let text: string;
-			let error: string | undefined;
-
-			switch (params.action) {
-				case "list":
-					text = todos.length
-						? sortedTodos(todos).map((todo) => `${statusMarker(todo.status)} #${todo.id} [${todo.status}] ${todo.text}`).join("\n")
-						: "No todos";
-					break;
-
-				case "add": {
-					if (!params.text) {
-						error = "text required for add";
-						text = `Error: ${error}`;
-						break;
-					}
-					const todo: Todo = { id: nextId++, text: params.text, status: params.status ?? "todo" };
-					todos.push(todo);
-					text = `Added todo #${todo.id} [${todo.status}]: ${todo.text}`;
-					break;
-				}
-
-				case "update": {
-					if (params.id === undefined || params.status === undefined) {
-						error = "id and status required for update";
-						text = `Error: ${error}`;
-						break;
-					}
-					const todo = todos.find((item) => item.id === params.id);
-					if (!todo) {
-						error = `#${params.id} not found`;
-						text = `Todo ${error}`;
-						break;
-					}
-					todo.status = params.status;
-					text = `Todo #${todo.id} is now ${todo.status}`;
-					break;
-				}
-
-				case "toggle": {
-					if (params.id === undefined) {
-						error = "id required for toggle";
-						text = `Error: ${error}`;
-						break;
-					}
-					const todo = todos.find((item) => item.id === params.id);
-					if (!todo) {
-						error = `#${params.id} not found`;
-						text = `Todo ${error}`;
-						break;
-					}
-					todo.status = todo.status === "todo" ? "doing" : todo.status === "doing" ? "done" : "todo";
-					text = `Todo #${todo.id} is now ${todo.status}`;
-					break;
-				}
-
-				case "clear": {
-					const count = todos.length;
-					todos = [];
-					nextId = 1;
-					text = `Cleared ${count} todos`;
-					break;
-				}
-			}
+			const result = applyTodoAction(state, params);
+			state = { todos: result.todos, nextId: result.nextId };
+			const text = params.action === "list"
+				? state.todos.length
+					? sortedTodos(state.todos).map((todo) => `${statusMarker(todo.status)} #${todo.id} [${todo.status}] ${todo.text}`).join("\n")
+					: "No todos"
+				: result.message;
 
 			refreshUI(ctx);
 			return {
 				content: [{ type: "text" as const, text }],
-				details: { action: params.action, todos: snapshot(), nextId, ...(error ? { error } : {}) } as TodoDetails,
+				details: {
+					action: params.action,
+					todos: snapshot(),
+					nextId: state.nextId,
+					...(result.error ? { error: result.error } : {}),
+				} as TodoDetails,
 			};
 		},
 
 		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} tasks`)}`;
 			if (args.text) text += ` ${theme.fg("dim", `"${args.text}"`)}`;
 			if (args.id !== undefined) text += ` ${theme.fg("accent", `#${args.id}`)}`;
 			if (args.status) text += ` ${themedStatus(theme, args.status, args.status)}`;
@@ -314,9 +220,7 @@ Execution discipline:
 			if (details.action === "list") {
 				const list = details.todos.map(normalizeTodo);
 				if (list.length === 0) return new Text(theme.fg("dim", "No todos"), 0, 0);
-				const display = sortedTodos(list);
-				const output = display.map((todo) => renderTodoLine(theme, todo)).join("\n");
-				return new Text(output, 0, 0);
+				return new Text(sortedTodos(list).map((todo) => renderTodoLine(theme, todo)).join("\n"), 0, 0);
 			}
 
 			const item = result.content[0];
@@ -326,14 +230,14 @@ Execution discipline:
 	});
 
 	pi.registerCommand("todos", {
-		description: "Show all todos on the current branch",
+		description: "Show active and closed tasks in the current plan",
 		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(todos, theme, () => done()),
+				new TodoListComponent(state.todos, theme, () => done()),
 			);
 		},
 	});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.8.2",
-  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
+  "version": "0.9.1",
+  "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
     "pi-package",
@@ -25,7 +25,8 @@
     "extensions": [
       "./extensions/todo.ts",
       "./extensions/cache-export/index.ts",
-      "./extensions/btw.ts"
+      "./extensions/btw.ts",
+      "./extensions/codex-edit/index.ts"
     ],
     "skills": [
       "./skills"
@@ -47,8 +48,8 @@
     "ws": "^8.19.0"
   },
   "scripts": {
-    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs && node tests/e2e-browser.mjs",
-    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts",
+    "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types ../tests/btw-history.mjs && node --experimental-strip-types ../tests/todo-state.mjs && node tests/e2e-browser.mjs && cd ../codex-edit && node --experimental-strip-types --test tests/package.test.mjs tests/parser.test.mjs",
+    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts && pi -ne -e ./extensions/btw.ts && pi -ne -e ./extensions/codex-edit/index.ts",
     "eval:agents": "node evaluations/agents-md/run.mjs",
     "eval:agents:test": "node evaluations/agents-md/tests/run-tests.mjs",
     "postinstall": "node scripts/install-agents.mjs"