@zhushanwen/pi-pending-notifications 0.7.5 → 0.7.7

package/README.md

@@ -0,0 +1,72 @@
+# @zhushanwen/pi-pending-notifications
+
+跨 extension 的异步操作注册/查询机制：workflow / subagent / bash 后台任务等长耗时异步操作在启动与结束时经 Pi EventBus 广播事件，本扩展监听事件并将注册/注销落盘为 session entries，同时提供 `pending_notifications` 工具供 LLM 查询当前活跃的异步操作（数量或列表）。
+
+## 提供的工具
+
+### `pending_notifications`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `action` | `"count"` \| `"list"` | `count` 返回活跃操作数量；`list` 返回列表（类型 / 名称 / id） |
+
+`list` 返回文本示例：
+
+```
+2 pending operation(s):
+- [subagent] 审查登录模块 (id=sa-xxxx)
+- [workflow] 重构数据层 (id=run-xxxx)
+```
+
+## 核心机制
+
+- **事件契约**：异步操作的宿主扩展经 Pi EventBus 广播：
+  - `pending:register { id, type, name }` —— 操作启动（`type` ∈ `workflow` / `subagent` / `bash`）
+  - `pending:unregister { id, reason }` —— 操作结束（`reason` 映射为终态 status）
+  - 发送方：subagent-core（subagent 与 workflow run 生命周期：启动注册 / 结束注销 / 崩溃恢复 sweep 补注销）、base-tool-enhance（bash 后台任务）、subagent-workflow（仅崩溃恢复补注销）
+- **session entries 唯一状态源**：register/unregister 经 `appendEntry` 落盘，无内存第二份状态；活跃集合 = register − unregister 差集，工具投影与写侧去重对同一份 entries 现算，结构上不可分歧
+- **写侧幂等**：重复 register、未知/已注销 id 的 unregister 均忽略，天然不重复落盘
+- **无 TTL**：三类操作均按进程存活口径处理，长任务（>1h）仍视为活跃
+- **跨 session 残留过滤**：查询按当前 session id 过滤 fork 继承的父级注册残留
+- **跨扩展导出**：`countActiveFromEntries()` 供 goal（continuation 守卫）、subagent-workflow（后代存活判定）直接复用差集计算；差集本体单点在 `@zhushanwen/extension-protocol`
+
+## 安装
+
+```bash
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-pending-notifications
+```
+
+本地开发可用 `--extension` 直接加载：
+
+```bash
+pi --extension <repo>/extensions/universal/pending-notifications/index.ts "<prompt>"
+```
+
+## 使用示例
+
+LLM 在决定「继续推进还是等待异步操作」前主动查询：
+
+```json
+{ "action": "count" }
+```
+
+```json
+{ "action": "list" }
+```
+
+典型场景：agent 想确认是否真有后台任务在跑（workflow run / subagent / bash 后台命令），避免在异步操作未收口时提前下结论或重复派发。
+
+## 文件结构
+
+```
+pending-notifications/
+├── index.ts            # 入口 — re-export src/index.ts
+├── mocks/
+│   └── typebox.ts      # 测试用 typebox mock
+└── src/
+    ├── index.ts        # 工厂入口（EventBus 监听 + session 基准 + pending_notifications 工具注册）
+    ├── state.ts        # PendingEntry 类型 + 差集/写侧判断纯函数（countActiveFromEntries / hasPendingId / isPendingActive）
+    └── __tests__/
+        └── pending-notifications.test.ts
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-pending-notifications",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Cross-extension async operation registration/query mechanism for Pi.",
   "type": "module",
   "main": "src/index.ts",
@@ -33,7 +33,7 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/extension-protocol": "0.14.0",
     "@zhushanwen/pi-extension-logger": "0.6.1"
   },
   "scripts": {

package/src/index.ts

@@ -13,9 +13,10 @@
  * - index.ts（本文件）: 工厂入口（EventBus 写侧监听 + session 基准 + 查询 tool）
  *
  * 事件契约（emit 端三组，与 extension-dependencies.json 本包条目 reason 同口径：
- * ① 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 主链 +
+ * ① subagent-core——notify-host.ts（register + record 终态化 unregister——finalizeRun
+ *   直落后的残留发射面，观测通道 = sweep reconciled WARN）/ orchestration/lifecycle.ts
+ *   （register 主链）；
+ * ② base-tool-enhance——bash 投影（notify.ts register/unregister 主链 +
  *   process-exit-guard.ts 退出边沿尽力补 emit（pending-reconcile 对账走 appendEntry
  *   权威路径，不经 emit））；
  * ③ subagent-workflow——仅崩溃恢复时 emit pending:unregister（session-lifecycle.ts
@@ -23,13 +24,24 @@
  * - emit("pending:register", { id, type, name })
  * - emit("pending:unregister", { id, reason })
  *
+ * 直落写方（不经本事件、直接 appendEntry 权威落盘——listener 的 isPendingActive
+ * 现算幂等门对两族写方统一生效，重复注销被自然拦截）：
+ * - subagent-core worker-message-pump.ts finalizeRun（reload-closeout D4：workflow
+ *   run 终态注销直落，emit 发射点已删——reload 转换窗/factory 顺序窗内 emit 丢失
+ *   即注销 entry 永缺位）；
+ * - subagent-core round-supervisor/reconcile-sweep.ts（对账 sweep 补注销，对账走
+ *   appendEntry 权威路径，不经 emit）；
+ * - base-tool-enhance pending-reconcile.ts（session_start 对账，同款）。
+ *
  * entry 契约（与 goal before-agent-start.ts 对齐，读取端按 e.data.id 算差集）：
  * - pending:register → { id, type, name, registeredAt, sessionId }
  * - pending:unregister → { id, reason, status }
  *
  * 状态权威源：session entries 是唯一状态——工具投影与写侧去重/活跃判断全部对
- * getEntries() 现算（appendEntry 同步入账，pi dist 实证），无内存第二份状态；
- * 历史的内存 registry、session_start 重建、TTL 与 shutdown 机器已删除。
+ * getEntries() 现算（appendEntry 同步入账，pi dist 实证，锚定 pi-semantics
+ * PS-29 extensionAPI appendEntry 直委托 appendCustomEntry + PS-17 _appendEntry
+ * 同步 push 无 debounce），无内存第二份状态；历史的内存 registry、
+ * session_start 重建、TTL 与 shutdown 机器已删除。
  *
  * 监听方式：pi.events.on（Pi 的 EventBus，真实 SDK 为 EventBus.on，非 optional）。
  * workflow 侧通过 deps.eventBus 注入 pi.events（同一总线）。