@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.0

package/src/execution/__tests__/finalize-record.test.ts

@@ -0,0 +1,173 @@
+// doFinalizeRecord — manifest status 透传测试（M3: 4 态方案）。
+//
+// 验证 finalize-record.ts 的 status 映射：done→completed, failed→failed, cancelled→cancelled
+// （cancelled 不再归并 failed）。crashed 不进 finalize 入参（TS 签名锁定 done/failed/cancelled）。
+//
+// 测试策略：record 不带 sessionFile/worktreeHandle,跳过 Step 0 (collectPatch) 和 Step 3
+// (finalized/tombstone/aliveMarker/worktree cleanup) 的文件操作,聚焦 Step 4 writeManifest
+// 的 status 产出。FinalizeDeps 用 stub 注入（manifestStore 为真实实例,指向 tmpDir）。
+
+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 { doFinalizeRecord } from "../finalize-record.ts";
+import { ManifestStore } from "../manifest-store.ts";
+import type { AgentResult, ExecutionRecord } from "../types.ts";
+
+function makeMinimalRecord(overrides: Partial<ExecutionRecord> = {}): ExecutionRecord {
+  return {
+    id: "finalize-test",
+    agent: "worker",
+    model: "test/model",
+    thinkingLevel: undefined,
+    mode: "background",
+    task: "test",
+    slug: "test",
+    startedAt: 1000,
+    rootSessionId: "session-main",
+    parentRecordId: undefined,
+    depth: 0,
+    status: "running",
+    turns: [],
+    turnCount: 0,
+    totalTokens: 0,
+    lastError: undefined,
+    endedAt: undefined,
+    result: undefined,
+    error: undefined,
+    agentResult: undefined,
+    sessionFile: undefined,
+    controller: undefined,
+    ...overrides,
+  } as ExecutionRecord;
+}
+
+function makeMinimalResult(): AgentResult {
+  return {
+    text: "done",
+    turns: 1,
+    durationMs: 100,
+    success: true,
+    sessionId: "sess-1",
+    toolCalls: [],
+  };
+}
+
+describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
+  let tmpDir: string;
+  let manifestStore: ManifestStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "finalize-test-"));
+    manifestStore = new ManifestStore(tmpDir);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  /** 构造最小 FinalizeDeps：record 无 sessionFile/worktreeHandle,跳过 Step 0/3 文件操作。 */
+  function makeDeps() {
+    return {
+      manifestStore,
+      worktreeManager: {} as never,
+      store: { archive: vi.fn() } as never,
+      modelService: {} as never,
+      pi: { appendEntry: vi.fn() },
+      clearThrottle: vi.fn(),
+      emitUnregister: vi.fn(),
+    };
+  }
+
+  it("status=cancelled → manifest 写 cancelled（不再归并 failed）", async () => {
+    const record = makeMinimalRecord({ id: "rec-cancelled" });
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "cancelled");
+
+    const manifest = await manifestStore.readManifest("rec-cancelled");
+    expect(manifest).not.toBeNull();
+    // 关键断言：cancelled 直接透传,不是 "failed"
+    expect(manifest?.status).toBe("cancelled");
+  });
+
+  it("status=done → manifest 写 completed", async () => {
+    const record = makeMinimalRecord({ id: "rec-done" });
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "done");
+
+    const manifest = await manifestStore.readManifest("rec-done");
+    expect(manifest?.status).toBe("completed");
+  });
+
+  it("status=failed → manifest 写 failed", async () => {
+    const record = makeMinimalRecord({ id: "rec-failed" });
+    await doFinalizeRecord(makeDeps(), record, makeMinimalResult(), "failed");
+
+    const manifest = await manifestStore.readManifest("rec-failed");
+    expect(manifest?.status).toBe("failed");
+  });
+
+  it("manifest write 抛错时 cleanup-first 顺序仍执行（Step 3 before Step 4 throw）", async () => {
+    // record 带 sessionFile 让 Step 3 finalized/aliveMarker 走真实路径；
+    // 不设 worktreeHandle → Step 0 (collectPatch) 和 Step 3 worktree cleanup 都跳过。
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    const record = makeMinimalRecord({ id: "rec-cleanup-first", sessionFile });
+
+    // 预写 .alive marker（让 removeAliveMarker 真实生效；不预写因 ENOENT 静默也 OK，
+    // 但预写后用 fs.existsSync 验证更直观）。
+    fs.writeFileSync(
+      `${sessionFile}.alive`,
+      `${JSON.stringify({ pid: 99999, id: "rec-cleanup-first", startedAt: 1000 })}\n`,
+      "utf-8",
+    );
+
+    // mock writeManifest 抛错（模拟 disk full）。在 mock 内捕获「writeManifest 被调用时
+    // finalized marker 是否已存在」——这是 cleanup-first 顺序的关键断言：若有人把
+    // manifest write 前移到 cleanup 之前，本标志会是 false（[Critical #1] 反例）。
+    const finalizedBeforeManifestWrite = { value: false };
+    vi.spyOn(manifestStore, "writeManifest").mockImplementation(async () => {
+      finalizedBeforeManifestWrite.value = fs.existsSync(`${sessionFile}.finalized`);
+      throw new Error("disk full");
+    });
+    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    const deps = makeDeps();
+
+    // ── 核心 claim 1：不抛错（cleanup-first → manifest write 失败不 throw）──
+    await expect(
+      doFinalizeRecord(deps, record, makeMinimalResult(), "done"),
+    ).resolves.toBeUndefined();
+
+    // ── 核心 claim 2：Step 3 cleanup 先执行 —— finalized marker 真实写入 ──
+    expect(fs.existsSync(`${sessionFile}.finalized`)).toBe(true);
+
+    // ── 核心 claim 3：Step 3 aliveMarker 被移除（预写的 .alive 不再存在）──
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+
+    // ── 核心 claim 4：pending-notifications 注销仍触发（emitUnregister）──
+    expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "done");
+
+    // ── 核心 claim 5：manifest 写失败被 console.error 记录（含 record id + error）──
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
+    const errMsg = consoleErrorSpy.mock.calls[0]?.[0];
+    expect(errMsg).toContain("rec-cleanup-first");
+    expect(errMsg).toContain("disk full");
+
+    // ── 核心 claim 6：pi.appendEntry 记录 "subagent:manifest-write-failed" 事件 ──
+    expect(deps.pi.appendEntry).toHaveBeenCalledWith(
+      "subagent:manifest-write-failed",
+      expect.objectContaining({ id: "rec-cleanup-first", error: "disk full" }),
+    );
+
+    // ── 核心 claim 7：manifest 实际未写入（writeManifest 抛错被吞咽）──
+    expect(await manifestStore.readManifest("rec-cleanup-first")).toBeNull();
+
+    // ── 核心 claim 8：[Critical #1] cleanup 在 manifest 写之前 —— 顺序锁定 ──
+    // 若有人把 manifest write 前移到 cleanup 之前，本标志会是 false（mock 捕获时刻
+    // .finalized 尚未被 Step 3 写入），保护 Critical #1 时序不变量。
+    expect(finalizedBeforeManifestWrite.value).toBe(true);
+
+    // 清理 spy 防止污染其他测试
+    consoleErrorSpy.mockRestore();
+  });
+});

package/src/execution/__tests__/gui-mode-dispatch.test.ts

@@ -8,12 +8,11 @@
 // adapter() 是纯函数，ctx.mode === "rpc" → details.__gui__ 被附加，
 // ctx.mode === "tui"/"json"/"print" → details.__gui__ 为 undefined。
 
-import { describe, expect, it } from "vitest";
-
 import type { GuiContext } from "@xyz-agent/extension-protocol";
+import { describe, expect, it } from "vitest";
 
-import { adapter } from "../../interface/subagent-actions.ts";
 import type { AdapterInput } from "../../interface/subagent-actions.ts";
+import { adapter } from "../../interface/subagent-actions.ts";
 
 function makeStartInput(): AdapterInput {
 	return {

package/src/execution/__tests__/helpers/spawn-mock.ts

@@ -0,0 +1,209 @@
+// src/execution/__tests__/helpers/spawn-mock.ts
+//
+// run-spawn-* 三文件（integration/edges/rpc-mode）共享的 FakeChild + 工具函数。
+//
+// 背景：vitest 的 vi.mock 会被提升到文件顶部，工厂函数体内**不能引用顶层 import 的变量**
+//（vitest 官方文档明确警告）。例外：async 工厂内可用 `await import()`（在模块需求时执行，
+// 此时所有模块已加载）。故本 helper 不导出「mock 工厂函数」（无法被 vi.mock 顶层引用），
+// 而是导出 **FakeChild class + 工具函数**，让各测试文件的 vi.mock 工厂用 `await import`
+// 动态取回 FakeChild。这样每个 vi.mock 工厂从 ~15 行（定义 class + vi.fn）缩到 ~4 行，
+// 且 FakeChild 定义只有一个权威来源。
+//
+// 共享内容（原 ~80 行 × 3 重复）：
+//   - FakeChild：EventEmitter + PassThrough stdout/stderr/stdin + kill 记录（class 定义）
+//   - lastSpawnedChild(mockSpawn)：从 mock.results 取回最近 spawn 返回的 FakeChild
+//   - waitForSpawn(mockSpawn)：轮询等 spawn 被调（比 vi.waitFor 在该 vitest 版本下可靠）
+//   - emitStdoutLine / sessionHeader：构造 stdout 行的辅助
+//   - makeRecord / makeOpts / makeCtx：构造最小合法的 record/opts/ctx（3 文件一致）
+//
+// 各测试文件 vi.mock 模式（每文件独立声明，vitest 的 vi.mock 是文件作用域）：
+//   ```ts
+//   vi.mock("node:child_process", async () => {
+//     const { EventEmitter } = await import("node:events");
+//     const events = { EventEmitter }; // 兼容旧注释
+//     const { FakeChild } = await import("./helpers/spawn-mock.ts");
+//     return {
+//       spawn: vi.fn(() => new FakeChild()),
+//       execFileSync: vi.fn(() => ""),
+//     };
+//   });
+//   vi.mock("node:fs", async () => {
+//     const actual = await import("node:fs");
+//     return {
+//       default: { ...actual, mkdirSync: vi.fn(), existsSync: vi.fn(() => false),
+//                   appendFileSync: vi.fn(), writeFileSync: vi.fn(), readdirSync: vi.fn(() => []) },
+//       mkdirSync: vi.fn(), existsSync: vi.fn(() => false),
+//       appendFileSync: vi.fn(), writeFileSync: vi.fn(), readdirSync: vi.fn(() => []),
+//       promises: actual.promises,
+//     };
+//   });
+//   vi.mock("../alive-store.ts", () => ({ writeAliveMarker: vi.fn() }));
+//   vi.mock("../temp-prompt.ts", () => ({
+//     writePromptToTempFile: vi.fn(async (agent: string) => {
+//       const safeName = agent.replace(/[^\w.-]+/g, "_");
+//       return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+//     }),
+//     cleanupTempPrompt: vi.fn(async () => {}),
+//   }));
+//   ```
+
+import type { ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+
+import { createRecord } from "../../execution-record.ts";
+import type { RunOptions, SessionRunnerContext } from "../../session-runner.ts";
+
+/**
+ * FakeChild：模拟 ChildProcess（EventEmitter + PassThrough streams）。
+ *
+ * 测试通过 mockSpawn.mock.results.at(-1).value 取回实例，控制 emit data/close/error 时序。
+ *
+ * 导出 class（而非只在工厂内部定义）是为了：
+ *   1. vi.mock 工厂内 `await import("./helpers/spawn-mock.ts")` 后 `new FakeChild()` 与
+ *      测试侧 `instanceof FakeChild` / 类型断言用同一个 class。
+ *   2. C13 e2e 测试可直接 `new FakeChild()` 手动构造 child 喂给 ui-request-queue（不经 spawn）。
+ */
+export class FakeChild extends EventEmitter {
+  pid = 12345;
+  stdout = new PassThrough();
+  stderr = new PassThrough();
+  stdin = new PassThrough();
+  killed = false;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean {
+    this.killed = true;
+    this.killSignal = sig;
+    return true;
+  }
+}
+
+/**
+ * spawn mock 返回的 fake child 类型（结构子集）。
+ *
+ * 测试文件优先 import { FakeChild } 用真实 class 类型；此 interface 仅为兼容现有
+ * describe 块内 `child: FakeChild` 的类型注解风格（与原代码一致，降低 diff 噪声）。
+ */
+export interface FakeChildLike {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  stdin: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+/**
+ * 从最近一次 spawn 调用取回返回的 FakeChild（测试控制器）。
+ *
+ * @param mockSpawn 调用方用 `vi.mocked(spawn)` 取回的 mock 引用
+ */
+export function lastSpawnedChild<
+  T extends { mock: { results: Array<{ value: ChildProcess | unknown }> } },
+>(mockSpawn: T): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+/**
+ * 等待 runSpawn 内部调到 spawn（拿到 child 控制器）。
+ *
+ * runSpawn 是 async，spawn 在 mkdirSync + writePromptToTempFile 之后才调（均有微任务/
+ * I/O 延迟）。用 setTimeout 轮询 mockSpawn.mock.results，比 vi.waitFor 在该 vitest 版本
+ * 下更可靠（vi.waitFor 偶发过早 resolve 导致后续读取竞态）。
+ *
+ * @param mockSpawn 调用方用 `vi.mocked(spawn)` 取回的 mock 引用
+ */
+export async function waitForSpawn<
+  T extends { mock: { results: unknown[] } },
+>(mockSpawn: T, timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length === 0) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn was not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+/** 向 stdout 写一行（自动补换行，runSpawn 按 \n split 行）。 */
+export function emitStdoutLine(child: FakeChild, obj: Record<string, unknown>): void {
+  child.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+
+/** 构造 session header 行（stdout 首行）。 */
+export function sessionHeader(id = "sess-abc"): Record<string, unknown> {
+  return {
+    type: "session",
+    id,
+    timestamp: "2026-07-03T12-00-00-000Z",
+    cwd: "/tmp/test",
+  };
+}
+
+/**
+ * 让 sessionFile 存在校验通过——runSpawn 在进程退出后用 existsSync(record.sessionFile)
+ * 判断是否补写 identity。默认 mock existsSync 返回 false（兜底查找），此 helper 在指定
+ * 路径返回 true。
+ */
+export function mockSessionFileExists(
+  mockExistsSync: { mockImplementation: (fn: (p: unknown) => boolean) => void },
+  sessionFilePath: string,
+): void {
+  mockExistsSync.mockImplementation((p: unknown) => String(p) === sessionFilePath);
+}
+
+// ── record / opts / ctx 构造（3 文件一致的最小合法形状）──
+
+/** 构造最小合法的 ExecutionRecord（runSpawn 入参）。 */
+export function makeRecord() {
+  return createRecord("run-1", {
+    agent: "general-purpose",
+    model: "test-model",
+    mode: "sync",
+    task: "do something",
+    startedAt: 1_000_000,
+    rootSessionId: "root-session",
+    parentRecordId: undefined,
+    depth: 0,
+  });
+}
+
+/** 构造最小合法的 RunOptions（runSpawn 入参，可 override 关键字段）。 */
+export function makeOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: {
+      model: {
+        id: "test-model",
+        name: "Test Model",
+        provider: "test",
+        reasoning: false,
+      },
+      thinkingLevel: undefined,
+    },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+/** 构造最小合法的 SessionRunnerContext（runSpawn 入参，可 override 关键字段）。 */
+export function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/tmp/test",
+    agentDir: "/tmp/test/agents",
+    skillDirs: [],
+    mainCwd: "/tmp/test",
+    mainSessionFile: undefined,
+    ...overrides,
+  };
+}

package/src/execution/__tests__/host-mode.test.ts

@@ -0,0 +1,87 @@
+// src/__tests__/host-mode.test.ts
+//
+// W1 红灯测试：host-mode.ts 主进程运行模式分类工具。
+//
+// 测试对象：extensions/subagent-workflow/src/execution/host-mode.ts（新建）
+// 契约来源：.fix-plans/00-master-summary.md §一 冲突 4 + §2.5（W4 守卫消费点）
+//
+// 三个导出：
+//   - resolveHostMode(mode): ExtensionMode | undefined → "tui" | "gui" | "headless"
+//   - willRespondToAskUser(mode): boolean（tui/gui → true，headless → false）
+//   - hasInteractiveUI(mode): boolean（非 headless → true）
+//
+// 红灯原因：host-mode.ts 尚未创建，import 失败。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  hasInteractiveUI,
+  resolveHostMode,
+  willRespondToAskUser,
+} from "../host-mode.ts";
+
+describe("resolveHostMode — ExtensionMode 聚合为 HostMode", () => {
+  it('"tui" → "tui"（纯 Pi TUI，ctx.ui.custom 可用）', () => {
+    expect(resolveHostMode("tui")).toBe("tui");
+  });
+
+  it('"rpc" → "gui"（xyz-agent GUI，sidecar 通道）', () => {
+    expect(resolveHostMode("rpc")).toBe("gui");
+  });
+
+  it('"json" → "headless"（无交互通道）', () => {
+    expect(resolveHostMode("json")).toBe("headless");
+  });
+
+  it('"print" → "headless"（无交互通道）', () => {
+    expect(resolveHostMode("print")).toBe("headless");
+  });
+
+  it('undefined → "headless"（向后兼容：mode 未穿透时按 headless）', () => {
+    expect(resolveHostMode(undefined)).toBe("headless");
+  });
+});
+
+describe("willRespondToAskUser — 主进程是否响应子进程 ask_user", () => {
+  it("tui → true（冲突 3 裁决：TUI 必须注入 handler）", () => {
+    expect(willRespondToAskUser("tui")).toBe(true);
+  });
+
+  it("rpc → true（GUI 透传所有 UI）", () => {
+    expect(willRespondToAskUser("rpc")).toBe(true);
+  });
+
+  it("json → false（headless 无 UI 通道）", () => {
+    expect(willRespondToAskUser("json")).toBe(false);
+  });
+
+  it("print → false（headless 无 UI 通道）", () => {
+    expect(willRespondToAskUser("print")).toBe(false);
+  });
+
+  it("undefined → false（向后兼容）", () => {
+    expect(willRespondToAskUser(undefined)).toBe(false);
+  });
+});
+
+describe("hasInteractiveUI — 是否有交互 UI 通道", () => {
+  it("tui → true", () => {
+    expect(hasInteractiveUI("tui")).toBe(true);
+  });
+
+  it("rpc → true", () => {
+    expect(hasInteractiveUI("rpc")).toBe(true);
+  });
+
+  it("json → false", () => {
+    expect(hasInteractiveUI("json")).toBe(false);
+  });
+
+  it("print → false", () => {
+    expect(hasInteractiveUI("print")).toBe(false);
+  });
+
+  it("undefined → false", () => {
+    expect(hasInteractiveUI(undefined)).toBe(false);
+  });
+});