@zhushanwen/subagent-core 0.2.0

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

@@ -0,0 +1,309 @@
+/**
+ * buildWorkerScript — workflow() 全局函数注入测试。
+ *
+ * 验证生成的 worker 源码字符串包含 workflow 嵌套调用所需的全部契约：
+ * - workflow() 全局函数声明
+ * - workflow-call 消息（Worker → Main）
+ * - workflow-result 消息处理（Main → Worker）
+ * - execute() context 包含 workflow
+ * - name 参数校验
+ */
+import { describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+describe("buildWorkerScript — workflow() global injection", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("injects workflow() global function", () => {
+    expect(script).toContain("async function workflow");
+  });
+
+  it('workflow() sends workflow-call message', () => {
+    expect(script).toContain('type: "workflow-call"');
+  });
+
+  it('handles workflow-result message', () => {
+    // worker 是 workflow-result 的接收方，用条件分支处理（非对象字面量）
+    expect(script).toContain('msg.type === "workflow-result"');
+  });
+
+  it("execute() context includes workflow", () => {
+    expect(script).toContain(
+      "module.exports.execute({ agent, parallel, pipeline, phase, log, workflow, $ARGS, $WORKSPACE, $BUDGET })",
+    );
+  });
+
+  it("workflow() validates name argument", () => {
+    expect(script).toContain(
+      "workflow() requires a workflow name string as first argument",
+    );
+  });
+});
+
+// ── H3: agent() task/agent 分支 skill 字段传递 ──
+
+describe("buildWorkerScript — agent() skill field in task/agent branch", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("task/agent branch includes skill in opts whitelist", () => {
+    // H3: agent({task, agent, skill}) 的 skill 在 task/agent 分支被丢弃。
+    // 验证生成的 worker 源码中，task/agent 分支的 opts 构造含 skill 字段。
+    // 找到 task/agent 分支的 opts 构造代码（含 firstArg.task || firstArg.agent）
+    const taskAgentBranch = script.match(/firstArg\.task \|\| firstArg\.agent[\s\S]*?\};/);
+    expect(taskAgentBranch).toBeTruthy();
+    expect(taskAgentBranch![0]).toContain("skill: firstArg.skill");
+  });
+});
+
+// ── W1: postMessage 防御 + parallel() 降级类型安全 ──
+
+describe("buildWorkerScript — W1 postMessage defense & parallel degrade", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  describe("_safePost wrapper", () => {
+    it("injects _safePost function", () => {
+      expect(script).toContain("function _safePost(msg, context)");
+    });
+
+    it("_safePost wraps postMessage in try/catch", () => {
+      // _safePost 在 module scope（parentPort 解析为 _parentPort），
+      // 用宽松正则匹配「try { <something>.postMessage(msg)」避免绑死变量名。
+      expect(script).toMatch(/_safePost[\s\S]*?try \{ _parentPort\.postMessage\(msg\)/);
+    });
+
+    it("_safePost logs failure with context to workerLogs", () => {
+      expect(script).toContain('_pushWorkerLog("error"');
+      expect(script).toContain('"[postMessage failed:" + context + "]"');
+    });
+  });
+
+  describe("agent() uses _safePost", () => {
+    it("agent-call postMessage guarded by _safePost", () => {
+      expect(script).toContain("_safePost({ type: \"agent-call\"");
+      expect(script).toContain('"agent-call"');
+    });
+
+    it("agent() throws on postMessage failure", () => {
+      expect(script).toContain("postMessage failed for agent-call");
+    });
+  });
+
+  describe("workflow() uses _safePost", () => {
+    it("workflow-call postMessage guarded by _safePost", () => {
+      expect(script).toContain("_safePost({ type: \"workflow-call\"");
+    });
+  });
+
+  describe("return/error use _safePost", () => {
+    it("return postMessage uses _safePost", () => {
+      expect(script).toContain('_safePost({ type: "return"');
+    });
+
+    it("error postMessage uses _safePost", () => {
+      expect(script).toContain('_safePost({ type: "error"');
+    });
+  });
+
+  describe("parallel() degrade returns object", () => {
+    it("rejected results become {status:failed,error} objects", () => {
+      expect(script).toContain('status: "failed"');
+      expect(script).toMatch(/parallel[\s\S]*?status: "failed"/);
+    });
+
+    it("non-object fulfilled values wrapped as failed", () => {
+      expect(script).toContain("agent returned non-object result");
+    });
+
+    it("object fulfilled values pass through unchanged", () => {
+      expect(script).toContain("!Array.isArray(v)");
+    });
+  });
+
+  describe("pipeline() error observability", () => {
+    it("single-arg mode logs stage errors before re-throwing", () => {
+      expect(script).toContain("[pipeline stage ");
+      expect(script).toContain("_pushWorkerLog(\"error\"");
+    });
+
+    it("cartesian mode logs stage errors instead of silent swallow", () => {
+      expect(script).toContain("[pipeline cartesian stage failed");
+    });
+  });
+});
+
+// ── W2: agent() returnMeta 模式 ──
+// 验证 returnMeta 标志：known fields 放行 + handler resolve 分支 + 缓存重放分支，
+// 且两处分支结构对称（returnMeta===true → {value, sessionFile, worktreePath, error}）。
+
+describe("buildWorkerScript — W2 agent() returnMeta mode", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  describe("returnMeta known field whitelist", () => {
+    it("includes returnMeta in _knownFields Set", () => {
+      expect(script).toContain('"returnMeta"');
+    });
+
+    it("includes returnMeta in unknown-fields warning text", () => {
+      expect(script).toContain("cwd, fork, worktree, returnMeta");
+    });
+
+    it("does NOT warn about returnMeta when only returnMeta is passed (parity with fork/worktree)", () => {
+      // fork/worktree 已是 known fields；returnMeta 加入后不应触发 warn 文案中的 returnMeta。
+      // 简化断言：warning 文案里 Known 列表含 returnMeta（即被识别）。
+      expect(script).toMatch(/Known fields:.*returnMeta/);
+    });
+  });
+
+  describe("_pendingCalls stores returnMeta flag", () => {
+    it("stores returnMeta: opts.returnMeta === true in _pendingCalls.set", () => {
+      expect(script).toContain(
+        "returnMeta: opts.returnMeta === true",
+      );
+    });
+  });
+
+  describe("agent-result handler resolve branch (改动 9b)", () => {
+    it("branches on pending.returnMeta", () => {
+      expect(script).toContain("if (pending.returnMeta)");
+    });
+
+    it("resolve branch returns {value, sessionFile, worktreePath, error}", () => {
+      const handlerBlock = script.match(
+        /if \(pending\.returnMeta\) \{[\s\S]*?\} else \{[\s\S]*?pending\.resolve\(_value\);[\s\S]*?\}/,
+      );
+      expect(handlerBlock).toBeTruthy();
+      expect(handlerBlock![0]).toContain("value: _value");
+      expect(handlerBlock![0]).toContain("sessionFile: msg.result.sessionFile");
+      expect(handlerBlock![0]).toContain("worktreePath: msg.result.worktreePath");
+      expect(handlerBlock![0]).toContain("error: msg.result.error");
+    });
+
+    it("fallback resolve single value uses msg.result.parsedOutput ?? msg.result.content", () => {
+      expect(script).toContain(
+        "const _value = msg.result.parsedOutput ?? msg.result.content;",
+      );
+    });
+  });
+
+  describe("cache replay returnMeta branch (改动 9c)", () => {
+    it("early-returns undefined when !cached", () => {
+      expect(script).toContain("if (!cached) return undefined;");
+    });
+
+    it("branches on opts.returnMeta === true", () => {
+      expect(script).toContain("if (opts.returnMeta === true)");
+    });
+
+    it("cache replay returns {value, sessionFile, worktreePath, error} from cached", () => {
+      const cacheBlock = script.match(
+        /if \(opts\.returnMeta === true\) \{[\s\S]*?return _cachedValue;/,
+      );
+      expect(cacheBlock).toBeTruthy();
+      expect(cacheBlock![0]).toContain("value: _cachedValue");
+      expect(cacheBlock![0]).toContain("sessionFile: cached.sessionFile");
+      expect(cacheBlock![0]).toContain("worktreePath: cached.worktreePath");
+      expect(cacheBlock![0]).toContain("error: cached.error");
+    });
+
+    it("cache replay fallback uses cached.parsedOutput ?? cached.content", () => {
+      expect(script).toContain(
+        "const _cachedValue = cached.parsedOutput ?? cached.content;",
+      );
+    });
+  });
+
+  describe("handler (9b) and cache replay (9c) branch symmetry", () => {
+    it("both expose worktreePath field (CL-1/DEC-2 core)", () => {
+      // handler 读 msg.result.worktreePath；cache replay 读 cached.worktreePath。
+      expect(script).toContain("msg.result.worktreePath");
+      expect(script).toContain("cached.worktreePath");
+    });
+  });
+});
+
+// ── thinkingLevel 参数透传（agent() 三分支） ──
+// 验证 thinkingLevel 在 string / task-agent / object.prompt 三个分支均被透传至
+// agent-call 的 opts，且加入 _knownFields 白名单（object.prompt 分支整体透传，
+// 不被 unknown-fields warn 误报）。底层 AgentCallOpts→mapToExecuteOptions→
+// buildSpawnArgs 拼 pi CLI --model provider/modelId:thinkingLevel 已打通，
+// 此处只验入口层 wiring。
+
+describe("buildWorkerScript — agent() thinkingLevel passthrough (3 branches)", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("string branch extracts thinkingLevel from secondArg (parity with model/scene/phase)", () => {
+    // agent("prompt", {thinkingLevel:"high"}) → string 分支 opts 提取 thinkingLevel
+    const stringBranch = script.match(/typeof firstArg === "string"[\s\S]*?\};/);
+    expect(stringBranch).toBeTruthy();
+    expect(stringBranch![0]).toContain(
+      "thinkingLevel: (secondArg && typeof secondArg === \"object\" && secondArg.thinkingLevel) || $THINKING_LEVEL",
+    );
+  });
+
+  it("task/agent branch includes thinkingLevel in opts (parity with model/skill/timeoutMs)", () => {
+    // agent({task, agent, thinkingLevel}) → task/agent 快捷分支透传 thinkingLevel
+    const taskAgentBranch = script.match(/firstArg\.task \|\| firstArg\.agent[\s\S]*?\};/);
+    expect(taskAgentBranch).toBeTruthy();
+    expect(taskAgentBranch![0]).toContain("thinkingLevel: firstArg.thinkingLevel");
+  });
+
+  it("thinkingLevel is a known field (object.prompt branch passes through without unknown-fields warn)", () => {
+    // object.prompt 分支 opts = firstArg 整体透传，thinkingLevel 自然带入；
+    // 但必须进 _knownFields 白名单，否则 Object.keys(opts) 含 thinkingLevel 会触发
+    // unknown-fields warn（workerLogs 污染）。验证 Set 与 warn 文案均识别 thinkingLevel。
+    expect(script).toContain('"thinkingLevel"');
+    expect(script).toMatch(/Known fields:.*thinkingLevel/);
+  });
+});
+
+// ── P3/P4: run-level model/thinkingLevel override global injection ──
+// Option B 对称单路径：workflow 顶层 model/thinkingLevel 经 workerData →
+// $MODEL/$THINKING_LEVEL worker global → agent() 三分支 fallback。
+// 验证生成的 worker 源码字符串包含 global 注入与三分支 fallback 逻辑。
+// 运行时真生效需 worker 集成 harness（设计文档 §6 降级为源码字符串断言）。
+
+describe("P3/P4 run-level model/thinkingLevel global injection + agent() fallback", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("injects $MODEL global from workerData.model", () => {
+    expect(script).toContain('const $MODEL = (workerData.model && typeof workerData.model === "string") ? workerData.model : undefined;');
+  });
+
+  it("injects $THINKING_LEVEL global from workerData.thinkingLevel", () => {
+    expect(script).toContain('const $THINKING_LEVEL = (workerData.thinkingLevel && typeof workerData.thinkingLevel === "string") ? workerData.thinkingLevel : undefined;');
+  });
+
+  it("string branch falls back to $MODEL when secondArg.model omitted", () => {
+    const stringBranch = script.match(/typeof firstArg === "string"[\s\S]*?\};/);
+    expect(stringBranch).toBeTruthy();
+    expect(stringBranch![0]).toContain('secondArg.model) || $MODEL');
+  });
+
+  it("string branch falls back to $THINKING_LEVEL when secondArg.thinkingLevel omitted", () => {
+    const stringBranch = script.match(/typeof firstArg === "string"[\s\S]*?\};/);
+    expect(stringBranch).toBeTruthy();
+    expect(stringBranch![0]).toContain('secondArg.thinkingLevel) || $THINKING_LEVEL');
+  });
+
+  it("task/agent branch falls back to $MODEL when firstArg.model omitted", () => {
+    const taskAgentBranch = script.match(/firstArg\.task \|\| firstArg\.agent[\s\S]*?\};/);
+    expect(taskAgentBranch).toBeTruthy();
+    expect(taskAgentBranch![0]).toContain('model: firstArg.model || $MODEL');
+  });
+
+  it("task/agent branch falls back to $THINKING_LEVEL when firstArg.thinkingLevel omitted", () => {
+    const taskAgentBranch = script.match(/firstArg\.task \|\| firstArg\.agent[\s\S]*?\};/);
+    expect(taskAgentBranch).toBeTruthy();
+    expect(taskAgentBranch![0]).toContain('thinkingLevel: firstArg.thinkingLevel || $THINKING_LEVEL');
+  });
+
+  it("object branch injects $MODEL when opts.model omitted (guard fallback)", () => {
+    expect(script).toContain('if (!opts.model && $MODEL) opts.model = $MODEL;');
+  });
+
+  it("object branch injects $THINKING_LEVEL when opts.thinkingLevel omitted (guard fallback)", () => {
+    expect(script).toContain('if (!opts.thinkingLevel && $THINKING_LEVEL) opts.thinkingLevel = $THINKING_LEVEL;');
+  });
+});
+

package/src/orchestration/__tests__/worker-script-template-snapshot.test.ts

@@ -0,0 +1,129 @@
+/**
+ * buildWorkerScript 模板 hoisting（IF5/IF6）— byte-identical 快照锚定。
+ *
+ * ES8：快照先行——fixture 由「改造前实现」生成落盘（本文件同 commit），
+ * 断言重构后输出与 fixture 逐字节一致，锁定 PRE/POST 边界换行与 userScript
+ * 缩进语义（AC-4「逐字保留」不变式）。IF6（_KNOWN_FIELDS 提升至生成源
+ * module scope）落地时基线已按设计在同一 commit 内更新为最终形态。
+ *
+ * 样例脚本覆盖 $ARGS / schema / parallel / pipeline / workflow / phase / log 特性。
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { buildWorkerScript } from "../worker-script-builder.ts";
+
+const sampleScript = [
+  "// sample exercising template features",
+  'const name = $ARGS.name ?? "default";',
+  'phase("build");',
+  'const spec = await agent("build it", { label: "builder", schema: { type: "object" } });',
+  "const results = await parallel([",
+  '  agent({ task: "unit tests", agent: "./tester.md" }),',
+  '  agent({ task: "lint", agent: "./linter.md", skill: "lint-skill" }),',
+  "]);",
+  "await pipeline([(x) => x, (x) => x]);",
+  'await workflow("deploy", { env: "prod" });',
+  'log("done " + name + " " + $WORKSPACE + " " + $BUDGET.remaining());',
+  "module.exports = { execute: async (ctx) => ctx.agent(\"finalize\") };",
+].join("\n");
+
+function loadFixture(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return readFileSync(join(here, "__fixtures__", "worker-template.snapshot.txt"), "utf8");
+}
+
+describe("buildWorkerScript — 模板 hoisting byte-identical 快照（IF5）", () => {
+  it("特性全量样例的输出与 fixture 逐字节一致", () => {
+    const out = buildWorkerScript(sampleScript);
+    expect(out).toBe(loadFixture());
+  });
+
+  it("首尾边界锚定：use strict 开头 + error handler 结尾 + userScript 缩进注入", () => {
+    const out = buildWorkerScript(sampleScript);
+    // PRE 边界：第一行 use strict（无前导换行）
+    expect(out.startsWith('"use strict";\n')).toBe(true);
+    // userScript 段：两空格缩进注入（AC-4 拼接语义）
+    expect(out).toContain("\n  // sample exercising template features\n");
+    // userScript 段结束后一个空行再接 auto-invoke 段（POST 首部换行语义）
+    expect(out).toContain("ctx.agent(\"finalize\") };\n\n  // ── Auto-invoke execute() for module.exports pattern ──");
+    // POST 边界：以 error handler 的 "});" 结尾（无尾随换行）
+    expect(out.endsWith('_safePost({ type: "error", runId, error: err.message || String(err), workerLogs: _workerLogs }, "error");\n});')).toBe(true);
+  });
+
+  it("空 userScript 与任意脚本的拼接语义稳定（PRE/POST 不含 userScript 状态）", () => {
+    const a = buildWorkerScript("x");
+    const b = buildWorkerScript("y");
+    // 除 userScript 段外完全一致：以 userScript 行为界切割比对
+    const [preA] = a.split("\n  x\n");
+    const [preB] = b.split("\n  y\n");
+    expect(preA).toBe(preB);
+  });
+
+  it("A8 rfl 仪表透传字段字面量锚定（tier-1 §7.1）：live resolve 与缓存重放两对称点均含三字段", () => {
+    const out = buildWorkerScript("// noop");
+    // live resolve 分支（agent-result 消息处理）
+    expect(out).toContain("usage: msg.result.usage,");
+    expect(out).toContain("durationMs: msg.result.durationMs,");
+    expect(out).toContain("sessionId: msg.result.sessionId,");
+    // 缓存重放分支（_callCache 命中重建，对称点）
+    expect(out).toContain("usage: cached.usage,");
+    expect(out).toContain("durationMs: cached.durationMs,");
+    expect(out).toContain("sessionId: cached.sessionId,");
+  });
+});
+
+describe("buildWorkerScript — _KNOWN_FIELDS module scope 提升（IF6）", () => {
+  const script = buildWorkerScript("// noop user script");
+
+  it("生成源含 module 级 _KNOWN_FIELDS 声明（与 _workerLogs 同级，IIFE 外）", () => {
+    // 声明在 IIFE 开始之前（module scope）：const _KNOWN_FIELDS 必须出现在 "(async () => {" 前
+    const iifePos = script.indexOf("(async () => {");
+    const knownPos = script.indexOf("const _KNOWN_FIELDS = new Set([");
+    expect(knownPos).toBeGreaterThan(-1);
+    expect(knownPos).toBeLessThan(iifePos);
+    // 紧随 _workerLogs 声明之后（design IF6：与 _workerLogs/:62 同级）
+    expect(script.indexOf("const _workerLogs = [];")).toBeLessThan(knownPos);
+  });
+
+  it("agent() 体内不再重建 Set（引用 _KNOWN_FIELDS，无 new Set）", () => {
+    // agent() 函数体（到 parallel 声明前）内不得有 new Set 构造
+    const agentPos = script.indexOf("async function agent(firstArg, secondArg)");
+    const parallelPos = script.indexOf("async function parallel(calls)");
+    expect(agentPos).toBeGreaterThan(-1);
+    expect(parallelPos).toBeGreaterThan(agentPos);
+    const agentBody = script.slice(agentPos, parallelPos);
+    expect(agentBody).not.toContain("new Set(");
+    expect(agentBody).toContain("_KNOWN_FIELDS.has(k)");
+  });
+
+  it("字段集合内容逐字段一致（18 known fields 不丢失——P4 增 engine，预算语义对齐增 maxTurns）", () => {
+    expect(script).toContain(
+      'const _KNOWN_FIELDS = new Set(["prompt", "description", "schema", "model", "scene", "label", "task", "agent", "phase", "skill", "timeoutMs", "maxTurns", "cwd", "fork", "worktree", "returnMeta", "thinkingLevel", "engine"]);',
+    );
+    // unknown-fields 警告文案不变（known 列表仍全量）
+    expect(script).toMatch(/Known fields:.*returnMeta.*thinkingLevel.*engine/);
+  });
+
+  it("agent() 各分支均透传 maxTurns（预算语义对齐：脚本作者可显式传 turn 上限）", () => {
+    // task/agent shortcut 分支：显式转发
+    expect(script).toContain("maxTurns: firstArg.maxTurns,");
+    // string+secondArg 分支：显式转发（?? 语义保真：显式 0 不被抹成 undefined，F-2/U5）
+    expect(script).toContain(
+      'maxTurns: (secondArg && typeof secondArg === "object" ? secondArg.maxTurns : undefined) ?? undefined,',
+    );
+    // opts = firstArg 直传分支无需处理（整对象透传）
+  });
+
+  // [F-2 maxTurns:0 吞没修复] 旧字符串分支 `&& maxTurns) || undefined` 把显式 0
+  // 抹成 undefined → runSpawn 落 env 兑底（SPAWN_WATCHDOG env 设置时误挂 watchdog），
+  // 与对象分支保真语义分裂。锁定生成源为 ?? 形态（0/null/undefined 区分处理）。
+  it("string 分支 maxTurns 用 ?? 语义（显式 0 不抹成 undefined，F-2）", () => {
+    const out = buildWorkerScript("// noop");
+    expect(out).not.toContain('secondArg.maxTurns) || undefined');
+    expect(out).toContain("?? undefined");
+  });
+});