@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/recursive-visibility-env.test.ts

@@ -0,0 +1,273 @@
+// src/__tests__/recursive-visibility-env.test.ts
+//
+// 递归 subagent 跨层可见性：env 身份贯穿验证（设计 docs/design/recursive-subagent-visibility.md 场景 1b）。
+//
+// 验证 runSpawn 构造的 childEnv 含 4 个 PI_SUBAGENT_* 身份 env，值 = ctx.sessionRootId /
+// record.id / String(record.depth) / ctx.rootCwd（[MF-3] 第 4 个：ROOT cwd，落盘目录编码键）。覆盖 opts.fork=true 与 opts.fork=false 两种（决策 2 无条件注入）。
+//
+// 这是场景 1（端到端三层嵌套全树可见）的「env 传递机制」确定性验证——不依赖 LLM 配合，
+// mock spawn 拦截 childEnv 直接断言。端到端可见性由场景 1（真实 pi CLI + recursive-worker agent）覆盖。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getSubagentSessionDir } from "../path-encoding.ts";
+
+// ── 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()),
+    // buildEnvBlock 用 execFile 异步取 git branch：默认 err-first 兜底（catch → branch=""），
+    // 形态同 worktree-manager.test.ts 的 setupExecFile
+    execFile: vi.fn(
+      (
+        _cmd: string,
+        _args: readonly string[],
+        _opts: unknown,
+        cb: (err: Error | null, stdout?: string, stderr?: string) => void,
+      ) => cb(new Error("execFile not configured in this test")),
+    ),
+  };
+});
+
+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 { spawn } from "node:child_process";
+import * as fs from "node:fs";
+
+import { waitForSpawn } from "./helpers/spawn-mock.ts";
+import { createRecord } from "../execution-record.ts";
+import { type RunOptions, runSpawn, type SessionRunnerContext } from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+const mockExistsSync = vi.mocked(fs.existsSync);
+
+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;
+}
+
+function getLastSpawnEnv(): Record<string, string | undefined> {
+  return (mockSpawn.mock.calls.at(-1)?.[2]?.env as Record<string, string | undefined>) ?? {};
+}
+
+// ── fixture ──
+
+function makeRecord(overrides: { id?: string; depth?: number } = {}) {
+  return createRecord(overrides.id ?? "sa-test-record", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "background",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "should-be-overridden-by-sessionRootId-source",
+    parentRecordId: undefined,
+    depth: overrides.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-main-session",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+// ── runSpawn childEnv 身份 env 注入（场景 1b）──
+
+describe("runSpawn 跨进程身份 env 注入（递归可见性场景 1b）", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockExistsSync.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("非 fork（fork=false/undefined）：无条件注入 4 个身份 env（决策 2）", async () => {
+    const record = makeRecord({ id: "sa-aaa", depth: 0 });
+    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const opts = makeRunOpts({ fork: false });
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-aaa");
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("0");
+    // [MF-3] 第 4 个贯穿 env：ROOT cwd（子进程落盘目录编码键）
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe("/fake/cwd");
+    // fork=false 不注入 fork depth env（与既有行为一致，本测试不改变它）
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBeUndefined();
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("fork=true：4 个身份 env 与 fork depth env 共存（决策 2 无条件注入不依赖 fork）", async () => {
+    const record = makeRecord({ id: "sa-bbb", depth: 2 });
+    const ctx = makeCtx({ sessionRootId: "root-main" });
+    const opts = makeRunOpts({ fork: true, parentForkDepth: 1 });
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+
+    // 身份 env 无条件存在（决策 2）
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-main");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-bbb");
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("2");
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe("/fake/cwd");
+    // fork depth env 同时存在（fork=true + parentForkDepth=1 → 2）
+    expect(childEnv.PI_SUBAGENT_FORK_DEPTH).toBe("2");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("深层 record（depth=3）：DEPTH env = String(record.depth)，正确贯穿嵌套层级", async () => {
+    const record = makeRecord({ id: "sa-deep", depth: 3 });
+    const ctx = makeCtx({ sessionRootId: "root-topmost" });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+
+    expect(childEnv.PI_SUBAGENT_DEPTH).toBe("3");
+    expect(childEnv.PI_SUBAGENT_SELF_RECORD_ID).toBe("sa-deep");
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("root-topmost");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("ROOT_SESSION_ID 恒等于 ctx.sessionRootId（贯穿真 ROOT，非 record.rootSessionId）", async () => {
+    // record.rootSessionId 是 createRecord 时写入的值（可能来自旧逻辑），但 env 注入用的是
+    // ctx.sessionRootId（经 buildSessionRunnerContext 从 this.sessionRootId 透传，贯穿真 ROOT）。
+    // 这保证深层 subagent 的子进程仍归顶层 ROOT（设计决策 1/3）。
+    const record = makeRecord({ id: "sa-ccc" }); // record.rootSessionId = fixture 默认值
+    const ctx = makeCtx({ sessionRootId: "real-root-session" });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+
+    // env 用 ctx.sessionRootId，不是 record.rootSessionId
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).toBe("real-root-session");
+    expect(childEnv.PI_SUBAGENT_ROOT_SESSION_ID).not.toBe(record.rootSessionId);
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("[MF-3 回归] worktree 模式（mainCwd=checkout ≠ rootCwd）：sessionDir 用 ROOT cwd 编码，深层 record 落盘到 ROOT 可扫描段", async () => {
+    // 模拟 B（worktree 子进程）spawn C：ctx.cwd/mainCwd = checkout 路径，rootCwd = 真 ROOT cwd。
+    // 旧实现 sessionDir 用 ctx.mainCwd 编码 → enc(checkout) 段，ROOT 磁盘重建扫不到（MF-3）。
+    const rootCwd = "/root/project";
+    const checkoutPath = "/var/folders/worktree/pi-subagents/--root-project--/branch";
+    const agentDir = "/fake/agent";
+    const record = makeRecord({ id: "sa-deep", depth: 2 });
+    const ctx = makeCtx({ cwd: checkoutPath, mainCwd: checkoutPath, rootCwd, agentDir });
+
+    const resultPromise = runSpawn(record, "test task", makeRunOpts(), ctx);
+    await waitForSpawn(mockSpawn);
+    const childEnv = getLastSpawnEnv();
+    const spawnArgs = mockSpawn.mock.calls.at(-1)?.[1] as string[];
+
+    // 第 4 个 env 贯穿 ROOT cwd
+    expect(childEnv.PI_SUBAGENT_ROOT_CWD).toBe(rootCwd);
+    // spawn --session-dir 指向 enc(ROOT cwd)（非 enc(checkout)）
+    expect(spawnArgs).toContain(getSubagentSessionDir(agentDir, rootCwd));
+    expect(spawnArgs).not.toContain(getSubagentSessionDir(agentDir, checkoutPath));
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

package/src/execution/__tests__/relay-env.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  RELAY_ENV_NODE,
+  RELAY_ENV_RECORD_ID,
+  RELAY_ENV_SCRIPT,
+  RELAY_ENV_SESSION_ID,
+  RELAY_ENV_SOCKET,
+  RELAY_EXIT_CODES,
+  RELAY_PROTOCOL_VERSION,
+  isRelayActive,
+} from '../relay-env.js';
+
+describe('relay env SSOT', () => {
+  it('激活判定：三 env 同时非空', () => {
+    expect(isRelayActive({ [RELAY_ENV_SOCKET]: '/x.sock', [RELAY_ENV_NODE]: '/node', [RELAY_ENV_SCRIPT]: '/relay.mjs' })).toBe(true);
+  });
+
+  it('任一缺失即不激活（全有或全无）', () => {
+    const full = {
+      [RELAY_ENV_SOCKET]: '/x.sock',
+      [RELAY_ENV_NODE]: '/node',
+      [RELAY_ENV_SCRIPT]: '/relay.mjs',
+    };
+    expect(isRelayActive({ ...full, [RELAY_ENV_SOCKET]: '' })).toBe(false);
+    expect(isRelayActive({ ...full, [RELAY_ENV_NODE]: undefined })).toBe(false);
+    expect(isRelayActive({})).toBe(false);
+    expect(isRelayActive(process.env)).toBe(false);
+  });
+
+  it('env 名与退出码稳定（relay.mjs 镜像一致性由 conformance relay 断言锁定）', () => {
+    expect(RELAY_ENV_SESSION_ID).toBe('XYZ_SUBAGENT_RELAY_SESSION_ID');
+    expect(RELAY_ENV_RECORD_ID).toBe('XYZ_SUBAGENT_RELAY_RECORD_ID');
+    expect(RELAY_PROTOCOL_VERSION).toBe(1);
+    expect(RELAY_EXIT_CODES).toEqual({
+      VERSION_MISMATCH: 10,
+      SOCKET_UNREACHABLE: 11,
+      SOCKET_CLOSED: 12,
+      MISSING_IDENTITY: 13,
+    });
+  });
+});

package/src/execution/__tests__/resource-policy.test.ts

@@ -0,0 +1,109 @@
+// resource-policy 单测 —— SP-6 资源策略配置化（idleTimeoutMs + env 覆盖）。
+//
+// 测试策略：
+//   - 验证 armIdleTimer 的三层优先级：参数 > env XYZ_SUBAGENT_IDLE_TIMEOUT_MS > 默认 300000ms。
+//   - 用 vi.useFakeTimers() 控制时间流逝。
+//   - 每个用例 beforeEach/afterEach 清理 env + reset lifecycle state。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  DEFAULT_IDLE_TIMEOUT_MS,
+  _resetLifecycleState,
+  armIdleTimer,
+  hasIdleTimer,
+} from "../lifecycle-manager.ts";
+
+describe("resource-policy — SP-6 idleTimeoutMs 配置化", () => {
+  const ENV_KEY = "XYZ_SUBAGENT_IDLE_TIMEOUT_MS";
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    _resetLifecycleState();
+    // 清理 env，确保用例间隔离。
+    delete process.env[ENV_KEY];
+  });
+
+  afterEach(() => {
+    _resetLifecycleState();
+    vi.useRealTimers();
+    delete process.env[ENV_KEY];
+  });
+
+  // TC-1: idleTimeoutMs 参数透传生效
+  it("TC-1: explicit timeoutMs 参数直接生效（不看 env）", () => {
+    const onTimeout = vi.fn();
+    armIdleTimer("sa-tc1", onTimeout, 1234);
+
+    expect(hasIdleTimer("sa-tc1")).toBe(true);
+
+    // 差 1ms 不触发
+    vi.advanceTimersByTime(1233);
+    expect(onTimeout).not.toHaveBeenCalled();
+
+    // 到点触发
+    vi.advanceTimersByTime(1);
+    expect(onTimeout).toHaveBeenCalledOnce();
+  });
+
+  // TC-2: env XYZ_SUBAGENT_IDLE_TIMEOUT_MS 覆盖默认值
+  it("TC-2: env XYZ_SUBAGENT_IDLE_TIMEOUT_MS 覆盖默认值（不传参数时）", () => {
+    process.env[ENV_KEY] = "5000"; // 5 秒
+
+    const onTimeout = vi.fn();
+    armIdleTimer("sa-tc2", onTimeout); // 不传 timeoutMs
+
+    // 4.9s 不触发
+    vi.advanceTimersByTime(4999);
+    expect(onTimeout).not.toHaveBeenCalled();
+
+    // 5s 触发（env 值，不是默认 300s）
+    vi.advanceTimersByTime(1);
+    expect(onTimeout).toHaveBeenCalledOnce();
+  });
+
+  // TC-3: 参数优先于 env
+  it("TC-3: explicit timeoutMs 参数优先于 env", () => {
+    process.env[ENV_KEY] = "99999"; // env 设大值
+
+    const onTimeout = vi.fn();
+    armIdleTimer("sa-tc3", onTimeout, 2000); // 参数设小值
+
+    // 2s 触发（参数优先，不等 env 的 99s）
+    vi.advanceTimersByTime(1999);
+    expect(onTimeout).not.toHaveBeenCalled();
+
+    vi.advanceTimersByTime(1);
+    expect(onTimeout).toHaveBeenCalledOnce();
+  });
+
+  // TC-4: 都不设时默认 5min (300000ms)
+  it("TC-4: 无参数无 env 时默认 300000ms (5min)", () => {
+    const onTimeout = vi.fn();
+    armIdleTimer("sa-tc4", onTimeout); // 不传 timeoutMs，env 也未设
+
+    // 差 1ms 不触发
+    vi.advanceTimersByTime(DEFAULT_IDLE_TIMEOUT_MS - 1);
+    expect(onTimeout).not.toHaveBeenCalled();
+
+    // 到点触发
+    vi.advanceTimersByTime(1);
+    expect(onTimeout).toHaveBeenCalledOnce();
+  });
+
+  // TC-5 (额外): env 非法值回落默认
+  it("TC-5: env 非法值（负数/非数字）回落默认 300000ms", () => {
+    process.env[ENV_KEY] = "not-a-number";
+
+    const onTimeout = vi.fn();
+    armIdleTimer("sa-tc5", onTimeout); // 不传 timeoutMs
+
+    // 非法 env → 回落默认 300s。299s 不触发。
+    vi.advanceTimersByTime(DEFAULT_IDLE_TIMEOUT_MS - 1);
+    expect(onTimeout).not.toHaveBeenCalled();
+
+    // 到点触发
+    vi.advanceTimersByTime(1);
+    expect(onTimeout).toHaveBeenCalledOnce();
+  });
+});

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

@@ -0,0 +1,89 @@
+// src/__tests__/rpc-mode.test.ts
+//
+// RPC 模式相关功能
+// 1. buildSpawnArgs 返回 --mode rpc（而非 json）
+// 2. parseSpawnLine 正确解析 Pi 原生 RpcResponse（type:response + command + success + data|error）
+
+import { describe, expect, it } from "vitest";
+
+import { buildSpawnArgs } from "../session-runner.ts";
+import { parseSpawnLine } from "../spawn-event-adapter.ts";
+
+describe("buildSpawnArgs - RPC mode", () => {
+  const baseParams = {
+    modelRef: { provider: "openai", id: "gpt-4" },
+    thinkingLevel: undefined,
+    agentTools: undefined,
+    appendSystemPromptPath: undefined,
+    sessionDir: "/tmp/sessions",
+    forkSource: undefined,
+    skillPaths: undefined,
+  };
+
+  it("生成 --mode rpc 参数（非 json）", () => {
+    const args = buildSpawnArgs(baseParams);
+    // 应包含 --mode rpc
+    expect(args).toContain("--mode");
+    const modeIdx = args.indexOf("--mode");
+    expect(args[modeIdx + 1]).toBe("rpc");
+  });
+
+  it("不包含 --mode json", () => {
+    const args = buildSpawnArgs(baseParams);
+    const modeIdx = args.indexOf("--mode");
+    expect(args[modeIdx + 1]).not.toBe("json");
+  });
+});
+
+describe("parseSpawnLine - RpcResponse", () => {
+  // Pi 原生 RpcResponse 格式（rpc-types.ts）：{type:"response", id?, command, success, data?, error?}
+  // W1 修复后 isRpcResponse 判 type:response + command:string + success:boolean（SR-1 根因 1b）
+
+  it("解析 Pi 原生 success response（kind=response）", () => {
+    const rpcResponse = JSON.stringify({
+      type: "response",
+      id: "req-123",
+      command: "run",
+      success: true,
+      data: { answers: [{ question: "Q1", answer: "A1" }] },
+    });
+    const result = parseSpawnLine(rpcResponse);
+    expect(result?.kind).toBe("response");
+    if (result?.kind === "response") {
+      expect(result.id).toBe("req-123");
+      expect(result.command).toBe("run");
+      expect(result.success).toBe(true);
+      expect(result.data).toEqual({ answers: [{ question: "Q1", answer: "A1" }] });
+    }
+  });
+
+  it("解析 Pi 原生 error response（kind=response）", () => {
+    const rpcError = JSON.stringify({
+      type: "response",
+      id: "req-456",
+      command: "run",
+      success: false,
+      error: "task failed: timeout",
+    });
+    const result = parseSpawnLine(rpcError);
+    expect(result?.kind).toBe("response");
+    if (result?.kind === "response") {
+      expect(result.id).toBe("req-456");
+      expect(result.success).toBe(false);
+      expect(result.error).toBe("task failed: timeout");
+    }
+  });
+
+  it("旧 JSON-RPC 2.0 格式不再归类为 response（W1 废弃）", () => {
+    // SR-1: 旧 {jsonrpc:"2.0", id, result} 无 type:response 字段，应落入 invalid
+    const oldRpc = JSON.stringify({ jsonrpc: "2.0", id: "req-old", result: { x: 1 } });
+    const result = parseSpawnLine(oldRpc);
+    expect(result?.kind).not.toBe("response");
+  });
+
+  it("非 response 类型的 JSON 不归类为 response", () => {
+    const normalEvent = JSON.stringify({ type: "tool_execution_start", toolName: "bash" });
+    const result = parseSpawnLine(normalEvent);
+    expect(result?.kind).not.toBe("response");
+  });
+});