@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/execution/engine/__tests__/common/capability-gate.test.ts

@@ -0,0 +1,91 @@
+// capability-gate.test.ts —— [D3-④ 预检 capabilities 化] 拦截矩阵单测。
+// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-④（r3 裁定：
+// EngineCapabilities +maxTurns 位 pi=true/zcode=false，不保留硬编码 shape 检查）+
+// §3.4 错误规格第 1 行 + §4 V4④⑤（正反向验收）。
+//
+// 覆盖（构建者白盒 + 使用者黑盒）：
+//   1. per-engine 拦截矩阵：pi 全放行（含 maxTurns/fork/conversation/worktree——V4⑤
+//      反向守护，pi 既有合法能力零拦截）；zcode 四参数全拦（fork/conversation/
+//      maxTurns/worktree）
+//   2. 错误族：engine_capability_unsupported + recovery 含可操作指引（换参数/换引擎）
+//   3. fork 判据（借位裁定）：session 分叉通道族任一可用即放行——pi conversation=
+//      native 放行（steer 虽 unsupported 不参与否决）；通道族全缺才拦
+
+import { describe, expect, it } from "vitest";
+
+import { assertTaskShapeSupported, type TaskShapeForGate } from "../../common/capability-gate.ts";
+import { EngineError } from "../../common/errors.ts";
+import type { EngineCapabilities } from "../../types.ts";
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+
+/** 真实引擎的 capabilities 面单测直取（D3 声明是判据本体——pi=true/zcode=false 扩位）。 */
+const PI_CAPS = new PiEngine({ getService: () => null }).capabilities();
+const ZCODE_CAPS = new ZcodeEngine({ engineDataDir: () => "/tmp/zcode-gate" }).capabilities();
+
+/** 会话分叉通道族可用的 zcode 形态变体（fork 判据用）。 */
+const ZCODE_CAPS_WITH_CONVERSATION: EngineCapabilities = { ...ZCODE_CAPS, conversation: "native" };
+
+function gate(
+  caps: EngineCapabilities,
+  task: TaskShapeForGate,
+  engineId = "zcode",
+): void {
+  assertTaskShapeSupported(engineId, caps, task);
+}
+
+function gateError(caps: EngineCapabilities, task: TaskShapeForGate, engineId = "zcode"): EngineError {
+  try {
+    gate(caps, task, engineId);
+  } catch (err) {
+    expect(err).toBeInstanceOf(EngineError);
+    return err as EngineError;
+  }
+  throw new Error("expected assertTaskShapeSupported to throw");
+}
+
+describe("capability-gate（D3-④ 拦截矩阵）", () => {
+  it("能力位声明：pi maxTurns=true、zcode maxTurns=false（r3 扩位裁定）", () => {
+    expect(PI_CAPS.maxTurns).toBe(true);
+    expect(ZCODE_CAPS.maxTurns).toBe(false);
+  });
+
+  it("[V4⑤ 反向] pi 引擎全参数放行：maxTurns/fork/forkFromSessionFile/conversation/worktree 零拦截", () => {
+    expect(() =>
+      gate(PI_CAPS, { maxTurns: 3, fork: true, conversation: true, worktree: true }, "pi"),
+    ).not.toThrow();
+    expect(() => gate(PI_CAPS, { forkFromSessionFile: "/tmp/sess.jsonl", worktree: { path: "/tmp/wt" } }, "pi")).not.toThrow();
+  });
+
+  it("[V4④ 正向] zcode 引擎四参数全拦：fork/conversation/maxTurns/worktree → engine_capability_unsupported", () => {
+    const cases: Array<[TaskShapeForGate, RegExp]> = [
+      [{ fork: true }, /不支持 fork/],
+      [{ forkFromSessionFile: "/tmp/sess.jsonl" }, /fork-from 同为父 session 上下文继承/],
+      [{ conversation: true }, /不支持 conversation/],
+      [{ maxTurns: 10 }, /不支持 maxTurns/],
+      [{ worktree: true }, /不支持 worktree 隔离/],
+      [{ worktree: { path: "/tmp/wt" } }, /不支持 worktree 隔离/],
+    ];
+    for (const [task, pattern] of cases) {
+      const err = gateError(ZCODE_CAPS, task);
+      expect(err.code).toBe("engine_capability_unsupported");
+      expect(err.message).toMatch(pattern);
+      expect(err.message).toContain("capabilities");
+      // 错误信息可操作（§3.4）：恢复指引指向换参数/换引擎
+      expect(err.recovery).toMatch(/engine: pi|不传|去掉/);
+    }
+  });
+
+  it("zcode 放行面：无能力参数的任务全放行；maxTurns undefined（未传）不拦", () => {
+    expect(() => gate(ZCODE_CAPS, {})).not.toThrow();
+    expect(() => gate(ZCODE_CAPS, { maxTurns: undefined, fork: false, conversation: false, worktree: false })).not.toThrow();
+  });
+
+  it("fork 判据（借位裁定）：session 分叉通道族任一可用即放行——conversation=native 的引擎 fork 放行", () => {
+    // pi 的 steer 声明 unsupported（spawn 链路未接通），fork 仍放行——通道族判定不因
+    // 单一通道缺失而误拦（上面 pi 用例已覆盖）。此处补 zcode 形态 + conversation 通道
+    // 可用的对照：fork 从拦截翻为放行。
+    expect(() => gate(ZCODE_CAPS_WITH_CONVERSATION, { fork: true })).not.toThrow();
+    expect(() => gate({ ...ZCODE_CAPS, steer: "native" }, { fork: true })).not.toThrow();
+  });
+});

package/src/execution/engine/__tests__/common/data-dir.test.ts

@@ -49,7 +49,7 @@ describe("getEngineDataDir", () => {
 
   it("缺 env → 回退宿主数据根（HostServices.dataRoot()，假宿主值）并 warn 一次", () => {
     const warnings: string[] = [];
-    const warn = (m: string): void => warnings.push(m);
+    const warn = (m: string): void => { warnings.push(m); };
     const dir1 = getEngineDataDir({}, warn);
     expect(dir1).toBe(FAKE_DATA_ROOT);
     expect(warnings.length).toBe(1);

package/src/execution/engine/__tests__/common/journal-wiring.test.ts

@@ -0,0 +1,84 @@
+// journal-wiring.test.ts —— [D3-③ journal 接线合一] host helper 单测（两域共用的
+// 唯一实现：writer 创建 + retarget + journaling onEvent + handle 回填 + close）。
+// 设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-③ + 双轨清单 #6。
+//
+// 覆盖：①占位池 key 初始路径与 retarget 后路径权威（getter 反映 retarget）；②先落盘
+// 再转发（forwardEvents）；③handle 回填写终态路径；④close 幂等不抛。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { JOURNAL_INITIAL_POOL_KEY, wireEventJournal } from "../../common/journal-wiring.ts";
+import { resolveJournalPath } from "../../paths.ts";
+import type { AgentEvent } from "../../types.ts";
+import type { EngineHandle } from "../../types.ts";
+
+let dataRoot: string;
+const PREV_DATA_DIR = process.env["XYZ_AGENT_DATA_DIR"];
+
+beforeEach(() => {
+  dataRoot = fs.mkdtempSync(path.join(os.tmpdir(), "journal-wiring-"));
+  process.env["XYZ_AGENT_DATA_DIR"] = dataRoot;
+});
+
+afterEach(() => {
+  if (PREV_DATA_DIR === undefined) delete process.env["XYZ_AGENT_DATA_DIR"];
+  else process.env["XYZ_AGENT_DATA_DIR"] = PREV_DATA_DIR;
+  fs.rmSync(dataRoot, { recursive: true, force: true });
+});
+
+function makeHandle(): EngineHandle {
+  return { data: { v: 1, engineId: "zcode", sessionRef: {}, poolKey: "p-m1", adapterVersion: "t" } };
+}
+
+describe("wireEventJournal（D3-③ host helper 唯一实现）", () => {
+  it("初始路径用占位池 key；onPoolResolved retarget 后 path getter 反映实际池 key（路径权威 = writer）", () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-1" });
+    expect(JOURNAL_INITIAL_POOL_KEY).toBe("shared");
+    expect(wiring.path).toBe(resolveJournalPath(dataRoot, "zcode", "shared", "sa-1"));
+    wiring.onPoolResolved("home-p-m1");
+    expect(wiring.path).toBe(resolveJournalPath(dataRoot, "zcode", "home-p-m1", "sa-1"));
+  });
+
+  it("journaling onEvent：先落盘再转发（forwardEvents 收到同一事件）", async () => {
+    const forwarded: AgentEvent[] = [];
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-2", forwardEvents: (e) => forwarded.push(e) });
+    wiring.onEvent({ type: "turn_end" });
+    wiring.onEvent({ type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } });
+    await wiring.close();
+    expect(forwarded.map((e) => e.type)).toEqual(["turn_end", "message_end"]);
+    // 落盘真实发生（close flush 后文件存在且行数吻合——先落盘语义由文件内容见证）
+    const lines = fs.readFileSync(wiring.path, "utf8").trim().split("\n");
+    expect(lines).toHaveLength(2);
+    expect(JSON.parse(lines[0]).taskId).toBe("sa-2");
+    expect(JSON.parse(lines[0]).engineId).toBe("zcode");
+  });
+
+  it("chat 域形态（无 forwardEvents）：事件只进 journal，不抛", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-3" });
+    wiring.onEvent({ type: "turn_end" });
+    await wiring.close();
+    expect(fs.existsSync(wiring.path)).toBe(true);
+  });
+
+  it("handle 回填：backfillHandle 写 retarget 后的终态路径（read ②级自描述定位符）", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-4" });
+    wiring.onPoolResolved("home-p-m1");
+    wiring.onEvent({ type: "turn_end" });
+    const handle = makeHandle();
+    wiring.backfillHandle(handle);
+    expect(handle.data.journalPath).toBe(resolveJournalPath(dataRoot, "zcode", "home-p-m1", "sa-4"));
+    await wiring.close();
+    expect(fs.existsSync(handle.data.journalPath!)).toBe(true);
+  });
+
+  it("close 幂等（重复调用不抛）；无事件任务不产生空 journal 文件", async () => {
+    const wiring = wireEventJournal({ engineId: "zcode", taskId: "sa-5" });
+    await wiring.close();
+    await expect(wiring.close()).resolves.toBeUndefined();
+    expect(fs.existsSync(wiring.path)).toBe(false);
+  });
+});

package/src/execution/engine/__tests__/common/kill-chain.test.ts

@@ -37,8 +37,8 @@ function makeFakeChild(): {
     child,
     signals,
     emitExit(code, signal) {
-      child.exitCode = code;
-      child.signalCode = signal;
+      (child as { exitCode: number | null }).exitCode = code;
+      (child as { signalCode: string | null }).signalCode = signal;
       for (const l of listeners.splice(0)) l(code, signal);
     },
   };
@@ -88,13 +88,40 @@ describe("killChain", () => {
   });
 });
 
+describe("killChain grace 参数化（D3-① 杀链合一：pi=30s / zcode=5s，现状语义逐字节保持）", () => {
+  it("pi 参数形态（graceMs=30s + unrefTimers + escalationNote）：29s 未升级，越 30s 窗口 SIGKILL", async () => {
+    const { child, signals } = makeFakeChild();
+    const p = killChain(child, {
+      graceMs: 30_000,
+      unrefTimers: true,
+      escalationNote: "child sa-x (source: spawn watchdog)",
+    });
+    expect(signals).toEqual(["SIGTERM"]); // SIGTERM 同步发出（信号序不变）
+    await vi.advanceTimersByTimeAsync(29_000);
+    expect(signals).toEqual(["SIGTERM"]); // 窗口内不升级（非贴边断言）
+    await vi.advanceTimersByTimeAsync(1_100); // 越过 30s 优雅窗口
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]); // 升级 SIGKILL（race-F4 语义）
+    await vi.advanceTimersByTimeAsync(10_000); // 有界收尸窗口
+    expect(await p).toBe("killed");
+  });
+
+  it("escalationNote 缺省（zcode 现状形态）：graceMs=5s 越窗 SIGKILL，升级路径同构", async () => {
+    const { child, signals } = makeFakeChild();
+    const p = killChain(child, { graceMs: 5_000 });
+    await vi.advanceTimersByTimeAsync(5_000);
+    expect(signals).toEqual(["SIGTERM", "SIGKILL"]);
+    await vi.advanceTimersByTimeAsync(10_000);
+    expect(await p).toBe("killed");
+  });
+});
+
 describe("synthesizeTimeoutOutcome", () => {
   it("合成 engine_timeout 终态：error 含 slug + stdout 尾部 + engine: pi 重跑建议；exitCode=null", () => {
     const outcome = synthesizeTimeoutOutcome(
-      { task: "review files", slug: "review-files" },
+      { prompt: "review files", description: "review-files" },
       "last stdout lines...",
     );
-    expect(outcome.error).toContain("engine_timeout");
+    expect(outcome.error!).toContain("engine_timeout");
     expect(outcome.error).toContain("review-files");
     expect(outcome.error).toContain("last stdout lines...");
     expect(outcome.error).toMatch(/`engine: pi`/);
@@ -105,13 +132,13 @@ describe("synthesizeTimeoutOutcome", () => {
 
   it("stdout 尾部超 2000 字截断；engineId 可指定", () => {
     const outcome = synthesizeTimeoutOutcome(
-      { task: "t", slug: "s" },
+      { prompt: "t", description: "s" },
       "y".repeat(3_000),
       "zcode",
     );
     expect(outcome.engineId).toBe("zcode");
-    expect(outcome.error).toContain("...");
-    expect(outcome.error.length).toBeLessThan(3_000);
+    expect(outcome.error!).toContain("...");
+    expect(outcome.error!.length).toBeLessThan(3_000);
   });
 });
 

package/src/execution/engine/__tests__/common/persona-router.test.ts

@@ -17,13 +17,14 @@ import type { EngineCapabilities } from "../../types.ts";
 const CAPS_FILE: EngineCapabilities = {
   schemaEnforcement: "emulated", steer: "unsupported", conversation: "unsupported",
   personaInjection: "file", eventGranularity: "coarse", sandbox: "none",
-  sessionRead: "partial", resume: "cold", interrupt: "kill-only", permissionMode: "native",
+  sessionRead: "partial", resume: "cold", interrupt: "kill-only", permissionMode: "native", maxTurns: false,
 };
 const CAPS_FLAG: EngineCapabilities = { ...CAPS_FILE, personaInjection: "flag" };
 const CAPS_PROMPT: EngineCapabilities = { ...CAPS_FILE, personaInjection: "prompt" };
 
+// [D6 合流] PersonaSpec 收拢层删除后，路由入参是 PersonaContent（结构子集：
+// appendSystemPrompt 正文 + skillPath 引用行；agentRef 已裁撤）
 const persona = {
-  agentRef: "reviewer",
   skillPath: "/skills/review.md",
   appendSystemPrompt: ["You are a careful code reviewer.", "Be terse."],
 };
@@ -34,7 +35,6 @@ describe("applyPersona 三策略路由", () => {
     expect(routing.promptSegment).toBe("");
     expect(routing.fileCandidate).toBeDefined();
     expect(routing.fileCandidate?.suggestedPath).toBe("persona.md");
-    expect(routing.fileCandidate?.content).toContain("# Agent: reviewer");
     expect(routing.fileCandidate?.content).toContain("/skills/review.md");
     expect(routing.fileCandidate?.content).toContain("You are a careful code reviewer.");
   });
@@ -51,7 +51,6 @@ describe("applyPersona 三策略路由", () => {
   it("prompt 策略：promptSegment 为带结构头的人设段（拼进最终 prompt）", () => {
     const routing = applyPersona(persona, CAPS_PROMPT);
     expect(routing.promptSegment.startsWith("## Persona")).toBe(true);
-    expect(routing.promptSegment).toContain("# Agent: reviewer");
     expect(routing.promptSegment).toContain("You are a careful code reviewer.");
   });
 
@@ -61,7 +60,7 @@ describe("applyPersona 三策略路由", () => {
     expect(applyPersona({}, CAPS_PROMPT)).toEqual({ promptSegment: "" });
   });
 
-  it("仅 appendSystemPrompt：file 通道照常落文件（agentRef/skillPath 头部行缺省）", () => {
+  it("仅 appendSystemPrompt：file 通道照常落文件（skillPath 头部行缺省）", () => {
     const routing = applyPersona({ appendSystemPrompt: ["only body"] }, CAPS_FILE);
     expect(routing.fileCandidate?.content).toBe("only body");
   });