@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/__tests__/lifecycle.test.ts

@@ -87,7 +87,7 @@ function makeRunningRealRun(
   const terminate = vi.fn(async () => {});
   const controller = new AbortController();
   const abort = vi.spyOn(controller, "abort");
-  const worker = { terminate, postMessage: vi.fn() } as unknown as Parameters<typeof RunRuntime.prototype.constructor>[0];
+  const worker = { terminate, postMessage: vi.fn() } as unknown as ConstructorParameters<typeof RunRuntime>[0];
   const runtime = new RunRuntime(
     worker as never,
     controller,
@@ -217,7 +217,7 @@ describe("runWorkflow", () => {
     const deps = makeDeps();
     // worker.start 被调时探测 runs 注册状态——证明 runs.set 在 assignRuntime 之后
     let runsSizeAtWorkerStart = -1;
-    deps.workerHost.start = vi.fn(() => {
+    vi.spyOn(deps.workerHost, "start").mockImplementation(() => {
       runsSizeAtWorkerStart = deps.runs.size;
       return { postMessage: vi.fn(), terminate: vi.fn(async () => {}) };
     });
@@ -251,6 +251,44 @@ describe("runWorkflow", () => {
     expect(deps.eventBus.emit).not.toHaveBeenCalled();
   });
 
+  // OR-1 顺序修复（unbounded-wait-audit §4.1）：budgetTimeMs 溢出的 fail-fast
+  // 必须发生在首个副作用（workerHost.start）之前——旧顺序 worker 先启动、
+  // scheduleTimeBudget 后 throw，产生「worker 已跑、run 永不可达」的孤儿。
+  it("OR-1: budgetTimeMs 溢出（>2^31-1）→ worker 启动前 fail-fast（zero side effects）", async () => {
+    const deps = makeDeps();
+    const spec = makeSpec({ budgetTimeMs: 3_000_000_000 });
+
+    await expect(runWorkflow(spec, deps)).rejects.toThrow(/2147483647/);
+
+    // fail-fast 先于全部副作用：worker 未启动、run 未注册、未落盘、未通知
+    expect(deps.workerHost.start).not.toHaveBeenCalled();
+    expect(deps.runs.size).toBe(0);
+    expect(deps.store.save).not.toHaveBeenCalled();
+    expect(deps.eventBus.emit).not.toHaveBeenCalled();
+  });
+
+  // OR-1 前移的代价：start 抛错时已挂的 timeBudget timer 会残留（到期对从未注册的
+  // runId 触发 abortRun → not found）——start 抛错路径必须就地 clearTimeout。
+  it("OR-1: budgetTimeMs 有效但 worker.start 抛错 → timeBudget timer 被清理（无残留）", async () => {
+    const deps = makeDeps();
+    deps.workerHost.start = vi.fn(() => {
+      throw new Error("worker boot failed");
+    });
+
+    // fake timers：用例开始时无 pending 计时器（beforeEach 全新安装）
+    expect(vi.getTimerCount()).toBe(0);
+
+    await expect(
+      runWorkflow(makeSpec({ budgetTimeMs: 60_000 }), deps),
+    ).rejects.toThrow("worker boot failed");
+
+    // timer 挂载（scheduleTimeBudget）发生在 start 之前 → 抛错路径必须回收：
+    // 无 pending 计时器残留（若漏清理此处为 1，到期会误 abort 幽灵 runId）
+    expect(vi.getTimerCount()).toBe(0);
+    // 既有行为不回归：runs Map 无该 runId 条目（abortRun not found 语义保持）
+    expect(deps.runs.size).toBe(0);
+  });
+
   it("带 budgetTimeMs 时调度时间预算计时器（真实消费：挂载 + 到期 time_limited）", async () => {
     const deps = makeDeps();
     const spec = makeSpec({ budgetTimeMs: 3000 });
@@ -359,6 +397,25 @@ describe("abortRun", () => {
     expect(deps.onRunDone).not.toHaveBeenCalled();
   });
 
+  it("[B-4] eventBus listener 抛错 → abortRun 不向调用方抛错、onRunDone 仍执行", async () => {
+    const { run, terminate } = makeRunningRealRun("wf-abort-fence");
+    const deps = makeDeps();
+    deps.eventBus.emit = vi.fn(() => {
+      throw new Error("listener exploded");
+    });
+    deps.runs.set("wf-abort-fence", run);
+
+    // 旧实现裸调 emit：listener 抛错 → 异常上抛给 tool 调用方 + 跳过 onRunDone
+    await expect(abortRun("wf-abort-fence", deps, "abort with broken bus")).resolves.toBeUndefined();
+
+    // abort 成功语义保持：终态转换/terminate 照常完成
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("aborted");
+    expect(terminate).toHaveBeenCalledTimes(1);
+    // 独立围栏：onRunDone 不被 emit 故障跳过
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
   it("自定义 doneReason（time_limited）", async () => {
     const { run } = makeRunningRealRun("wf-abort-3");
     const deps = makeDeps();
@@ -436,7 +493,27 @@ describe("terminateRunningRuns", () => {
     expect(deps.store.save).toHaveBeenCalledWith(run);
   });
 
-  it("单 run save 抛错不中断其余（其余 run 仍落盘 + unregister）", async () => {
+  it("[B-4] eventBus listener 抛错 → 不向调用方抛错、本 run 收尾完成、其余 run 继续终止", async () => {
+    const { run: a, terminate: terminateA } = makeRunningRealRun("wf-term-fence-a");
+    const { run: b, terminate: terminateB } = makeRunningRealRun("wf-term-fence-b");
+    const deps = makeDeps();
+    deps.runs.set("wf-term-fence-a", a);
+    deps.runs.set("wf-term-fence-b", b);
+    // 仅 runA 的 emit 抛错（按 payload id 判别模拟坏 listener）
+    deps.eventBus.emit = vi.fn((_event: string, payload: { id: string }) => {
+      if (payload.id === "wf-term-fence-a") throw new Error("listener exploded");
+    });
+
+    await expect(terminateRunningRuns(deps, "Session switched: run terminated")).resolves.toBeUndefined();
+
+    // 两个 run 都走到终态（runA 的 emit 故障不中断批量收尾）
+    expect(a.state.reason).toBe("failed");
+    expect(b.state.reason).toBe("failed");
+    expect(terminateA).toHaveBeenCalledTimes(1);
+    expect(terminateB).toHaveBeenCalledTimes(1);
+  });
+
+  it("单 run save 抛错不中断其余（save best-effort：unregister 仍发 + 其余 run 照常落盘）", async () => {
     const { run: bad } = makeRunningRealRun("wf-term-err");
     const { run: good } = makeRunningRealRun("wf-term-ok");
     const deps = makeDeps();
@@ -448,10 +525,12 @@ describe("terminateRunningRuns", () => {
 
     await terminateRunningRuns(deps, "Session shutdown: run terminated");
 
-    // 抛错的 run：transition 先于 save，状态已转 done，但 unregister 被 save 失败短路
+    // [D5-② finalizeRun 收敛] save 失败 best-effort（SW-DATA-3 统一）：transition 先于
+    // save，状态已转 done；与收敛前不同，unregister 不再被 save 失败短路——否则
+    // pending 通知幽灵注销（列表残留永不清理的 running 条目）
     expect(bad.state.status).toBe("done");
     expect(bad.state.reason).toBe("failed");
-    expect(deps.eventBus.emit).not.toHaveBeenCalledWith("pending:unregister", {
+    expect(deps.eventBus.emit).toHaveBeenCalledWith("pending:unregister", {
       id: "wf-term-err",
       reason: "failed",
     });

package/src/orchestration/__tests__/non-cloneable-return-e2e.test.ts

@@ -80,7 +80,7 @@ describe("[F1] 不可克隆 return → run failed（非悬挂）— e2e", () =>
       // worker 侧 fallback 消息经 handleScriptError 超限路径写入归因
       expect(run.state.error).toContain("structured-clone failed");
       // 终态副作用齐全（对比 SW-DATA-3/F1 前的幽灵悬挂：无 unregister / 无 onRunDone）
-      expect(deps.eventBus.emit).toHaveBeenCalledWith(
+      expect(deps.eventBus!.emit).toHaveBeenCalledWith(
         "pending:unregister",
         expect.objectContaining({ id: runId, reason: "failed" }),
       );

package/src/orchestration/__tests__/run-snapshot.test.ts

@@ -0,0 +1,356 @@
+// run-snapshot.test.ts —— WorkflowRun 快照 codec 单源（下沉收口 D4/U8）。
+//
+// 四视角：
+// ①使用者——toRunSnapshot/fromRunSnapshot 往返等值（含 pi 壳 jsonl-run-store
+//   serializeRun 现网形态样本：键序/v 字段/无 live 的快照行，⛔5 往返逐字节一致）；
+// ②隔离者——live-strip 产出新对象，不 mutate 内存中的 run（save 后 run 可继续跑）；
+// ③幸存者——版本 guard（D4 裁决③：v 不匹配即拒，字符串无大小序）+ 形状校验
+//   全分支不抛（返回 undefined）；
+// ④接线者——「缺 v 宽容」不内聚进 codec（D4 裁决②归属：store 层预处理职责，
+//   codec 层缺 v 即拒，保 pi 侧 v1 存量静默跳过语义）+ spec.budgetRef 剔除。
+//
+// 纯内存测试：无 configureCore 依赖（codec 不触 host-services）。
+
+import { describe, expect, it } from "vitest";
+
+import type { ExecutionRecord } from "../../execution/types.ts";
+import type { ExecutionTraceNode } from "../models/types.ts";
+import { AgentCall } from "../models/agent-call.ts";
+import { Budget } from "../models/budget.ts";
+import { Trace } from "../models/trace.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import { SNAPSHOT_VERSION, fromRunSnapshot, toRunSnapshot } from "../run-snapshot.ts";
+
+/** 构造可持久化的 WorkflowRun（对齐 file-run-store.test.ts makeRun 模式）。 */
+function makeRun(runId: string, opts: { status?: "running" | "done" } = {}): WorkflowRun {
+  const status = opts.status ?? "running";
+  return WorkflowRun.reconstruct(
+    runId,
+    {
+      scriptSource: "export function execute() { return 'ok'; }",
+      args: { topic: "demo", count: 2 },
+      scriptName: "test-script",
+      scriptPath: "/fake/test.js",
+      parameters: { type: "object" },
+      budgetTokens: 1000,
+    },
+    {
+      status,
+      ...(status === "done" ? { reason: "completed" as const } : {}),
+      budget: new Budget({ maxTokens: 1000, usedTokens: 42, usedCost: 0.5, totalCallCount: 3 }),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+      scriptResult: status === "done" ? { summary: "done-value" } : undefined,
+    },
+    { startedAt: "2026-08-30T00:00:00.000Z" },
+  );
+}
+
+/** 最小 live 执行进度对象（strip 逻辑只解构键名，值形态不可达——对齐
+ *  lifecycle-predicates.test.ts 的 partial + as ExecutionRecord 先例）。 */
+function makeLiveRecord(id: string): ExecutionRecord {
+  return {
+    id,
+    agent: "coder",
+    model: "test-model",
+    thinkingLevel: undefined,
+    mode: "background",
+    task: "do work",
+    slug: "do-work",
+    startedAt: 0,
+    rootSessionId: undefined,
+    parentRecordId: undefined,
+    depth: 0,
+    status: "running",
+    turns: [],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: undefined,
+    round: 0,
+    endedAt: undefined,
+    result: undefined,
+    error: undefined,
+    agentResult: undefined,
+    controller: undefined,
+  } as ExecutionRecord;
+}
+
+/**
+ * pi 壳 jsonl-run-store.ts serializeRun 现网形态样本（顶层 done 前的 running
+ * run，字段集/键序按其对象字面量排列）。pi 存量行恒无 live（其 serializeRun
+ * strip）、恒带 v="wf-run-v2"（D4 裁决①：版本值沿用）。
+ */
+const PI_FORM_SNAPSHOT = {
+  v: "wf-run-v2",
+  runId: "wf-pi-form-1",
+  spec: {
+    scriptSource: "export function execute() { return 'pi-form'; }",
+    args: { topic: "demo" },
+    scriptName: "test-script",
+    scriptPath: "/fake/test.js",
+    budgetTokens: 1000,
+  },
+  state: {
+    status: "running",
+    budget: { maxTokens: 1000, usedTokens: 42, usedCost: 0.5, totalCallCount: 3 },
+    calls: [
+      {
+        id: 0,
+        opts: { prompt: "do work" },
+        status: "done",
+        attempts: 1,
+        result: { content: "ok" },
+        sessionId: "sess-1",
+        sessionFile: "/tmp/sess-1.jsonl",
+        traceNode: {
+          stepIndex: 0,
+          agent: "coder",
+          task: "do work",
+          model: "test-model",
+          status: "completed",
+          startedAt: "2026-08-30T00:00:01.000Z",
+          completedAt: "2026-08-30T00:00:02.000Z",
+          sessionId: "sess-1",
+          sessionFile: "/tmp/sess-1.jsonl",
+        },
+      },
+    ],
+    trace: [
+      {
+        stepIndex: 0,
+        agent: "coder",
+        task: "do work",
+        model: "test-model",
+        status: "completed",
+        startedAt: "2026-08-30T00:00:01.000Z",
+        completedAt: "2026-08-30T00:00:02.000Z",
+        sessionId: "sess-1",
+        sessionFile: "/tmp/sess-1.jsonl",
+      },
+    ],
+    errorLogs: [{ level: "warn", message: "retrying" }],
+  },
+  meta: { startedAt: "2026-08-30T00:00:00.000Z" },
+};
+
+describe("run-snapshot — toRunSnapshot/fromRunSnapshot 往返等值", () => {
+  it("⛔5 pi 现网形态样本：重水合 → 再序列化与原行逐字节一致（v 字段保持 wf-run-v2）", () => {
+    const line = JSON.stringify(PI_FORM_SNAPSHOT);
+
+    const run = fromRunSnapshot(JSON.parse(line));
+    expect(run).toBeDefined();
+    expect(run!.runId).toBe("wf-pi-form-1");
+
+    // 逐字节一致：pi 切换本 codec 后存量行往返不变（u-sw-store ⛔5 前提）
+    expect(JSON.stringify(toRunSnapshot(run!))).toBe(line);
+  });
+
+  it("running 快照往返：runId/spec/budget/trace/meta 字段保真", () => {
+    const run = makeRun("wf-snap-1");
+    const back = fromRunSnapshot(JSON.parse(JSON.stringify(toRunSnapshot(run))));
+
+    expect(back).toBeDefined();
+    expect(back!.runId).toBe("wf-snap-1");
+    expect(back!.state.status).toBe("running");
+    expect(back!.spec.scriptName).toBe("test-script");
+    expect(back!.spec.args).toEqual({ topic: "demo", count: 2 });
+    expect(back!.state.budget).toBeInstanceOf(Budget);
+    expect(back!.state.budget.usedTokens).toBe(42);
+    expect(back!.state.budget.totalCallCount).toBe(3);
+    expect(back!.state.trace).toBeInstanceOf(Trace);
+    expect(back!.runtime).toBeUndefined();
+    expect(back!.meta.startedAt).toBe("2026-08-30T00:00:00.000Z");
+  });
+
+  it("done 快照往返：reason/scriptResult/errorLogs/completedAt 保真", () => {
+    const run = makeRun("wf-snap-2", { status: "done" });
+    run.state.errorLogs.push({ level: "warn", message: "transient" });
+    run.meta.workerErrorCount = 1;
+
+    const back = fromRunSnapshot(JSON.parse(JSON.stringify(toRunSnapshot(run))));
+
+    expect(back!.state.status).toBe("done");
+    expect(back!.state.reason).toBe("completed");
+    expect(back!.state.scriptResult).toEqual({ summary: "done-value" });
+    expect(back!.state.errorLogs).toEqual([{ level: "warn", message: "transient" }]);
+    expect(back!.meta.completedAt).toBe(run.meta.completedAt);
+    expect(back!.meta.workerErrorCount).toBe(1);
+  });
+
+  it("含 calls 的往返：calls Map 逐项保真 + traceNode 回链 Trace 副本（D-10 尽力恢复）", () => {
+    const run = makeRun("wf-snap-3");
+    const node = {
+      stepIndex: 0,
+      agent: "coder",
+      task: "do work",
+      model: "test-model",
+      status: "completed" as const,
+    };
+    run.state.trace.append(node);
+    const call = new AgentCall(0, { prompt: "do work" }, node);
+    call.status = "done";
+    call.attempts = 1;
+    run.state.calls.set(0, call);
+
+    const back = fromRunSnapshot(JSON.parse(JSON.stringify(toRunSnapshot(run))))!;
+
+    expect(back.state.calls.size).toBe(1);
+    const restored = back.state.calls.get(0)!;
+    expect(restored.opts.prompt).toBe("do work");
+    expect(restored.status).toBe("done");
+    expect(restored.attempts).toBe(1);
+    expect(restored.traceNode).toBe(back.state.trace.toArray()[0]);
+  });
+});
+
+describe("run-snapshot — live-strip 防御内聚", () => {
+  it("trace 节点与 calls[].traceNode 带 live → 序列化输出无 live 键", () => {
+    const run = makeRun("wf-live-1");
+    const node: ExecutionTraceNode = {
+      stepIndex: 0,
+      agent: "coder",
+      task: "do work",
+      model: "test-model",
+      status: "running",
+      live: undefined,
+    };
+    run.state.trace.append(node);
+    const call = new AgentCall(0, { prompt: "do work" }, node);
+    run.state.calls.set(0, call);
+    // D-10：call.traceNode 与 trace 节点共享引用，live 挂节点上（running 态常态）
+    node.live = makeLiveRecord("run-0");
+
+    const snap = toRunSnapshot(run);
+    const serialized = JSON.stringify(snap);
+
+    expect(serialized.includes('"live"')).toBe(false);
+    expect(snap.state.trace[0]).not.toHaveProperty("live");
+    expect(snap.state.calls[0].traceNode).not.toHaveProperty("live");
+  });
+
+  it("strip 产出新对象，不 mutate 内存 run（save 后 run 可继续跑）", () => {
+    const run = makeRun("wf-live-2");
+    const node: ExecutionTraceNode = {
+      stepIndex: 0,
+      agent: "coder",
+      task: "do work",
+      model: "test-model",
+      status: "running",
+      live: undefined,
+    };
+    run.state.trace.append(node);
+    node.live = makeLiveRecord("run-0");
+
+    toRunSnapshot(run);
+
+    // 原节点 live 保留（运行期消费面——TUI 事件流投影——不受落盘影响）
+    expect(node.live).toBeDefined();
+    expect(node.live!.id).toBe("run-0");
+  });
+});
+
+describe("run-snapshot — spec.budgetRef 剔除", () => {
+  it("spec.budgetRef（进程内共享引用）不落盘，spec 其余字段保真", () => {
+    const run = makeRun("wf-ref-1");
+    const specWithRef = { ...run.spec, budgetRef: new Budget({ maxTokens: 500 }) };
+    // reconstruct 直造带 budgetRef 的聚合（嵌套 workflow 的 run 形态）
+    const nested = WorkflowRun.reconstruct("wf-ref-1", specWithRef, run.state, run.meta);
+
+    const snap = toRunSnapshot(nested);
+
+    expect(nested.spec.budgetRef).toBeDefined(); // 内存对象不受影响
+    expect(snap.spec).not.toHaveProperty("budgetRef");
+    expect(snap.spec.scriptName).toBe("test-script");
+
+    const back = fromRunSnapshot(JSON.parse(JSON.stringify(snap)))!;
+    expect(back.spec).not.toHaveProperty("budgetRef");
+    expect(back.spec.budgetTokens).toBe(1000);
+  });
+});
+
+describe("run-snapshot — 版本 guard（D4 裁决③）", () => {
+  it(`v = 当前版本（${SNAPSHOT_VERSION}）通过`, () => {
+    const run = fromRunSnapshot(JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-v-ok")))));
+    expect(run).toBeDefined();
+  });
+
+  it("未知更高版本（wf-run-v3）拒绝——字符串版本无大小序，不引入比较逻辑", () => {
+    const snap = { ...JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-v-3")))), v: "wf-run-v3" };
+    expect(fromRunSnapshot(snap)).toBeUndefined();
+  });
+
+  it("旧版本 wf-run-v1 拒绝（pi 存量静默跳过语义的数据防线）", () => {
+    const snap = { ...JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-v-1")))), v: "wf-run-v1" };
+    expect(fromRunSnapshot(snap)).toBeUndefined();
+  });
+
+  it("缺 v 字段拒绝——「缺 v 宽容」是 store 层预处理职责，不内聚进 codec（D4 裁决②）", () => {
+    const { v: _v, ...legacy } = JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-v-none"))));
+    expect(fromRunSnapshot(legacy)).toBeUndefined();
+  });
+
+  it("v 为非字符串脏值（数字/null）拒绝", () => {
+    const base = JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-v-dirty"))));
+    expect(fromRunSnapshot({ ...base, v: 2 })).toBeUndefined();
+    expect(fromRunSnapshot({ ...base, v: null })).toBeUndefined();
+  });
+});
+
+describe("run-snapshot — 形状校验（损坏行不抛，返回 undefined）", () => {
+  it("null / 非对象 / 缺 runId / 空 runId 拒绝", () => {
+    expect(fromRunSnapshot(null)).toBeUndefined();
+    expect(fromRunSnapshot("not an object")).toBeUndefined();
+    expect(fromRunSnapshot({ v: SNAPSHOT_VERSION, spec: {}, state: {}, meta: {} })).toBeUndefined();
+    expect(fromRunSnapshot({ v: SNAPSHOT_VERSION, runId: "", spec: {}, state: {}, meta: {} })).toBeUndefined();
+  });
+
+  it("缺 spec / 缺 state / 非法 status / 缺 budget / 缺 calls / 缺 trace / 缺 meta 拒绝", () => {
+    const ok = () => JSON.parse(JSON.stringify(toRunSnapshot(makeRun("wf-shape-base"))));
+    const without = (keys: string[]) => {
+      const snap = ok();
+      for (const k of keys) delete snap[k];
+      return snap;
+    };
+
+    expect(fromRunSnapshot(without(["spec"]))).toBeUndefined();
+    expect(fromRunSnapshot(without(["state"]))).toBeUndefined();
+    expect(fromRunSnapshot(without(["meta"]))).toBeUndefined();
+
+    const badStatus = ok();
+    badStatus.state.status = "paused"; // v1 三态残留在 v2 快照 = 形状损坏
+    expect(fromRunSnapshot(badStatus)).toBeUndefined();
+
+    const noBudget = ok();
+    delete noBudget.state.budget;
+    expect(fromRunSnapshot(noBudget)).toBeUndefined();
+
+    const noCalls = ok();
+    delete noCalls.state.calls;
+    expect(fromRunSnapshot(noCalls)).toBeUndefined();
+
+    const noTrace = ok();
+    delete noTrace.state.trace;
+    expect(fromRunSnapshot(noTrace)).toBeUndefined();
+  });
+
+  it("calls 内残缺条目跳过不炸整个 run（traceNode 缺失条目被丢弃）", () => {
+    const run = makeRun("wf-shape-call");
+    const node = {
+      stepIndex: 0,
+      agent: "coder",
+      task: "do work",
+      model: "test-model",
+      status: "completed" as const,
+    };
+    run.state.trace.append(node);
+    run.state.calls.set(0, new AgentCall(0, { prompt: "do work" }, node));
+
+    const snap = JSON.parse(JSON.stringify(toRunSnapshot(run)));
+    snap.state.calls.push({ notACall: true });
+
+    const back = fromRunSnapshot(snap)!;
+    expect(back).toBeDefined();
+    expect(back.state.calls.size).toBe(1);
+  });
+});