@zhushanwen/pi-pending-notifications 0.3.5 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "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,16 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import pendingNotificationsExtension from "../index";
 import type { PendingEntry } from "../state";
-import { countActiveFromEntries, createRegistry, getActive, rebuildFromEntries, register, unregister } from "../state";
+import {
+	countActiveFromEntries,
+	createRegistry,
+	getActive,
+	PENDING_LIFECYCLE,
+	normalizePendingType,
+	rebuildFromEntries,
+	register,
+	unregister,
+} from "../state";
 
 // ── Mock 工具 ───────────────────────────────────────
 
@@ -511,3 +520,165 @@ describe("countActiveFromEntries（纯差集，供 goal / subagent-workflow 复
 		expect(countActiveFromEntries([inherited, flushed, own]).ids).toEqual(["my-bg"]);
 	});
 });
+
+// ────────────────────────────────────────────────────
+// D16 lifecycle 分档（M3）：process 档（type=bash）纯函数行为
+// ────────────────────────────────────────────────────
+
+/** bash register entry 的真实落盘形状：无 expiresAt 键（写入侧省略，D16） */
+function makeBashRegisterEntry(id: string, overrides: Record<string, unknown> = {}): MockSessionEntry {
+	return {
+		customType: "pending:register",
+		data: {
+			id,
+			type: "bash",
+			name: `task-${id}`,
+			registeredAt: NOW,
+			sessionId: "sess-current",
+			...overrides,
+		},
+	};
+}
+
+describe("D16 lifecycle 分档：常量与 type 归一化", () => {
+	it("PENDING_LIFECYCLE：subagent/workflow=session，bash=process", () => {
+		expect(PENDING_LIFECYCLE).toEqual({
+			subagent: "session",
+			workflow: "session",
+			bash: "process",
+		});
+	});
+
+	it("normalizePendingType：subagent/bash 直通，其余（缺失/未知/大小写不符）归 workflow", () => {
+		expect(normalizePendingType("subagent")).toBe("subagent");
+		expect(normalizePendingType("bash")).toBe("bash");
+		expect(normalizePendingType("workflow")).toBe("workflow");
+		expect(normalizePendingType(undefined)).toBe("workflow");
+		expect(normalizePendingType("scheduler")).toBe("workflow");
+		expect(normalizePendingType("Bash")).toBe("workflow");
+	});
+});
+
+describe("D16 process 档（type=bash）纯函数行为", () => {
+	it("读取侧不回填 TTL：无 expiresAt 的 bash entry → registry entry.expiresAt=undefined 且 active", () => {
+		const r = createRegistry();
+		const result = rebuildFromEntries(r, [makeBashRegisterEntry("bt-1")], "sess-current", NOW);
+		expect(result.activeIds).toEqual(["bt-1"]);
+		expect(result.expiredToFlush).toEqual([]);
+		expect(r.operations.get("bt-1")!.expiresAt).toBeUndefined();
+	});
+
+	it("U3 不判过期：bash entry 注册超 1h（TTL 之外）→ 仍 active、无 expiredToFlush", () => {
+		const entry = makeBashRegisterEntry("bt-1", { registeredAt: NOW - 3_700_000 });
+		const comp = rebuild([entry], "sess-current", NOW);
+		expect(comp.activeIds).toEqual(["bt-1"]);
+		expect(comp.expiredToFlush).toEqual([]);
+	});
+
+	it("U4 跨 session 不标 expired：bash entry sessionId 不符当前 session → 仍 active（进程级生命周期跨 session 续存）", () => {
+		const comp = rebuild(
+			[makeBashRegisterEntry("bt-1", { sessionId: "sess-other" })],
+			"sess-current",
+			NOW,
+		);
+		expect(comp.activeIds).toEqual(["bt-1"]);
+		expect(comp.expiredToFlush).toEqual([]);
+	});
+
+	it("session 档对照回归：同形状（无 expiresAt 键）的 workflow entry → 回填 TTL 且过期照旧判 expired", () => {
+		// 保证分档判定没有把 session 档的 TTL 路径一并豁免
+		const legacy = {
+			customType: "pending:register",
+			data: { id: "w-1", type: "workflow", name: "w", registeredAt: NOW - 3_700_000, sessionId: "sess-current" },
+		};
+		const comp = rebuild([legacy], "sess-current", NOW);
+		expect(comp.activeIds).toEqual([]);
+		expect(comp.expiredToFlush).toEqual([{ id: "w-1", status: "expired" }]);
+	});
+
+	it("差集路径识别 bash entry：register 计入且 type 保留，unregister 抵消", () => {
+		const bashReg = makeBashRegisterEntry("bt-1");
+		const res = countActiveFromEntries([bashReg] as unknown[]);
+		expect(res.count).toBe(1);
+		expect(res.entries[0].type).toBe("bash");
+		expect(res.entries[0].expiresAt).toBeUndefined();
+
+		expect(
+			countActiveFromEntries([bashReg, makeUnregisterEntry("bt-1")] as unknown[]).count,
+		).toBe(0);
+	});
+
+	it("types 过滤：bash 可作为过滤类型", () => {
+		const entries = [makeBashRegisterEntry("bt-1"), makeRegisterEntry("w-1")] as unknown[];
+		expect(countActiveFromEntries(entries, { types: ["bash"] }).ids).toEqual(["bt-1"]);
+		expect(countActiveFromEntries(entries, { types: ["workflow"] }).ids).toEqual(["w-1"]);
+	});
+});
+
+// ────────────────────────────────────────────────────
+// D16 lifecycle 分档（M3）：process 档（type=bash）工厂行为
+// ────────────────────────────────────────────────────
+
+describe("D16 process 档（type=bash）工厂行为", () => {
+	let setup: MockSetup;
+
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.setSystemTime(NOW);
+		setup = createMockPi();
+		pendingNotificationsExtension(setup.pi);
+	});
+
+	afterEach(() => {
+		vi.useRealTimers();
+	});
+
+	it("register 写入：bash → 落盘 data 无 expiresAt 键且 type=bash 直通（不被归并为 workflow）", async () => {
+		fireSessionStart(setup, createMockCtx([]));
+
+		setup.handlers.pendingRegister!({ id: "bt-1", type: "bash", name: "run tests" });
+
+		expect(await getCount(setup)).toBe(1);
+		const regCall = setup.appendEntryMock.mock.calls.find((c) => c[0] === "pending:register");
+		expect(regCall).toBeDefined();
+		const data = regCall![1] as Record<string, unknown>;
+		expect(data.type).toBe("bash");
+		expect("expiresAt" in data).toBe(false);
+	});
+
+	it("session 档对照回归：workflow register → 落盘 data.expiresAt = NOW + TTL", async () => {
+		fireSessionStart(setup, createMockCtx([]));
+
+		setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "run" });
+
+		const regCall = setup.appendEntryMock.mock.calls.find((c) => c[0] === "pending:register");
+		const data = regCall![1] as Record<string, unknown>;
+		expect(data.expiresAt).toBe(NOW + 3_600_000);
+	});
+
+	it("U3 工厂级：bash entry 超 1h 后 session_start rebuild → 仍 active、不补 unregister", async () => {
+		vi.setSystemTime(NOW + 3_700_000);
+		const stale = makeBashRegisterEntry("bt-1", { registeredAt: NOW });
+		fireSessionStart(setup, createMockCtx([stale]));
+
+		expect(await getCount(setup)).toBe(1);
+		const flushCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:unregister");
+		expect(flushCalls).toHaveLength(0);
+	});
+
+	it("session_shutdown：bash 不标 cancelled、不补 unregister entry、内存仍 active", async () => {
+		fireSessionStart(setup, createMockCtx([]));
+		setup.handlers.pendingRegister!({ id: "bt-1", type: "bash", name: "run tests" });
+		// 同时注册一个 session 档条目，对照证明分档只豁免 process 档
+		setup.handlers.pendingRegister!({ id: "w-1", type: "workflow", name: "run" });
+		setup.appendEntryMock.mockClear();
+
+		if (!setup.handlers.sessionShutdown) throw new Error("session_shutdown not registered");
+		void setup.handlers.sessionShutdown({ type: "session_shutdown" }, createMockCtx([]));
+
+		const unregisterCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:unregister");
+		expect(unregisterCalls).toHaveLength(1);
+		expect((unregisterCalls[0][1] as { id: string }).id).toBe("w-1");
+		expect(await getCount(setup)).toBe(1);
+	});
+});

package/src/index.ts

@@ -15,7 +15,8 @@
  * - emit("pending:unregister", { id, reason })
  *
  * entry 契约（与 goal before-agent-start.ts 对齐，读取端按 e.data.id 算差集）：
- * - pending:register → { id, type, name, registeredAt, expiresAt, sessionId }
+ * - pending:register → { id, type, name, registeredAt, expiresAt?, sessionId }
+ *   （expiresAt 仅 session 档写入；process 档（D16）省略该字段）
  * - pending:unregister → { id, reason, status }
  *
  * 监听方式：pi.events.on（Pi 的 EventBus，真实 SDK 为 EventBus.on，非 optional）。
@@ -29,22 +30,26 @@ import { Type } from "typebox";
 import {
 	createRegistry,
 	getActive,
+	PENDING_LIFECYCLE,
 	PENDING_TTL_MS,
 	type PendingEntry,
 	type PendingRegistry,
 	type PendingStatus,
 	type PendingType,
+	normalizePendingType,
 	rebuildFromEntries,
 	register,
 	unregister,
 } from "./state.ts";
 
 // 跨扩展消费 API：goal（continuation 守卫）/ subagent-workflow（agent_end 后代判定）
-// 直接 import 本包的导出，避免各自复制差集逻辑。
+// 直接 import 本包的导出，避免各自复制差集逻辑。PENDING_LIFECYCLE 供消费方（如
+// base-tool-enhance 启动时的 peer 版本检查）读取分档声明。
 export {
 	countActiveFromEntries,
 	createRegistry,
 	getActive,
+	PENDING_LIFECYCLE,
 	PENDING_TTL_MS,
 	type CountActiveOptions,
 	type CountActiveResult,
@@ -141,13 +146,15 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		debugLog("debug", "listener: pending:register parsed", parsed);
 
 		const now = Date.now();
+		// D16 分档：process 档（bash 后台任务）不计算 expiresAt——进程级生命周期
+		// 无 TTL 概念，任务寿命由其自身超时/reaper 管理，session 档保持 TTL 不变。
 		const entry: PendingEntry = {
 			id: parsed.id,
 			type: parsed.type,
 			name: parsed.name,
 			status: "active",
 			registeredAt: now,
-			expiresAt: now + PENDING_TTL_MS,
+			expiresAt: PENDING_LIFECYCLE[parsed.type] === "session" ? now + PENDING_TTL_MS : undefined,
 			sessionId: currentSessionId,
 		};
 
@@ -158,12 +165,14 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 			return;
 		}
 
+		// 落盘与内存 entry 对称：process 档省略 expiresAt 字段（而非写 undefined），
+		// 读取侧 normalizeRegisterEntry 对 process 档同样不回填，两侧共同兑现 TTL 豁免。
 		safeAppendEntry("pending:register", {
 			id: entry.id,
 			type: entry.type,
 			name: entry.name,
 			registeredAt: entry.registeredAt,
-			expiresAt: entry.expiresAt,
+			...(entry.expiresAt !== undefined ? { expiresAt: entry.expiresAt } : {}),
 			sessionId: entry.sessionId,
 		});
 
@@ -226,6 +235,10 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 	pi.on("session_shutdown", (_event, _ctx: ExtensionContext) => {
 		const active = getActive(registry);
 		for (const op of active) {
+			// D16 分档：process 档跳过 cancelled 标注——进程级生命周期的任务跨
+			// session 替换继续运行（fork/switch），收尾归任务自身/reaper，
+			// 不由 session 退出裁定。
+			if (PENDING_LIFECYCLE[op.type] === "process") continue;
 			const changed = unregister(registry, op.id, "cancelled");
 			if (changed) {
 				safeAppendEntry("pending:unregister", {
@@ -241,7 +254,7 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		name: "pending_notifications",
 		label: "Pending Notifications",
 		description:
-			"查询当前活跃的异步操作（workflow/subagent）。action=count 返回数量；action=list 返回列表。状态由 EventBus + session entries 维护，无需手动注册。",
+			"查询当前活跃的异步操作（workflow/subagent/bash 后台任务）。action=count 返回数量；action=list 返回列表。状态由 EventBus + session entries 维护，无需手动注册。",
 		parameters: PendingNotificationsParams,
 		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);
@@ -279,7 +292,8 @@ function parseRegisterEvent(data: unknown): ParsedRegister | null {
 	if (typeof d.id !== "string") return null;
 	return {
 		id: d.id,
-		type: d.type === "subagent" ? "subagent" : "workflow",
+		// D16：bash 类型直通（归一化映射与 state.ts 读取侧共用同一函数，防两侧漂移）
+		type: normalizePendingType(d.type),
 		name: typeof d.name === "string" ? d.name : d.id,
 	};
 }

package/src/state.ts

@@ -14,8 +14,22 @@
  *   不直接写 entry —— 写 entry 是副作用，由 index.ts 负责
  */
 
-/** 异步操作类型（来源：workflow / subagent） */
-export type PendingType = "workflow" | "subagent";
+/** 异步操作类型（来源：workflow / subagent / bash 后台任务） */
+export type PendingType = "workflow" | "subagent" | "bash";
+
+/**
+ * 生命周期分档（D16）：type 级声明，行为按档判定（不做 type 特判）——
+ * 未来 scheduler 等长任务类型声明 process 档即零改动获得同语义。
+ * - "session"：随 session entry 存活——TTL 过期（U3）、跨 session 清理（U4）、
+ *   shutdown 标 cancelled 全套生效。
+ * - "process"：随进程存活——无 TTL（不计算/不回填 expiresAt）、跨 session 续存
+ *   （fork/switch 后任务仍在跑）、shutdown 不标 cancelled（收尾归任务自身/reaper）。
+ */
+export const PENDING_LIFECYCLE: Record<PendingType, "session" | "process"> = {
+	subagent: "session",
+	workflow: "session",
+	bash: "process",
+};
 
 /** 异步操作终态/过渡状态。active = 仍在运行；其他都视为已结束 */
 export type PendingStatus = "active" | "completed" | "failed" | "cancelled" | "expired" | "time_limited" | "aborted";
@@ -32,8 +46,8 @@ export interface PendingEntry {
 	status: PendingStatus;
 	/** 注册时间戳 ms */
 	registeredAt: number;
-	/** 过期时间戳 ms（registeredAt + TTL） */
-	expiresAt: number;
+	/** 过期时间戳 ms（registeredAt + TTL）；process 档恒 undefined（D16：进程级生命周期无 TTL） */
+	expiresAt: number | undefined;
 	/** 注册时的 sessionId（用于跨 session 残留检测） */
 	sessionId: string;
 }
@@ -110,7 +124,7 @@ export function getActive(registry: PendingRegistry): PendingEntry[] {
 
 /** countActiveFromEntries 的过滤选项。 */
 export interface CountActiveOptions {
-	/** 只统计指定类型的活跃 pending；缺省 = 全部类型（subagent + workflow） */
+	/** 只统计指定类型的活跃 pending；缺省 = 全部类型（subagent + workflow + bash） */
 	types?: PendingType[];
 }
 
@@ -181,7 +195,8 @@ export interface RebuildResult {
  *
  * 算法（对齐 goal before-agent-start.ts 的读取契约）：
  * 1. 收集所有 pending:register entry，按 id 算差集（减去 pending:unregister 的 id）
- *    前提：id 全局唯一（workflow runId=`wf-<ts>-<rand>`、subagent id=`bg-/run-<tag>-<seq>-<ts>`）。
+ *    前提：id 全局唯一（workflow runId=`wf-<ts>-<rand>`、subagent id=`bg-/run-<tag>-<seq>-<ts>`、
+ *    bash 后台任务 id=`bt-<ts>-<rand>`）。
  *    若未来 id 复用（register→unregister→register 同 id），全局 Set 差集会误跳第二次 register。
  * 2. 对每个活跃的 register entry 检查：
  *    - sessionId 不符当前 session → expired（U4 跨 session 残留）
@@ -190,28 +205,62 @@ export interface RebuildResult {
  *
  * 注意：本函数只重建 registry + 计算需补的 entry，不写 entry（副作用归 index.ts）。
  */
-export function rebuildFromEntries(
-	registry: PendingRegistry,
-	entries: unknown[],
-	currentSessionId: string,
-	now: number,
-): RebuildResult {
-	const registerEntries: Array<{ data: RegisterEntryData }> = [];
-	const unregisteredIds = new Set<string>();
+/** rebuildFromEntries 的扫描阶段结果：register 原始 data 列表 + 已注销 id 集合 */
+interface PendingEntryScan {
+	registerEntries: Array<{ data: RegisterEntryData }>;
+	unregisteredIds: Set<string>;
+}
+
+/** 单趟扫描 entries 按 customType 分流（pending:register / pending:unregister）。 */
+function scanPendingEntries(entries: unknown[]): PendingEntryScan {
+	const scan: PendingEntryScan = { registerEntries: [], unregisteredIds: new Set() };
 
 	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 });
+			scan.registerEntries.push({ data: (raw.data ?? {}) as RegisterEntryData });
 		} else if (raw.customType === "pending:unregister") {
 			const data = (raw.data ?? {}) as UnregisterEntryData;
 			if (typeof data.id === "string") {
-				unregisteredIds.add(data.id);
+				scan.unregisteredIds.add(data.id);
 			}
 		}
 	}
 
+	return scan;
+}
+
+/**
+ * 判定单个 register entry 重建时是否应标 expired：
+ * - 跨 session 残留（U4）→ expired
+ * - TTL 过期（U3）→ expired
+ *
+ * process 档两检全跳过（D16：进程级生命周期跨 session 续存且无 TTL）。
+ */
+function isExpiredEntry(entry: PendingEntry, currentSessionId: string, now: number): boolean {
+	// 跨 session 残留（U4）——process 档跳过（D16：进程级生命周期跨 session 续存，
+	// fork/switch 后任务仍在跑；标 expired 补 unregister 会让差集消费方误判「无活跃任务」）
+	if (PENDING_LIFECYCLE[entry.type] === "session" && entry.sessionId !== currentSessionId) {
+		return true;
+	}
+	// 过期（U3）——process 档跳过（D16：无 TTL，expiresAt 恒 undefined）；
+	// session 档理论上恒有值，防御 undefined 不过期（缺失 = 该条目不过期）
+	return (
+		PENDING_LIFECYCLE[entry.type] === "session" &&
+		entry.expiresAt !== undefined &&
+		entry.expiresAt <= now
+	);
+}
+
+export function rebuildFromEntries(
+	registry: PendingRegistry,
+	entries: unknown[],
+	currentSessionId: string,
+	now: number,
+): RebuildResult {
+	const { registerEntries, unregisteredIds } = scanPendingEntries(entries);
+
 	const activeIds: string[] = [];
 	const expiredToFlush: Array<{ id: string; status: PendingStatus }> = [];
 
@@ -220,13 +269,7 @@ export function rebuildFromEntries(
 		if (unregisteredIds.has(data.id)) continue;
 
 		const entry = normalizeRegisterEntry(data, currentSessionId);
-		// 跨 session 残留（U4）
-		if (entry.sessionId !== currentSessionId) {
-			expiredToFlush.push({ id: entry.id, status: "expired" });
-			continue;
-		}
-		// 过期（U3）
-		if (entry.expiresAt <= now) {
+		if (isExpiredEntry(entry, currentSessionId, now)) {
 			expiredToFlush.push({ id: entry.id, status: "expired" });
 			continue;
 		}
@@ -238,16 +281,35 @@ export function rebuildFromEntries(
 	return { activeIds, expiredToFlush };
 }
 
+/**
+ * type 归一化：subagent/bash 原样保留，其余（含缺失/未知值）归 workflow。
+ * state.ts 与 index.ts 两处归一化共用本函数，防止「写入侧直通、读取侧归并」漂移。
+ */
+export function normalizePendingType(raw: unknown): PendingType {
+	if (raw === "subagent") return "subagent";
+	if (raw === "bash") return "bash";
+	return "workflow";
+}
+
 /** 从 entry data 归一化为 PendingEntry（补默认值，容错缺失字段） */
 function normalizeRegisterEntry(data: RegisterEntryData, currentSessionId: string): PendingEntry {
 	const registeredAt = typeof data.registeredAt === "number" ? data.registeredAt : Date.now();
+	const type = normalizePendingType(data.type);
 	return {
 		id: data.id as string,
-		type: (data.type === "subagent" ? "subagent" : "workflow") as PendingType,
+		type,
 		name: typeof data.name === "string" ? data.name : (data.id as string),
 		status: "active",
 		registeredAt,
-		expiresAt: typeof data.expiresAt === "number" ? data.expiresAt : registeredAt + PENDING_TTL_MS,
+		// D16：process 档不回填 TTL——写入侧本就省略 expiresAt，读取侧若回填
+		// registeredAt + TTL 会抵消写入侧的豁免（分档必须两侧同改）。session 档
+		// 缺失时回填 TTL 兼容旧 entry。
+		expiresAt:
+			PENDING_LIFECYCLE[type] === "process"
+				? undefined
+				: typeof data.expiresAt === "number"
+					? data.expiresAt
+					: registeredAt + PENDING_TTL_MS,
 		sessionId: typeof data.sessionId === "string" ? data.sessionId : currentSessionId,
 	};
 }