@zhushanwen/pi-pending-notifications 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Cross-extension async operation registration/query mechanism for Pi — prevents message injection during long-running operations.",
   "type": "module",
   "main": "src/index.ts",

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 工具 ───────────────────────────────────────
 
@@ -215,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)", () => {
@@ -421,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

@@ -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([
@@ -97,11 +115,11 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		}
 	}
 
-	// debug 日志：环境变量 PENDING_DEBUG=1 时输出到 console.debug。
+	// debug 日志：环境变量 XYZ_AGENT_DEBUG=1 时输出到 console.debug。
 	// 不再写入 session entry（pending:log）——session entries 是 append-only 无法 GC，
 	// 12 处 debug 日志会让长 session 的 entries 线性膨胀，而 goal before-agent-start
 	// 每 turn 全量扫描 getEntries()。状态数据（pending:register/unregister）仍写 entry。
-	const debugEnabled = process.env.PENDING_DEBUG === "1";
+	const debugEnabled = process.env.XYZ_AGENT_DEBUG === "1";
 	function debugLog(level: string, message: string, data?: unknown): void {
 		if (!debugEnabled) return;
 		console.debug(`[pending-notifications:${level}] ${message}`, data ?? "");

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") {