@zhushanwen/pi-goal 0.3.0 → 0.4.0

package/src/__tests__/event-adapter.test.ts

@@ -0,0 +1,339 @@
+/**
+ * event-adapter.ts 测试 — agent_end / before_agent_start 核心逻辑
+ *
+ * 覆盖 agent_end 的 continuation + ESC 守卫（FR-6.7）+
+ * before_agent_start 的 AUTO_CLEAR/context wrap-up。
+ *
+ * 全解耦后不再测 allTasksDone followUp（原依赖 pi.__todoGetList，已删）。
+ * agent_end 流程简化为：budget 检查 → continuation 去抖。
+ *
+ * 用 fake pi + fake ctx（不 import Pi SDK）。handler 签名 (pi, session, ctx) → void/result。
+ */
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import { handleAgentEnd } from "../adapters/event-handlers/agent-end";
+import { handleBeforeAgentStart } from "../adapters/event-handlers/before-agent-start";
+import { createGoalState } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import { createGoalSession } from "../session";
+
+// ── Fake pi / ctx ────────────────────────────────────
+
+interface RecordedCall {
+	kind: "appendState" | "appendHistory" | "notify" | "sendContext" | "sendUser" | "setStatus" | "setWidget";
+	payload?: unknown;
+	text?: string;
+	level?: string;
+	content?: string;
+	deliverAs?: string;
+	customType?: string;
+	key?: string;
+}
+
+function makeFakePi(): { pi: ExtensionAPI; calls: RecordedCall[]; states: unknown[]; history: unknown[] } {
+	const calls: RecordedCall[] = [];
+	const states: unknown[] = [];
+	const history: unknown[] = [];
+	const pi = {
+		appendEntry(customType: string, data?: unknown): void {
+			calls.push({ kind: customType === "goal-history" ? "appendHistory" : "appendState", payload: data });
+			if (customType === "goal-history") history.push(data);
+			else states.push(data);
+		},
+		sendMessage(message: unknown, _options?: unknown): void {
+			const msg = message as { customType?: string; content?: string; display?: boolean };
+			calls.push({
+				kind: "sendContext",
+				content: msg.content,
+				customType: msg.customType,
+				payload: _options,
+			});
+		},
+		sendUserMessage(content: string | unknown[], options?: unknown): void {
+			calls.push({
+				kind: "sendUser",
+				content: typeof content === "string" ? content : undefined,
+				payload: options,
+			});
+		},
+	} as unknown as ExtensionAPI;
+	return { pi, calls, states, history };
+}
+
+function makeFakeCtx(overrides?: {
+	aborted?: boolean;
+	hasUI?: boolean;
+	contextUsage?: { tokens?: number; contextWindow?: number };
+}): { ctx: ExtensionContext; calls: RecordedCall[] } {
+	const calls: RecordedCall[] = [];
+	const signal = { aborted: overrides?.aborted ?? false } as AbortSignal;
+	const ctx = {
+		hasUI: overrides?.hasUI ?? true,
+		signal,
+		getContextUsage: () => overrides?.contextUsage,
+		ui: {
+			notify: (text: string, level: string) => {
+				calls.push({ kind: "notify", text, level });
+			},
+			setStatus: (key: string, text: string | undefined) => {
+				calls.push({ kind: "setStatus", key, text });
+			},
+			setWidget: (key: string, _content: unknown) => {
+				calls.push({ kind: "setWidget", key });
+			},
+			theme: {
+				fg: (_color: string, text: string) => text,
+				bold: (text: string) => text,
+			},
+		},
+		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+	} as unknown as ExtensionContext;
+	return { ctx, calls };
+}
+
+function allCalls(piCalls: RecordedCall[], ctxCalls: RecordedCall[]): RecordedCall[] {
+	return [...piCalls, ...ctxCalls];
+}
+
+// ── 辅助：构造 state ──────────────────────────────────
+
+function makeRunningState(overrides?: Partial<GoalRuntimeState>): GoalRuntimeState {
+	return {
+		...createGoalState("test objective"),
+		timeStartedAt: 0, // 关闭时间累计（避免测试随机性）
+		...overrides,
+	};
+}
+
+// ── handleAgentEnd：ESC 守卫 ──────────────────────────
+
+describe("handleAgentEnd — FR-6.7 ESC 守卫", () => {
+	it("aborted=true：不发 continuation、不递增 stall、不做 budget 检查、goal 保持 active", async () => {
+		const { pi, calls: piCalls, states } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({ aborted: true });
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 1000, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// 不发 continuation（无 sendContext/sendUser）
+		expect(all.filter((c) => c.kind === "sendContext" || c.kind === "sendUser")).toHaveLength(0);
+		// 不做 budget 检查（无 notify 关于 budget）
+		expect(all.filter((c) => c.kind === "notify")).toHaveLength(0);
+		// goal 保持 active（status 不变）
+		expect(session.state!.status).toBe("active");
+		// 不 persist（ESC 不触发副作用）
+		expect(states).toHaveLength(0);
+	});
+
+	it("aborted=true + 终态：仍走终态 notify（ESC 不影响终态路径）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({ aborted: true });
+		const session = createGoalSession();
+		session.state = makeRunningState({ status: "complete" });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// 终态 notify 仍触发
+		const notify = all.filter((c) => c.kind === "notify");
+		expect(notify).toHaveLength(1);
+		expect(notify[0]!.text).toContain("Objective completed");
+	});
+});
+
+// ── handleAgentEnd：continuation（去抖 + 正常发送）──────
+
+describe("handleAgentEnd — continuation", () => {
+	it("continuation 去抖：tokenDelta=0（空 turn）不发", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState({
+			tokensUsed: 100,
+			lastTurnTokensUsed: 100, // tokenDelta = 0
+		});
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const sendContext = all.filter((c) => c.kind === "sendContext");
+		expect(sendContext).toHaveLength(0); // 空 turn 不发
+	});
+
+	it("continuation 正常：tokenDelta>0 → 发 continuationPrompt", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState({
+			tokensUsed: 200,
+			lastTurnTokensUsed: 0, // tokenDelta = 200 > 0
+		});
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const sendContext = all.filter((c) => c.kind === "sendContext");
+		expect(sendContext).toHaveLength(1);
+		expect(sendContext[0]!.content).toContain("[GOAL]");
+	});
+});
+
+// ── handleAgentEnd：并发保护（G-021）+ stale（G-020）───
+
+describe("handleAgentEnd — 并发保护 + stale 快照", () => {
+	it("isProcessing=true → 直接返回（防重入）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState();
+		session.isProcessing = true; // 已锁
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// 无任何副作用
+		expect(all).toHaveLength(0);
+	});
+
+	it("finally 块释放 isProcessing（即使中途 return）", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx({ aborted: true });
+		const session = createGoalSession();
+		session.state = makeRunningState();
+
+		await handleAgentEnd(pi, session, ctx);
+
+		expect(session.isProcessing).toBe(false);
+	});
+
+	it("state=null → 直接返回（无 goal 时）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx();
+		const session = createGoalSession();
+		// session.state 保持 null
+
+		await handleAgentEnd(pi, session, ctx);
+
+		expect(allCalls(piCalls, ctxCalls)).toHaveLength(0);
+	});
+});
+
+// ── handleBeforeAgentStart ────────────────────────────
+
+describe("handleBeforeAgentStart", () => {
+	it("state=null → 返回 undefined", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx();
+		const session = createGoalSession();
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeUndefined();
+	});
+
+	it("正常 active goal → 返回 context injection 消息", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState();
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeDefined();
+		expect(result!.message.customType).toBe("goal-context");
+		expect(result!.message.content).toContain("[GOAL mode activated]");
+		expect(result!.message.display).toBe(false);
+	});
+
+	// 全解耦后：planAvailable 恒 true（不再运行时探测 pi.__planStart）。
+	// contextInjectionPrompt 恒定注入 plan mode 建议段落，AI 自行判断是否用。
+	it("恒定注入 plan mode 建议段落（全解耦：不再探测 plan extension）", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState();
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeDefined();
+		expect(result!.message.customType).toBe("goal-context");
+		expect(result!.message.content).toContain("plan mode");
+	});
+
+	// FR-8.1 G-007: AUTO_CLEAR_TURNS=2
+	it("终态 + turnsInTerminal >= 2 → clearGoalSession（state 清空）", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState({
+			status: "complete",
+			currentTurnIndex: 10,
+			completedAtTurnIndex: 8, // turnsInTerminal = 2 >= AUTO_CLEAR_TURNS
+		});
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeUndefined();
+		expect(session.state).toBeNull();
+	});
+
+	it("终态 + turnsInTerminal < 2 → 不清理，折叠 status bar", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({ hasUI: true });
+		const session = createGoalSession();
+		session.state = makeRunningState({
+			status: "complete",
+			currentTurnIndex: 10,
+			completedAtTurnIndex: 9, // turnsInTerminal = 1 < 2
+		});
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		expect(result).toBeUndefined();
+		expect(session.state).not.toBeNull(); // 未清理
+		// setStatus 触发（折叠为终态单行）
+		expect(all.filter((c) => c.kind === "setStatus" && c.key === "goal").length).toBeGreaterThan(0);
+	});
+
+	// ADR-002 context usage 提示（CONTEXT_USAGE_RATIO_LIMIT=0.85，保持 active）
+	it("context 使用率 > 85% → 保持 active + 注入 wrap-up 指令", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx({ contextUsage: { tokens: 9000, contextWindow: 10000 } }); // 90% > 85%
+		const session = createGoalSession();
+		session.state = makeRunningState();
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeDefined();
+		expect(result!.message.customType).toBe("goal-context-exceeded");
+		// ADR-002：goal 保持 active（不转 paused）
+		expect(session.state!.status).toBe("active");
+	});
+
+	it("context 使用率 <= 85% → 正常 context injection", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx({ contextUsage: { tokens: 5000, contextWindow: 10000 } }); // 50%
+		const session = createGoalSession();
+		session.state = makeRunningState();
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result!.message.customType).toBe("goal-context");
+		expect(session.state!.status).toBe("active");
+	});
+
+	it("非 active（blocked）→ 返回 undefined（不注入）", async () => {
+		const { pi } = makeFakePi();
+		const { ctx } = makeFakeCtx();
+		const session = createGoalSession();
+		session.state = makeRunningState({ status: "blocked" });
+
+		const result = await handleBeforeAgentStart(pi, session, ctx);
+
+		expect(result).toBeUndefined();
+	});
+});

package/src/__tests__/goal-control-adapter.test.ts

@@ -0,0 +1,303 @@
+/**
+ * goal_control adapter 测试 — handler 用 fake ports
+ *
+ * 覆盖 #3 验收：
+ * - complete: active 守卫 + evidence 必填 + finalizeAndPersist（status→complete + history）
+ * - report_blocked: active 守卫 + reason 必填 + tickState + transitionStatus(active→blocked) + persistState
+ *
+ * 全解耦后不再测 todo 前置检查（checkCompletePrerequisites / buildProgressInput / findIncompleteTodos 已删）。
+ * complete 不做 todo 完成硬检查——AI 自行判断（prompt 软建议）。
+ *
+ * 不 import Pi SDK（handler 接收 ServicePorts，纯逻辑）。
+ */
+import { describe, expect, it } from "vitest";
+
+import {
+	handleComplete,
+	handleCreate,
+	handleReportBlocked,
+} from "../adapters/goal-control-adapter";
+import { createGoalState, transitionStatus } from "../engine/goal";
+import type { GoalRuntimeState } from "../engine/types";
+import type { UiPort } from "../ports";
+import type { ServicePorts } from "../service";
+import { createGoalSession } from "../session";
+
+// ── Fake Ports ───────────────────────────────────────
+
+function makeFakePorts(): ServicePorts & {
+	states: GoalRuntimeState[];
+	history: unknown[];
+	notifications: Array<{ text: string; level: string }>;
+} {
+	const states: GoalRuntimeState[] = [];
+	const history: unknown[] = [];
+	const notifications: Array<{ text: string; level: string }> = [];
+	return {
+		states,
+		history,
+		notifications,
+		persistence: {
+			appendState: (s) => {
+				states.push(s);
+			},
+			appendHistory: (e) => {
+				history.push(e);
+			},
+		},
+		ui: {
+			setWidget: () => {},
+			setStatus: () => {},
+			notify: (text, level) => {
+				notifications.push({ text, level });
+			},
+			hasUI: true,
+			// widget.asTheme 期望 fg/bold（ports.ts 的 uiPort 同样携带）
+			fg: (_color: string, text: string) => text,
+			bold: (text: string) => text,
+		} as UiPort,
+		messaging: {
+			sendContextMessage: () => {},
+			sendUserMessage: () => {},
+		},
+		session: {
+			getEntries: () => [],
+			getContextUsage: () => null,
+			signal: undefined,
+		},
+	};
+}
+
+const activeState = (overrides: Partial<GoalRuntimeState> = {}): GoalRuntimeState => ({
+	...createGoalState("test"),
+	...overrides,
+});
+
+// ── handleComplete ───────────────────────────────────
+
+describe("handleComplete — active 守卫 + evidence + finalizeAndPersist", () => {
+	it("active + evidence → status complete + 写 history", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		const ports = makeFakePorts();
+
+		const details = handleComplete({ action: "complete", evidence: "tests pass" }, session, ports);
+
+		expect(details.action).toBe("complete");
+		expect(details.status).toBe("complete");
+		expect(session.state!.status).toBe("complete");
+		// finalizeAndPersist 写 history（FR-8.7）
+		expect(ports.history).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("info");
+	});
+
+	it("非 active（blocked）→ throw", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "blocked" });
+		expect(() => handleComplete({ action: "complete", evidence: "x" }, session, makeFakePorts())).toThrow(
+			/not active/,
+		);
+	});
+
+	it("evidence 空 → throw", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() =>
+			handleComplete({ action: "complete", evidence: "   " }, session, makeFakePorts()),
+		).toThrow(/evidence/);
+	});
+
+	it("completedTasks 写入 history", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		const ports = makeFakePorts();
+		handleComplete({ action: "complete", evidence: "done", completedTasks: 5 }, session, ports);
+		expect((ports.history[0] as { completedTasks?: number }).completedTasks).toBe(5);
+	});
+});
+
+// ── handleCreate ─────────────────────────────────────
+
+describe("handleCreate — slug+objective 必填 + 非终态守卫 + createGoal", () => {
+	it("无旧 goal + slug + objective → status active + slug 写入 + 持久化 + notify", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		const details = handleCreate(
+			{ action: "create", slug: "ship-feature-x", objective: "ship feature X" },
+			session,
+			ports,
+		);
+
+		expect(details.action).toBe("create");
+		expect(details.status).toBe("active");
+		expect(details.slug).toBe("ship-feature-x");
+		expect(session.state).not.toBeNull();
+		expect(session.state!.objective).toBe("ship feature X");
+		expect(session.state!.slug).toBe("ship-feature-x");
+		expect(session.state!.status).toBe("active");
+		// createGoal 内部 persistState 写一条 state
+		expect(ports.states).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("info");
+		expect(ports.notifications[0]?.text).toContain("ship feature X");
+	});
+
+	it("objective 空 → throw（即使有 slug）", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", slug: "x", objective: "   " }, session, makeFakePorts()),
+		).toThrow(/objective/);
+	});
+
+	it("slug 空 → throw（即使有 objective）", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", slug: "   ", objective: "do thing" }, session, makeFakePorts()),
+		).toThrow(/slug/);
+	});
+
+	it("slug 缺省 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate({ action: "create", objective: "do thing" }, session, makeFakePorts()),
+		).toThrow(/slug/);
+	});
+
+	it("已有 active goal → throw（D25 非终态守卫）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "active" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有 paused goal → throw（paused 也是非终态）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "paused" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有 blocked goal → throw（blocked 也是非终态）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "blocked" });
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "new", objective: "new obj" },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/already active/i);
+	});
+
+	it("已有终态 goal → 覆盖创建（快速路径，goalId 变新，slug 写入）", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "complete" });
+		const oldId = session.state!.goalId;
+		const ports = makeFakePorts();
+
+		const details = handleCreate(
+			{ action: "create", slug: "next-obj", objective: "next obj" },
+			session,
+			ports,
+		);
+
+		expect(details.status).toBe("active");
+		expect(session.state!.objective).toBe("next obj");
+		expect(session.state!.slug).toBe("next-obj");
+		expect(session.state!.goalId).not.toBe(oldId);
+	});
+
+	it("tokenBudget <= 0 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "x", objective: "x", tokenBudget: 0 },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/tokenBudget/);
+	});
+
+	it("timeBudgetMinutes <= 0 → throw", () => {
+		const session = createGoalSession();
+		expect(() =>
+			handleCreate(
+				{ action: "create", slug: "x", objective: "x", timeBudgetMinutes: -5 },
+				session,
+				makeFakePorts(),
+			),
+		).toThrow(/timeBudgetMinutes/);
+	});
+
+	it("合法 budget → 合并进新 state", () => {
+		const session = createGoalSession();
+		const ports = makeFakePorts();
+
+		handleCreate(
+			{ action: "create", slug: "x", objective: "x", tokenBudget: 8000, timeBudgetMinutes: 30 },
+			session,
+			ports,
+		);
+
+		expect(session.state!.budget.tokenBudget).toBe(8000);
+		expect(session.state!.budget.timeBudgetMinutes).toBe(30);
+	});
+});
+
+// ── handleReportBlocked ──────────────────────────────
+
+describe("handleReportBlocked — active 守卫 + tick + transition + persist", () => {
+	it("active + reason → status blocked + reason 记录 + tick 累加", () => {
+		const session = createGoalSession();
+		const past = Date.now() - 4000;
+		session.state = activeState({ timeStartedAt: past, timeUsedSeconds: 6 });
+		const ports = makeFakePorts();
+
+		const details = handleReportBlocked(
+			{ action: "report_blocked", reason: "stuck on X" },
+			session,
+			ports,
+		);
+
+		expect(details.action).toBe("report_blocked");
+		expect(details.status).toBe("blocked");
+		expect(session.state!.status).toBe("blocked");
+		expect(session.state!.lastBlockerReason).toBe("stuck on X");
+		// MF-3 tick：转 blocked 前累加当前运行段（6 + ~4s）
+		expect(session.state!.timeUsedSeconds).toBeGreaterThanOrEqual(9);
+		// persistState 持久化
+		expect(ports.states).toHaveLength(1);
+		expect(ports.notifications[0]?.level).toBe("warning");
+	});
+
+	it("非 active（complete）→ throw", () => {
+		const session = createGoalSession();
+		session.state = activeState({ status: "complete" });
+		expect(() =>
+			handleReportBlocked({ action: "report_blocked", reason: "x" }, session, makeFakePorts()),
+		).toThrow(/not active/);
+	});
+
+	it("reason 空 → throw", () => {
+		const session = createGoalSession();
+		session.state = activeState();
+		expect(() =>
+			handleReportBlocked({ action: "report_blocked", reason: "" }, session, makeFakePorts()),
+		).toThrow(/reason/);
+	});
+
+	it("active→blocked 是合法转换", () => {
+		// transitionStatus 自身已由 engine 测试覆盖，此处验证集成不破坏
+		expect(transitionStatus("active", "blocked")).toBe("blocked");
+	});
+});