@zhushanwen/pi-subagent-workflow 8.5.0 → 8.7.0

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

@@ -1,231 +0,0 @@
-// 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

@@ -1,62 +0,0 @@
-// 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

@@ -1,183 +0,0 @@
-// 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}`
-  );
-}