@zhushanwen/pi-todo 0.3.0 → 0.4.0

package/src/__tests__/tool-rpc.test.ts

@@ -0,0 +1,285 @@
+/**
+ * executeTodoAction handler 级测试 —— 覆盖 `if (ctx.mode === "rpc")` 分支
+ * 和非 RPC 模式不附加 __gui__ 的路径。对齐 ask-user R-1~R-7 handler 级范式。
+ *
+ * 策略：executeTodoAction 未导出，通过 registerTodoTool + mock pi 捕获
+ * 已注册 tool，再以不同 ctx.mode 调 execute。每个用例新建 state（隔离），
+ * 无模块级状态需重置。
+ */
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import { createTodoSessionState, type TodoSessionState } from "../state";
+import { registerTodoTool } from "../tool";
+
+// ── Types for the registered tool ───────────────────────
+type TestMode = "tui" | "rpc" | "json" | "print";
+
+interface ExecuteResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: {
+		action: string;
+		todos: Array<{ id: number; text: string; status: string; isVerification?: boolean }>;
+		nextId: number;
+		__gui__?: {
+			v: number;
+			component: { type: string; props: { items: unknown[] } };
+		};
+	};
+}
+
+interface RegisteredTool {
+	name: string;
+	execute: (
+		toolCallId: string,
+		params: Record<string, unknown>,
+		signal: AbortSignal | undefined,
+		onUpdate: unknown,
+		ctx: { mode: TestMode },
+	) => Promise<ExecuteResult>;
+}
+
+// pi-coding-agent 的 ExtensionContext 类型声明里没有 mode 字段（运行时实际有），
+// 与 extension-protocol 的 GuiContext 结构化兼容。这里做最小 mock 并断言。
+interface MockPi {
+	tool?: RegisteredTool;
+	registerTool(tool: RegisteredTool): void;
+}
+
+/** 捕获注册的 tool，返回 + 暴露 state 供断言。 */
+function setup(): { tool: RegisteredTool; state: TodoSessionState } {
+	const state = createTodoSessionState();
+	const pi: MockPi = {
+		registerTool(tool) {
+			this.tool = tool;
+		},
+	};
+	registerTodoTool(pi as unknown as ExtensionAPI, state, () => {});
+	if (!pi.tool) throw new Error("registerTodoTool did not register a tool");
+	return { tool: pi.tool, state };
+}
+
+// ── Theme passthrough（与 todo.test.ts mockTheme 一致） ──
+const stubTheme = {
+	fg: (_color: string, text: string) => text,
+	bg: (_color: string, text: string) => text,
+	bold: (text: string) => text,
+	italic: (text: string) => text,
+	underline: (text: string) => text,
+	inverse: (text: string) => text,
+	strikethrough: (text: string) => text,
+	getFgAnsi: (_color: string) => "",
+	getBgAnsi: (_color: string) => "",
+	getColorMode: () => "truecolor" as const,
+	getThinkingBorderColor: () => (text: string) => text,
+	getBashModeBorderColor: () => (text: string) => text,
+} as unknown as Theme;
+
+/** RPC 模式 ctx：hasUI=false，refreshDisplay 调用 ui.theme/setStatus/setWidget。 */
+const makeRpcCtx = () => ({
+	mode: "rpc" as const,
+	hasUI: false,
+	ui: {
+		theme: stubTheme,
+		setStatus: () => {},
+		setWidget: () => {},
+	},
+});
+
+/** TUI 模式 ctx：hasUI=true。 */
+const makeTuiCtx = () => ({
+	mode: "tui" as const,
+	hasUI: true,
+	ui: {
+		theme: stubTheme,
+		setStatus: () => {},
+		setWidget: () => {},
+	},
+});
+
+// ── RPC 模式：附加 __gui__ ────────────────────────────
+
+describe("executeTodoAction — RPC mode attaches __gui__", () => {
+	it("R-1: rpc + add → details.__gui__ exists, type is list-tree", async () => {
+		const { tool } = setup();
+		const result = await tool.execute(
+			"id",
+			{ action: "add", texts: ["task A", "task B"] },
+			undefined,
+			undefined,
+			makeRpcCtx(),
+		);
+		expect(result.details.__gui__).toBeDefined();
+		expect(result.details.__gui__!.v).toBe(1);
+		expect(result.details.__gui__!.component.type).toBe("list-tree");
+		// 两条新增 todo 反映在 items 中
+		const items = result.details.__gui__!.component.props.items as Array<{
+			label: string;
+			icon: string;
+		}>;
+		expect(items).toHaveLength(2);
+		expect(items[0]).toMatchObject({ label: "#1: task A", icon: "dot" });
+		expect(items[1]).toMatchObject({ label: "#2: task B", icon: "dot" });
+	});
+
+	it("R-2: rpc + list → __gui__ reflects current todo state", async () => {
+		const { tool, state } = setup();
+		// 预置状态（绕开 add，直接构造 todos）
+		state.todos = [
+			{ id: 1, text: "pending task", status: "pending" },
+			{ id: 2, text: "active task", status: "in_progress" },
+			{ id: 3, text: "done task", status: "completed" },
+		];
+		state.nextId = 4;
+		const result = await tool.execute(
+			"id",
+			{ action: "list" },
+			undefined,
+			undefined,
+			makeRpcCtx(),
+		);
+		expect(result.details.__gui__).toBeDefined();
+		expect(result.details.__gui__!.component.type).toBe("list-tree");
+		const items = result.details.__gui__!.component.props.items as Array<{
+			label: string;
+			icon: string;
+			status?: string;
+		}>;
+		expect(items).toHaveLength(3);
+		// pending → dot 无 status
+		expect(items[0]).toMatchObject({ label: "#1: pending task", icon: "dot" });
+		expect(items[0]).not.toHaveProperty("status");
+		// in_progress → circle / running
+		expect(items[1]).toMatchObject({
+			label: "#2: active task",
+			icon: "circle",
+			status: "running",
+		});
+		// completed → check / done
+		expect(items[2]).toMatchObject({
+			label: "#3: done task",
+			icon: "check",
+			status: "done",
+		});
+	});
+
+	it("R-3: rpc + update → __gui__ reflects post-update status", async () => {
+		const { tool, state } = setup();
+		state.todos = [{ id: 1, text: "item", status: "pending" }];
+		state.nextId = 2;
+		const result = await tool.execute(
+			"id",
+			{ action: "update", updates: [{ id: 1, status: "in_progress" }] },
+			undefined,
+			undefined,
+			makeRpcCtx(),
+		);
+		expect(result.details.__gui__).toBeDefined();
+		const items = result.details.__gui__!.component.props.items as Array<{
+			icon: string;
+			status?: string;
+		}>;
+		expect(items[0]).toMatchObject({ icon: "circle", status: "running" });
+	});
+});
+
+// ── TUI 模式：不附加 __gui__ ──────────────────────────
+
+describe("executeTodoAction — non-RPC modes omit __gui__", () => {
+	it("T-1: tui + add → details.__gui__ is undefined", async () => {
+		const { tool } = setup();
+		const result = await tool.execute(
+			"id",
+			{ action: "add", texts: ["task A"] },
+			undefined,
+			undefined,
+			makeTuiCtx(),
+		);
+		expect(result.details.__gui__).toBeUndefined();
+		// details 仍带原生文本路径数据（todos / nextId）
+		expect(result.details.todos).toHaveLength(1);
+		expect(result.content[0].text).toContain("Added");
+	});
+
+	it("T-2: tui + list → details.__gui__ is undefined", async () => {
+		const { tool, state } = setup();
+		state.todos = [{ id: 1, text: "x", status: "pending" }];
+		state.nextId = 2;
+		const result = await tool.execute(
+			"id",
+			{ action: "list" },
+			undefined,
+			undefined,
+			makeTuiCtx(),
+		);
+		expect(result.details.__gui__).toBeUndefined();
+		// 文本内容仍可读
+		expect(result.content[0].text).toContain("#1");
+	});
+
+	it("T-3: print mode + add → details.__gui__ is undefined", async () => {
+		const { tool } = setup();
+		const result = await tool.execute(
+			"id",
+			{ action: "add", texts: ["task A"] },
+			undefined,
+			undefined,
+			{ mode: "print", hasUI: false, ui: { theme: stubTheme, setStatus: () => {}, setWidget: () => {} } },
+		);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+
+	it("T-4: json mode + add → details.__gui__ is undefined", async () => {
+		const { tool } = setup();
+		const result = await tool.execute(
+			"id",
+			{ action: "add", texts: ["task A"] },
+			undefined,
+			undefined,
+			{ mode: "json", hasUI: false, ui: { theme: stubTheme, setStatus: () => {}, setWidget: () => {} } },
+		);
+		expect(result.details.__gui__).toBeUndefined();
+	});
+});
+
+// ── 共享 state：rpc 附加但 details.todos 是快照副本 ────
+
+describe("executeTodoAction — state isolation & snapshot", () => {
+	it("S-1: each setup() yields independent state (no module-level leak)", async () => {
+		const { tool: tool1 } = setup();
+		await tool1.execute("id", { action: "add", texts: ["first"] }, undefined, undefined, makeRpcCtx());
+		// 第二个 setup 起步，不应看到第一个的 todos
+		const { tool: tool2, state: state2 } = setup();
+		expect(state2.todos).toHaveLength(0);
+		const result = await tool2.execute(
+			"id",
+			{ action: "list" },
+			undefined,
+			undefined,
+			makeRpcCtx(),
+		);
+		expect(result.content[0].text).toBe("No todos");
+		// 空 list 仍走 buildGui([])（rpc 分支无条件 attach）
+		expect(result.details.__gui__).toBeDefined();
+		expect(result.details.__gui__!.component.props.items).toEqual([]);
+	});
+
+	it("S-2: details.todos is a shallow array copy (splice-safe, element-shared)", async () => {
+		// executeTodoAction 用 [...state.todos] 做浅拷贝：数组独立、元素共享。
+		// add/clear 改数组长度时旧 details.todos 不受影响；但原地改元素会共享。
+		const { tool } = setup();
+		await tool.execute("id", { action: "add", texts: ["a", "b"] }, undefined, undefined, makeRpcCtx());
+		const before = (await tool.execute(
+			"id",
+			{ action: "list" },
+			undefined,
+			undefined,
+			makeRpcCtx(),
+		)).details.todos;
+		expect(before).toHaveLength(2);
+		// clear 改 state.todos 数组，已发出的 before 快照仍为 2 项
+		await tool.execute("id", { action: "clear" }, undefined, undefined, makeRpcCtx());
+		expect(before).toHaveLength(2);
+	});
+});

package/src/component.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Theme } from "@mariozechner/pi-coding-agent";
-import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
+import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 
 import type { Todo } from "./model";
 import { FALLBACK_TERM_WIDTH, renderDualColumn } from "./render";

package/src/handlers.ts

@@ -25,7 +25,7 @@ const REMINDER_INTERVAL = 2;
 export type RefreshDisplayFn = (ctx: ExtensionContext) => void;
 
 /** 构建极简提醒：只含下一个推荐任务 */
-function buildMinimalReminder(state: TodoSessionState): string {
+export function buildMinimalReminder(state: TodoSessionState): string {
 	const pendingTodos = state.todos.filter((t) => t.status !== "completed");
 	if (pendingTodos.length === 0) return "";
 
@@ -33,8 +33,7 @@ function buildMinimalReminder(state: TodoSessionState): string {
 	return `<todo_context>\n[TODO] 你有 ${pendingTodos.length} 个未完成任务。下一个应处理：#${next.id} ${next.text}\n</todo_context>`;
 }
 
-/** 构建 before_agent_start 的 todo context */
-function buildBeforeAgentStartMessage(state: TodoSessionState): { message: { customType: string; content: string; display: boolean } } | undefined {
+export function buildBeforeAgentStartMessage(state: TodoSessionState): { message: { customType: string; content: string; display: boolean } } | undefined {
 	if (state.todos.length === 0) return undefined;
 
 	const pendingTodos = state.todos.filter((t) => t.status !== "completed");
@@ -55,7 +54,7 @@ function buildBeforeAgentStartMessage(state: TodoSessionState): { message: { cus
 
 // ── 状态重建 ────────────────────────────────────────
 
-function reconstructState(state: TodoSessionState, ctx: ExtensionContext): void {
+export function reconstructState(state: TodoSessionState, ctx: ExtensionContext): void {
 	state.todos = [];
 	state.nextId = 1;
 	state.userMessageCount = 0;
@@ -100,8 +99,7 @@ function reconstructState(state: TodoSessionState, ctx: ExtensionContext): void
 
 // ── agent_end 子函数 ────────────────────────────────
 
-/** 1. Auto-clear */
-function handleAutoClear(state: TodoSessionState): { handled: boolean; cleared: boolean } {
+export function handleAutoClear(state: TodoSessionState): { handled: boolean; cleared: boolean } {
 	const allCompleted = state.todos.every((t) => t.status === "completed");
 	if (!allCompleted) {
 		state.allCompletedAtCount = null;
@@ -120,8 +118,7 @@ function handleAutoClear(state: TodoSessionState): { handled: boolean; cleared:
 	return { handled: true, cleared: false };
 }
 
-/** 2. 全部 completed 时设置延迟 steer（仅一次），由 before_agent_start 消费 */
-function handleCompletionSteer(state: TodoSessionState): boolean {
+export function handleCompletionSteer(state: TodoSessionState): boolean {
 	if (state.completionSteered) return false;
 	const allCompleted = state.todos.length > 0 && state.todos.every((t) => t.status === "completed");
 	if (!allCompleted) return false;
@@ -131,8 +128,7 @@ function handleCompletionSteer(state: TodoSessionState): boolean {
 	return true;
 }
 
-/** 3. Stall 检测 — 设置延迟 steer */
-function handleStallDetection(state: TodoSessionState): boolean {
+export function handleStallDetection(state: TodoSessionState): boolean {
 	if (
 		!state.stallNotified &&
 		state.userMessageCount - state.lastTodoCallCount >= STALL_THRESHOLD
@@ -147,8 +143,7 @@ function handleStallDetection(state: TodoSessionState): boolean {
 	return false;
 }
 
-/** 4. 提醒 — 设置延迟 steer */
-function handleReminder(state: TodoSessionState): boolean {
+export function handleReminder(state: TodoSessionState): boolean {
 	if (state.userMessageCount - state.lastTodoCallCount >= REMINDER_INTERVAL) {
 		const reminder = buildMinimalReminder(state);
 		if (reminder) {

package/src/index.ts

@@ -1,24 +1,23 @@
 /**
- * Todo Extension v2 - 三态任务清单，支持状态栏和 entry GC
+ * Todo Extension — 轻量三态任务清单（pending / in_progress / completed）。
  *
- * 改动要点：
- * - done: boolean → status: "pending" | "in_progress" | "completed" | "failed"
- * - toggle → update（id + 可选 status/text，带参数守卫）
- * - 新增 delete action
- * - 状态栏通过 ctx.ui.setStatus 显示进度
- * - reconstructState 向后兼容旧 done 字段 + entry GC
- * - 支持 verifyText/verifyAttempts 字段（数据模型增强）
- * - add 支持 verifyTexts 参数（验证文本映射）
+ * 设计定位：刻意不做状态机约束（与 goal 扩展的 7 态对立），状态自由流转；
+ * 状态持久化复用 Pi 自动记录的 toolResult entry（非 appendEntry）；
+ * 通过 agent_end → before_agent_start 的延迟 steer 驱动任务推进。
  *
- * 文件拆分（v3.1 — 修复 P1-1/P1-2/P1-3/P1-4 拆分后）：
- * - state.ts: TodoSessionState 接口 + 工厂
- * - model.ts: 数据模型 + 纯函数（add/update/migrate/format）
- * - render.ts: 状态栏 / widget / tool result 渲染
- * - component.ts: TodoListComponent TUI 组件
- * - tool.ts: TodoParams schema + 5 个 action handler + execute dispatcher + registerTodoTool
- * - handlers.ts: 5 个事件处理器 + reconstructState + buildPendingContext
- * - commands.ts: /todos 命令
- * - index.ts（本文件）: 工厂入口（创建 state + 注册所有 handler）
+ * 文件职责：
+ * - state.ts:    TodoSessionState 会话状态接口 + 工厂（闭包内创建，session 隔离）
+ * - model.ts:    纯函数数据层（Todo 类型、migrateTodo 兼容迁移、addTodos/updateTodos、format/buildGui）
+ * - tool.ts:     todo tool 注册 — 5 个 action（list/add/update/delete/clear）+ execute dispatcher
+ * - handlers.ts: 5 个事件处理器（session_start/session_tree/agent_start/before_agent_start/agent_end）
+ *                + reconstructState（回放最后一条 todo toolResult）+ steer 四机制（autoClear/completion/stall/reminder）
+ * - render.ts:   状态栏（status line）/ widget（单双列自适应）/ tool result 三层渲染
+ * - component.ts: /todos 命令的 TodoListComponent TUI 视图（只读双列）
+ * - commands.ts: /todos 命令注册
+ * - index.ts（本文件）: 工厂入口（创建 state + 注册 tool/command/event + refreshDisplay）
+ *
+ * 错误处理：handler 失败直接 throw（见 CLAUDE.md「Tool 设计」），不返回错误成功模式。
+ * model 层纯函数返回 Result 对象（合法），dispatcher 拿到 error 时 throw。
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";

package/src/model.ts

@@ -4,6 +4,8 @@
  * （cancelled 不可恢复；isVerification 标记验证任务，FR-6 completion audit 用）
  */
 
+import { guiComponent, type GuiRenderResult, guiResult, type TreeItem } from "@xyz-agent/extension-protocol";
+
 // ── 数据模型 ─────────────────────────────────────────
 
 export interface Todo {
@@ -18,15 +20,8 @@ export interface TodoDetails {
 	action: "list" | "add" | "update" | "delete" | "clear";
 	todos: Todo[];
 	nextId: number;
-	error?: string;
-	_render?: {
-		type: "task-list";
-		summary?: string;
-		data: {
-			items: Array<{ id: number; text: string; status: string }>;
-			meta: Record<string, string>;
-		};
-	};
+	/** GUI 渲染结果（仅 RPC 模式填充，前端 list-tree 渲染）。对齐 extension-protocol@0.2.0。 */
+	__gui__?: GuiRenderResult;
 }
 
 export const VALID_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
@@ -65,19 +60,42 @@ export function migrateTodo(raw: Todo): Todo {
 	};
 }
 
-// ── 渲染辅助 ─────────────────────────────────────────
+// ── GUI 渲染辅助 ─────────────────────────────────────
 
-export function buildRender(todoList: Todo[]): TodoDetails["_render"] {
-	const completed = todoList.filter((t) => t.status === "completed").length;
-	const total = todoList.length;
-	return {
-		type: "task-list" as const,
-		summary: `${completed}/${total} completed`,
-		data: {
-			items: todoList.map((t) => ({ id: t.id, text: t.text, status: t.status })),
-			meta: {},
-		},
-	};
+/**
+ * 把 todos 映射为 list-tree GuiRenderResult（对齐 extension-protocol@0.2.0）。
+ * status → icon/status 映射：
+ *   pending      → dot      / 无 status
+ *   in_progress  → circle   / running
+ *   completed    → check    / done
+ *   cancelled    → cross    / failed
+ */
+export function buildGui(todos: Todo[]): GuiRenderResult {
+	const items: TreeItem[] = todos.map((t) => {
+		const icon =
+			t.status === "completed"
+				? "check"
+				: t.status === "in_progress"
+					? "circle"
+					: t.status === "cancelled"
+						? "cross"
+						: "dot"; // pending
+		const status =
+			t.status === "in_progress"
+				? "running"
+				: t.status === "completed"
+					? "done"
+					: t.status === "cancelled"
+						? "failed"
+						: undefined; // pending 无 status
+		return {
+			icon,
+			label: `#${t.id}: ${t.text}`,
+			status,
+			depth: 0,
+		};
+	});
+	return guiResult(guiComponent("list-tree", { items }));
 }
 
 export function getDisplayStatus(t: Todo): string {

package/src/render.ts

@@ -3,7 +3,7 @@
  */
 
 import type { Theme } from "@mariozechner/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 import {
 	getDisplayStatus,
@@ -166,7 +166,7 @@ function buildTodoListText(todoList: Todo[], options: { expanded: boolean }, the
 
 // ── Tool renderResult handler ────────────────────────
 
-import { Text } from "@mariozechner/pi-tui";
+import { Text } from "@earendil-works/pi-tui";
 
 export function renderTodoResult(result: unknown, options: { expanded: boolean }, theme: Theme): Text {
 	const r = result as { content: Array<{ type: string; text?: string }>; details?: unknown };
@@ -176,10 +176,6 @@ export function renderTodoResult(result: unknown, options: { expanded: boolean }
 		return new Text(text?.type === "text" ? (text.text ?? "") : "", 0, 0);
 	}
 
-	if (details.error) {
-		return new Text(theme.fg("error", `Error: ${details.error}`), 0, 0);
-	}
-
 	const todoList = details.todos;
 
 	switch (details.action) {