@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/engine/__tests__/conformance/contract.abort.test.ts

@@ -0,0 +1,109 @@
+// contract.abort.test.ts —— conformance C4（abort 行为）：运行中 cancel → 宿主合成
+// 终态（exitCode=null）、无悬挂 promise（run 正常 resolve、exited 收口）、错误事件
+// 先于终态 emit（不变量 5 的事件面）。fake launcher 注入（不依赖真机）。
+
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { RunContext } from "../../port.ts";
+import type { AgentEvent, AgentTaskSpec } from "../../types.ts";
+import { ZcodeEngine, type ZcodeEngineDeps } from "../../engines/zcode/zcode-engine.ts";
+import type { ZcodeLaunchedProcess } from "../../engines/zcode/launcher.ts";
+
+const PROVIDER = "provider-x";
+
+let tmpRoot: string;
+let dataDir: string;
+let v2Path: string;
+
+function writeJson(p: string, v: unknown): void {
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(v));
+}
+
+/** 长驻 fake 进程：stdout 永不结束（模拟运行中），abort 由测试主动触发。 */
+function makeHangingLaunch(): {
+  launch: ZcodeEngineDeps["launch"];
+  proc: () => ZcodeLaunchedProcess | undefined;
+  triggerAbort: () => void;
+} {
+  let launched: ZcodeLaunchedProcess | undefined;
+  const stdout = new PassThrough();
+  const stderr = new PassThrough();
+  let killTriggered = false;
+  let resolveExited: (v: { code: number | null; signal: string | undefined }) => void = () => {};
+  const exited = new Promise<{ code: number | null; signal: string | undefined }>((resolve) => {
+    resolveExited = resolve;
+  });
+  const launch = (): ZcodeLaunchedProcess => {
+    launched = {
+      // D10 记账形态：child = 立即退出的真实 node 短进程（本用例不消费记账面）
+      child: spawn(process.execPath, ["-e", ""]),
+      pid: 4242,
+      stdout,
+      stderr,
+      abort: async () => {
+        killTriggered = true;
+        // 杀链语义：进程被信号杀死（code=null）——微任务后 settle 模拟 kill 时序
+        setTimeout(() => resolveExited({ code: null, signal: "SIGTERM" }), 5);
+      },
+      exited,
+      killedByUs: () => killTriggered,
+    };
+    return launched;
+  };
+  return { launch, proc: () => launched, triggerAbort: () => resolveExited({ code: null, signal: "SIGTERM" }) };
+}
+
+beforeEach(() => {
+  tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "c4-abort-"));
+  dataDir = path.join(tmpRoot, "data");
+  v2Path = path.join(tmpRoot, "v2.json");
+  writeJson(v2Path, {
+    provider: { [PROVIDER]: { options: { apiKey: "k" }, models: { m1: {} } } },
+  });
+});
+
+afterEach(() => {
+  fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+describe("conformance C4：abort 行为（运行中 cancel → 合成终态、无悬挂）", () => {
+  it("abort → run 正常 resolve（不悬挂）：exitCode=null + error 事件合成 + killedByUs", async () => {
+    const fake = makeHangingLaunch();
+    const engine = new ZcodeEngine({
+      engineDataDir: () => dataDir,
+      sources: { v2ConfigPath: v2Path },
+      processEnv: { PATH: "/usr/bin" },
+      launch: fake.launch,
+    });
+
+    const controller = new AbortController();
+    const events: AgentEvent[] = [];
+    const ctx: RunContext = {
+      taskId: "sa-c4",
+      poolKey: "",
+      signal: controller.signal,
+      onEvent: (ev) => events.push(ev),
+    };
+    const task: AgentTaskSpec = { task: "hang", slug: "abort", model: `${PROVIDER}/m1` };
+
+    const runP = engine.run(task, ctx);
+    // run 进行中触发 abort（等待 spawn 完成——微任务两拍让 launch 已执行）
+    await new Promise((r) => setTimeout(r, 20));
+    controller.abort();
+    const { handle, outcome } = await runP; // 必须正常 resolve（杀链合成终态，不悬挂）
+
+    expect(outcome.exitCode).toBeNull();
+    expect(outcome.error).toContain("中止");
+    // 终态前 error 事件已 emit（不变量 5 的事件面——journal 可重放出失败事实）
+    expect(events.some((e) => e.type === "error")).toBe(true);
+    expect(fake.proc()?.killedByUs()).toBe(true);
+    expect(handle.data.engineId).toBe("zcode");
+  }, 15_000);
+});

package/src/execution/engine/__tests__/conformance/contract.agent-events.test.ts

@@ -0,0 +1,101 @@
+// contract.agent-events.test.ts —— conformance C3（AgentEvent 不变量）+ 负例自证
+// （A12「套件有牙」：故意破坏一个不变量的样本必须被断言器检出——用「注入坏
+// parser」的形态：wrap 真实 synthesizeCoarseEvents 抽掉 message_end，断言套件转红；
+// 若断言器检不出破坏则本元测试失败）。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentEvent } from "../../../types.ts";
+import { ZCODE_GOLDEN_STDOUT } from "../../engines/zcode/golden-sample.ts";
+import { parseZcodeTerminal, synthesizeCoarseEvents } from "../../engines/zcode/parser.ts";
+import {
+  assertAgentEventInvariants,
+  checkAgentEventInvariants,
+} from "./agent-event-invariants.ts";
+
+/** golden 实录的 coarse 事件流（真实 parser + 真实合成器的产出）。 */
+function goldenCoarseEvents(): AgentEvent[] {
+  const terminal = parseZcodeTerminal(ZCODE_GOLDEN_STDOUT);
+  if (!terminal.ok) throw new Error("golden 样本解析失败");
+  return synthesizeCoarseEvents(terminal.payload.response, terminal.payload.usage);
+}
+
+describe("conformance C3：AgentEvent 不变量（真实 parser 产出全绿）", () => {
+  it("zcode golden 合成事件满足五条不变量（coarse 口径）", () => {
+    assertAgentEventInvariants(goldenCoarseEvents(), { granularity: "coarse" });
+  });
+
+  it("不变量 1：终态唯一——turn_end 后不得再出现非 error 事件", () => {
+    const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }, { type: "text_delta", delta: "x" }];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "1")).toBe(true);
+  });
+
+  it("不变量 2：message_end.usage 残缺对象（NaN token）被判违例", () => {
+    const events: AgentEvent[] = [
+      { type: "message_end", usage: { input: Number.NaN, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+
+  it("不变量 2 正例：usage 显式缺省整个字段 = 合法（不给残缺）", () => {
+    const events: AgentEvent[] = [{ type: "message_end" }, { type: "turn_end" }];
+    expect(checkAgentEventInvariants(events, { granularity: "coarse" })).toEqual([]);
+  });
+
+  it("不变量 3a：流式 text_delta 拼接 ≠ content 判违例（byte 级）", () => {
+    const events: AgentEvent[] = [
+      { type: "text_delta", delta: "abc" },
+      { type: "message_end", usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(events, { granularity: "stream", content: "abd" });
+    expect(findings.some((f) => f.invariant === "3a")).toBe(true);
+  });
+
+  it("不变量 3b：coarse 序列缺 message_end（turn_end 裸终态）判违例", () => {
+    const events: AgentEvent[] = [{ type: "turn_end" }];
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+  });
+
+  it("不变量 4：未配对 tool_start 且无 error 兜底判违例；error 兜底合法", () => {
+    const unpaired: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(unpaired, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(true);
+
+    const withError: AgentEvent[] = [
+      { type: "tool_start", toolName: "bash" },
+      { type: "error", message: "boom" },
+      { type: "turn_end" },
+    ];
+    expect(checkAgentEventInvariants(withError, { granularity: "coarse" }).some((f) => f.invariant === "4")).toBe(false);
+  });
+});
+
+describe("conformance 负例自证（A12：套件有牙）", () => {
+  it("注入坏 parser（抽掉 message_end 的合成器）：断言器必须检出（不变量 3b 转红）", () => {
+    // 坏 parser 形态：zcode 新版本漂移后合成器丢 message_end——不变量 3b 应抓到
+    const badParser = (): AgentEvent[] => [{ type: "turn_end" }];
+    const events = badParser();
+    const findings = checkAgentEventInvariants(events, { granularity: "coarse" });
+    expect(findings.length).toBeGreaterThan(0);
+    expect(findings.some((f) => f.invariant === "3b")).toBe(true);
+    // 断言形态同步转红（conformance 用例消费的入口）
+    expect(() => assertAgentEventInvariants(events, { granularity: "coarse" })).toThrowError(/不变量/);
+  });
+
+  it("注入坏 parser（usage 半映射）：断言器必须检出（不变量 2 转红）", () => {
+    // 坏 parser 形态：新版本 usage 字段改名，数值映射 Number(undefined) → NaN 渗入
+    const badParser = (): AgentEvent[] => [
+      { type: "message_end", usage: { input: Number.NaN, output: 2, cacheRead: 0, cacheWrite: 0 } },
+      { type: "turn_end" },
+    ];
+    const findings = checkAgentEventInvariants(badParser(), { granularity: "coarse" });
+    expect(findings.some((f) => f.invariant === "2")).toBe(true);
+  });
+});

package/src/execution/engine/__tests__/conformance/contract.probe.test.ts

@@ -0,0 +1,77 @@
+// contract.probe.test.ts —— conformance C1（probe 形状）：ProbeReport 字段完整；
+// ok=false 时 error.recovery 非空（§3.3.5——恢复指引是错误闭环「错误→权威源→重试」
+// 的载体，空指引 = 拦截了但不知道怎么修）。pi/zcode 双引擎都过（任何 adapter 必过）。
+//
+// fake 注入（不依赖真机）：pi 用 probeVersion fake + 不可解析 invocation 场景；
+// zcode 用不存在的 cliPath 构造 binary check 失败。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+import type { ProbeReport } from "../../types.ts";
+
+function assertProbeShape(report: ProbeReport): void {
+  expect(typeof report.ok).toBe("boolean");
+  expect(typeof report.engineVersion).toBe("string");
+  expect(Array.isArray(report.checks)).toBe(true);
+  expect(report.checks.length).toBeGreaterThan(0);
+  for (const c of report.checks) {
+    expect(typeof c.name).toBe("string");
+    expect(typeof c.ok).toBe("boolean");
+  }
+  if (!report.ok) {
+    expect(report.error).toBeDefined();
+    expect(report.error?.code).toBe("engine_probe_failed");
+    // 恢复指引非空且指向动作（C1 断言核心——空指引直接 fail）
+    expect(report.error?.recovery).toBeTruthy();
+    expect(report.error?.recovery.length).toBeGreaterThan(20);
+  }
+}
+
+describe("conformance C1：probe 形状（ProbeReport 字段完整 + 失败含恢复指引）", () => {
+  it("pi：成功路径形状（fake 版本探测，不 spawn 真进程）", async () => {
+    const engine = new PiEngine({ getService: () => null, probeVersion: async () => "0.84.1" });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(true);
+    expect(report.engineVersion).toBe("0.84.1");
+  });
+
+  it("pi：失败路径（invocation 不可解析）——error.recovery 非空", async () => {
+    const engine = new PiEngine({
+      getService: () => null,
+      probeVersion: async () => undefined,
+    });
+    // PATH 无 pi 时 invocation check 失败；有 pi 时版本 fake 失败——两形态都走断言器
+    const report = await engine.probe({ force: true });
+    assertProbeShape(report);
+  });
+
+  it("zcode：成功路径形状（存在的 cliPath + fake 版本探测）", async () => {
+    const engine = new ZcodeEngine({
+      engineDataDir: () => fs.mkdtempSync(path.join(os.tmpdir(), "probe-zcode-")),
+      cliPath: fileURLToPath(import.meta.url),
+      probeVersion: async () => "0.16.5",
+    });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(true);
+  });
+
+  it("zcode：失败路径（二进制不存在）——error.recovery 非空且含重探指引", async () => {
+    const engine = new ZcodeEngine({
+      engineDataDir: () => fs.mkdtempSync(path.join(os.tmpdir(), "probe-zcode-")),
+      cliPath: "/nonexistent/zcode.cjs",
+    });
+    const report = await engine.probe();
+    assertProbeShape(report);
+    expect(report.ok).toBe(false);
+    expect(report.error?.recovery).toContain("--version");
+  });
+});

package/src/execution/engine/__tests__/conformance/contract.read-degradation.test.ts

@@ -0,0 +1,104 @@
+// contract.read-degradation.test.ts —— conformance C5（read 降级链）：三级都不 throw、
+// 坏 handle → 结构化降级（outcome-only）非崩溃、②级 journal 重放与 live 一致
+// （重放等价性，§3.3.6——journal 重放与 live 通路共用同一 reducer 的断言面）。
+//
+// fake 注入：zcode 用坏 dbPath（①级失败）+ 临时 journal 文件（②级命中）；pi 用
+// 不存在的 sessionFile（①级失败）+ journal（②级）。
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { eventsToSessionView } from "../../common/journal-replay.ts";
+import { JournalWriter } from "../../common/event-journal.ts";
+import { PiEngine } from "../../engines/pi/pi-engine.ts";
+import { ZcodeEngine } from "../../engines/zcode/zcode-engine.ts";
+import type { AgentEvent, EngineHandle } from "../../types.ts";
+
+function makeHandle(engineId: string, sessionRef: Record<string, string>, journalPath?: string): EngineHandle {
+  return {
+    data: {
+      v: 1,
+      engineId,
+      sessionRef,
+      poolKey: "shared",
+      ...(journalPath !== undefined ? { journalPath } : {}),
+      adapterVersion: "1.0.0-test",
+    },
+  };
+}
+
+/** live 通路形态的事件序列（与 golden 回放同源——重放等价性的比对基准）。 */
+const liveEvents: AgentEvent[] = [
+  { type: "text_delta", delta: "part one. " },
+  { type: "text_delta", delta: "part two." },
+  { type: "message_end", usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 } },
+  { type: "turn_end" },
+];
+
+describe("conformance C5：read 降级链（三级都不 throw）", () => {
+  let dataDir: string;
+  beforeEach(() => {
+    dataDir = fs.mkdtempSync(path.join(os.tmpdir(), "c5-read-"));
+  });
+  afterEach(() => {
+    fs.rmSync(dataDir, { recursive: true, force: true });
+  });
+
+  it("重放等价性：journal 重放 turns 与 live 累积一致（共用 updateFromEvent reducer）", () => {
+    const live = eventsToSessionView(liveEvents, "pi", "sess-x");
+    expect(live.source).toBe("journal");
+    expect(live.turns).toHaveLength(1);
+    expect(live.turns[0]?.text).toBe("part one. part two.");
+    expect(live.usage?.total).toBe(15);
+  });
+
+  it("zcode：①级坏 handle（dbPath 指向不存在文件）→ ②级 journal 命中（source=journal）", async () => {
+    const journalPath = path.join(dataDir, "journal-sa-c5.jsonl");
+    const writer = new JournalWriter({ path: journalPath, taskId: "sa-c5", engineId: "zcode" });
+    for (const ev of liveEvents) writer.append(ev);
+    await writer.close();
+
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const handle = makeHandle("zcode", { sessionId: "sess-c5", dbPath: ".zcode/cli/db/db.sqlite" }, journalPath);
+    const view = await engine.read(handle); // ①级 db 不存在 → catch → ②级重放
+    expect(view.source).toBe("journal");
+    expect(view.engineId).toBe("zcode");
+    expect(view.turns[0]?.text).toBe("part one. part two.");
+  });
+
+  it("zcode：②级也不可达（无 journalPath）→ ③级 outcome-only，不 throw", async () => {
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const handle = makeHandle("zcode", { sessionId: "sess-c5", dbPath: ".zcode/cli/db/db.sqlite" });
+    const view = await engine.read(handle);
+    expect(view.source).toBe("outcome-only");
+    expect(view.turns).toEqual([]);
+  });
+
+  it("zcode：跨引擎 handle（engineId 不符）→ 结构化 outcome-only，不 throw", async () => {
+    const engine = new ZcodeEngine({ engineDataDir: () => dataDir });
+    const view = await engine.read(makeHandle("pi", {}));
+    expect(view.source).toBe("outcome-only");
+  });
+
+  it("pi：①级坏 handle（sessionFile 不存在）→ ②级 journal 命中；②级缺省 → ③级", async () => {
+    const engine = new PiEngine({ getService: () => null });
+
+    const journalPath = path.join(dataDir, "journal-sa-pi-c5.jsonl");
+    const writer = new JournalWriter({ path: journalPath, taskId: "sa-pi-c5", engineId: "pi" });
+    for (const ev of liveEvents) writer.append(ev);
+    await writer.close();
+
+    const viaJournal = await engine.read(
+      makeHandle("pi", { sessionFile: "/nonexistent/session.jsonl" }, journalPath),
+    );
+    expect(viaJournal.source).toBe("journal");
+    expect(viaJournal.turns[0]?.text).toBe("part one. part two.");
+
+    const outcomeOnly = await engine.read(makeHandle("pi", { sessionFile: "/nonexistent/session.jsonl" }));
+    expect(outcomeOnly.source).toBe("outcome-only");
+    expect(outcomeOnly.turns).toEqual([]);
+  });
+});