@zhushanwen/pi-goal 0.6.3 → 0.6.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-goal",
-  "version": "0.6.3",
+  "version": "0.6.4",
   "description": "Codex-style /goal command for Pi — persistent goal-driven autonomous loop with evidence-based completion, token/time budgets, blocked detection, and steering templates.",
   "type": "module",
   "main": "src/index.ts",

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

@@ -65,6 +65,7 @@ function makeFakeCtx(overrides?: {
 	aborted?: boolean;
 	hasUI?: boolean;
 	contextUsage?: { tokens?: number; contextWindow?: number };
+	entries?: unknown[];
 }): { ctx: ExtensionContext; calls: RecordedCall[] } {
 	const calls: RecordedCall[] = [];
 	const signal = { aborted: overrides?.aborted ?? false } as AbortSignal;
@@ -87,7 +88,7 @@ function makeFakeCtx(overrides?: {
 				bold: (text: string) => text,
 			},
 		},
-		sessionManager: { getEntries: () => [], getBranch: () => undefined },
+		sessionManager: { getEntries: () => overrides?.entries ?? [], getBranch: () => undefined },
 	} as unknown as ExtensionContext;
 	return { ctx, calls };
 }
@@ -179,6 +180,153 @@ describe("handleAgentEnd — continuation", () => {
 		expect(sendContext).toHaveLength(1);
 		expect(sendContext[0]!.content).toContain("[GOAL]");
 	});
+
+	// ── pending 守卫：background subagent/workflow 运行时不死循环 ──
+
+	it("有活跃 pending → 不发 continuation（pending 守卫生效）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0); // 有活跃 pending，不发 continuation
+	});
+
+	it("pending register 已 unregister → 差集归零，正常发 continuation", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:unregister", data: { id: "bg-1" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
+
+	it("pending expiresAt 已过期 → 仍判活跃不发 continuation（刻意不校验 TTL）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", expiresAt: Date.now() - 1000 } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0); // 过期仍判活跃，避免长任务死循环复现
+	});
+
+	it("有活跃 pending → appendEntry goal:log 诊断记录（多元素计数 + ids 透出）", async () => {
+		const { pi, states } = makeFakePi();
+		const { ctx } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-2" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+
+		// goal:log 走 appendEntry（非 goal-history）→ 进 states
+		const deferredLog = states.find(
+			(s) =>
+				(s as { component?: string } | undefined)?.component === "goal:agent-end" &&
+				/continuation deferred/.test(String((s as { message?: string } | undefined)?.message ?? "")),
+		);
+		expect(deferredLog).toBeDefined();
+		const data = (deferredLog as { data?: { activePending?: number; ids?: string[] } } | undefined)?.data;
+		expect(data?.activePending).toBe(2); // 多元素计数（替代原 >=1 弱断言）
+		expect(data?.ids).toEqual(["bg-1", "bg-2"]); // ids 透出
+	});
+
+	it("重复 register 同 id → 去重计为 1（seen.has 守卫）", async () => {
+		const { pi, calls: piCalls, states } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1" } },
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// 守卫触发：count>0 不发 continuation
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(0);
+		// seen 去重：2 条同 id register 计为 1（非 2）
+		const deferredLog = states.find(
+			(s) => (s as { component?: string } | undefined)?.component === "goal:agent-end",
+		);
+		expect((deferredLog as { data?: { activePending?: number } } | undefined)?.data?.activePending).toBe(1);
+	});
+
+	it("非字符串/缺失 id 的 register → 被忽略，正常发 continuation（typeof id 防御）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: 123 } }, // 数字 id（非字符串）
+				{ type: "custom", customType: "pending:register", data: {} }, // 无 id
+			],
+		});
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		// count=0，守卫不触发，走正常 continuation
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
+
+	it("无 pending entries → 正常发 continuation（回归保护）", async () => {
+		const { pi, calls: piCalls } = makeFakePi();
+		const { ctx, calls: ctxCalls } = makeFakeCtx(); // getEntries 默认空
+		const session = createGoalSession();
+		session.state = makeRunningState({ tokensUsed: 200, lastTurnTokensUsed: 0 });
+
+		await handleAgentEnd(pi, session, ctx);
+		const all = allCalls(piCalls, ctxCalls);
+
+		const followUp = all.filter(
+			(c) => c.kind === "sendContext" && (c.payload as { deliverAs?: string } | undefined)?.deliverAs === "followUp",
+		);
+		expect(followUp).toHaveLength(1);
+	});
 });
 
 // ── handleAgentEnd：并发保护（G-021）+ stale（G-020）───
@@ -339,53 +487,14 @@ describe("handleBeforeAgentStart", () => {
 
 	// ── pending-notifications（W2 跨扩展集成）───────────────────
 
-	it("有活跃 pending operations → 注入提示含 pending 数量", async () => {
-		const { pi } = makeFakePi();
-		// 创建带 pending:register entries 的 ctx
-		const entries = [
-			{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
-			{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
-		];
-		const ctx = {
-			hasUI: true,
-			signal: { aborted: false } as AbortSignal,
-			getContextUsage: () => undefined,
-			ui: {
-				notify: vi.fn(),
-				setStatus: vi.fn(),
-				setWidget: vi.fn(),
-				theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
-			},
-			sessionManager: { getEntries: () => entries, getBranch: () => undefined },
-		} as unknown as ExtensionContext;
-		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("2 pending async operation(s)");
-	});
-
-	it("有 pending register 但已 unregister → 不注入提示", async () => {
+	it("有活跃 pending entries → 注入 content 不含 pending 提示（pendingHint 已移除）", async () => {
 		const { pi } = makeFakePi();
-		const entries = [
-			{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
-			{ type: "custom", customType: "pending:unregister", data: { id: "wf-1" } },
-		];
-		const ctx = {
-			hasUI: true,
-			signal: { aborted: false } as AbortSignal,
-			getContextUsage: () => undefined,
-			ui: {
-				notify: vi.fn(),
-				setStatus: vi.fn(),
-				setWidget: vi.fn(),
-				theme: { fg: (_c: string, t: string) => t, bold: (t: string) => t },
-			},
-			sessionManager: { getEntries: () => entries, getBranch: () => undefined },
-		} as unknown as ExtensionContext;
+		const { ctx } = makeFakeCtx({
+			entries: [
+				{ type: "custom", customType: "pending:register", data: { id: "wf-1", type: "workflow", name: "test-wf" } },
+				{ type: "custom", customType: "pending:register", data: { id: "bg-1", type: "subagent", name: "worker" } },
+			],
+		});
 		const session = createGoalSession();
 		session.state = makeRunningState();
 
@@ -393,6 +502,7 @@ describe("handleBeforeAgentStart", () => {
 
 		expect(result).toBeDefined();
 		expect(result!.message.customType).toBe("goal-context");
+		// pendingHint 已删除：pending 感知交给 LLM 调 pending_notifications tool（mandatory）
 		expect(result!.message.content).not.toContain("pending async operation");
 	});
 

package/src/adapters/event-handlers/agent-end.ts

@@ -28,6 +28,7 @@ import {
 } from "../../projection/prompts";
 import { persistAndUpdate, tickState } from "../../service";
 import type { GoalSession } from "../../session";
+import type { SessionEntryLike } from "../../ports";
 import { buildPorts } from "../ports";
 import { makeStaleChecker } from "./shared";
 
@@ -169,9 +170,61 @@ async function handleContinuation(
 	// 终态守卫：persistAndUpdate 可能把 goal 转为 budget_limited/time_limited 终态。
 	// 此时不应发 continuation（deliverAs:"followUp" 会触发新 turn，让已耗尽预算的 agent 再跑一轮）。
 	if (isTerminalStatus(state.status)) return;
+	// pending 守卫：有活跃 background subagent/workflow 时不发 continuation。
+	// 靠 subagent/workflow 完成时 sendMessage({triggerTurn:true,deliverAs:"steer"}) 自然唤醒主 agent；
+	// goal 抢先催会与异步任务完成通知叠加，形成“停不下来”的死循环——continuation 排入
+	// _followUpMessages 队列 → _handlePostAgentRun 的 hasQueuedMessages() 返回 true → agent.continue()
+	// 新 turn → 又 agent_end → 又 continuation。
+	// 刻意不校验 expiresAt：长任务 subagent（>1h TTL）完成时仍 triggerTurn 唤醒主 agent，
+	// 按 TTL 判非活跃会让死循环在长任务场景复现。
+	const pendingOps = countActivePendingOps(ctx.sessionManager.getEntries());
+	if (pendingOps.count > 0) {
+		pi.appendEntry("goal:log", {
+			timestamp: Date.now(),
+			level: "debug",
+			component: "goal:agent-end",
+			message: `continuation deferred: ${pendingOps.count} active pending operation(s)`,
+			data: { activePending: pendingOps.count, ids: pendingOps.ids },
+		});
+		// 用户可见反馈：goal 在等待后台任务完成而非卡死（deferred 无反馈时用户只看到
+		// goal active 但无产出，无法区分等待 vs 死循环）。
+		ctx.ui.notify(
+			`Goal waiting for ${pendingOps.count} background task(s) to complete.`,
+			"info",
+		);
+		return;
+	}
 	// 发 continuation（FR-8.7: 去 debounce 后才发）
 	buildPorts(pi, ctx).messaging.sendContextMessage(
 		continuationPrompt(state, state.timeUsedSeconds),
 		"followUp",
 	);
 }
+
+/** 类型守卫：unknown → Record<string, unknown>（替代裸 as 断言访问 entry.data.id）。 */
+const isRecord = (x: unknown): x is Record<string, unknown> =>
+	typeof x === "object" && x !== null;
+
+/** 计算活跃的 pending async operation（background subagent/workflow）数量。
+ *  读 session entries 里 customType="pending:register" 减 "pending:unregister" 的 id 差集。
+ *  刻意不校验 expiresAt（见 handleContinuation 守卫注释）。 */
+function countActivePendingOps(
+	entries: readonly SessionEntryLike[],
+): { count: number; ids: string[] } {
+	const unregistered = new Set<string>();
+	for (const e of entries) {
+		if (e.type !== "custom" || e.customType !== "pending:unregister") continue;
+		const id = isRecord(e.data) ? e.data.id : undefined;
+		if (typeof id === "string") unregistered.add(id);
+	}
+	const activeIds: string[] = [];
+	const seen = new Set<string>();
+	for (const e of entries) {
+		if (e.type !== "custom" || e.customType !== "pending:register") continue;
+		const id = isRecord(e.data) ? e.data.id : undefined;
+		if (typeof id !== "string" || unregistered.has(id) || seen.has(id)) continue;
+		seen.add(id);
+		activeIds.push(id);
+	}
+	return { count: activeIds.length, ids: activeIds };
+}

package/src/adapters/event-handlers/before-agent-start.ts

@@ -15,7 +15,7 @@
  * contextInjectionPrompt 恒定建议 plan mode（AI 自行决定是否用）。
  */
 
-import type { CustomEntry, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 import { AUTO_CLEAR_TURNS, CONTEXT_USAGE_RATIO_LIMIT } from "../../constants";
 import { isActiveStatus, isTerminalStatus } from "../../engine/goal";
@@ -33,14 +33,6 @@ interface BeforeAgentStartResult {
 	};
 }
 
-/** 类型守卫：把 SDK 的 SessionEntry 联合收窄到 CustomEntry。
- *  SessionEntry 现为联合类型（SessionMessageEntry | CompactionEntry | CustomEntry | ...），
- *  只有 CustomEntry 带 customType/data（pending:register/unregister 由 pi.appendEntry 落地，
- *  type 恒为 "custom"）。读取前必须先收窄。 */
-function isCustomEntry(e: { type: string }): e is CustomEntry {
-	return e.type === "custom";
-}
-
 export async function handleBeforeAgentStart(
 	pi: ExtensionAPI,
 	session: GoalSession,
@@ -69,47 +61,12 @@ export async function handleBeforeAgentStart(
 
 	// 正常 context injection。
 	// 全解耦：planAvailable 恒 true（contextInjectionPrompt 恒定建议 plan mode，AI 自行决定）。
-	// pending-notifications：若有活跃的异步操作，注入等待提示。
-	// 读取 pending:register/unregister entry 算差集，并校验 expiresAt（TTL 过期的视为非活跃）。
-	// pending-notifications 的 rebuildFromEntries 在其 session_start 已 flush 跨 session/过期残留，
-	// 但同一 session 内超时未 unregister 的 entry（如崩溃恢复遗漏）需此处完补以防误报 active。
-	const now = Date.now();
-	const entries = ctx.sessionManager.getEntries();
-	// pending:register/unregister 由 pi.appendEntry 落地为 CustomEntry（type:"custom"）。
-	// 先用 isCustomEntry 收窄联合类型，再读 customType/data。
-	const customEntries = entries.filter(isCustomEntry);
-	const pendingUnregisters = new Set(
-		customEntries.filter((e) => e.customType === "pending:unregister").map((e) => (e.data as Record<string, unknown>)?.id),
-	);
-	const activePending = customEntries.filter((e) => {
-		if (e.customType !== "pending:register") return false;
-		const id = (e.data as Record<string, unknown>)?.id;
-		if (pendingUnregisters.has(id)) return false;
-		// TTL 过期视为非活跃（expiresAt 缺失或类型错误时宽容处理为活跃）
-		const expiresAt = (e.data as Record<string, unknown>)?.expiresAt;
-		if (typeof expiresAt === "number" && expiresAt <= now) return false;
-		return true;
-	});
-	const pendingHint = activePending.length > 0
-		? `\nNote: There are ${activePending.length} pending async operation(s) running. Consider waiting for them to complete before starting new work.`
-		: "";
-
-	pi.appendEntry("goal:log", {
-		timestamp: Date.now(),
-		level: "debug",
-		component: "goal:before-agent-start",
-		message: "pending entries computed",
-		data: {
-			activePending: activePending.length,
-			injectHint: activePending.length > 0,
-			pendingIds: activePending.map((e) => (e.data as Record<string, unknown>)?.id),
-		},
-	});
-
+	// pending 感知由 LLM 自行调 pending_notifications tool（mandatory）查询当前活跃异步操作，
+	// goal 不在此注入——避免与 tool 查询结果形成双信息源不一致（tool 是 EventBus+entries 维护的权威源）。
 	return {
 		message: {
 			customType: "goal-context",
-			content: contextInjectionPrompt(session.state, session.state.timeUsedSeconds, true) + pendingHint,
+			content: contextInjectionPrompt(session.state, session.state.timeUsedSeconds, true),
 			display: false,
 		},
 	};