@zhushanwen/pi-subagent-workflow 8.14.7 → 9.0.1

package/README.md

@@ -59,13 +59,14 @@ pi --tools todo,goal_control,workflow,subagent,ask_user
 
 系统内置 `n = 10` 深度护栏（`MAX_FORK_DEPTH`，fork 链与通用嵌套两个计数器共享上限、取严者生效）：fork 链超限抛 `ForkDepthExceededError`，通用嵌套护栏报 `nested_spawn_rejected`。实测建议控制在 **3-4 层**以内——更深层会因上下文逐层压缩导致信息失真。
 
-## Workflow 生命周期（one-shot）
+## Workflow 生命周期
 
-Workflow run 是一次性执行，状态机两态：`running → done`（`done` 唯一终态，reason 区分 completed / aborted / failed / budget_limited / time_limited）。`workflow` tool 仅 3 个 action：`run` / `status` / `abort`。run 的 `name` 接受 `<available_workflows>` 列出的 workflow 名（内置 chain / parallel / map-reduce / scatter-gather / review-fix-loop 或已保存脚本）或 `.js` 绝对路径。一次性执行、无 pause/resume：提前停止只有 abort 一条路，要新结果就重新 run。
+Workflow run 有两类结束形态：**终局**（`done`，outcome 区分 done / failed / cancelled / time_limited——成败已定）与**中断**（`interrupted` 暂停态——执行被打断但可续跑）。`workflow` tool 共 4 个 action：`run` / `status` / `abort` / `resume`。run 的 `name` 接受 `<available_workflows>` 列出的 workflow 名（内置 chain / parallel / map-reduce / scatter-gather / review-fix-loop 或已保存脚本）或 `.js` 绝对路径。
 
-- **abort 是唯一的提前停止方式**：`{"action":"abort","runId":"<id>"}`（可选 `"error":"<reason>"`）。不存在 pause/resume action，调用会被 pi schema 校验拒绝（`Validation failed for tool "workflow"`）；`/workflows pause|resume <id>` 返回 removed 提示
-- **session 切换/关闭时**，所有 running run 当即作废转 `done,failed`（state.error 为 `Session switched: run terminated` / `Session shutdown: run terminated`），已投入的 token 作废；需要结果就重新 run
-- **快照格式 `wf-run-v2`**（status 两态、无 `pausedAt`）；旧 `wf-run-v1` 文件加载时静默跳过
+- **abort（主动取消）**：`{"action":"abort","runId":"<id>"}`（可选 `"error":"<reason>"`）→ `cancelled` 终局。要新结果就重新 run
+- **resume（断点续跑）**：`{"action":"resume","runId":"<id>"}`（可选 args 校验一致性与时间预算）——对 interrupted run 从断点恢复：已完成的调用回放缓存零 token、未完成的按三档恢复（会话完整 → 捞回结果；请求未完成 → 同会话续写；会话不在 → 整跑）；`/workflows resume <id>` 同能力
+- **session 切换/关闭时**，所有 running run 转 `interrupted` 暂停态（被打断不记失败）——回原 session 可 resume 续跑
+- **持久化 = record 事件流**（`<runId>.record.jsonl`，append-only 单一事实源）：状态由事件流折叠得出；旧 `wf-run-v1`/`wf-run-v2` 快照文件为历史遗留，读取面不消费
 - **worker 崩溃自动重建重试**（默认 3 次）：重建时在飞 agent 调用被清除重跑，已完成的调用保留 replay 缓存，不重复消耗 token
 
 ## 性能：sessions-index.json 持久化索引

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.14.7",
+  "version": "9.0.1",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",
@@ -25,7 +25,10 @@
     "src/index.ts",
     "src/jsonl-run-store.ts",
     "src/session-lifecycle.ts",
+    "src/model-events.ts",
+    "src/subagents-events.ts",
     "src/workflow-events.ts",
+    "src/workflow-notify.ts",
     "src/host/",
     "src/injectors/",
     "src/interface/"
@@ -55,20 +58,21 @@
     ]
   },
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.14.0",
-    "@zhushanwen/session-delivery": "0.10.1",
-    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/extension-protocol": "0.16.0",
+    "@zhushanwen/session-delivery": "0.11.0",
+    "@zhushanwen/pi-ext-guards": "0.4.2",
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/subagent-core": "0.11.1",
-    "@zhushanwen/pi-subagent-cli": "0.4.3",
-    "@zhushanwen/zcode-subagent-cli": "0.4.1"
+    "@zhushanwen/pi-notify-ledger-host": "0.2.0",
+    "@zhushanwen/subagent-core": "0.13.0",
+    "@zhushanwen/zcode-subagent-cli": "0.4.3",
+    "@zhushanwen/pi-subagent-cli": "0.4.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.4",
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.7",
+    "@zhushanwen/pi-pending-notifications": "0.8.0",
     "@zhushanwen/pi-structured-output": "5.1.9"
   },
   "peerDependenciesMeta": {
@@ -82,7 +86,8 @@
   "devDependencies": {
     "@types/node": "^24.0.0",
     "@vitest/coverage-v8": "^4.1.9",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.8",
+    "@zhushanwen/subagent-engine-sdk": "0.7.1"
   },
   "scripts": {
     "typecheck": "npx tsc --noEmit",

package/relay/relay.mjs

@@ -33,6 +33,9 @@
  *   dir="down"（代理 stdin → runtime → 真实 pi stdin）/ "up"（→ 代理 stdout）/
  *   "up-stderr"（→ 代理 stderr）。方向以「数据流向真实 pi」为参照：下行 = 流向 pi。
  * - 退出帧 {"kind":"exit","code":C,"signal":S} → 代理以相同 code/signal 退出
+ * - goodbye 帧 {"v":1,"kind":"goodbye"}（代理 → runtime，收到宿主 SIGTERM/SIGINT 时）：
+ *   正常收割预告——runtime 据此把后续 socket close 判定为正常 teardown（kill 行为不变，
+ *   仅日志分级），无预告的 close 保持异常断连语义（kill-on-disconnect warn）
  * - socket 断（close/error/EOF）→ 退出码 12：socket 是代理的生命线，断 = runtime
  *   崩溃等场景下 extension 侧感知「子进程死亡」的机制（崩溃矩阵②），不自杀会变孤儿。
  *
@@ -59,10 +62,14 @@ const RELAY_EXIT_CODES = {
   MISSING_IDENTITY: 13,
 };
 
-/** 首次连接失败到重试的间隔（毫秒）。设计未定值；取短值——只需覆盖 runtime 建 socket 与主 pi spawn 的毫秒级窗口。 */
-const CONNECT_RETRY_DELAY_MS = 200;
+/** 首次连接失败到重试的间隔（毫秒）。设计未定值；取短值——只需覆盖 runtime 建 socket 与主 pi spawn 的毫秒级窗口。
+ * RELAY_CONNECT_RETRY_DELAY_MS 仅测试注入通道（集成测试注入短值压缩重试等待）；NaN/非正数退回默认（负值会让 setTimeout 立即触发 busy retry）。 */
+const _retryDelayEnv = Number(process.env.RELAY_CONNECT_RETRY_DELAY_MS);
+const CONNECT_RETRY_DELAY_MS = Number.isFinite(_retryDelayEnv) && _retryDelayEnv > 0 ? _retryDelayEnv : 200;
 /** 退出前等待 stderr/stdout flush 的兜底上限（毫秒）：pipe 写是异步的，process.exit 会丢未 flush 数据。 */
 const FLUSH_TIMEOUT_MS = 1000;
+/** goodbye 帧写出后等待 flush 的兜底上限（毫秒）：runtime 已死等形态下 write 回调永不到达。 */
+const GOODBYE_FLUSH_TIMEOUT_MS = 500;
 
 const stdin = process.stdin;
 const stdout = process.stdout;
@@ -87,6 +94,42 @@ process.on("uncaughtException", (err) => {
   );
 });
 
+// 宿主终止预告（goodbye 帧）：宿主（extension/引擎）收割代理发 SIGTERM/SIGINT——
+// 这通常发生在 agent_settled 后的正常收割，与宿主崩溃在 runtime 侧同表现为 socket
+// close。被终止前先向 runtime 发 goodbye 预告帧，runtime 据此把 close 判定为正常
+// teardown（info 级日志），异常断连才保留 warn 级 kill-on-disconnect。注册 handler 后
+// Node 不再执行信号默认终止，发帧（含 flush 等待）后自行按 128+signo 退出，对宿主侧
+// 的退出码口径（spawn close 折算 143）保持一致。
+process.on("SIGTERM", () => hostTerminate("SIGTERM"));
+process.on("SIGINT", () => hostTerminate("SIGINT"));
+
+/** 宿主信号终止：best-effort 发 goodbye → 等 flush（有界）→ 按 128+signo 退出。 */
+function hostTerminate(sig) {
+  if (exiting) return;
+  exiting = true;
+  const signum = os.constants.signals[sig];
+  const exitCode = 128 + (typeof signum === "number" ? signum : 0);
+  const die = () => process.exit(exitCode);
+  try {
+    if (sock !== null && !sock.destroyed && handshakeAccepted) {
+      // write 回调 = 帧已离开写缓冲；兜底超时防 runtime 已死时回调永不到达。
+      const timer = setTimeout(die, GOODBYE_FLUSH_TIMEOUT_MS);
+      timer.unref();
+      sock.write(
+        JSON.stringify({ v: RELAY_PROTOCOL_VERSION, kind: "goodbye" }) + "\n",
+        () => {
+          clearTimeout(timer);
+          die();
+        },
+      );
+      return;
+    }
+  } catch {
+    // socket 已坏（runtime 先死等形态）：无预告通道，直接按信号口径退出
+  }
+  die();
+}
+
 main();
 
 function main() {

package/skills/workflow-script-format/SKILL.md

@@ -151,11 +151,11 @@ const [r1, r2, r3] = await parallel([
 ]);
 ```
 
-并发默认上限 6（ConcurrencyPool 限流，`maxConcurrent=6` 来源 ADR-030 决策 3），超出自动排队。元素也可以是返回 Promise 的函数，会被直接调用：
+并发默认上限 6（ConcurrencyPool 限流，`maxConcurrent=6` 来源 ADR-030 决策 3），超出自动排队。元素也可以是返回 Promise 的函数，会被直接调用。
 
 ### `pipeline(...)` — Execute stages sequentially
 
-**模式一：顺序模式** — 传入 stage 数组，每个 stage 收到上一个 stage 的结果：
+传入 stage 数组，每个 stage 收到上一个 stage 的结果：
 
 ```javascript
 const final = await pipeline([
@@ -164,60 +164,6 @@ const final = await pipeline([
 ]);
 ```
 
-**模式二：笛卡尔积模式** — 传入 items 数组 + 多个 stage，对每个 item 依次跑完所有 stage（批处理杀手锏）：
-
-```javascript
-// 对每个 file 依次跑 review → fix
-await pipeline(
-  files,                                      // items
-  (file) => agent({ prompt: `Review ${file}`, description: 'review', schema: {...} }),
-  (review, file) => agent({ prompt: `Fix ${file}: ${JSON.stringify(review)}`, description: 'fix' }),
-);
-// stage 函数签名：(prevResult, currentItem) => result；第一个 stage 只收 currentItem
-```
-
-### `workflow(name, args?)` — Call another workflow (nested orchestration)
-
-调用已定义的子 workflow（by name），实现 workflow 嵌套编排（顺序 chain / 并行 parallel / scatter-gather / map-reduce）。被调用的 workflow 必须已通过 `workflow-script save` 或放在 `.pi/workflows/` / `~/.pi/agent/workflows/` 可被发现。
-
-**签名**：`workflow(name: string, args?: object) => Promise<AgentResult>`
-
-**参数**：
-- `name` — 目标 workflow 的名称（`meta.name`，即文件名 stem）
-- `args` — 传给子 workflow 的参数对象，子 workflow 内通过 `$ARGS` 读取
-
-**返回值**：`AgentResult`，与 `agent()` 返回结构同构：
-- `content: string` — 子 workflow 的 return 值（字符串化）
-- `parsedOutput?: unknown` — 子 workflow return 的对象（当 return 是对象时）
-- `usage?: {...}` — token 消耗
-- `error?: string` — 失败原因（成功时无此字段）
-
-**嵌套配额**：`workflow()` 调用走同一 ConcurrencyPool，按 depth 分层分配配额（`max(1, 6 - depth)`，保底 1 槽防饿死）。`parallel()` 内的 `workflow()` 调用共享父 workflow 的配额池，超出自动排队（不报错）。嵌套深度受 `MAX_FORK_DEPTH` 护栏保护（见 ADR-030 决策 3）。
-
-**返回值**：`workflow()` 返回 `AgentResult` 对象（与 `agent()` 一致）：
-- 成功：`{ content: string, parsedOutput?: object }`——content 是子 workflow execute() 返回值的 JSON 字符串；parsedOutput 是返回值为对象时的原样回传
-- 失败：`{ content: "", error: string }`——子 workflow 未找到/lint 失败/执行异常/被 abort
-
-**循环检测**：`workflow()` 自动追踪调用链（A→B→C），如果目标 name 已在当前调用链中（如 A→B→A），立即返回 error result（`Circular workflow call detected: A → B → A`），不执行子 workflow。
-
-**预算继承**：子 workflow 的 token 预算继承父 workflow 的剩余预算。子 workflow 消耗的 tokens/cost 执行后累加回父 workflow 的预算池。父 workflow abort 时子 workflow 级联 abort。
-
-**chain 基础示例**（顺序：每步输出作下步输入）：
-```javascript
-const a = await workflow("extract", { source: inputPath });
-const b = await workflow("transform", { raw: a.content });
-const c = await workflow("load", { normalized: b.content });
-```
-
-**parallel 基础示例**（并行：多个独立子 workflow 同时跑）：
-```javascript
-const results = await parallel(
-  tasks.map((t) => workflow(t, { target }))
-);
-```
-
-> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce / review-fix-loop，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
-
 ### Other globals
 
 - `$ARGS` — Object with workflow arguments (from `--args key=val`)

package/src/host/__tests__/inflight-reporter.test.ts

@@ -158,7 +158,7 @@ describe("绝对计数语义（每帧携带当下值，非增量）", () => {
   });
 });
 
-describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）", () => {
+describe("失败折叠 + 延迟重试（有界：累计 MAX_REPORT_ATTEMPTS 次放弃，D5 缺席语义②）", () => {
   it("select resolve undefined（超时/旧版 runtime）→ 折叠重试；重试帧携带完整快照；ack 后停", async () => {
     const channel = makeSelectChannel();
     const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
@@ -211,6 +211,31 @@ describe("失败折叠 + 延迟重试直至成功一次（D5 缺席语义②）"
     channel.settleAll(INFLIGHT_REPORT_ACK);
     await advance(0);
   });
+
+  it("累计失败达默认上限（3 次）即放弃：不再重试，后续迁移也不再发帧", async () => {
+    const channel = makeSelectChannel();
+    // 未注入 maxAttempts：锁默认上限 MAX_REPORT_ATTEMPTS = 3（增强面降级语义）。
+    const reporter = createInFlightReporter({ retryDelayMs: RETRY_MS, selectTimeoutMs: SELECT_TIMEOUT_MS });
+    reporter.attachSession(makeCtx(channel));
+    await advance(0);
+    expect(channel.calls).toHaveLength(1);
+
+    // 三帧全部失败落定：首帧 + 2 次退避重试；第 3 次失败触顶
+    channel.settle(0, undefined);
+    await advance(RETRY_MS);
+    expect(channel.calls).toHaveLength(2);
+    channel.settle(1, undefined);
+    await advance(RETRY_MS);
+    expect(channel.calls).toHaveLength(3);
+    channel.settle(2, undefined);
+
+    // 达到上限：放弃为 session 内终态——时间推进与后续迁移都不再发帧
+    await advance(RETRY_MS * 10);
+    expect(channel.calls).toHaveLength(3);
+    reporter.onInFlightChanged();
+    await advance(RETRY_MS * 10);
+    expect(channel.calls).toHaveLength(3);
+  });
 });
 
 describe("不阻塞生命周期主链（D5 接线约束①）", () => {