@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

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

@@ -1,123 +0,0 @@
-// persona-router.test.ts —— persona 三策略路由 + argv 预算前置拦截。
-//
-// 三视角：①构建者——三通道产出物各归其位；②使用者——argv 超限时报
-// prompt_too_large 且文案含三条恢复建议；③观察者——估算口径含多字节字符与分隔符。
-
-import { describe, expect, it } from "vitest";
-
-import {
-  applyPersona,
-  assertArgvBudget,
-  DEFAULT_ARGV_BUDGET_BYTES,
-  estimateArgvBytes,
-} from "../../common/persona-router.ts";
-import { EngineError } from "../../common/errors.ts";
-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",
-};
-const CAPS_FLAG: EngineCapabilities = { ...CAPS_FILE, personaInjection: "flag" };
-const CAPS_PROMPT: EngineCapabilities = { ...CAPS_FILE, personaInjection: "prompt" };
-
-const persona = {
-  agentRef: "reviewer",
-  skillPath: "/skills/review.md",
-  appendSystemPrompt: ["You are a careful code reviewer.", "Be terse."],
-};
-
-describe("applyPersona 三策略路由", () => {
-  it("file 策略：人设全文进 fileCandidate（路径相对池目录），promptSegment 为空", () => {
-    const routing = applyPersona(persona, CAPS_FILE);
-    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.");
-  });
-
-  it("flag 策略：promptSegment 为纯人设正文（launcher 组 flag 直传），无 fileCandidate", () => {
-    const routing = applyPersona(persona, CAPS_FLAG);
-    expect(routing.fileCandidate).toBeUndefined();
-    expect(routing.promptSegment).toContain("You are a careful code reviewer.");
-    expect(routing.promptSegment).toContain("Be terse.");
-    // 纯正文：不带 prompt 通道的结构头
-    expect(routing.promptSegment).not.toContain("## Persona");
-  });
-
-  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.");
-  });
-
-  it("空 persona（全字段缺省）：三通道都产出空载体（白占 argv/prompt 无意义）", () => {
-    expect(applyPersona({}, CAPS_FILE)).toEqual({ promptSegment: "" });
-    expect(applyPersona({}, CAPS_FLAG)).toEqual({ promptSegment: "" });
-    expect(applyPersona({}, CAPS_PROMPT)).toEqual({ promptSegment: "" });
-  });
-
-  it("仅 appendSystemPrompt：file 通道照常落文件（agentRef/skillPath 头部行缺省）", () => {
-    const routing = applyPersona({ appendSystemPrompt: ["only body"] }, CAPS_FILE);
-    expect(routing.fileCandidate?.content).toBe("only body");
-  });
-});
-
-describe("estimateArgvBytes", () => {
-  it("ASCII：字节数之和 + 每参数 1 个 NUL 分隔符", () => {
-    // "ab"(2) + "cde"(3) + 2 个 NUL = 7
-    expect(estimateArgvBytes(["ab", "cde"])).toBe(7);
-    expect(estimateArgvBytes([])).toBe(0);
-  });
-
-  it("多字节字符按 UTF-8 计（中文 3 字节/字）——字符数口径会低估", () => {
-    // "中"=3 字节 + 1 NUL = 4
-    expect(estimateArgvBytes(["中"])).toBe(4);
-    // "a中b" = 1+3+1 = 5 字节 + 1 = 6
-    expect(estimateArgvBytes(["a中b"])).toBe(6);
-  });
-});
-
-describe("assertArgvBudget", () => {
-  it(`默认上限 ${DEFAULT_ARGV_BUDGET_BYTES} 字节（128KB）且预算内通过`, () => {
-    expect(DEFAULT_ARGV_BUDGET_BYTES).toBe(128 * 1024);
-    expect(() => assertArgvBudget(["--prompt", "short"])).not.toThrow();
-  });
-
-  it("超限抛 prompt_too_large：detail 含实际/上限字节数", () => {
-    const bigArg = "x".repeat(1024);
-    const argv = [bigArg, bigArg]; // 2KB，limit 1KB
-    let caught: EngineError | undefined;
-    try {
-      assertArgvBudget(argv, 1024);
-      expect.unreachable("should throw");
-    } catch (err) {
-      caught = err as EngineError;
-    }
-    expect(caught).toBeInstanceOf(EngineError);
-    expect(caught?.code).toBe("prompt_too_large");
-    expect(caught?.message).toContain("2050"); // 1024*2 + 2 NUL
-    expect(caught?.message).toContain("1024");
-  });
-
-  it("错误恢复指引含三条建议：缩短 task / persona 移 file 通道 / 换 stdin 引擎", () => {
-    try {
-      assertArgvBudget(["y".repeat(3000)], 1024);
-      expect.unreachable("should throw");
-    } catch (err) {
-      const e = err as EngineError;
-      expect(e.recovery).toMatch(/shorten the task/i);
-      expect(e.recovery).toMatch(/file channel/);
-      expect(e.recovery).toMatch(/stdin/);
-    }
-  });
-
-  it("limit 可配（调用方收紧到引擎实测限额）", () => {
-    expect(() => assertArgvBudget(["a".repeat(100)], 50)).toThrowError(/prompt_too_large/);
-    expect(() => assertArgvBudget(["a".repeat(100)], 101)).not.toThrow();
-  });
-});

package/src/execution/engine/__tests__/common/pool-manager.test.ts

@@ -1,154 +0,0 @@
-// pool-manager.test.ts —— 池 acquire/release 引用计数 / 归零整池删除 / journal 保留
-// / 清理失败标记 / spawnedFiles 单次清理（D5 + §3.3.9）。
-//
-// 三视角：①构建者——计数归零才删、删除边界三硬规则逐条；②使用者——release 幂等
-// 安全（无引用 no-op）；③观察者——清理失败有 .pool-cleanup-failed 标记（可观测）。
-
-import { mkdirSync, mkdtempSync, existsSync, readdirSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import {
-  acquirePool,
-  cleanupSpawnedFiles,
-  POOL_CLEANUP_FAILED_MARKER,
-  releasePoolRef,
-  resetPoolRegistryForTests,
-} from "../../common/pool-manager.ts";
-import { resolvePoolDir } from "../../paths.ts";
-
-let tmpRoot: string;
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), "engine-pool-test-"));
-  resetPoolRegistryForTests();
-});
-
-afterEach(() => {
-  rmSync(tmpRoot, { recursive: true, force: true });
-});
-
-describe("acquirePool", () => {
-  it("mkdir -p 返回池目录（路径经 resolvePoolDir 派生），重复 acquire 幂等", async () => {
-    const dir1 = await acquirePool(tmpRoot, "zcode", "reviewer");
-    const dir2 = await acquirePool(tmpRoot, "zcode", "reviewer");
-    expect(dir1).toBe(resolvePoolDir(tmpRoot, "zcode", "reviewer"));
-    expect(dir1).toBe(dir2);
-    expect(existsSync(dir1)).toBe(true);
-  });
-
-  it("poolKey 经 sanitizeSeg 归一（脏字符不进文件系统路径）", async () => {
-    const dir = await acquirePool(tmpRoot, "zcode", "weird/key..name");
-    expect(dir).toBe(resolvePoolDir(tmpRoot, "zcode", "weird-key-name"));
-  });
-});
-
-describe("releasePoolRef 引用计数与整池删除", () => {
-  it("双引用：release 一次池仍在（原生状态未删），归零才整池删除", async () => {
-    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
-    await acquirePool(tmpRoot, "zcode", "reviewer");
-    await acquirePool(tmpRoot, "zcode", "reviewer");
-    mkdirSync(join(poolDir, "home"), { recursive: true });
-    writeFileSync(join(poolDir, "home", "config.json"), "{}");
-
-    await releasePoolRef(tmpRoot, "zcode", "reviewer");
-    expect(existsSync(join(poolDir, "home"))).toBe(true); // 计数 1，不删
-
-    await releasePoolRef(tmpRoot, "zcode", "reviewer"); // 归零
-    expect(existsSync(join(poolDir, "home"))).toBe(false); // 原生状态已删
-  });
-
-  it("journal-*.jsonl 不随池删（生命周期跟随 record），目录保留", async () => {
-    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
-    await acquirePool(tmpRoot, "zcode", "reviewer");
-    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
-    mkdirSync(join(poolDir, "home"), { recursive: true });
-
-    await releasePoolRef(tmpRoot, "zcode", "reviewer");
-    expect(existsSync(join(poolDir, "journal-bg-1.jsonl"))).toBe(true);
-    expect(existsSync(join(poolDir, "home"))).toBe(false);
-    // 只剩 journal：目录本体保留（journal 还在用）
-    expect(existsSync(poolDir)).toBe(true);
-    expect(readdirSync(poolDir)).toEqual(["journal-bg-1.jsonl"]);
-  });
-
-  it("无引用的 release（进程重启后 GC）→ 保守 no-op 不删池", async () => {
-    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
-    mkdirSync(join(poolDir, "home"), { recursive: true });
-    await releasePoolRef(tmpRoot, "zcode", "reviewer");
-    expect(existsSync(join(poolDir, "home"))).toBe(true);
-  });
-
-  it("池目录不存在时 release 归零 → 无原生状态可清，视为成功不抛", async () => {
-    await acquirePool(tmpRoot, "zcode", "ghost");
-    // 归零但目录已被外部删除
-    rmSync(resolvePoolDir(tmpRoot, "zcode", "ghost"), { recursive: true, force: true });
-    await expect(releasePoolRef(tmpRoot, "zcode", "ghost")).resolves.toBeUndefined();
-  });
-
-  it("删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），不 throw", async () => {
-    const poolDir = resolvePoolDir(tmpRoot, "zcode", "reviewer");
-    await acquirePool(tmpRoot, "zcode", "reviewer");
-    mkdirSync(join(poolDir, "home"), { recursive: true });
-    writeFileSync(join(poolDir, "journal-bg-1.jsonl"), "{}\n");
-
-    // 注入失败 fs：rm 对 home 目录 reject（标记写入仍走真实 fs——失败要可观测）
-    const realFs = await import("node:fs/promises");
-    const injected = {
-      mkdir: (p: string, o: { recursive: boolean }) => realFs.mkdir(p, o),
-      readdir: (p: string) => realFs.readdir(p, { withFileTypes: true }),
-      rm: async (p: string, o: { recursive: boolean; force: boolean }) => {
-        if (p === join(poolDir, "home")) throw new Error("EACCES: permission denied");
-        return realFs.rm(p, o);
-      },
-      rmdir: (p: string) => realFs.rmdir(p),
-      writeFile: (p: string, d: string) => realFs.writeFile(p, d, "utf8"),
-    };
-
-    await expect(releasePoolRef(tmpRoot, "zcode", "reviewer", injected)).resolves.toBeUndefined();
-    const markerPath = join(poolDir, POOL_CLEANUP_FAILED_MARKER);
-    expect(existsSync(markerPath)).toBe(true);
-    // 标记内容是失败清单 JSON（含失败条目与原因）
-    const payload = JSON.parse(
-      (await import("node:fs")).readFileSync(markerPath, "utf8"),
-    ) as { failures: string[] };
-    expect(payload.failures.length).toBe(1);
-    expect(payload.failures[0]).toContain("home");
-    expect(payload.failures[0]).toContain("EACCES");
-  });
-});
-
-describe("cleanupSpawnedFiles（单次性产物）", () => {
-  it("keepForResume=true → 全部保留（resume 续接原 session，不重写产物）", async () => {
-    const f = join(tmpRoot, "prompt.txt");
-    writeFileSync(f, "x");
-    await cleanupSpawnedFiles([f], { keepForResume: true });
-    expect(existsSync(f)).toBe(true);
-  });
-
-  it("keepForResume=false → 删除；目录产物递归删", async () => {
-    const file = join(tmpRoot, "prompt.txt");
-    const dir = join(tmpRoot, "persona");
-    writeFileSync(file, "x");
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "persona.md"), "y");
-    await cleanupSpawnedFiles([file, dir], { keepForResume: false });
-    expect(existsSync(file)).toBe(false);
-    expect(existsSync(dir)).toBe(false);
-  });
-
-  it("不存在的路径幂等（ENOENT 忽略）；单条失败不 throw 其余继续", async () => {
-    const good = join(tmpRoot, "good.txt");
-    writeFileSync(good, "x");
-    // 真实 fs 下很难制造 rm 失败——用「父路径为文件」制造 ENOTDIR 失败：
-    // rm(recursive, force) 对 «file/child» 形态报 ENOTDIR（force 只豁免 ENOENT）
-    const blocked = join(tmpRoot, "plain-file", "child");
-    writeFileSync(join(tmpRoot, "plain-file"), "not a dir");
-    await expect(
-      cleanupSpawnedFiles([blocked, good], { keepForResume: false }),
-    ).resolves.toBeUndefined();
-    expect(existsSync(good)).toBe(false);
-  });
-});

package/src/execution/engine/__tests__/common/schema-emulation.test.ts

@@ -1,128 +0,0 @@
-// schema-emulation.test.ts —— 三级容错提取逐级用例 + ajv 校验 + tail 载体。
-//
-// 三视角：①构建者——三级容错每级有独立触达用例（直接 parse / fence / 括号扫描）；
-// ②使用者——ok:false 时 error 简述 + tail 足以构造重试 prompt；③观察者——prompt
-// 注入段含 schema 声明与输出约定（emulated 引擎拼进 prompt 后模型可遵循）。
-
-import { describe, expect, it } from "vitest";
-
-import {
-  buildSchemaEmulationSegment,
-  extractAndValidateStructuredOutput,
-  SCHEMA_EMULATION_TAIL_CHARS,
-} from "../../common/schema-emulation.ts";
-
-const objectSchema = {
-  type: "object",
-  properties: { verdict: { type: "string" }, issues: { type: "array", items: { type: "string" } } },
-  required: ["verdict"],
-} as const;
-
-describe("buildSchemaEmulationSegment", () => {
-  it("注入段含 schema JSON 声明 + 输出格式约定（用户可见 prompt 断言）", () => {
-    const segment = buildSchemaEmulationSegment(objectSchema);
-    expect(segment).toContain("## Structured Output Requirement");
-    expect(segment).toContain(JSON.stringify(objectSchema));
-    expect(segment).toMatch(/```json/);
-    expect(segment).toMatch(/ONLY the JSON value/);
-    expect(segment).toMatch(/JSON Schema \(draft-07\)/);
-  });
-});
-
-describe("extractAndValidateStructuredOutput 三级容错", () => {
-  it("第 1 级：输出整体即合法 JSON → 直接 parse 通过 + ajv 通过", () => {
-    const text = JSON.stringify({ verdict: "pass", issues: [] });
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "pass", issues: [] } });
-  });
-
-  it("第 2 级：markdown code fence 包裹 → 剥 fence 后 parse 通过", () => {
-    const text = "Here is my answer:\n```json\n{\"verdict\": \"fail\", \"issues\": [\"a\", \"b\"]}\n```\n";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["a", "b"] } });
-  });
-
-  it("第 2 级：无语言标注的裸 fence 也能剥", () => {
-    const text = "```\n{\"verdict\": \"pass\"}\n```";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "pass" } });
-  });
-
-  it("第 3 级：前后杂文本包裹 → 首尾括号扫描提取", () => {
-    const text = "Sure! The review result is:\n\n{\"verdict\": \"fail\", \"issues\": [\"x\"]}\n\nHope this helps.";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result).toEqual({ ok: true, parsed: { verdict: "fail", issues: ["x"] } });
-  });
-
-  it("第 3 级：array 根也支持（首个 '[' 到末个 ']'）", () => {
-    const arraySchema = { type: "array", items: { type: "string" } };
-    const result = extractAndValidateStructuredOutput("prefix [\"a\",\"b\"] suffix", arraySchema);
-    expect(result).toEqual({ ok: true, parsed: ["a", "b"] });
-  });
-
-  it("提取成功但 ajv 校验失败 → ok:false 含 ajv 错误明细与原始尾部", () => {
-    // verdict 缺失（required）+ issues 类型错
-    const text = '{"issues": "not-an-array"}';
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("Schema validation failed");
-      expect(result.error).toContain("verdict");
-      expect(result.tail).toBe(text);
-    }
-  });
-
-  it("三级提取全失败（无任何 JSON）→ ok:false 且 error 指明三级路径", () => {
-    const result = extractAndValidateStructuredOutput("no json here at all", objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("3-stage");
-      expect(result.error).toContain("code-fence");
-      expect(result.error).toContain("bracket scan");
-    }
-  });
-
-  it("提取成功但 JSON 语法损坏（括号扫描后仍 parse 失败）→ ok:false", () => {
-    const result = extractAndValidateStructuredOutput("result: {verdict: pass}", objectSchema);
-    expect(result.ok).toBe(false);
-  });
-
-  it("ajv 编译失败（非法 schema）→ ok:false 指明 host 侧编译失败", () => {
-    // type: "foo" 是 ajv 编译期拒绝的非法类型值
-    const result = extractAndValidateStructuredOutput('{"a":1}', { type: "foo" });
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toContain("compilation failed");
-    }
-  });
-});
-
-describe("tail 载体（错误展示）", () => {
-  it(`tail 截断到原始输出尾部 ${SCHEMA_EMULATION_TAIL_CHARS} 字`, () => {
-    const head = "H".repeat(300);
-    const tailPart = "T".repeat(400);
-    const text = `${head}${tailPart}`; // 700 字，尾部 500 = 末段（100H + 400T）
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.tail.length).toBe(SCHEMA_EMULATION_TAIL_CHARS);
-      expect(result.tail).toBe("H".repeat(100) + "T".repeat(400));
-    }
-  });
-
-  it("短输出 tail 为原文（不截断）", () => {
-    const text = "short broken output";
-    const result = extractAndValidateStructuredOutput(text, objectSchema);
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.tail).toBe(text);
-    }
-  });
-});
-
-describe("D4 硬分流守护（静态断言）", () => {
-  it("本模块的 ajv 只在 emulated 路径——native 引擎（pi-env 链路）不 import 本模块（由全仓 grep 守护，见任务报告）", () => {
-    // 占位用例：硬分流是 import 约束，运行时无对应断言点；保留用例记录守护方式
-    expect(typeof extractAndValidateStructuredOutput).toBe("function");
-  });
-});

package/src/execution/engine/__tests__/conformance/__fixtures__/pi-golden-events.json

@@ -1,28 +0,0 @@
-{
-  "_meta": {
-    "engineId": "pi",
-    "description": "pi 引擎 golden 事件序列（统一 AgentEvent 形态——spawn-event-adapter/session-runner 翻译后的 onEvent 出口序列，即 journal 落盘形态）",
-    "source": "从 spawn-event-adapter.test.ts / session-runner 事件形状构造的典型流式序列：bash 工具调用（含 pendingTools 配对）→ 双段 text_delta → message_end（完整 usage）→ turn_end。字段形状与 handleSdkEvent 翻译产物逐一锚定（tool_start.toolName/args、tool_end.result/isError、text_delta.delta、message_end.usage 四项 token、turn_end）",
-    "recordedAt": "2026-08-25",
-    "usageMapping": "message_end.usage = pi SDK message.usage（input/output/cacheRead/cacheWrite 四项 + cost.total 投影为 cost）"
-  },
-  "events": [
-    { "type": "tool_start", "toolName": "bash", "args": { "command": "ls -la /tmp/probe" } },
-    {
-      "type": "tool_end",
-      "toolName": "bash",
-      "args": { "command": "ls -la /tmp/probe" },
-      "result": { "output": "total 0\ndrwxr-xr-x  2 user  staff  64 Aug 25 10:00:00 ." },
-      "isError": false
-    },
-    { "type": "thinking_delta", "delta": "目录为空，无需进一步检查。" },
-    { "type": "text_delta", "delta": "Probe directory is empty. " },
-    { "type": "text_delta", "delta": "Nothing to clean up." },
-    {
-      "type": "message_end",
-      "usage": { "input": 12599, "output": 17, "cacheRead": 512, "cacheWrite": 0, "cost": 0.0001 }
-    },
-    { "type": "turn_end" }
-  ],
-  "content": "Probe directory is empty. Nothing to clean up."
-}

package/src/execution/engine/__tests__/conformance/agent-event-invariants.ts

@@ -1,141 +0,0 @@
-// agent-event-invariants.ts —— AgentEvent 产出不变量断言器（conformance C3 的实现体）。
-//
-// 设计权威源：docs/architecture/subagent-engine-abstraction.md §3.3.7「AgentEvent 产出
-// 不变量」五条（全部引擎必须满足）。任何 adapter 的 conformance 套件（golden 回放层 /
-// 合成样本）都经本断言器校验——负例守护（A12「套件有牙」）靠注入坏序列证明它转红。
-//
-// 为什么独立成模块（非内联在测试文件）：pi/zcode 两套 golden 回放 + 负例元测试共用
-// 同一断言逻辑；断言规则漂移会同步影响所有引擎的 conformance，单点维护。
-
-import type { AgentEvent, AgentUsage } from "../../../types.ts";
-
-/** 单条不变量违例。invariant 是规则编号（"1"/"2a"...），detail 是定位信息。 */
-export interface InvariantFinding {
-  invariant: string;
-  detail: string;
-}
-
-/** 断言选项。granularity 决定不变量 3 走流式（byte 级拼接）还是 coarse 口径。 */
-export interface InvariantOptions {
-  granularity: "stream" | "coarse";
-  /** 流式引擎的终态 content（不变量 3a：text_delta 拼接 === content，byte 级）。 */
-  content?: string;
-}
-
-/** 五条不变量的纯校验（不 throw，返回违例清单——元测试要拿清单做反证）。 */
-export function checkAgentEventInvariants(
-  events: readonly AgentEvent[],
-  opts: InvariantOptions,
-): InvariantFinding[] {
-  const findings: InvariantFinding[] = [];
-  if (events.length === 0) {
-    return [{ invariant: "0", detail: "事件序列为空——至少需要 turn_end 终态" }];
-  }
-
-  // 不变量 1：终态序唯一——最后一个非 error 事件必是 turn_end；message_end（若出现）
-  // 必在其前（turn_end 之后不允许任何非 error 事件）
-  const nonError = events.filter((e) => e.type !== "error");
-  const last = nonError[nonError.length - 1];
-  if (last === undefined || last.type !== "turn_end") {
-    findings.push({
-      invariant: "1",
-      detail: `最后一个非 error 事件是 ${String(last?.type ?? "(none)")}，必须唯一且为 turn_end`,
-    });
-  }
-  const lastTurnEndIdx = findLastIndex(events, (e) => e.type === "turn_end");
-  if (lastTurnEndIdx >= 0) {
-    for (let i = lastTurnEndIdx + 1; i < events.length; i++) {
-      const ev = events[i];
-      if (ev !== undefined && ev.type !== "error") {
-        findings.push({ invariant: "1", detail: `turn_end 之后出现非 error 事件 ${ev.type}（idx ${i}）` });
-      }
-    }
-  }
-  const lastMessageEndIdx = findLastIndex(events, (e) => e.type === "message_end");
-  if (lastMessageEndIdx >= 0 && lastTurnEndIdx >= 0 && lastMessageEndIdx > lastTurnEndIdx) {
-    findings.push({ invariant: "1", detail: "message_end 出现在 turn_end 之后（必须在其前）" });
-  }
-
-  // 不变量 2：message_end.usage 出现时为完整 AgentUsage 形状——给不出完整 usage 时
-  // 显式缺省整个字段，不给残缺对象（NaN/缺键 = 残缺）
-  events.forEach((ev, idx) => {
-    if (ev.type !== "message_end") return;
-    if (ev.usage === undefined) return; // 显式缺省 = 合法
-    if (!isCompleteUsage(ev.usage)) {
-      findings.push({ invariant: "2", detail: `message_end(idx ${idx}).usage 残缺（四项 token 必须全为有限数）` });
-    }
-  });
-
-  // 不变量 3a（流式）：全部 text_delta 拼接 === content（byte 级）
-  if (opts.granularity === "stream") {
-    if (opts.content === undefined) {
-      findings.push({ invariant: "3a", detail: "流式口径必须提供 content 供拼接比对" });
-    } else {
-      const joined = events.filter((e) => e.type === "text_delta").map((e) => (e as { delta: string }).delta).join("");
-      if (Buffer.from(joined, "utf8").toString("hex") !== Buffer.from(opts.content, "utf8").toString("hex")) {
-        findings.push({ invariant: "3a", detail: "text_delta 拼接与 content 不一致（byte 级比对失败）" });
-      }
-    }
-  } else {
-    // 不变量 3b（coarse）：turn_end 前至少一个 message_end
-    if (lastTurnEndIdx < 0 || !events.slice(0, lastTurnEndIdx).some((e) => e.type === "message_end")) {
-      findings.push({ invariant: "3b", detail: "coarse 引擎 turn_end 前必须至少一个 message_end" });
-    }
-  }
-
-  // 不变量 4：tool_start/tool_end 按名配对——终态前未配对的 tool_start 必须有配对
-  // tool_end（isError 可）或后续 error 事件兜底
-  const openTools: Array<{ toolName: string; idx: number }> = [];
-  let errorSeen = false;
-  events.forEach((ev, idx) => {
-    if (ev.type === "error") {
-      errorSeen = true;
-      return;
-    }
-    if (ev.type === "tool_start") {
-      openTools.push({ toolName: ev.toolName, idx });
-      return;
-    }
-    if (ev.type === "tool_end") {
-      const at = openTools.findIndex((t) => t.toolName === ev.toolName);
-      if (at >= 0) openTools.splice(at, 1);
-      return;
-    }
-  });
-  for (const t of openTools) {
-    if (!errorSeen) {
-      findings.push({
-        invariant: "4",
-        detail: `tool_start(${t.toolName}, idx ${t.idx}) 终态前未配对（无 tool_end 也无 error 兜底）`,
-      });
-    }
-  }
-
-  return findings;
-}
-
-/** 断言形态（conformance 用例直接消费——违例 throw，测试转红）。 */
-export function assertAgentEventInvariants(events: readonly AgentEvent[], opts: InvariantOptions): void {
-  const findings = checkAgentEventInvariants(events, opts);
-  if (findings.length > 0) {
-    const lines = findings.map((f) => `  [不变量 ${f.invariant}] ${f.detail}`).join("\n");
-    throw new Error(`AgentEvent 不变量违例（§3.3.7 五条）：\n${lines}`);
-  }
-}
-
-/** AgentUsage 完整形状判定（四项 token 有限数；cost 可选）。 */
-function isCompleteUsage(u: AgentUsage): boolean {
-  return (
-    Number.isFinite(u.input) && Number.isFinite(u.output) &&
-    Number.isFinite(u.cacheRead) && Number.isFinite(u.cacheWrite)
-  );
-}
-
-/** Array.prototype.findLastIndex 的 ES2022 前兼容（node 18+ 有原生，防御口径手写）。 */
-function findLastIndex<T>(arr: readonly T[], pred: (v: T) => boolean): number {
-  for (let i = arr.length - 1; i >= 0; i--) {
-    const v = arr[i];
-    if (v !== undefined && pred(v)) return i;
-  }
-  return -1;
-}