@zhushanwen/pi-pending-notifications 0.2.1 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Cross-extension async operation registration/query mechanism for Pi — prevents message injection during long-running operations.",
   "type": "module",
   "main": "src/index.ts",
@@ -26,7 +26,7 @@
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "typebox": "*"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/src/__tests__/pending-notifications.test.ts

@@ -16,7 +16,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import pendingNotificationsExtension from "../index";
 import type { PendingEntry } from "../state";
-import { createRegistry, getActive, rebuildFromEntries, register, unregister } from "../state";
+import { countActiveFromEntries, createRegistry, getActive, rebuildFromEntries, register, unregister } from "../state";
 
 // ── Mock 工具 ───────────────────────────────────────
 
@@ -90,9 +90,15 @@ async function runTool(
 	params: Record<string, unknown>,
 ): Promise<{ content: Array<{ type: string; text: string }>; details: unknown }> {
 	const tool = setup.registerToolMock.mock.calls[0][0] as {
-		execute: (p: unknown) => Promise<{ content: Array<{ type: string; text: string }>; details: unknown }>;
+		execute: (
+			toolCallId: string,
+			p: unknown,
+			signal: AbortSignal | undefined,
+			onUpdate: unknown,
+			ctx: ExtensionContext,
+		) => Promise<{ content: Array<{ type: string; text: string }>; details: unknown }>;
 	};
-	return tool.execute(params);
+	return tool.execute("test-call-id", params, undefined, undefined, createMockCtx([]));
 }
 
 async function getCount(setup: MockSetup): Promise<number> {
@@ -209,6 +215,17 @@ describe("state pure functions", () => {
 			expect(comp.activeIds).toEqual([]);
 			expect(comp.expiredToFlush).toEqual([{ id: "w-1", status: "expired" }]);
 		});
+
+		it("entries 含 null/undefined 元素 → 跳过不抛 TypeError（S-10）", () => {
+			const comp = rebuildFromEntries(
+				createRegistry(),
+				[null, makeRegisterEntry("w-1"), undefined],
+				"sess-current",
+				NOW,
+			);
+			expect(comp.activeIds).toEqual(["w-1"]);
+			expect(comp.expiredToFlush).toEqual([]);
+		});
 	});
 
 	describe("normalizeRegisterEntry defaults (via rebuild)", () => {
@@ -415,3 +432,82 @@ describe("pendingNotificationsExtension factory", () => {
 		});
 	});
 });
+
+describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow 复用）", () => {
+	const mkRegister = (id: string, type: "subagent" | "workflow" = "subagent", overrides: Record<string, unknown> = {}) => ({
+		type: "custom",
+		customType: "pending:register",
+		data: { id, type, name: id, registeredAt: 1000, expiresAt: 1000 + 3_600_000, sessionId: "s-1", ...overrides },
+	});
+	const mkUnregister = (id: string, reason = "completed") => ({
+		type: "custom",
+		customType: "pending:unregister",
+		data: { id, reason },
+	});
+
+	it("空 entries → 0 活跃", () => {
+		expect(countActiveFromEntries([])).toEqual({ count: 0, ids: [], entries: [] });
+	});
+
+	it("纯 register → count = register 数，返回完整 entry", () => {
+		const res = countActiveFromEntries([mkRegister("bg-1"), mkRegister("bg-2", "workflow")]);
+		expect(res.count).toBe(2);
+		expect(res.ids).toEqual(["bg-1", "bg-2"]);
+		expect(res.entries[0]).toMatchObject({ id: "bg-1", type: "subagent" });
+	});
+
+	it("register + unregister 同 id → 差集抵消", () => {
+		expect(countActiveFromEntries([mkRegister("bg-1"), mkUnregister("bg-1")]).count).toBe(0);
+	});
+
+	it("混合：部分注销 → 只统计仍活跃的", () => {
+		const res = countActiveFromEntries([
+			mkRegister("bg-1"),
+			mkRegister("bg-2"),
+			mkUnregister("bg-1"),
+		]);
+		expect(res.count).toBe(1);
+		expect(res.ids).toEqual(["bg-2"]);
+	});
+
+	it("types 过滤：只统计指定类型的活跃 pending", () => {
+		const entries = [mkRegister("bg-1", "subagent"), mkRegister("wf-1", "workflow")];
+		expect(countActiveFromEntries(entries, { types: ["subagent"] }).ids).toEqual(["bg-1"]);
+		expect(countActiveFromEntries(entries, { types: ["workflow"] }).ids).toEqual(["wf-1"]);
+		expect(countActiveFromEntries(entries, { types: ["subagent", "workflow"] }).count).toBe(2);
+	});
+
+	it("TTL 过期仍判活跃（刻意不校验 expiresAt，对齐 goal continuation 守卫语义）", () => {
+		const expired = mkRegister("bg-1", "subagent", { registeredAt: 0, expiresAt: 1 });
+		expect(countActiveFromEntries([expired]).count).toBe(1);
+	});
+
+	it("同 id 重复 register → 只算一次", () => {
+		expect(countActiveFromEntries([mkRegister("bg-1"), mkRegister("bg-1")]).count).toBe(1);
+	});
+
+	it("entries 含 null/undefined 元素 → 跳过不抛 TypeError（S-10）", () => {
+		// S-10 回归：外部调用方可能传入含 null/undefined 的 entries（session 文件坏行/脏数据），
+		// 遍历时访问 raw.customType 前必须守卫，否则 TypeError 炸掉整个差集判定。
+		const withNulls = [null, undefined, mkRegister("bg-1"), mkUnregister("bg-1"), null];
+		expect(countActiveFromEntries(withNulls).count).toBe(0);
+		const mixed = [undefined, null, mkRegister("bg-2")];
+		expect(countActiveFromEntries(mixed).ids).toEqual(["bg-2"]);
+		// register 循环同样守卫：unregister 遍历前的 null 不污染差集
+		expect(countActiveFromEntries([null, undefined]).count).toBe(0);
+	});
+
+	it("malformed register（id 非 string）→ 跳过", () => {
+		const bad = { type: "custom", customType: "pending:register", data: { id: 42 } };
+		const good = mkRegister("bg-1");
+		expect(countActiveFromEntries([bad, good]).ids).toEqual(["bg-1"]);
+	});
+
+	it("跨 session 残留（fork 继承的 register）不校验 sessionId——由 session_start 重建流程补 expired unregister 抵消", () => {
+		// 模拟 P fork 主 session：继承来主 session 的 register（sessionId=s-0），已被 rebuild 补 unregister(expired)
+		const inherited = mkRegister("parent-bg", "subagent", { sessionId: "s-0" });
+		const flushed = mkUnregister("parent-bg", "expired");
+		const own = mkRegister("my-bg");
+		expect(countActiveFromEntries([inherited, flushed, own]).ids).toEqual(["my-bg"]);
+	});
+});

package/src/index.ts

@@ -23,7 +23,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "@sinclair/typebox";
+import { Type } from "typebox";
 
 import {
 	createRegistry,
@@ -38,6 +38,24 @@ import {
 	unregister,
 } from "./state.ts";
 
+// 跨扩展消费 API：goal（continuation 守卫）/ subagent-workflow（agent_end 后代判定）
+// 直接 import 本包的导出，避免各自复制差集逻辑。
+export {
+	countActiveFromEntries,
+	createRegistry,
+	getActive,
+	PENDING_TTL_MS,
+	type CountActiveOptions,
+	type CountActiveResult,
+	type PendingEntry,
+	type PendingRegistry,
+	type PendingStatus,
+	type PendingType,
+	rebuildFromEntries,
+	register,
+	unregister,
+} from "./state.ts";
+
 /** 工具参数 schema */
 const PendingNotificationsParams = Type.Object({
 	action: Type.Union([
@@ -46,9 +64,12 @@ const PendingNotificationsParams = Type.Object({
 	]),
 });
 
-/** tool 入参形状 */
-interface ToolParams {
-	action: "count" | "list";
+/** pending_notifications 工具的 details 形状。两个分支共用同一结构（items 缺省时 undefined），
+ *  让 registerTool 泛型对 TDetails 推断一致，避免 union 细节冲突。 */
+interface PendingToolDetails {
+	action: string;
+	count: number;
+	items?: PendingEntry[];
 }
 
 /**
@@ -218,13 +239,12 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		description:
 			"查询当前活跃的异步操作（workflow/subagent）。action=count 返回数量；action=list 返回列表。状态由 EventBus + session entries 维护，无需手动注册。",
 		parameters: PendingNotificationsParams,
-		execute: async (params: unknown) => {
-			const p = params as ToolParams;
+		execute: async (_toolCallId: string, params: { action: "count" | "list" }, _signal: AbortSignal | undefined, _onUpdate: unknown, _ctx: ExtensionContext): Promise<{ content: { type: "text"; text: string }[]; details: PendingToolDetails }> => {
 			const active = getActive(registry);
 
-			debugLog("debug", `tool ${p.action} requested`, { action: p.action, activeCount: active.length });
+			debugLog("debug", `tool ${params.action} requested`, { action: params.action, activeCount: active.length });
 
-			if (p.action === "count") {
+			if (params.action === "count") {
 				return {
 					content: [{ type: "text" as const, text: `${active.length} pending operation(s)` }],
 					details: { action: "count", count: active.length },

package/src/state.ts

@@ -108,6 +108,66 @@ export function getActive(registry: PendingRegistry): PendingEntry[] {
 	return Array.from(registry.operations.values()).filter((op) => op.status === "active");
 }
 
+/** countActiveFromEntries 的过滤选项。 */
+export interface CountActiveOptions {
+	/** 只统计指定类型的活跃 pending；缺省 = 全部类型（subagent + workflow） */
+	types?: PendingType[];
+}
+
+/** countActiveFromEntries 的结果。 */
+export interface CountActiveResult {
+	count: number;
+	ids: string[];
+	/** 活跃的完整 entry（含类型/名称/TTL，供调用方展示或后续判断） */
+	entries: PendingEntry[];
+}
+
+/**
+ * 从持久化 entries 计算活跃 pending 数（register − unregister 差集）。
+ *
+ * 与 rebuildFromEntries 的分工：本函数只做「有没有活跃 pending」的只读判断，
+ * 不写 registry、不判 sessionId/expiresAt（TTL 刻意不校验——长任务 subagent >1h
+ * 仍应视为活跃，对齐 goal agent-end 的 continuation 守卫语义）。
+ * 调用方：goal（agent_end 时判断是否发 continuation）、subagent-workflow
+ * （agent_end 时判断子进程是否有活跃后代，决定是否保持进程等 steer 唤醒）。
+ *
+ * 注：跨 session 残留（fork 继承的 register）由 index.ts 的 session_start 重建
+ * 流程补 unregister(expired) 抵消；本函数只做纯差集，不重复处理。
+ */
+export function countActiveFromEntries(
+	entries: unknown[],
+	opts?: CountActiveOptions,
+): CountActiveResult {
+	const unregistered = new Set<string>();
+	for (const raw of entries as EntryLike[]) {
+		// S-10：entries 元素可能是 null/undefined（外部调用方/坏数据），
+		// EntryLike 断言前先守卫，避免访问 raw.customType 抛 TypeError 炸掉差集判定。
+		if (!raw || typeof raw !== "object") continue;
+		if (raw.customType !== "pending:unregister") continue;
+		const data = (raw.data ?? {}) as UnregisterEntryData;
+		if (typeof data.id === "string") unregistered.add(data.id);
+	}
+
+	const active: PendingEntry[] = [];
+	const seen = new Set<string>();
+	for (const raw of entries as EntryLike[]) {
+		if (!raw || typeof raw !== "object") continue;
+		if (raw.customType !== "pending:register") continue;
+		const data = (raw.data ?? {}) as RegisterEntryData;
+		if (typeof data.id !== "string" || unregistered.has(data.id) || seen.has(data.id)) continue;
+		seen.add(data.id);
+		const entry = normalizeRegisterEntry(data, "");
+		if (opts?.types && !opts.types.includes(entry.type)) continue;
+		active.push(entry);
+	}
+
+	return {
+		count: active.length,
+		ids: active.map((e) => e.id),
+		entries: active,
+	};
+}
+
 /** rebuildFromEntries 的结果：重建后的活跃列表 + 需要补注销的 entry */
 export interface RebuildResult {
 	/** 重建后识别为 active 的 id 列表（已写入 registry） */
@@ -140,6 +200,8 @@ export function rebuildFromEntries(
 	const unregisteredIds = new Set<string>();
 
 	for (const raw of entries as EntryLike[]) {
+		// S-10：同 countActiveFromEntries——null/undefined 元素先守卫再访问字段。
+		if (!raw || typeof raw !== "object") continue;
 		if (raw.customType === "pending:register") {
 			registerEntries.push({ data: (raw.data ?? {}) as RegisterEntryData });
 		} else if (raw.customType === "pending:unregister") {