@zhushanwen/subagent-core 0.4.0 → 0.5.1

package/src/orchestration/__tests__/worker-message-pump-finalize-run.test.ts

@@ -0,0 +1,229 @@
+/**
+ * finalizeRun — D5-② 终态 coda 单写点测试。
+ *
+ * 「transition → save → pending:unregister → onRunDone」四步终态序列的唯一
+ * 定义点（worker-message-pump.ts）。收敛前 8 处逐字复制（本文件 6 处 + lifecycle
+ * 2 处）——本文件锁定：
+ * 1. 四步恰好一次且有序（transition 先于 save 先于 unregister 先于 onRunDone）
+ * 2. notifyDone:false 真差异承载（terminateRunningRuns 不发 onRunDone、unregister 仍发）
+ * 3. transition 让位（并发终态化）→ 后三步全不执行
+ * 4. save best-effort（SW-DATA-3）→ unregister/onRunDone 不被落盘失败短路
+ *
+ * 其余终态路径的「恰好一次四步」行为断言（save×1 + unregister + onRunDone×1）
+ * 已由既有测试覆盖：handleWorkerError/handleScriptError/handleWorkerExit 超限
+ * （worker-message-pump-handlers / worker-exit-without-result）、time_limited
+ * （worker-message-pump-handlers race-F3 describe）、abortRun（lifecycle.test）、
+ * handleReturn（worker-exit-without-result SW-DATA-3 describe）。本文件补齐
+ * budget_limited 路径（dispatchAgentCall coda）与 notifyDone:false 路径。
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  finalizeRun,
+  handleWorkerMessage,
+} from "../worker-message-pump.ts";
+import { Budget } from "../models/budget.ts";
+import { RunRuntime } from "../models/run-runtime.ts";
+import { Trace } from "../models/trace.ts";
+import type { AgentResult } from "../models/types.ts";
+import { WorkflowRun } from "../models/workflow-run.ts";
+import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
+import type { WorkerHandle } from "../worker-handle.ts";
+
+// ── helpers ──────────────────────────────────────────────────
+
+/** 构造真实 WorkflowRun（真实状态机 transition）+ 初始 runtime。 */
+function makeRealRun(runId: string): WorkflowRun {
+  const run = new WorkflowRun(
+    runId,
+    {
+      scriptName: "test-wf",
+      scriptSource: "agent('hi')",
+      args: {},
+      scriptPath: "/tmp/test-wf.js",
+    },
+    {
+      status: "running",
+      budget: new Budget(),
+      calls: new Map(),
+      trace: new Trace(),
+      errorLogs: [],
+    },
+    { startedAt: new Date().toISOString() },
+  );
+  const worker = {
+    postMessage: vi.fn(),
+    terminate: vi.fn(async () => {}),
+  } as unknown as WorkerHandle;
+  run.assignRuntime(new RunRuntime(worker, new AbortController()));
+  return run;
+}
+
+/** deps mock：副作用打点进单一顺序数组（断言四步顺序）。 */
+function makeTracingDeps(): LifecycleDeps & {
+  order: string[];
+  store: { save: ReturnType<typeof vi.fn> };
+} {
+  const order: string[] = [];
+  return {
+    order,
+    store: {
+      save: vi.fn(async () => {
+        order.push("save");
+      }),
+    },
+    workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
+    runner: { run: vi.fn(async () => ({}) as AgentResult) },
+    runs: new Map(),
+    eventBus: {
+      emit: vi.fn((event: string) => {
+        order.push(`emit:${event}`);
+      }),
+    },
+    onRunDone: vi.fn(() => {
+      order.push("onRunDone");
+    }),
+    log: vi.fn(),
+  } as unknown as ReturnType<typeof makeTracingDeps>;
+}
+
+/** flush 微任务队列（void finalizeRun 的 async 链推进到稳定态）。 */
+async function flushMicrotasks(ticks = 20): Promise<void> {
+  for (let i = 0; i < ticks; i++) {
+    // eslint-disable-next-line no-await-in-loop -- 排空微任务队列的固定 tick 循环，非逐项等待
+    await Promise.resolve();
+  }
+}
+
+// ── finalizeRun 直测 ─────────────────────────────────────────
+
+describe("finalizeRun（D5-② 单写点直测）", () => {
+  it("四步恰好一次且有序：transition → save → pending:unregister → onRunDone", async () => {
+    const run = makeRealRun("wf-fin-1");
+    const deps = makeTracingDeps();
+
+    const transitionSpy = vi.spyOn(run, "transition");
+    const ok = await finalizeRun(run, deps, "completed", { context: "test" });
+
+    expect(ok).toBe(true);
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("completed");
+    // 四步各恰好一次
+    expect(transitionSpy).toHaveBeenCalledTimes(1);
+    expect(deps.store.save).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+    // 顺序：save → unregister → onRunDone（transition 已同步先行）
+    expect(deps.order).toEqual(["save", "emit:pending:unregister", "onRunDone"]);
+    // unregister reason = transition 后的 state.reason
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-fin-1",
+      reason: "completed",
+    });
+  });
+
+  it("notifyDone:false → onRunDone 不调、unregister 仍发（terminateRunningRuns 真差异经参数承载）", async () => {
+    const run = makeRealRun("wf-fin-2");
+    const deps = makeTracingDeps();
+
+    const ok = await finalizeRun(run, deps, "failed", {
+      context: "terminateRunningRuns",
+      notifyDone: false,
+    });
+
+    expect(ok).toBe(true);
+    expect(run.state.reason).toBe("failed");
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-fin-2",
+      reason: "failed",
+    });
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+    expect(deps.order).toEqual(["save", "emit:pending:unregister"]);
+  });
+
+  it("transition 抛错（并发 abort 抢先终态化）→ 返回 false，后三步全不执行", async () => {
+    const run = makeRealRun("wf-fin-3");
+    // 抢先终态化——此后 running→done 转移抛 illegal-transition
+    run.transition("done", "aborted");
+    const deps = makeTracingDeps();
+
+    const ok = await finalizeRun(run, deps, "failed", { context: "test" });
+
+    expect(ok).toBe(false);
+    // 抢先方已兑现 unregister/onRunDone——本路径让位，不重复执行
+    expect(deps.store.save).not.toHaveBeenCalled();
+    expect(deps.eventBus!.emit).not.toHaveBeenCalled();
+    expect(deps.onRunDone).not.toHaveBeenCalled();
+    expect(run.state.reason).toBe("aborted");
+  });
+
+  it("save 抛错（ENOSPC）→ best-effort：unregister + onRunDone 照常（SW-DATA-3 统一）", async () => {
+    const run = makeRealRun("wf-fin-4");
+    const deps = makeTracingDeps();
+    deps.store.save = vi.fn(async () => {
+      throw new Error("ENOSPC: no space left on device");
+    });
+
+    const ok = await finalizeRun(run, deps, "failed", { context: "test" });
+
+    expect(ok).toBe(true);
+    expect(run.state.status).toBe("done");
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+
+  it("onRunDone 抛错 → 被捕获记日志（M12：真实副作用错误不静默吞、不上抛）", async () => {
+    const run = makeRealRun("wf-fin-5");
+    const deps = makeTracingDeps();
+    deps.onRunDone = vi.fn(() => {
+      throw new Error("interface notify blew up");
+    });
+
+    await expect(
+      finalizeRun(run, deps, "completed", { context: "test" }),
+    ).resolves.toBe(true);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(run.state.status).toBe("done");
+  });
+});
+
+// ── budget_limited 路径（dispatchAgentCall coda）四步恰好一次 ────────────
+
+describe("budget_limited 终态路径（dispatchAgentCall → finalizeRun）", () => {
+  it("agent call 后预算超限 → 四步恰好一次（unregister reason=budget_limited + onRunDone）", async () => {
+    const run = makeRealRun("wf-budget-1");
+    const deps = makeTracingDeps();
+    // budget.isExceeded 恒 true——runner.run 成功返回后命中 C-2 coda
+    (run.state.budget as unknown as { isExceeded: () => boolean }).isExceeded =
+      () => true;
+    deps.runner.run = vi.fn(async () =>
+      ({ content: "ok", durationMs: 1, error: undefined, toolCalls: [] }) as AgentResult,
+    );
+    const handlers: WorkerHandlers = {
+      onMessage: vi.fn(async () => {}),
+      onError: vi.fn(async () => {}),
+      onExit: vi.fn(async () => {}),
+    };
+
+    await handleWorkerMessage(
+      run,
+      { type: "agent-call", callId: 1, opts: { prompt: "p", description: "d" } },
+      deps,
+      handlers,
+    );
+    await flushMicrotasks();
+
+    expect(run.state.status).toBe("done");
+    expect(run.state.reason).toBe("budget_limited");
+    // save 2 次 = call 完成快照（dispatchAgentCall .then 的常规持久化）+ budget
+    // 终态快照（finalizeRun 内）——两次语义不同，收敛前后一致
+    expect(deps.store.save).toHaveBeenCalledTimes(2);
+    expect(deps.eventBus!.emit).toHaveBeenCalledTimes(1);
+    expect(deps.eventBus!.emit).toHaveBeenCalledWith("pending:unregister", {
+      id: "wf-budget-1",
+      reason: "budget_limited",
+    });
+    expect(deps.onRunDone).toHaveBeenCalledTimes(1);
+  });
+});

package/src/orchestration/__tests__/{error-recovery-handlers.test.ts → worker-message-pump-handlers.test.ts}

@@ -1,7 +1,7 @@
 /**
- * error-recovery handlers — handleWorkerExit/Error/ScriptError + postBudgetUpdate 测试。
+ * worker-message-pump handlers — handleWorkerExit/Error/ScriptError + postBudgetUpdate 测试。
  *
- * 参考 error-recovery-workflow-call.test.ts 的 mock 构建。通过 vi.useFakeTimers() 跳过
+ * 参考 worker-message-pump-workflow-call.test.ts 的 mock 构建。通过 vi.useFakeTimers() 跳过
  * scheduleRebuild 的指数退避（1s/2s/4s）。
  *
  * 覆盖：
@@ -23,11 +23,11 @@ import {
   handleWorkerMessage,
   postBudgetUpdate,
   rebuildRuntime,
-} from "../error-recovery.ts";
+} from "../worker-message-pump.ts";
 import { Budget } from "../models/budget.ts";
 import { RunRuntime } from "../models/run-runtime.ts";
 import { Trace } from "../models/trace.ts";
-import type { AgentResult } from "../models/types.ts";
+import type { AgentResult, DoneReason, RunStatus } from "../models/types.ts";
 import { WorkflowRun } from "../models/workflow-run.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkerHandle } from "../worker-handle.ts";
@@ -71,26 +71,34 @@ function makeRunningRun(opts: {
       receivedTerminalMessage: opts.receivedTerminalMessage,
     },
     // transition 副作用——run.state.status 由调用方通过 mock 控制后再次断言
-    transition(target: string, reason?: string): void {
+    transition(this: WorkflowRun, target: RunStatus, reason?: DoneReason): void {
       this.state.status = target;
       if (target === "done") this.state.reason = reason;
     },
-    replaceRuntime(rt: unknown): void {
+    replaceRuntime(this: WorkflowRun, rt: NonNullable<WorkflowRun["runtime"]>): void {
       this.runtime = rt;
     },
   } as unknown as WorkflowRun;
 }
 
-/** LifecycleDeps mock：store/workerHost/runner/eventBus/scheduleTimeBudget 可观察。 */
+/** LifecycleDeps mock：store/workerHost/runner/eventBus/scheduleTimeBudget 可观察。
+ *  mock 成员 = 真实签名 & vi.fn 能力（交叉纯 Mock 会丢真实签名，传回被测函数即报错）。 */
+type MockLifecycleDeps = Omit<
+  LifecycleDeps,
+  "store" | "workerHost" | "runner" | "eventBus" | "onRunDone" | "log"
+> & {
+  // 真实类型整体保留（RunStore/WorkerHost 等接口成员完整），仅 mock 方法交叉 vi.fn 能力
+  store: LifecycleDeps["store"] & { save: LifecycleDeps["store"]["save"] & ReturnType<typeof vi.fn> };
+  workerHost: LifecycleDeps["workerHost"] & { start: LifecycleDeps["workerHost"]["start"] & ReturnType<typeof vi.fn> };
+  runner: LifecycleDeps["runner"] & { run: LifecycleDeps["runner"]["run"] & ReturnType<typeof vi.fn> };
+  eventBus: NonNullable<LifecycleDeps["eventBus"]> & { emit: NonNullable<LifecycleDeps["eventBus"]>["emit"] & ReturnType<typeof vi.fn> };
+  onRunDone: LifecycleDeps["onRunDone"] & ReturnType<typeof vi.fn>;
+  log: LifecycleDeps["log"] & ReturnType<typeof vi.fn>;
+};
+
 function makeDeps(opts: {
   scheduleTimeBudget?: LifecycleDeps["scheduleTimeBudget"];
-} = {}): LifecycleDeps & {
-  store: { save: ReturnType<typeof vi.fn> };
-  workerHost: { start: ReturnType<typeof vi.fn> };
-  eventBus: { emit: ReturnType<typeof vi.fn> };
-  onRunDone: ReturnType<typeof vi.fn>;
-  log: ReturnType<typeof vi.fn>;
-} {
+} = {}): MockLifecycleDeps {
   return {
     store: { save: vi.fn(async () => {}) },
     workerHost: { start: vi.fn(() => ({ postMessage: vi.fn() })) },
@@ -344,7 +352,7 @@ describe("rebuildRuntime", () => {
 
   it("带 budgetTimeMs 时重排 scheduleTimeBudget 计时器", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());
@@ -413,7 +421,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
     // 已耗 70%（3500ms）→ 剩余 1500ms；fake Date 冻结，elapsed 精确
     run.meta.startedAt = new Date(Date.now() - 3500).toISOString();
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());
@@ -429,7 +437,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 });
     // 已耗 6000ms > 预算 5000ms（退避 advance 1000ms 后已耗 7000ms，仍耗尽）
     run.meta.startedAt = new Date(Date.now() - 6000).toISOString();
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     const p = handleScriptError(run, "boom", [], deps, makeHandlers());
@@ -452,7 +460,7 @@ describe("race-F3: rebuild 时间预算折算", () => {
 
   it("预算未耗尽（fresh run）→ 照常 rebuild，不误转 time_limited（防误伤回归）", async () => {
     const run = makeRunningRun({ budgetTimeMs: 5000 }); // startedAt ≈ now，remaining 满
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     const p = handleScriptError(run, "boom", [], deps, makeHandlers());
@@ -745,7 +753,7 @@ describe("rebuildRuntime 可观察性（OB3 日志点）", () => {
 
   it("U7: 带 budgetTimeMs + scheduleTimeBudget 注入时含 L2（在 L1 之后、L3 之前，payload 含 budgetTimeMs）", () => {
     const run = makeRealRun("wf-rebuild-log-2", { budgetTimeMs: 5000 });
-    const scheduleTimeBudget = vi.fn(() => undefined);
+    const scheduleTimeBudget = vi.fn((_runId: string, _budgetTimeMs: number) => undefined);
     const deps = makeDeps({ scheduleTimeBudget });
 
     rebuildRuntime(run, deps, makeHandlers());

package/src/orchestration/__tests__/{error-recovery-postmessage-defense.test.ts → worker-message-pump-postmessage-defense.test.ts}

@@ -1,4 +1,4 @@
-// src/orchestration/__tests__/error-recovery-postmessage-defense.test.ts
+// src/orchestration/__tests__/worker-message-pump-postmessage-defense.test.ts
 //
 // W2: 主线程层 postMessage 防御测试。
 //
@@ -35,13 +35,13 @@ vi.mock("../../core/logger.ts", () => ({
   getLogger: () => loggerMock,
 }));
 
-import { handleWorkerMessage, postBudgetUpdate } from "../error-recovery.ts";
+import { handleWorkerMessage, postBudgetUpdate } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const ERROR_RECOVERY_SRC = readFileSync(
-  join(__dirname, "../error-recovery.ts"),
+const WORKER_MESSAGE_PUMP_SRC = readFileSync(
+  join(__dirname, "../worker-message-pump.ts"),
   "utf-8",
 );
 
@@ -273,7 +273,7 @@ describe("W2b: dispatchWorkflowCall postResult 防御 DataCloneError", () => {
 // 子进程）。利用这一点构造行为测试——往 cached.result 里塞不可克隆值（function），
 // mock postMessage 在首次发送 agent-result 时抛 DataCloneError，验证 fallback 路径。
 //
-// 另外补充：验证 error-recovery.ts 源码中三处 postMessage 调用点都有 try/catch 包裹，
+// 另外补充：验证 worker-message-pump.ts 源码中三处 postMessage 调用点都有 try/catch 包裹，
 // 防止未来重构误删防御（类似 worker-script-builder.test.ts 的源码字符串断言模式）。
 
 /** 构造 status="running" 且 calls 已含一个 done 结果（含不可克隆成员）的 mock run。
@@ -376,7 +376,7 @@ describe("W2c: postAgentResult 防御（源码结构断言）", () => {
   }
 
   it("postAgentResult 包含 try/catch + fallback result", () => {
-    const match = ERROR_RECOVERY_SRC.match(/function postAgentResult\([\s\S]*?\n\}/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/function postAgentResult\([\s\S]*?\n\}/);
     expect(match, "postAgentResult 函数定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
     // fallback 通过共享工厂 makeSerializeFailedResult 构造纯字符串 result（必可克隆）
@@ -387,14 +387,14 @@ describe("W2c: postAgentResult 防御（源码结构断言）", () => {
   });
 
   it("postBudgetUpdate 包含 try/catch", () => {
-    const match = ERROR_RECOVERY_SRC.match(/export function postBudgetUpdate\([\s\S]*?\n\}/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/export function postBudgetUpdate\([\s\S]*?\n\}/);
     expect(match, "postBudgetUpdate 函数定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
   });
 
   it("dispatchWorkflowCall postResult 闭包包含 try/catch + fallback", () => {
     // postResult 是 const 闭包，匹配到下一个 }; 结尾
-    const match = ERROR_RECOVERY_SRC.match(/const postResult = \(result[\s\S]*?\n  \};/);
+    const match = WORKER_MESSAGE_PUMP_SRC.match(/const postResult = \(result[\s\S]*?\n  \};/);
     expect(match, "postResult 闭包定义应存在").toBeTruthy();
     expect(hasTryCatchAroundPostMessage(match![0])).toBe(true);
     expect(match![0]).toContain("Workflow result serialization failed");

package/src/orchestration/__tests__/{error-recovery-serialize-failed-result.test.ts → worker-message-pump-serialize-failed-result.test.ts}

@@ -1,4 +1,4 @@
-// src/orchestration/__tests__/error-recovery-serialize-failed-result.test.ts
+// src/orchestration/__tests__/worker-message-pump-serialize-failed-result.test.ts
 //
 // makeSerializeFailedResult 独立单测（W2 防御关键纯函数）。
 //
@@ -15,7 +15,7 @@
 
 import { describe, expect, it } from "vitest";
 
-import { makeSerializeFailedResult } from "../error-recovery.ts";
+import { makeSerializeFailedResult } from "../worker-message-pump.ts";
 
 describe("makeSerializeFailedResult", () => {
   it("返回 {content:'', error:'<prefix>: <errMsg>'} 形状（必可克隆 fallback）", () => {

package/src/orchestration/__tests__/{error-recovery-workflow-call.test.ts → worker-message-pump-workflow-call.test.ts}

@@ -10,7 +10,7 @@
  */
 import { describe, expect, it, vi } from "vitest";
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import type { LifecycleDeps, WorkerHandlers } from "../models/ports.ts";
 import type { WorkflowRun } from "../models/workflow-run.ts";
 

package/src/orchestration/__tests__/worker-pending-timeout-abort.test.ts

@@ -105,7 +105,7 @@ function runWorker(userScript: string, opts: RunOptions = {}): Promise<RunResult
     worker.on("message", (raw: unknown) => {
       if (isAgentCall(raw)) {
         result.agentCallCount += 1;
-        opts.onAgentCall?.(raw as { callId: number; opts: Record<string, unknown> }, worker);
+        opts.onAgentCall?.(raw as unknown as { callId: number; opts: Record<string, unknown> }, worker);
         return;
       }
       if (isReturn(raw)) {

package/src/orchestration/__tests__/worker-script-builder.test.ts

@@ -225,7 +225,7 @@ describe("buildWorkerScript — W2 agent() returnMeta mode", () => {
 // ── thinkingLevel 参数透传（agent() 三分支） ──
 // 验证 thinkingLevel 在 string / task-agent / object.prompt 三个分支均被透传至
 // agent-call 的 opts，且加入 _knownFields 白名单（object.prompt 分支整体透传，
-// 不被 unknown-fields warn 误报）。底层 AgentCallOpts→mapToExecuteOptions→
+// 不被 unknown-fields warn 误报）。底层 AgentCallOpts（D6 合流后 EnginePort 直传，
 // buildSpawnArgs 拼 pi CLI --model provider/modelId:thinkingLevel 已打通，
 // 此处只验入口层 wiring。
 

package/src/orchestration/__tests__/workflow-nesting-e2e.test.ts

@@ -24,7 +24,7 @@ vi.mock("../lifecycle.ts", () => ({
   scheduleTimeBudget: vi.fn(() => undefined),
 }));
 
-import { handleWorkerMessage } from "../error-recovery.ts";
+import { handleWorkerMessage } from "../worker-message-pump.ts";
 import { executeNestedWorkflow, type LauncherDeps } from "../launcher.ts";
 import { runWorkflow } from "../lifecycle.ts";
 import { Budget } from "../models/budget.ts";

package/src/orchestration/agent-opts-resolver.ts

@@ -10,7 +10,7 @@
  * agent ref 处理（systemPrompt/model/thinkingLevel）已移交 resolveIdentity（execution 层，
  * 经 getAgentConfig + resolveModel 完整覆盖），消除双重注入与 model 层级混乱。
  *
- * 调用方：engine/error-recovery.ts dispatchAgentCall（每次 agent-call 消息）。
+ * 调用方：engine/worker-message-pump.ts dispatchAgentCall（每次 agent-call 消息）。
  * - skill → resolveSkillPath → skillPath（--skill）
  * - schema → 结构化输出指令内容直传 appendSystemPrompt（--append-system-prompt）+ schemaEnv（PI_WORKFLOW_SCHEMA）
  *

package/src/orchestration/args-validator.ts

@@ -58,6 +58,57 @@ function formatMessage(name: string, errors: readonly unknown[]): string {
   );
 }
 
+// ── validateRunArgs 阶段 helper（按 预处理/编译 提取，主函数只留编排） ────
+
+/** schema.properties 提取（畸形/缺失 → {}，null-scan 在空 properties 上安全退化）。 */
+function extractSchemaProperties(schema: Record<string, unknown>): Record<string, unknown> {
+  return schema.properties !== null && typeof schema.properties === "object"
+    ? (schema.properties as Record<string, unknown>)
+    : {};
+}
+
+/** 单个 property 声明是否 nullable（type 含 "null" 或 type === "null"）。 */
+function isNullableProp(prop: unknown): boolean {
+  if (prop === null || typeof prop !== "object") return false;
+  const propType = (prop as Record<string, unknown>).type;
+  return Array.isArray(propType)
+    ? (propType as unknown[]).includes("null")
+    : propType === "null";
+}
+
+/**
+ * null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
+ * 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
+ * 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
+ */
+function deleteNonNullableNullArgs(
+  args: Record<string, unknown>,
+  schema: Record<string, unknown>,
+): void {
+  const properties = extractSchemaProperties(schema);
+  for (const key of Object.keys(args)) {
+    if (args[key] !== null) continue;
+    if (!isNullableProp(properties[key])) delete args[key];
+  }
+}
+
+/** ajv 编译（畸形 schema → 结构化 ArgsValidationError，不泄漏原始 throw）。 */
+function compileSchema(
+  parameters: Record<string, unknown>,
+  scriptName: string,
+): ReturnType<Ajv["compile"]> {
+  try {
+    return ajv.compile(parameters);
+  } catch (err) {
+    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ArgsValidationError(
+      scriptName,
+      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
+    );
+  }
+}
+
 /**
  * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
  *
@@ -79,38 +130,9 @@ export function validateRunArgs(spec: RunSpec): void {
     );
   }
 
-  // null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
-  // 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
-  // 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
-  const schema = parameters as Record<string, unknown>;
-  const properties =
-    schema.properties !== null && typeof schema.properties === "object"
-      ? (schema.properties as Record<string, unknown>)
-      : {};
-  for (const key of Object.keys(args)) {
-    if (args[key] !== null) continue;
-    const prop = properties[key];
-    let isNullable = false;
-    if (prop !== null && typeof prop === "object") {
-      const propType = (prop as Record<string, unknown>).type;
-      isNullable = Array.isArray(propType)
-        ? (propType as unknown[]).includes("null")
-        : propType === "null";
-    }
-    if (!isNullable) delete args[key];
-  }
+  deleteNonNullableNullArgs(args, parameters);
 
-  let validate: ReturnType<Ajv["compile"]>;
-  try {
-    validate = ajv.compile(parameters);
-  } catch (err) {
-    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
+  const validate = compileSchema(parameters, scriptName);
 
   if (!validate(args)) {
     throw new ArgsValidationError(