@zhushanwen/pi-pending-notifications 0.7.1 → 0.7.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Cross-extension async operation registration/query mechanism for Pi.",
   "type": "module",
   "main": "src/index.ts",
@@ -33,6 +33,7 @@
     "typebox": "*"
   },
   "dependencies": {
+    "@xyz-agent/extension-protocol": "0.11.0",
     "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "scripts": {

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

@@ -454,16 +454,16 @@ describe("pendingNotificationsExtension factory", () => {
 	});
 
 	describe("写侧幂等（P2）", () => {
-		it("bte 对账已直接落盘 unregister 后，收尾尽力补 emit 不重复落盘", async () => {
-			// bte 对账权威路径 = 直接 appendEntry（不经本包 listener）；对账平掉差集后，
-			// 任务收尾的尽力补 emit 到达 listener——前置判断对同一份 entries 现算发现
-			// 已注销 → 跳过（历史内存态形态下此路径会产生第二条重复 unregister entry）。
+		it("任一发送方重复发 unregister（对账先落盘、事件后到达等）不重复落盘", async () => {
+			// bte 对账权威路径 = 直接 appendEntry（不经本包 listener）；对账落盘后，
+			// 任一现役发送方重复发 unregister 到 listener——前置判断对同一份 entries
+			// 现算发现已注销 → 跳过（历史内存态形态下此路径会产生第二条重复 unregister entry）。
 			fireSessionStart(setup);
 			setup.handlers.pendingRegister!({ id: "bt-1", type: "bash", name: "run" });
 
 			// 对账直接落盘（模拟 bte：不经 listener 的 pi.appendEntry）
 			setup.appendEntryMock("pending:unregister", { id: "bt-1", reason: "completed", status: "completed" });
-			// 收尾尽力补 emit 到达 listener
+			// 重复 unregister 事件到达 listener
 			setup.handlers.pendingUnregister!({ id: "bt-1", reason: "completed" });
 
 			const unregisterCalls = setup.appendEntryMock.mock.calls.filter((c) => c[0] === "pending:unregister");

package/src/index.ts

@@ -16,7 +16,8 @@
  * ① subagent-core——notify-host.ts / orchestration/lifecycle.ts /
  *   worker-message-pump.ts / round-supervisor/reconcile-sweep.ts（崩溃恢复 sweep
  *   补注销）；② base-tool-enhance——bash 投影（notify.ts register/unregister 主链 +
- *   process-exit-guard.ts / pending-reconcile.ts 收殓对账尽力补）；
+ *   process-exit-guard.ts 退出边沿尽力补 emit（pending-reconcile 对账走 appendEntry
+ *   权威路径，不经 emit））；
  * ③ subagent-workflow——仅崩溃恢复时 emit pending:unregister（session-lifecycle.ts
  *   recoverCrashedRuns 回调））：
  * - emit("pending:register", { id, type, name })
@@ -35,6 +36,7 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { mapReasonToStatus as mapReasonToStatusImpl } from "@xyz-agent/extension-protocol";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { Type } from "typebox";
 
@@ -183,7 +185,8 @@ export default function pendingNotificationsExtension(pi: ExtensionAPI): void {
 		debugLog("debug", "listener: pending:unregister parsed", parsed);
 
 		// 未知/已注销 id 忽略（U8）：对 entries 现算（有 register 且无任何 unregister
-		// 才落盘）——bte 对账已直接落盘的注销在此同样生效，收尾尽力补 emit 天然幂等。
+		// 才落盘）——bte 对账已直接落盘的注销在此同样生效，任一发送方重复 unregister
+		// 被本前置判断拦截，天然不重复落盘。
 		const status = mapReasonToStatus(parsed.reason);
 		if (!isPendingActive(currentEntries(), parsed.id)) {
 			debugLog("debug", "listener: pending:unregister ignored (unknown id)", { id: parsed.id });
@@ -278,27 +281,12 @@ function parseUnregisterEvent(data: unknown): ParsedUnregister | null {
 }
 
 /** 将事件 reason 映射为 pending:unregister entry 的 status 字段（落盘契约组成部分）。
- *  [U5 / 永久会话模型 §3.2.5 通知词表对齐] subagent-core 新 stopReason 展示值经注销
- *  reason 通道到达（interrupted/interrupted-by-restart/interrupted-by-parent → aborted、
- *  reopened → completed）——防新词落 default 被记为 completed 的误标（cancelled 同族
- *  事故先例：新枚举值漏映射静默落兜底）。 */
+ *  权威单点在 protocol pending-entries（ext-simplify-17 D10）——本函数是对 protocol
+ *  导出的类型收窄包装（PendingStatus 枚举留在本包，protocol 不引 extension 侧类型），
+ *  既有调用点零改动；bte 对账写侧同引 protocol 单点，两侧映射不再可能漂移。
+ *  词表演化背景（U5 / §3.2.5 通知词表对齐）见 protocol 实现处 JSDoc。 */
 function mapReasonToStatus(reason: string): PendingStatus {
-	switch (reason) {
-		case "completed": return "completed";
-		case "failed": return "failed";
-		case "cancelled": return "cancelled";
-		case "expired": return "expired";
-		case "time_limited": return "time_limited";
-		case "budget_limited": return "failed";
-		case "aborted": return "aborted";
-		case "interrupted":
-		case "interrupted-by-restart":
-		case "interrupted-by-parent":
-			return "aborted";
-		case "reopened":
-			return "completed";
-		default: return "completed";
-	}
+	return mapReasonToStatusImpl(reason) as PendingStatus;
 }
 
 /** 格式化 active 列表为可读文本 */

package/src/state.ts

@@ -8,6 +8,10 @@
  * - hasPendingId / isPendingActive: 写侧落盘前置判断（register 去重 / unregister 活跃判定）
  *
  * 设计要点：
+ * - 差集规则本体（register 首见去重 + unregister 全局抵消 + id 非法跳过）单点在
+ *   @xyz-agent/extension-protocol 的 pending-entries（与 bte 对账同源消费，
+ *   ext-simplify-13 E6）；本文件在其上只保留 pending 产品语义：类型归一 /
+ *   opts.types / currentSessionId 过滤与写侧判定
  * - session entries 是唯一状态源，本文件无内存状态（历史的内存 registry、session_start
  *   重建、TTL 与 shutdown 机器已删除）——「落盘了什么」与「查询到什么」共用同一份扫描，
  *   结构上不可分歧
@@ -16,6 +20,7 @@
  *   对齐 goal continuation 守卫语义）；历史 session 文件中遗留的带 expiresAt 的
  *   register entry 无需迁移——差集语义不读该键
  */
+import { applyPendingDiff, scanPendingEntries } from "@xyz-agent/extension-protocol";
 
 /** 异步操作类型（来源：workflow / subagent / bash 后台任务） */
 export type PendingType = "workflow" | "subagent" | "bash";
@@ -39,27 +44,6 @@ export interface PendingEntry {
 	sessionId: string;
 }
 
-/** pending:register entry 在 entries 里的最小可识别形状 */
-interface RegisterEntryData {
-	id: unknown;
-	type: unknown;
-	name: unknown;
-	registeredAt: unknown;
-	sessionId: unknown;
-}
-
-/** pending:unregister entry 在 entries 里的最小可识别形状。
- *  T2 通知由 subagent-workflow 自有通道 bg-notify-render 承担，不经本事件。 */
-interface UnregisterEntryData {
-	id: unknown;
-}
-
-/** SessionEntry 的最小可识别形状（duck-typed，避免依赖 SDK 具体类型） */
-interface EntryLike {
-	customType?: string;
-	data?: unknown;
-}
-
 /** countActiveFromEntries 的过滤选项。 */
 export interface CountActiveOptions {
 	/** 只统计指定类型的活跃 pending；缺省 = 全部类型（subagent + workflow + bash） */
@@ -99,9 +83,9 @@ export function countActiveFromEntries(
 	entries: unknown[],
 	opts?: CountActiveOptions,
 ): CountActiveResult {
-	// 单趟扫描分流 register/unregister（S-10 容错一致），差集过滤见 filterActiveRegisters
-	const { registerEntries, unregisteredIds } = scanPendingEntries(entries);
-	const active = filterActiveRegisters(registerEntries, unregisteredIds, opts);
+	// 差集本体（首见去重 + 抵消 + id 非法跳过，S-10 容错在内）单点委托 protocol；
+	// 本层只叠加 pending 产品过滤（normalize / types / currentSessionId，见 filterActiveRegisters）
+	const active = filterActiveRegisters(applyPendingDiff(scanPendingEntries(entries)), opts);
 
 	return {
 		count: active.length,
@@ -121,9 +105,9 @@ export function hasPendingId(entries: unknown[], id: string): boolean {
 
 /**
  * 写侧前置判断②：id 是否活跃（有 register 且无任何 unregister）。
- * unregister listener 落盘前判断用（U8 未知/已注销 id 忽略）；bte 对账直接
- * appendEntry 的注销与事件落盘的注销在同一份 entries 上生效（构造性一致，
- * 收尾尽力补 emit 天然幂等）。
+ * unregister listener 落盘前判断用（U8 未知/已注销 id 忽略）；构造性一致：
+ * bte 对账直接 appendEntry 的注销与事件落盘的注销落在同一份 entries 上，
+ * 任一发送方重复 unregister 均被本前置判断拦截，天然不重复落盘。
  */
 export function isPendingActive(entries: unknown[], id: string): boolean {
 	const { registerEntries, unregisteredIds } = scanPendingEntries(entries);
@@ -131,43 +115,15 @@ export function isPendingActive(entries: unknown[], id: string): boolean {
 	return registerEntries.some(({ data }) => data.id === id);
 }
 
-/** scanPendingEntries 的结果：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") {
-			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") {
-				scan.unregisteredIds.add(data.id);
-			}
-		}
-	}
-
-	return scan;
-}
-
-/** 差集过滤：跳过 id 非法 / 已注销 / 重复 register / 跨 session 残留的 entry，按 opts.types 过滤类型。 */
+/** pending 特有过滤层：normalize 归一 + opts.types 过滤 + 跨 session 残留过滤。
+ *  差集本体（首见去重 / 抵消 / id 非法跳过）已由 protocol applyPendingDiff 单点
+ *  完成——本函数不做任何差集判定，只消费其活跃结果。 */
 function filterActiveRegisters(
-	registerEntries: Array<{ data: RegisterEntryData }>,
-	unregisteredIds: Set<string>,
+	activeRegisters: Array<{ data: Record<string, unknown> }>,
 	opts?: CountActiveOptions,
 ): PendingEntry[] {
 	const active: PendingEntry[] = [];
-	const seen = new Set<string>();
-	for (const { data } of registerEntries) {
-		if (typeof data.id !== "string" || unregisteredIds.has(data.id) || seen.has(data.id)) continue;
-		seen.add(data.id);
+	for (const { data } of activeRegisters) {
 		const entry = normalizeRegisterEntry(data, "");
 		if (opts?.types && !opts.types.includes(entry.type)) continue;
 		// 跨 session 残留跳过（基准 = opts.currentSessionId）。判据读原始 data.sessionId
@@ -202,8 +158,9 @@ export function normalizePendingType(raw: unknown): PendingType {
 	return "workflow";
 }
 
-/** 从 entry data 归一化为 PendingEntry（补默认值，容错缺失字段） */
-function normalizeRegisterEntry(data: RegisterEntryData, currentSessionId: string): PendingEntry {
+/** 从 entry data 归一化为 PendingEntry（补默认值，容错缺失字段）。
+ *  id 的 string 合法性已由差集层（applyPendingDiff）判定，此处直接窄化。 */
+function normalizeRegisterEntry(data: Record<string, unknown>, currentSessionId: string): PendingEntry {
 	const registeredAt = typeof data.registeredAt === "number" ? data.registeredAt : Date.now();
 	return {
 		id: data.id as string,