@zhushanwen/pi-todo 0.2.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-todo",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AI-driven todo list for Pi — stateful task management with session persistence and /todos command.",
   "type": "module",
   "main": "src/index.ts",

package/src/__tests__/todo.test.ts

@@ -11,6 +11,8 @@ import {
 	VALID_STATUSES,
 } from "../model";
 import { renderWidgetLines } from "../render";
+import { createTodoSessionState } from "../state";
+import { handleSingleUpdate } from "../tool";
 
 // ── 数据模型 + 向后兼容 ──────────────────────────────
 
@@ -24,8 +26,8 @@ describe("Todo data model", () => {
 		expect(migrated.id).toBe(1);
 	});
 
-	it("should include exactly three valid statuses", () => {
-		expect(VALID_STATUSES).toEqual(["pending", "in_progress", "completed"]);
+	it("should include exactly four valid statuses", () => {
+		expect(VALID_STATUSES).toEqual(["pending", "in_progress", "completed", "cancelled"]);
 	});
 
 	it("should migrate verifying → in_progress", () => {
@@ -51,6 +53,18 @@ describe("Todo data model", () => {
 		const migrated = migrateTodo(veryOldTodo);
 		expect(migrated.status).toBe("pending");
 	});
+
+	it("should preserve isVerification flag (FR-6)", () => {
+		const todo = { id: 1, text: "run tests", status: "pending", isVerification: true } as unknown as Todo;
+		const migrated = migrateTodo(todo);
+		expect(migrated.isVerification).toBe(true);
+	});
+
+	it("should preserve cancelled status (FR-1 four-state)", () => {
+		const todo = { id: 1, text: "dropped", status: "cancelled" } as unknown as Todo;
+		const migrated = migrateTodo(todo);
+		expect(migrated.status).toBe("cancelled");
+	});
 });
 
 // ── todo add ────────────────────────────────────────
@@ -90,6 +104,25 @@ describe("todo add", () => {
 		expect(result.error).toBeUndefined();
 		expect(result.newTodos[0].text).toBe("new task");
 	});
+
+	it("should mark todos as verification when isVerification=true (FR-6)", () => {
+		const result = addTodos([], 1, ["run tests", "typecheck"], true);
+		expect(result.error).toBeUndefined();
+		expect(result.newTodos[0].isVerification).toBe(true);
+		expect(result.newTodos[1].isVerification).toBe(true);
+	});
+
+	it("should not set isVerification when omitted", () => {
+		const result = addTodos([], 1, ["regular task"]);
+		expect(result.error).toBeUndefined();
+		expect(result.newTodos[0].isVerification).toBeUndefined();
+	});
+
+	it("should not set isVerification when isVerification=false", () => {
+		const result = addTodos([], 1, ["regular task"], false);
+		expect(result.error).toBeUndefined();
+		expect(result.newTodos[0].isVerification).toBeUndefined();
+	});
 });
 
 // ── todo update batch ───────────────────────────────
@@ -144,6 +177,40 @@ describe("todo update batch", () => {
 		const result = updateTodos(todos, [{ id: 1, status: "banana" }]);
 		expect(result.error).toContain("invalid status");
 	});
+
+	it("FR-6: cancelled todo 不可恢复（status 更新拒绝）", () => {
+		const todos: Todo[] = [{ id: 1, text: "dropped", status: "cancelled" }];
+		const result = updateTodos(todos, [{ id: 1, status: "pending" }]);
+		expect(result.error).toBe("id 1 is cancelled");
+		expect(result.resultText).toContain("cannot be restored");
+		expect(result.updatedTodos).toEqual(todos);
+	});
+
+	it("FR-6: 验证任务不可 cancelled", () => {
+		const todos: Todo[] = [{ id: 2, text: "run tests", status: "in_progress", isVerification: true }];
+		const result = updateTodos(todos, [{ id: 2, status: "cancelled" }]);
+		expect(result.error).toBe("id 2 is verification todo");
+		expect(result.resultText).toContain("cannot be cancelled");
+		expect(result.updatedTodos).toEqual(todos);
+	});
+});
+
+// ── handleSingleUpdate FR-6 守卫（tool 单条路径）────
+
+describe("handleSingleUpdate FR-6 guards (tool single path)", () => {
+	it("FR-6: cancelled todo + status → cannot restore", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 1, text: "dropped", status: "cancelled" }];
+		const result = handleSingleUpdate(state, { action: "update", id: 1, status: "pending" });
+		expect(result.error).toBe("#1 is cancelled (cannot restore)");
+	});
+
+	it("FR-6: verification todo + status=cancelled → cannot cancel", () => {
+		const state = createTodoSessionState();
+		state.todos = [{ id: 2, text: "run tests", status: "in_progress", isVerification: true }];
+		const result = handleSingleUpdate(state, { action: "update", id: 2, status: "cancelled" });
+		expect(result.error).toBe("#2 is verification todo (cannot cancel)");
+	});
 });
 
 // ── completed 无拦截 ────────────────────────────────
@@ -195,6 +262,11 @@ describe("formatTodoLine", () => {
 		const todo: Todo = { id: 3, text: "task C", status: "completed" };
 		expect(formatTodoLine(todo)).toBe("[x] #3: task C");
 	});
+
+	it("should format cancelled todo", () => {
+		const todo: Todo = { id: 4, text: "task D", status: "cancelled" };
+		expect(formatTodoLine(todo)).toBe("[-] #4: task D");
+	});
 });
 
 // ── buildRender ─────────────────────────────────────

package/src/handlers.ts

@@ -55,7 +55,7 @@ function buildBeforeAgentStartMessage(state: TodoSessionState): { message: { cus
 
 // ── 状态重建 ────────────────────────────────────────
 
-export function reconstructState(state: TodoSessionState, ctx: ExtensionContext): void {
+function reconstructState(state: TodoSessionState, ctx: ExtensionContext): void {
 	state.todos = [];
 	state.nextId = 1;
 	state.userMessageCount = 0;

package/src/index.ts

@@ -35,6 +35,9 @@ export default function (pi: ExtensionAPI) {
 	// ── 闭包内状态（session 隔离） ─────────────────────
 	const state = createTodoSessionState();
 
+	// 全解耦：不再暴露 pi.__todoGetList 跨扩展 API（goal 不再读 todo 状态）。
+	// todo 进度由 AI 自行管理，goal 不做强制检查。
+
 	// ── 刷新显示（依赖闭包 state） ─────────────────────
 	function refreshDisplay(ctx: ExtensionContext): void {
 		const statusText = renderStatusText(state.todos, ctx.ui.theme);

package/src/model.ts

@@ -1,6 +1,7 @@
 /**
  * Todo 数据模型 — 纯函数，不依赖 Pi 运行时。
- * 三态: pending → in_progress → completed
+ * 四态: pending → in_progress → completed；任一状态 → cancelled
+ * （cancelled 不可恢复；isVerification 标记验证任务，FR-6 completion audit 用）
  */
 
 // ── 数据模型 ─────────────────────────────────────────
@@ -8,7 +9,9 @@
 export interface Todo {
 	id: number;
 	text: string;
-	status: "pending" | "in_progress" | "completed";
+	status: "pending" | "in_progress" | "completed" | "cancelled";
+	/** 验证任务标记（FR-6 completion audit）。验证任务必须 completed，不可 cancelled。 */
+	isVerification?: boolean;
 }
 
 export interface TodoDetails {
@@ -26,21 +29,12 @@ export interface TodoDetails {
 	};
 }
 
-export const VALID_STATUSES = ["pending", "in_progress", "completed"] as const;
+export const VALID_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
 
 export type ValidStatus = (typeof VALID_STATUSES)[number];
 
 // ── 迁移/兼容 ───────────────────────────────────────
 
-const STALE_CONTEXT_PATTERNS = ["aborted", "context canceled", "stale context", "stalecontext", "extension context no longer active"];
-
-/** 检查错误是否表示 stale / canceled context */
-export function isStaleContextError(error: Error | unknown): boolean {
-	const msg = error instanceof Error ? error.message : String(error);
-	const lower = msg.toLowerCase();
-	return STALE_CONTEXT_PATTERNS.some((p) => lower.includes(p));
-}
-
 /** 旧格式迁移：verifying → in_progress，failed → pending，done:boolean → status */
 export function migrateTodo(raw: Todo): Todo {
 	const record = raw as unknown as Record<string, unknown>;
@@ -66,6 +60,8 @@ export function migrateTodo(raw: Todo): Todo {
 		id: record.id as number,
 		text: record.text as string,
 		status,
+		// FR-6: 保留 isVerification 标记（可选字段，旧数据可能缺失）
+		isVerification: record.isVerification === true ? true : undefined,
 	};
 }
 
@@ -101,6 +97,7 @@ export function addTodos(
 	currentTodos: Todo[],
 	currentNextId: number,
 	texts: string[],
+	isVerification?: boolean,
 ): AddResult {
 	if (!texts || texts.length === 0) {
 		return {
@@ -129,6 +126,8 @@ export function addTodos(
 			id: nextId++,
 			text: trimmed[i],
 			status: "pending" as const,
+			// FR-6: isVerification 标记验证任务（可选，仅 add 时可设）
+			isVerification: isVerification === true ? true : undefined,
 		});
 	}
 	const endId = nextId - 1;
@@ -183,6 +182,21 @@ export function updateTodos(
 				resultText: `Error: invalid status '${u.status}' for update item id ${u.id}`,
 			};
 		}
+		// FR-6 不变量守卫：(a) cancelled 不可恢复；(b) 验证任务不可 cancelled
+		if (todo.status === "cancelled" && u.status !== undefined) {
+			return {
+				updatedTodos: currentTodos,
+				error: `id ${u.id} is cancelled`,
+				resultText: `Error: Todo #${u.id} is cancelled and cannot be restored`,
+			};
+		}
+		if (todo.isVerification && u.status === "cancelled") {
+			return {
+				updatedTodos: currentTodos,
+				error: `id ${u.id} is verification todo`,
+				resultText: `Error: Todo #${u.id} is a verification todo and cannot be cancelled`,
+			};
+		}
 	}
 
 	const updated = currentTodos.map((t) => {
@@ -207,6 +221,8 @@ export function formatTodoLine(t: Todo): string {
 			? "x"
 			: t.status === "in_progress"
 				? "~"
-				: " ";
+				: t.status === "cancelled"
+					? "-"
+					: " ";
 	return `[${mark}] #${t.id}: ${t.text}`;
 }

package/src/render.ts

@@ -6,7 +6,6 @@ import type { Theme } from "@mariozechner/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
 
 import {
-	buildRender,
 	getDisplayStatus,
 	type Todo,
 	type TodoDetails,
@@ -55,22 +54,25 @@ export function renderStatusText(todoList: Todo[], th: Theme): string {
 // ── Widget 双列渲染 ──────────────────────────────────
 
 /** 渲染单条 todo 的 widget 行（不含缩进），供 component.ts 复用 */
-export function renderWidgetItem(t: Todo, th: Theme): string {
+function renderWidgetItem(t: Todo, th: Theme): string {
 	const mark =
 		t.status === "completed"
 			? th.fg("success", "\u2713")
 			: t.status === "in_progress"
 				? th.fg("warning", "\u25cf")
-				: th.fg("dim", "\u25cb");
+				: t.status === "cancelled"
+					? th.fg("error", "\u2715")
+					: th.fg("dim", "\u25cb");
 	const id = th.fg("accent", `#${t.id}`);
-	const text = t.status === "completed" ? th.fg("dim", t.text) : th.fg("text", t.text);
+	const text =
+		t.status === "completed" || t.status === "cancelled" ? th.fg("dim", t.text) : th.fg("text", t.text);
 	return `${mark} ${id} ${text}`;
 }
 
 /** 单列布局渲染（widget 少量任务时使用） */
 const PI_TEXT_PADDING = 2;
 
-export function renderSingleColumn(
+function renderSingleColumn(
 	todos: Todo[],
 	th: Theme,
 	termWidth: number,
@@ -136,7 +138,7 @@ export function renderWidgetLines(
 
 // ── 列表渲染辅助函数 ─────────────────────────────────
 
-export function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, theme: Theme): string {
+function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, theme: Theme): string {
 	if (todoList.length === 0) {
 		return theme.fg("dim", "No todos");
 	}
@@ -149,9 +151,11 @@ export function buildTodoListText(todoList: Todo[], options: { expanded: boolean
 				? theme.fg("success", "\u2713")
 				: status === "in_progress"
 					? theme.fg("warning", "\u25cf")
-					: theme.fg("dim", "\u25cb");
+					: status === "cancelled"
+						? theme.fg("error", "\u2715")
+						: theme.fg("dim", "\u25cb");
 		const itemText =
-			status === "completed" ? theme.fg("dim", t.text) : theme.fg("muted", t.text);
+			status === "completed" || status === "cancelled" ? theme.fg("dim", t.text) : theme.fg("muted", t.text);
 		listText += `\n${mark} ${theme.fg("accent", `#${t.id}`)} ${itemText}`;
 	}
 	if (!options.expanded && todoList.length > MAX_COLLAPSED_ITEMS) {
@@ -205,4 +209,3 @@ export function renderTodoResult(result: unknown, options: { expanded: boolean }
 	}
 }
 
-export { buildRender };

package/src/tool.ts

@@ -28,33 +28,39 @@ export interface TodoActionParams {
 	texts?: string[];
 	ids?: number[];
 	status?: string;
+	isVerification?: boolean;
 	updates?: Array<{ id: number; status?: string; text?: string }>;
 }
 
 // ── TodoParams schema ────────────────────────────────
 
-export const TodoParams = Type.Object({
+const TodoParams = Type.Object({
 	action: StringEnum(["list", "add", "update", "delete", "clear"] as const),
 	text: Type.Optional(Type.String({ description: "Todo text (for update action)" })),
 	id: Type.Optional(Type.Number({ description: "Todo ID (for update action)" })),
 	texts: Type.Optional(Type.Array(Type.String(), { description: "Todo text list (for add action)" })),
 	ids: Type.Optional(Type.Array(Type.Number(), { description: "Todo ID list (for delete action)" })),
 	status: Type.Optional(
-		StringEnum(VALID_STATUSES, { description: "Target status (for update action)" }),
+			StringEnum(VALID_STATUSES, { description: "Target status (for update action)" }),
+		),
+	isVerification: Type.Optional(
+		Type.Boolean({
+			description: "Mark added todos as verification tasks (for add action). Verification todos must be completed (not cancelled) before goal completion.",
+		}),
 	),
 	updates: Type.Optional(
-		Type.Array(
-			Type.Object({
-				id: Type.Number({ description: "Todo ID to update" }),
-				status: Type.Optional(
-					Type.String({ description: "Target status; one of pending/in_progress/completed" }),
-				),
-				text: Type.Optional(Type.String({ description: "New todo text" })),
-			}),
-			{ description: "Batch updates array (takes priority over single id/status/text)" },
+			Type.Array(
+				Type.Object({
+					id: Type.Number({ description: "Todo ID to update" }),
+					status: Type.Optional(
+						Type.String({ description: "Target status; one of pending/in_progress/completed/cancelled" }),
+					),
+					text: Type.Optional(Type.String({ description: "New todo text" })),
+				}),
+				{ description: "Batch updates array (takes priority over single id/status/text)" },
+			),
 		),
-	),
-});
+	});
 
 // ── 错误结果构造 helper ──────────────────────────────
 
@@ -97,7 +103,7 @@ function handleAdd(
 		return { resultText: "", error: "texts required" };
 	}
 
-	const addResult = addTodos(state.todos, state.nextId, params.texts);
+	const addResult = addTodos(state.todos, state.nextId, params.texts, params.isVerification);
 	if (addResult.error) {
 		return { resultText: addResult.resultText || "", error: addResult.error };
 	}
@@ -134,7 +140,7 @@ function handleBatchUpdate(
 }
 
 /** update action: single */
-function handleSingleUpdate(
+export function handleSingleUpdate(
 	state: TodoSessionState,
 	params: TodoActionParams,
 ): { resultText: string; error?: string } {
@@ -151,6 +157,14 @@ function handleSingleUpdate(
 	const todo = state.todos.find((t) => t.id === params.id);
 	if (!todo) return { resultText: "", error: `#${params.id} not found` };
 
+	// FR-6 不变量守卫：(a) cancelled 不可恢复；(b) 验证任务不可 cancelled
+	if (todo.status === "cancelled" && params.status !== undefined) {
+		return { resultText: "", error: `#${params.id} is cancelled (cannot restore)` };
+	}
+	if (todo.isVerification && params.status === "cancelled") {
+		return { resultText: "", error: `#${params.id} is verification todo (cannot cancel)` };
+	}
+
 	if (params.status !== undefined) {
 		todo.status = params.status as Todo["status"];
 	}
@@ -219,7 +233,7 @@ function handleClear(state: TodoSessionState): string {
 
 // ── Dispatcher ───────────────────────────────────────
 
-export function executeTodoAction(
+function executeTodoAction(
 	params: TodoActionParams,
 	state: TodoSessionState,
 	ctx: ExtensionContext,
@@ -333,19 +347,19 @@ export function registerTodoTool(
 			"Manage a todo list." +
 			"\n\nAvailable actions:" +
 			"\n- list: View all todos" +
-			"\n- add: Batch add todos (requires texts array)" +
+			"\n- add: Batch add todos (requires texts array; optional isVerification marks verification tasks)" +
 			"\n- update: Update a todo (requires id, optional status/text)" +
 			"\n- delete: Batch delete todos (requires ids array)" +
-			"\n- clear: Clear all todos and reset IDs"
-		+ "\nWhen /goal is active, do NOT use this tool — use goal_manager's add_subtasks instead.",
-		promptSnippet: "Use todo when breaking multi-step work into trackable items during normal (non-goal) conversation. Not for single-step operations.",
+			"\n- clear: Clear all todos and reset IDs",
+		promptSnippet: "Use todo when breaking multi-step work into trackable items. Add verification todos (isVerification=true) for checks like running tests.",
 		promptGuidelines: [
 			"[Usage] 多步骤工作（3+步）时使用。AI 自发创建，无需用户触发",
-			"[Goal 冲突] /goal 激活后禁止使用 todo — 改用 add_subtasks",
+			"[验证任务] 执行任务 + 验证任务（isVerification=true，如 run tests / typecheck）一起建",
 			"[批量优先] 完成多项任务时使用 updates[] 批量更新，减少工具调用次数",
 			"[自动闭合] 全部完成后工具自动清理，无需手动 clear",
-			"[Not for] 单步操作、简单对话、/goal 已激活时",
+			"[Not for] 单步操作、简单对话",
 		],
+		executionMode: "sequential",
 		parameters: TodoParams,
 
 		async execute(_toolCallId: string, params: Static<typeof TodoParams>, signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {