@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/spawn-event-adapter.test.ts

@@ -0,0 +1,167 @@
+// src/__tests__/spawn-event-adapter.test.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import {
+  deriveSessionFilePath,
+  findSessionFileByHeaderId,
+  parseSpawnLine,
+} from "../spawn-event-adapter.ts";
+
+describe("parseSpawnLine", () => {
+  describe("空白行", () => {
+    it("空字符串返回 null", () => {
+      expect(parseSpawnLine("")).toBeNull();
+    });
+
+    it("纯空白返回 null", () => {
+      expect(parseSpawnLine("   ")).toBeNull();
+      expect(parseSpawnLine("\t\t")).toBeNull();
+    });
+  });
+
+  describe("header 行", () => {
+    it("type=session + id 识别为 header", () => {
+      const line = JSON.stringify({
+        type: "session",
+        id: "abc-123",
+        timestamp: "2026-07-03T12:00:00.000Z",
+        cwd: "/home/user/project",
+      });
+      const result = parseSpawnLine(line);
+      expect(result?.kind).toBe("header");
+      if (result?.kind === "header") {
+        expect(result.header.id).toBe("abc-123");
+        expect(result.header.cwd).toBe("/home/user/project");
+      }
+    });
+
+    it("header 含 parentSession + version", () => {
+      const line = JSON.stringify({
+        type: "session",
+        id: "child-456",
+        timestamp: "2026-07-03T12:00:00.000Z",
+        cwd: "/home/user/project",
+        parentSession: "parent-789",
+        version: 2,
+      });
+      const result = parseSpawnLine(line);
+      expect(result?.kind).toBe("header");
+      if (result?.kind === "header") {
+        expect(result.header.parentSession).toBe("parent-789");
+        expect(result.header.version).toBe(2);
+      }
+    });
+  });
+
+  describe("事件行", () => {
+    it("tool_execution_start 识别为 event", () => {
+      const line = JSON.stringify({
+        type: "tool_execution_start",
+        toolName: "bash",
+        toolCallId: "call-1",
+        args: { command: "ls" },
+      });
+      const result = parseSpawnLine(line);
+      expect(result?.kind).toBe("event");
+      if (result?.kind === "event") {
+        expect(result.event.type).toBe("tool_execution_start");
+        expect(result.event.toolName).toBe("bash");
+      }
+    });
+
+    it("message_end 识别为 event", () => {
+      const line = JSON.stringify({
+        type: "message_end",
+        message: {
+          role: "assistant",
+          usage: { input: 100, output: 50 },
+        },
+      });
+      const result = parseSpawnLine(line);
+      expect(result?.kind).toBe("event");
+      if (result?.kind === "event") {
+        expect(result.event.type).toBe("message_end");
+      }
+    });
+
+    it("turn_end 识别为 event", () => {
+      const result = parseSpawnLine(JSON.stringify({ type: "turn_end" }));
+      expect(result?.kind).toBe("event");
+    });
+
+    it("未知 type 仍识别为 event（schema 校验由调用方）", () => {
+      const result = parseSpawnLine(JSON.stringify({ type: "some_future_event" }));
+      expect(result?.kind).toBe("event");
+    });
+  });
+
+  describe("invalid 行", () => {
+    it("非 JSON 返回 invalid", () => {
+      const result = parseSpawnLine("not json at all");
+      expect(result?.kind).toBe("invalid");
+      if (result?.kind === "invalid") {
+        expect(result.raw).toBe("not json at all");
+        expect(result.error).toBeTruthy();
+      }
+    });
+
+    it("JSON 但无 type 字段返回 invalid", () => {
+      const result = parseSpawnLine(JSON.stringify({ foo: "bar" }));
+      expect(result?.kind).toBe("invalid");
+      if (result?.kind === "invalid") {
+        expect(result.error).toContain("type");
+      }
+    });
+
+    it("JSON 但 type 非 string 返回 invalid", () => {
+      const result = parseSpawnLine(JSON.stringify({ type: 123 }));
+      expect(result?.kind).toBe("invalid");
+    });
+
+    it("JSON null 返回 invalid", () => {
+      const result = parseSpawnLine("null");
+      expect(result?.kind).toBe("invalid");
+    });
+  });
+});
+
+describe("deriveSessionFilePath", () => {
+  it("拼接 sessionDir + fileTimestamp(冒号点转连字符) + id", () => {
+    const header = {
+      type: "session" as const,
+      id: "abc-123",
+      timestamp: "2026-07-03T12:00:00.000Z",
+      cwd: "/proj",
+    };
+    const path = deriveSessionFilePath(header, "/sessions/dir");
+    // fileTimestamp = timestamp.replace(/[:.]/g, "-") = "2026-07-03T12-00-00-000Z"
+    expect(path).toBe("/sessions/dir/2026-07-03T12-00-00-000Z_abc-123.jsonl");
+  });
+});
+
+describe("findSessionFileByHeaderId", () => {
+  it("sessionId 后缀匹配返回实际文件路径", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "spawn-adapter-test-"));
+    const expectedFile = path.join(tmpDir, "2026-07-03T12-00-00-000Z_sid-456.jsonl");
+    fs.writeFileSync(expectedFile, "{}");
+    const result = findSessionFileByHeaderId(tmpDir, "sid-456");
+    expect(result).toBe(expectedFile);
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("无匹配返回 undefined", () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "spawn-adapter-test-"));
+    const result = findSessionFileByHeaderId(tmpDir, "nonexistent");
+    expect(result).toBeUndefined();
+    fs.rmSync(tmpDir, { recursive: true });
+  });
+
+  it("目录不存在返回 undefined（不抛错）", () => {
+    const result = findSessionFileByHeaderId("/nonexistent/path/xyz", "sid");
+    expect(result).toBeUndefined();
+  });
+});

package/src/execution/__tests__/spawn-worktree-guidance.test.ts

@@ -0,0 +1,207 @@
+// src/execution/__tests__/spawn-worktree-guidance.test.ts
+//
+// worktree 模式认知纠正提示注入测试。
+//
+// 背景：worktree checkout 放 os.tmpdir()（路径形似临时沙箱），子 agent 无 worktree 语义
+// 提示时误判 cwd 为"空隔离目录"，主动 cd 别处放弃隔离（wave-agent 事故 session 019ff64c）。
+// 修复在 runSpawn 的 appendParts 注入 WORKTREE_GUIDANCE_PROMPT。
+//
+// 验证：
+//   - worktree 模式（opts.worktree 传入）→ appendSystemPrompt content 含 WORKTREE_GUIDANCE_PROMPT
+//   - 非 worktree 模式 → content 不含 worktree 提示
+//
+// 测试策略：mock writePromptToTempFile 捕获拼接后的 appendParts content（vi.hoisted 防
+// vi.mock hoisting 引用未初始化变量），断言含/不含 worktree 提示标识。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 捕获 writePromptToTempFile 的 content 参数（appendParts.join("\n\n")）。
+// vi.hoisted 保证变量在 vi.mock factory hoisting 前已声明可用。
+const captured = vi.hoisted(() => ({ content: "" }));
+
+// ── mock modules（与 session-runner-schema-env.test.ts 同模式）──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stdin = new PassThrough(); // runSpawn 注册 stdin EPIPE handler（session-runner），FakeChild 必须提供
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  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, content: string) => {
+    captured.content = content;
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import { createRecord } from "../execution-record.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function getLastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+async function waitForSpawn(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));
+  }
+}
+
+function makeRecord() {
+  return createRecord("wt-guidance-1", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "sync",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "s1",
+    parentRecordId: undefined,
+    depth: 0,
+  });
+}
+
+function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-session-test",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+describe("worktree guidance prompt injection", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.content = "";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("worktree 模式 → appendSystemPrompt content 含 worktree 认知纠正提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts({
+      worktree: {
+        path: "/tmp/pi-subagents/--fake--/pi-sub-sa-wt-guidance-1",
+        branch: "pi-sub-sa-wt-guidance-1",
+        baseCommit: "abc123",
+        mainCwd: "/fake/cwd",
+      },
+    });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    // content 含 WORKTREE_GUIDANCE_PROMPT 的标题
+    expect(captured.content).toContain("Git Worktree");
+    // 含关键纠正信息：cwd 含完整项目代码（非临时沙箱）
+    expect(captured.content).toContain("complete project source code");
+    // 含防 cd 别处的行为指引
+    expect(captured.content).toContain("Do NOT");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("非 worktree 模式 → content 不含 worktree 认知提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts(); // 不传 worktree
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    expect(captured.content).not.toContain("Git Worktree");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

package/src/execution/__tests__/spawned-children.test.ts

@@ -0,0 +1,92 @@
+// src/execution/__tests__/spawned-children.test.ts
+//
+// spawnedChildren Map + getChildByRecord + killAllSpawnedChildren 单元测试（M2-B1）。
+//
+// M2-B1 把 spawnedChildren 从 Set<ChildProcess> 改为 Map<recordId, ChildProcess>，
+// 建立 record→child 映射（busy 投递定位活进程用，设计决策 6）。本文件测 Map API 核心行为：
+//   - getChildByRecord：set 后能查到；delete 后查不到；未注册返回 undefined
+//   - killAllSpawnedChildren：遍历 .values() kill + clear；跳过 child.killed=true；单 child kill 抛错不阻断
+//
+// 直接操作模块级 spawnedChildren（afterEach clear 防泄漏），不依赖 runSpawn/spawn/fs。
+
+import type { ChildProcess } from "node:child_process";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+}));
+vi.mock("../../core/logger.ts", () => ({ getLogger: () => loggerMock }));
+
+import { getChildByRecord, killAllSpawnedChildren, spawnedChildren } from "../session-runner.ts";
+
+/** 假 child：只关心 killed 标记 + kill 调用（killAllSpawnedChildren 遍历用）。 */
+function makeFakeChild(killed = false): ChildProcess & { kill: ReturnType<typeof vi.fn> } {
+  return { killed, kill: vi.fn() } as unknown as ChildProcess & { kill: ReturnType<typeof vi.fn> };
+}
+
+describe("spawnedChildren Map + getChildByRecord (M2-B1)", () => {
+  afterEach(() => {
+    spawnedChildren.clear();
+  });
+
+  it("set(recordId, child) 后 getChildByRecord 能查到；未注册返回 undefined", () => {
+    const child = makeFakeChild();
+    spawnedChildren.set("rec-1", child);
+    expect(getChildByRecord("rec-1")).toBe(child);
+    expect(getChildByRecord("rec-2")).toBeUndefined();
+  });
+
+  it("delete(recordId) 后 getChildByRecord 返回 undefined（close/error 回调语义）", () => {
+    const child = makeFakeChild();
+    spawnedChildren.set("rec-1", child);
+    spawnedChildren.delete("rec-1");
+    expect(getChildByRecord("rec-1")).toBeUndefined();
+  });
+
+  it("killAllSpawnedChildren 遍历 .values() 对每个未 killed child kill + clear", () => {
+    const c1 = makeFakeChild();
+    const c2 = makeFakeChild();
+    spawnedChildren.set("rec-a", c1);
+    spawnedChildren.set("rec-b", c2);
+
+    const n = killAllSpawnedChildren();
+
+    expect(n).toBe(2);
+    expect(c1.kill).toHaveBeenCalledTimes(1);
+    expect(c2.kill).toHaveBeenCalledTimes(1);
+    expect(spawnedChildren.size).toBe(0);
+  });
+
+  it("killAllSpawnedChildren 跳过 child.killed=true（不重复 kill 已 kill 的）", () => {
+    const alive = makeFakeChild(false);
+    const alreadyKilled = makeFakeChild(true);
+    spawnedChildren.set("rec-1", alive);
+    spawnedChildren.set("rec-2", alreadyKilled);
+
+    const n = killAllSpawnedChildren();
+
+    expect(n).toBe(1);
+    expect(alive.kill).toHaveBeenCalledTimes(1);
+    expect(alreadyKilled.kill).not.toHaveBeenCalled();
+    expect(spawnedChildren.size).toBe(0);
+  });
+
+  it("killAllSpawnedChildren 对单个 child kill 抛错不阻断其他（best-effort catch）", () => {
+    const ok = makeFakeChild();
+    const throwy = makeFakeChild();
+    throwy.kill.mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    spawnedChildren.set("rec-1", ok);
+    spawnedChildren.set("rec-2", throwy);
+
+    const n = killAllSpawnedChildren();
+
+    // throwy 抛错被 catch，不计入 n；ok 正常 kill。两者都调过 kill，Map 已 clear。
+    expect(n).toBe(1);
+    expect(ok.kill).toHaveBeenCalledTimes(1);
+    expect(throwy.kill).toHaveBeenCalledTimes(1);
+    expect(spawnedChildren.size).toBe(0);
+  });
+});

package/src/execution/__tests__/start-sync-model-guard.test.ts

@@ -0,0 +1,150 @@
+// src/execution/__tests__/start-sync-model-guard.test.ts
+//
+// [U1 验收 3] start 同步期裁决：非全等 model 入参在 start 工具调用同步期 isError——
+// 无 spawn、无子 session、record 不落盘。
+//
+// 用真实 SubagentService（tmpdir + mock pi）走 execute 全链路，断言：
+//   1. execute 在 IDENTITY 解析（resolveModel 裁决）阶段 reject（问句式报错）；
+//   2. buildSpawnArgs 从未被调用（vi.mock spy 包装真实实现）——spawn 前置守卫的结构性证据；
+//   3. node:child_process.spawn 从未被调用——无子进程；
+//   4. pi.appendEntry 从未被调用——record 未创建（emitPendingRegister 未发生）。
+//
+// 放行路径（全等 → 裁决通过）由 model-ref.test.ts / model-resolver.test.ts 锁定，
+// 全链路放行的 spawn 行为由 run-spawn-* 契约测试覆盖。
+
+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 { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("node:child_process", async () => {
+  const actual = await import("node:child_process");
+  return {
+    ...actual,
+    spawn: vi.fn(() => {
+      throw new Error("spawn must not be called on sync-model rejection");
+    }),
+  };
+});
+
+// buildSpawnArgs 包装为 spy（保留真实实现）——「非全等拒单不触达 spawn 参数组装」的承重断言。
+vi.mock("../session-runner.ts", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../session-runner.ts")>();
+  return { ...actual, buildSpawnArgs: vi.fn(actual.buildSpawnArgs) };
+});
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import { buildSpawnArgs } from "../session-runner.ts";
+import type { PiLike } from "../subagent-service.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockBuildSpawnArgs = vi.mocked(buildSpawnArgs);
+
+// ── 工具 ──
+
+function makeModel(over: Partial<ModelInfo> = {}): ModelInfo {
+  return {
+    id: over.id ?? "GLM-5.3-Flash",
+    name: over.name ?? "GLM 5.3 Flash",
+    provider: over.provider ?? "zai-coding-cn",
+    reasoning: over.reasoning ?? false,
+    ...over,
+  };
+}
+
+/** registry 快照：真实形态（大小写混合 id），无孪生（P-A2 放行快照形态）。 */
+function makeRegistry(models: ModelInfo[]): ModelRegistryLike {
+  return {
+    getAvailable: () => models,
+    find: (provider, modelId) => models.find((m) => m.provider === provider && m.id === modelId),
+    hasConfiguredAuth: () => true,
+  };
+}
+
+function makePi(): PiLike {
+  return {
+    appendEntry: vi.fn(),
+    events: { emit: vi.fn() },
+    sendMessage: vi.fn(),
+  } as unknown as PiLike;
+}
+
+describe("start 同步期裁决（U1 验收 3：非全等 → isError 且无 spawn 无子 session）", () => {
+  let tmpDir: string;
+  let service: SubagentService;
+  let pi: PiLike;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "sw-start-guard-"));
+    const modelService = new ModelConfigService({ agentDir: tmpDir, cwd: tmpDir });
+    modelService.initModel({
+      modelRegistry: makeRegistry([makeModel()]),
+      sessionId: "guard-session",
+    });
+    service = new SubagentService({ cwd: tmpDir, modelService });
+    pi = makePi();
+    service.initSession({ pi, sessionId: "guard-session" });
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("小写变体入参 → execute 同步 reject（问句式报错），buildSpawnArgs/spawn/appendEntry 均未被调", async () => {
+    await expect(
+      service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      }),
+    ).rejects.toThrow(/is not a registry entry.*Did you mean one of these\?/s);
+
+    // spawn 链路零触达：参数组装（buildSpawnArgs）与进程创建（spawn）都未发生
+    expect(mockBuildSpawnArgs).not.toHaveBeenCalled();
+    expect(mockSpawn).not.toHaveBeenCalled();
+    // record 未创建（emitPendingRegister 未发生）→ 无子 session 前置状态
+    expect(pi.appendEntry).not.toHaveBeenCalled();
+  });
+
+  it("错误含 case variant 首位建议 + 继承指引（可直接重发的合法串）", async () => {
+    let msg = "";
+    try {
+      await service.execute({
+        task: "probe task",
+        slug: "guard",
+        model: "zai-coding-cn/glm-5.3-flash",
+      });
+    } catch (e) {
+      msg = (e as Error).message;
+    }
+    expect(msg).toContain('zai-coding-cn/GLM-5.3-Flash   ← case variant of "glm-5.3-flash"');
+    expect(msg).toMatch(/Or omit the `model` param to inherit the main agent model\./);
+  });
+
+  it("全等入参通过裁决（reject 不发生，放行链路触达 spawn 参数组装）——守卫零误伤对照", async () => {
+    // 放行路径会进入 kickOffBackground（detached）；execute resolve 即视为裁决放行。
+    // spawn 本身由 FakeChild 缺失抛错收口——本断言只关心「越过了同步裁决」：
+    // execute 不 reject，且 buildSpawnArgs 已被调（或即将被调的 record 已创建）。
+    const promise = service.execute({
+      task: "probe task",
+      slug: "guard-exact",
+      model: "zai-coding-cn/GLM-5.3-Flash",
+    });
+    // 放行路径：裁决不抛（execute 最终可能因 mock 环境子进程收尾而 reject，
+    // 但错误不能是模型裁决错误）
+    try {
+      await promise;
+    } catch (e) {
+      expect((e as Error).message).not.toMatch(/is not a registry entry/);
+      expect((e as Error).message).not.toMatch(/ambiguous case variants/);
+    }
+    // 全等放行 → record 已创建（emitPendingRegister 发生）——与拒单路径形成对照
+    expect(pi.appendEntry).toHaveBeenCalled();
+  });
+});