@zhushanwen/pi-subagent-workflow 8.4.0 → 8.6.0

package/src/execution/engine/__tests__/routing.test.ts

@@ -0,0 +1,231 @@
+// routing.test.ts —— P4 配置路由三层 + probe fallback 三守卫 + strict（验收 1/2 的
+// 单测面）。fake probe/getEngine 注入（不依赖真机引擎与真实探针）。
+
+import { describe, expect, it } from "vitest";
+
+import type { EnginePort, RunContext } from "../port.ts";
+import { DEFAULT_ENGINE_ID, EngineNotFoundError } from "../registry.ts";
+import { EngineError } from "../common/errors.ts";
+import type { AgentTaskSpec, ProbeReport, SessionView } from "../types.ts";
+import { resolveEngineRouting, routeEngine, type EngineRouteOptions } from "../routing.ts";
+
+/** 最小可运行假引擎（probe 结果可注入）。 */
+function makeFakeEngine(id: string, probeOk: boolean): EnginePort {
+  return {
+    id,
+    capabilities: () => ({
+      schemaEnforcement: "emulated",
+      steer: "unsupported",
+      conversation: "unsupported",
+      personaInjection: "prompt",
+      eventGranularity: "coarse",
+      sandbox: "none",
+      sessionRead: "outcome-only",
+      resume: "cold",
+      interrupt: "kill-only",
+      permissionMode: "native",
+    }),
+    probe: () =>
+      Promise.resolve(
+        probeOk
+          ? { ok: true, engineVersion: "1.0.0", checks: [{ name: "stub", ok: true }] }
+          : {
+              ok: false,
+              engineVersion: "",
+              checks: [{ name: "binary", ok: false, detail: "missing" }],
+              error: { code: "engine_probe_failed", recovery: "reinstall the engine binary and retry the probe" },
+            } satisfies ProbeReport,
+      ),
+    run: (_t: AgentTaskSpec, _c: RunContext) => Promise.reject(new Error("fake: run not implemented")),
+    interact: () => Promise.resolve({ ok: false, code: "engine_capability_unsupported", message: "stub" }),
+    read: (_h: Parameters<EnginePort["read"]>[0]): Promise<SessionView> =>
+      Promise.resolve({ engineId: id, turns: [], source: "outcome-only" }),
+  };
+}
+
+/** routeEngine 的装配器：注册 {pi:ok, zcode:probeOk} 两引擎。 */
+function makeRoute(overrides?: {
+  zcodeProbeOk?: boolean;
+  strict?: boolean;
+  routing?: Partial<EngineRouteOptions["routing"]>;
+  taskModel?: string;
+  /** 额外注册第三引擎（probe ok）——fallback 目标为「非 pi 的其他全局默认」用例。 */
+  globalEngine?: string;
+}) {
+  const engines = new Map<string, EnginePort>();
+  engines.set(DEFAULT_ENGINE_ID, makeFakeEngine("pi", true));
+  engines.set("zcode", makeFakeEngine("zcode", overrides?.zcodeProbeOk ?? true));
+  if (overrides?.globalEngine !== undefined) {
+    engines.set(overrides.globalEngine, makeFakeEngine(overrides.globalEngine, true));
+  }
+  const probeCalls: string[] = [];
+  const opts: EngineRouteOptions = {
+    routing: overrides?.routing ?? {},
+    taskModel: overrides?.taskModel,
+    strict: overrides?.strict ?? false,
+    probe: (id) => {
+      probeCalls.push(id);
+      return engines.get(id)!.probe();
+    },
+    getEngineFn: (id) => {
+      const e = engines.get(id);
+      if (e === undefined) throw new EngineNotFoundError(id, [...engines.keys()]);
+      return e;
+    },
+    hasEngineFn: (id) => engines.has(id),
+    listEnginesFn: () => [...engines.keys()],
+  };
+  return { opts, probeCalls, engines };
+}
+
+// ── 三层优先级（验收 1）──
+
+describe("resolveEngineRouting：三层优先级", () => {
+  it("无任何指定 → 全局缺省 'pi'", () => {
+    expect(resolveEngineRouting({})).toEqual({ engineId: "pi", source: "default" });
+  });
+
+  it("全局默认引擎指定（config defaultEngine=zcode）→ zcode", () => {
+    expect(resolveEngineRouting({ globalDefaultEngine: "zcode" })).toEqual({ engineId: "zcode", source: "default" });
+  });
+
+  it("frontmatter 指定 > 全局默认", () => {
+    expect(resolveEngineRouting({ agentEngine: "zcode", globalDefaultEngine: "pi" })).toEqual({
+      engineId: "zcode",
+      source: "frontmatter",
+    });
+  });
+
+  it("调用参数 > frontmatter > 全局默认（三层全设时调用参数胜）", () => {
+    expect(
+      resolveEngineRouting({ callEngine: "pi", agentEngine: "zcode", globalDefaultEngine: "zcode" }),
+    ).toEqual({ engineId: "pi", source: "call" });
+  });
+
+  it("空串视为未指定（AgentCallOpts.engine='' 落下一层）", () => {
+    expect(resolveEngineRouting({ callEngine: "", agentEngine: "zcode" })).toEqual({
+      engineId: "zcode",
+      source: "frontmatter",
+    });
+  });
+});
+
+describe("routeEngine：路由 + 探针 + 守卫编排（验收 1/2）", () => {
+  it("缺省 pi：免探（零行为变化口径）直接返回引擎", async () => {
+    const { opts, probeCalls, engines } = makeRoute();
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.engineFallback).toBeUndefined();
+    expect(probeCalls).toEqual([]); // pi 缺省路径不探（D7 轻量口径）
+  });
+
+  it("frontmatter 指定 zcode + probe ok：返回 zcode 引擎，无 fallback", async () => {
+    const { opts, probeCalls, engines } = makeRoute({ routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("zcode"));
+    expect(result.engineId).toBe("zcode");
+    expect(result.engineFallback).toBeUndefined();
+    expect(probeCalls).toEqual(["zcode"]);
+  });
+
+  it("调用参数指定 zcode：覆盖 frontmatter 的 pi（透传链 A7）", async () => {
+    const { opts } = makeRoute({ routing: { callEngine: "zcode", agentEngine: "pi" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("zcode");
+    expect(result.source).toBe("call");
+  });
+
+  it("未注册 id（调用参数层）：engine_not_found，文案含注册清单（前置暴露）", async () => {
+    const { opts } = makeRoute({ routing: { callEngine: "nonexistent" } });
+    await expect(routeEngine(opts)).rejects.toThrowError(EngineNotFoundError);
+    await expect(routeEngine(opts)).rejects.toThrowError(/Registered engines: pi, zcode/);
+  });
+
+  // ── fallback 与三守卫（验收 2）──
+
+  it("frontmatter 指定 zcode + probe 失败 → 路由回 pi + engineFallback 留痕（A9①）", async () => {
+    const { opts, engines } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.requestedEngineId).toBe("zcode");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("守卫 a：调用参数显式指定 + probe 失败 → 不兜底，报 engine_probe_failed", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { callEngine: "zcode" } });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineError);
+    expect((err as EngineError).code).toBe("engine_probe_failed");
+    expect((err as EngineError).message).toContain("调用参数显式指定");
+    expect((err as EngineError).recovery).toContain("retry the probe");
+  });
+
+  it("守卫 b（首期与 a 合流）：AgentTaskSpec.requires 形状预留存在且不参与首期判定", async () => {
+    // 形状预留的类型面由 typecheck 守护；行为面：frontmatter 指定（非 call）+ 无 model
+    // → 仍走 fallback（守卫 b 独立生效留给 requires 下钻，见 types.ts 注释）
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineFallback).toBeDefined();
+  });
+
+  it("守卫 c：显式 model + probe 失败 → 不换引擎，报 model_not_available", async () => {
+    const { opts } = makeRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode" },
+      taskModel: "builtin:bigmodel-coding-plan/GLM-5.3",
+    });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(EngineError);
+    expect((err as EngineError).code).toBe("model_not_available");
+    expect((err as EngineError).message).toContain("GLM-5.3");
+  });
+
+  it("守卫 c 不误伤：无显式 model 时 probe 失败正常 fallback", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { agentEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("pi");
+  });
+
+  it("strict=true：frontmatter 层 probe 失败也直接报 engine_probe_failed（A5）", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, strict: true, routing: { agentEngine: "zcode" } });
+    const err = await routeEngine(opts).catch((e: unknown) => e);
+    expect((err as EngineError).code).toBe("engine_probe_failed");
+    expect((err as EngineError).message).toContain("strict");
+  });
+
+  it("全局默认引擎自身 probe 失败（defaultEngine=zcode）：fallback 回内置 pi", async () => {
+    const { opts } = makeRoute({ zcodeProbeOk: false, routing: { globalDefaultEngine: "zcode" } });
+    const result = await routeEngine(opts);
+    expect(result.engineId).toBe("pi");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("frontmatter zcode + config 默认同为 zcode + probe 失败：fallback 回 pi（不回退同一坏引擎）", async () => {
+    // review MF3 回归：全局默认 === 请求引擎时，fallback 目标不得 = 刚 probe 失败的
+    // 引擎（from==to 原地重试坏引擎 + 误导留痕）——回内置缺省 pi
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      routing: { agentEngine: "zcode", globalDefaultEngine: "zcode" },
+    });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("pi"));
+    expect(result.engineId).toBe("pi");
+    expect(result.requestedEngineId).toBe("zcode");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+
+  it("frontmatter zcode + config 默认为其他引擎：probe 失败回全局默认（既有行为不回归）", async () => {
+    // 全局默认 ≠ 请求引擎且非 pi：fallback 目标仍是全局默认（相等比较只拦截 from==to 形态）
+    const { opts, engines } = makeRoute({
+      zcodeProbeOk: false,
+      globalEngine: "claude",
+      routing: { agentEngine: "zcode", globalDefaultEngine: "claude" },
+    });
+    const result = await routeEngine(opts);
+    expect(result.engine).toBe(engines.get("claude"));
+    expect(result.engineId).toBe("claude");
+    expect(result.engineFallback).toEqual({ from: "zcode", reason: "engine_probe_failed" });
+  });
+});

package/src/execution/engine/common/data-dir.ts

@@ -0,0 +1,62 @@
+// src/execution/engine/common/data-dir.ts
+//
+// 引擎数据目录解析（P2）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D5/D6——engines 根锚定 getDataDir()
+// 顶层（journal / 隔离池的父目录），extension 写侧与 runtime 校验侧同源推导。
+//
+// 通道调查结论（2026-08-25，P2 实测证据链）：
+//   - runtime spawn pi 主会话时 RpcClient.buildSafeEnv 从 runtime process.env 继承
+//     XYZ_ 前缀白名单变量（rpc-client.ts:14-30），且显式设置 PI_CODING_AGENT_DIR；
+//   - dev 模式 Electron main 设置 XYZ_AGENT_DATA_DIR（apps/electron/main/main.ts:122），
+//     经 process-control.ts:262 透传给 runtime → 透传链成立；
+//   - prod 默认路径（~/.xyz-agent 缺省）下 runtime 进程 env 中**没有**该变量
+//     （shared getDataDir 缺省时不写 env）→ 透传链断——已在 runtime 侧
+//     process-manager.ts spawn env 补注入 XYZ_AGENT_DATA_DIR 修复（跨包改动）。
+//
+// 回退语义：缺 env 时回退 piAgentDir（getAgentDir()——尊重 PI_CODING_AGENT_DIR，
+// 独立 pi 用户直跑 extension 的场景）并 warn 一次——不留静默漂移（journal 落点变化
+// 必须可观测）。
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("subagents");
+
+/** xyz-agent 数据目录 env 名（与 packages/shared/src/paths.ts 的 SSOT 变量同名）。 */
+export const XYZ_DATA_DIR_ENV = "XYZ_AGENT_DATA_DIR";
+
+/** 测试隔离专用：重置 warn-once 标记（生产禁用）。 */
+let warned = false;
+export function resetDataDirWarnForTests(): void {
+  warned = false;
+}
+
+/**
+ * 解析引擎数据目录（journal 落盘 / 隔离池的根）：
+ *   1. process.env.XYZ_AGENT_DATA_DIR（xyz-agent 宿主注入，权威通道）；
+ *   2. 缺失 → piAgentDir（getAgentDir()）+ warn 一次。
+ * 每次调用重新解析（env 读取是零成本操作，不缓存路径防测试/宿主切换时读到旧值）。
+ */
+export function getEngineDataDir(
+  env: NodeJS.ProcessEnv = process.env,
+  warn: (msg: string) => void = defaultWarn,
+): string {
+  const fromEnv = env[XYZ_DATA_DIR_ENV]?.trim();
+  if (fromEnv !== undefined && fromEnv !== "") return fromEnv;
+
+  const fallback = getAgentDir();
+  if (!warned) {
+    warned = true;
+    warn(
+      `[engine-data-dir] ${XYZ_DATA_DIR_ENV} is not set; engine journal/pool fall back to the pi agent dir ` +
+        `(${fallback}). The xyz-agent host normally injects this env — if you are running inside xyz-agent, ` +
+        `check the runtime spawn env; standalone pi installs intentionally use the pi agent dir.`,
+    );
+  }
+  return fallback;
+}
+
+function defaultWarn(msg: string): void {
+  logger.warn(msg);
+}

package/src/execution/engine/common/errors.ts

@@ -0,0 +1,183 @@
+// src/execution/engine/common/errors.ts
+//
+// 引擎层错误 SSOT（P2 公共降级层）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md §3.3.3 错误规格全表（11 条）。
+//
+// 为什么集中一处：错误文案契约（code + 恢复指引）被三层消费——公共降级层
+// （prompt_too_large / nested_spawn_rejected / engine_timeout）、后续 wave 的路由与
+// 探针（engine_not_found / engine_probe_failed / model_not_available）、引擎适配器
+// （engine_run_failed / engine_session_not_resumable）。散落各处会漂移成同一错误
+// 多种文案，GUI 无法按 code 分流。
+//
+// 与 registry.ts 的 EngineNotFoundError 的关系：那是 P1 随注册表落地的
+// engine_not_found 错误类（getEngine 抛出），本文件不复制其类定义、只对齐 code
+// 字面量——后续 wave 统一收敛时以本表为 SSOT。
+
+// ============================================================
+// 错误码全集（§3.3.3 表 code 列，顺序与设计文档一致）
+// ============================================================
+
+export const ENGINE_ERROR_CODES = [
+  "engine_not_found",
+  "engine_probe_failed",
+  "engine_credential_missing",
+  "nested_spawn_rejected",
+  "schema_emulation_failed",
+  "engine_timeout",
+  "engine_capability_unsupported",
+  "engine_session_not_resumable",
+  "model_not_available",
+  "prompt_too_large",
+  "engine_run_failed",
+] as const;
+
+export type EngineErrorCode = (typeof ENGINE_ERROR_CODES)[number];
+
+/** unknown → EngineErrorCode 收窄（外部输入携带错误码时的运行时 guard）。 */
+export function isEngineErrorCode(value: unknown): value is EngineErrorCode {
+  return typeof value === "string" && (ENGINE_ERROR_CODES as readonly string[]).includes(value);
+}
+
+// ============================================================
+// 错误类（code + 恢复指引的结构化载体）
+// ============================================================
+
+/**
+ * 引擎层结构化错误。message 恒为 `<code>: <detail>` 前缀格式（AgentOutcome.error
+ * 的错误码前缀约定，§3.3.5）；recovery 指向恢复动作（全局规则：错误信息必须可操作）。
+ */
+export class EngineError extends Error {
+  readonly code: EngineErrorCode;
+  /** 恢复指引：指向具体下一步（命令 / 配置路径 / 替代方案），非安慰性文案。 */
+  readonly recovery: string;
+
+  constructor(code: EngineErrorCode, detail: string, recovery: string) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineError";
+    this.code = code;
+    this.recovery = recovery;
+  }
+
+  /** 结构化投影（InteractResult.code/message 与 GUI 警告条共用形态）。 */
+  toStructured(): { code: EngineErrorCode; message: string; recovery: string } {
+    return { code: this.code, message: this.message, recovery: this.recovery };
+  }
+}
+
+// ============================================================
+// 默认恢复指引模板（§3.3.3 恢复指引列的静态部分）
+// ============================================================
+
+/**
+ * 11 条错误的默认恢复指引。Record<EngineErrorCode, string> 使 TS 强制全集覆盖——
+ * 新增错误码漏写模板会在此处编译失败，而不是运行时空指引。
+ * 含动态参数的恢复指引（版本命令 / 模型清单 / 字节数）用下方具名构造器，不走此表。
+ */
+export const DEFAULT_RECOVERY_HINTS: Record<EngineErrorCode, string> = {
+  engine_not_found:
+    "Check the engine id in the agent .md frontmatter (engine: field) against the registered engine list, " +
+    "fix the typo, or install/register the engine first.",
+  engine_probe_failed:
+    "Confirm the engine version (e.g. `<engine> --version`), then re-run the engine probe. " +
+    "For contract drift, see docs/research/agent-engine-*.md for the expected output format.",
+  engine_credential_missing:
+    "Configure the engine credentials (see the engine credential section of docs/research/agent-engine-*.md), " +
+    "then retry — the preparer cannot synthesize credentials it has no source for.",
+  nested_spawn_rejected:
+    "Subagents must not spawn further subagents (unbounded recursion guard). " +
+    "Do the work directly inside the current task instead of delegating.",
+  schema_emulation_failed:
+    "The model output failed JSON extraction or schema validation. Retry once with a strengthened prompt " +
+    "(buildSchemaEmulationSegment output + the error tail); if it still fails, relax the schema or switch to a " +
+    "schema-native engine (engine: pi).",
+  engine_timeout:
+    "The engine was killed by the host timeout chain. Inspect the captured stdout tail, then re-run with a larger " +
+    "timeout, a narrower task, or `engine: pi`.",
+  engine_capability_unsupported:
+    "This engine declares the capability unsupported. Use a single-shot call instead of interactive steering, " +
+    "or dispatch with `engine: pi` which supports it.",
+  engine_session_not_resumable:
+    "Idle-process reuse does not survive a main-session reload. Use a cold resume path " +
+    "(engine --resume / --session with the recorded session reference), or start a new subagent.",
+  model_not_available:
+    "The requested model is not resolvable in this engine's provider system. Pick a model from the engine's " +
+    "available model list — the host never swaps engines implicitly on model mismatch.",
+  prompt_too_large:
+    "Shorten the task text, move the persona to the file channel, or use an engine with a stdin prompt channel.",
+  engine_run_failed:
+    "The engine process failed at runtime (parse failure / non-zero exit / contract drift). " +
+    "Check the captured stdout tail and exit code, confirm the engine version, re-run the probe, or retry with `engine: pi`.",
+};
+
+// ============================================================
+// P2 消费的具名构造器（动态参数进 detail/recovery）
+// ============================================================
+
+/** 错误回显长度上限（截断长输出，避免错误消息爆炸——对齐 structured-output echo 上限量级）。 */
+const DETAIL_ECHO_MAX_CHARS = 200;
+
+/** truncate(text, max)：尾部截断 + 省略号标记（模板共用）。 */
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+
+/**
+ * prompt_too_large（persona-router 的 argv 预算拦截消费）：仅 argv 投递的引擎在
+ * prepare 期报——禁止 spawn 后撞 E2BIG 才失败（§3.3.3 第 10 行）。
+ */
+export function promptTooLargeError(actualBytes: number, limitBytes: number): EngineError {
+  return new EngineError(
+    "prompt_too_large",
+    `estimated argv size ${actualBytes} bytes exceeds the ${limitBytes}-byte budget`,
+    DEFAULT_RECOVERY_HINTS.prompt_too_large,
+  );
+}
+
+/** nested_spawn_rejected（nesting-guard 消费）：文案说明防护规则 + 指向 task 内自行完成。 */
+export function nestedSpawnRejectedError(): EngineError {
+  return new EngineError(
+    "nested_spawn_rejected",
+    "this process is already a subagent (XYZ_AGENT_SUBAGENT=1)",
+    DEFAULT_RECOVERY_HINTS.nested_spawn_rejected,
+  );
+}
+
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+export const STDOUT_TAIL_ECHO_CHARS = 2000;
+
+/**
+ * engine_timeout 的 outcome.error 文案（kill-chain 的 synthesizeTimeoutOutcome 消费）：
+ * 含 stdout 尾部 2000 字 + 「可用 engine: pi 重跑」建议（§3.3.3 第 6 行）。
+ */
+export function engineTimeoutDetail(stdoutTail: string): string {
+  return (
+    `host timeout chain exhausted (SIGTERM -> grace -> SIGKILL). ` +
+    `Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.engine_timeout}`
+  );
+}
+
+/**
+ * engine_run_failed 的 outcome.error 文案：含 stdout 尾部 2000 字 + exit code +
+ * 恢复指引（版本确认 + 探针重跑 / engine: pi 重跑，§3.3.3 第 11 行）。
+ */
+export function engineRunFailedDetail(reason: string, exitCode: number | null, stdoutTail: string): string {
+  const exit = exitCode === null ? "killed by signal" : `exit code ${exitCode}`;
+  return (
+    `engine failed at runtime: ${reason} (${exit}). ` +
+    `Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.engine_run_failed}`
+  );
+}
+
+/**
+ * schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）：
+ * 与 structured-output 的重试语义对齐（重试一次 → 报错含原始输出尾部）。
+ */
+export function schemaEmulationFailedDetail(error: string, tail: string): string {
+  return (
+    `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. ` +
+    `Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. ` +
+    `Recovery: ${DEFAULT_RECOVERY_HINTS.schema_emulation_failed}`
+  );
+}