@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

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

@@ -1,109 +0,0 @@
-// 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

@@ -1,101 +0,0 @@
-// 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

@@ -1,77 +0,0 @@
-// 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

@@ -1,104 +0,0 @@
-// 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([]);
-  });
-});