@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/engine/host-task-spec.ts

@@ -0,0 +1,47 @@
+// src/execution/engine/host-task-spec.ts
+//
+// ExecuteOptions → AgentTaskSpec 的宿主侧最小正向映射（U0：chat 工具域引擎分支）。
+//
+// 与 engines/pi/task-spec-mapper.ts 的关系：那是 pi 引擎方向的映射（taskSpecToExecuteOptions
+// 还原 + schemaEnv 内化派生等 pi 专有语义），归属 pi 引擎模块；本 mapper 服务宿主编排层
+// （subagent-service 引擎分支），不 import 任何具体引擎模块（registry.ts 依赖方向纪律：
+// 上层按中立类型组装声明，引擎细节归引擎）。字段映射是 ExecuteOptions → AgentTaskSpec
+// 的中立直译（task/slug/agent/model 原样；thinkingLevel → effort；skillPath +
+// appendSystemPrompt → persona；schema/maxTurns/graceTurns/worktree/cwd 原样透传）。
+//
+// conversation/fork 在调用本 mapper 前已被 assertEngineParamSupport 预检拒绝（非 pi 引擎
+// unsupported），透传仅保持映射完整性——未来引擎支持时无需改本函数。
+
+import type { ExecuteOptions } from "../types.ts";
+import type { AgentTaskSpec, PersonaSpec } from "./types.ts";
+
+/** 纯函数：ExecuteOptions（chat 域执行选项）→ 引擎中立任务声明。无副作用、幂等。 */
+export function executeOptionsToEngineTaskSpec(opts: ExecuteOptions): AgentTaskSpec {
+  // persona 归并口径与 pi mapper 一致：skillPath / appendSystemPrompt 有其一即建，
+  // 避免空对象噪声（下游 spread 空数组与 undefined 均为 no-op）。
+  const persona: PersonaSpec | undefined =
+    opts.skillPath !== undefined || opts.appendSystemPrompt !== undefined
+      ? {
+          ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
+          ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+        }
+      : undefined;
+  return {
+    task: opts.task,
+    slug: opts.slug,
+    agent: opts.agent,
+    model: opts.model,
+    // pi 7 档 thinkingLevel 是引擎私有语义——中立层透传 effort 字符串，各引擎自行映射
+    effort: opts.thinkingLevel,
+    ...(persona !== undefined ? { persona } : {}),
+    schema: opts.schema,
+    maxTurns: opts.maxTurns,
+    graceTurns: opts.graceTurns,
+    fork: opts.fork,
+    worktree: opts.worktree,
+    cwd: opts.cwd,
+    conversation: opts.conversation,
+    idleTimeoutMs: opts.idleTimeoutMs,
+    // 运行期字段（signal/ctxModel）不入声明——归 RunContext（port.ts 删字段去向）。
+  };
+}

package/src/execution/engine/model-prompt.ts

@@ -0,0 +1,59 @@
+// src/execution/engine/model-prompt.ts
+//
+// [U7] 引擎模型段 system prompt 注入（模型可发现性）。
+//
+// 背景：pi 核心在 system prompt 生成 <available_provider_models> 段并教育 agent
+// 「subagent/workflow 的 model 参数用这些 id」——该教育对 engine: zcode 等自带
+// provider 体系的引擎是误导（pi 的 id 在引擎侧是未知 provider）。本模块按
+// 「defaultEngine 开关」（用户拍板 2026-08-25）补齐非默认引擎的模型可发现性：
+// defaultEngine 指向非 pi 引擎且该引擎实现 EnginePort.listModels 时，追加
+// <available_<engine>_models> 段，与 pi 段形成「一段一引擎」的分界标注。
+//
+// engine-neutral：遍历注册表驱动，未来引擎实现 listModels 即自动注入，宿主零改动。
+
+import { DEFAULT_ENGINE_ID, getEngine, hasEngine } from "./registry.ts";
+
+/** pi 段之外的引擎才需要清单段（pi 与主 agent 模型体系一致，核心已有段）。 */
+const CORE_ENGINE_ID = DEFAULT_ENGINE_ID;
+
+/** 单引擎段格式：XML 包裹 + 分界语义（与 pi 核心段的 <model><id> 形态对齐）。 */
+function buildEngineSection(engineId: string, models: Array<{ id: string; name?: string }>): string {
+  const lines = models.map((m) =>
+    m.name !== undefined ? `<model><id>${m.id}</id><name>${m.name}</name></model>` : `<model><id>${m.id}</id></model>`,
+  );
+  return [
+    `<available_${engineId}_models>`,
+    `The following models are available for subagents dispatched with engine '${engineId}' ONLY (their provider registry differs from the main agent's; ids above in <available_provider_models> do NOT apply to engine '${engineId}' dispatches). Omit model to use the engine default.`,
+    ...lines,
+    `</available_${engineId}_models>`,
+  ].join("\n");
+}
+
+/**
+ * 依据全局 defaultEngine 生成追加段（不含前导换行；无需注入时返回空串）。
+ *
+ * 规则（用户拍板的开关语义）：
+ *   - defaultEngine 为 pi / 缺省 → 不注入（pi 段已由核心提供）；
+ *   - defaultEngine 指向已注册且实现 listModels 的引擎 → 注入该引擎段；
+ *   - 引擎未实现 listModels / 清单为空 → 不注入（可发现性降级不阻塞，prepare 报错
+ *     的事后清单兜底仍在）。
+ * fail-safe：任何异常返回空串（注入失败不阻塞 agent loop——与 system-prompt
+ * extension 的 before_agent_start 处置一致）。
+ */
+export function buildEngineModelsPromptAppend(defaultEngine: string | undefined): string {
+  try {
+    const engineId = defaultEngine?.trim() || CORE_ENGINE_ID;
+    if (engineId === CORE_ENGINE_ID) return "";
+    if (!hasEngine(engineId)) return "";
+    const engine = getEngine(engineId);
+    if (engine.listModels === undefined) return "";
+    const models = engine.listModels();
+    if (models === null || models.length === 0) return "";
+    return buildEngineSection(engineId, models);
+  } catch {
+    return "";
+  }
+}
+
+/** 测试口：段格式导出（避免测试依赖注册表组装全链）。 */
+export const _testHooks = { buildEngineSection, CORE_ENGINE_ID };

package/src/execution/engine/paths.ts

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+
+/**
+ * 引擎数据目录布局 SSOT（设计文档 D5/D6）。
+ *
+ * 为什么独立成模块：extension 写侧（journal 落盘 / preparer 池目录）与
+ * runtime 校验侧（subagent-extractor 前缀白名单）必须同源推导——
+ * 双方 import 同一份纯函数，禁止各自拼字符串漂移。
+ *
+ * 布局：`<dataDir>/engines/<engineId>/<pool-key>/journal-<taskId>.jsonl`
+ * 隔离池跨任务保留复用；journal 生命周期跟随 record，不随池删除（D5）。
+ */
+
+/** 路径段安全编码后的最大字符数（防超长段击穿文件名长度上限；runtime 校验侧同源）。 */
+const MAX_SEG_CHARS = 80;
+
+/** 路径段进入文件系统前的安全编码：路径穿越、分隔符、空白、超长全部归一。 */
+export function sanitizeSeg(input: string): string {
+  const s = input.replace(/[^A-Za-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+  return s.length > 0 ? s.slice(0, MAX_SEG_CHARS) : 'default';
+}
+
+export function resolveEnginesRoot(dataDir: string): string {
+  return join(dataDir, 'engines');
+}
+
+export function resolveEngineDir(dataDir: string, engineId: string): string {
+  return join(resolveEnginesRoot(dataDir), sanitizeSeg(engineId));
+}
+
+export function resolvePoolDir(dataDir: string, engineId: string, poolKey: string): string {
+  return join(resolveEngineDir(dataDir, sanitizeSeg(engineId)), sanitizeSeg(poolKey));
+}
+
+export function resolveJournalPath(
+  dataDir: string,
+  engineId: string,
+  poolKey: string,
+  taskId: string,
+): string {
+  return join(resolvePoolDir(dataDir, engineId, poolKey), `journal-${sanitizeSeg(taskId)}.jsonl`);
+}

package/src/execution/engine/port.ts

@@ -0,0 +1,153 @@
+// src/execution/engine/port.ts
+//
+// EnginePort 接口（P1）。设计权威源：docs/architecture/subagent-engine-abstraction.md
+// §3.3.5「EnginePort 完整签名」——本文件是可编码落地的契约层，后续 wave（公共降级层
+// P2 / zcode 引擎 P3 / 配置路由 P4）以本接口为实现契约，字段级变更须先改设计文档。
+//
+// 四个能力面（D1）：
+//   run        —— 主语义：一次性 fire-to-completion 任务执行；
+//   interact   —— 交互控制面（chatMode 的 message/close/cancel + idle，可选能力面，
+//                 capabilities.conversation 声明接通与否）；
+//   read       —— session 历史读取（D6 三级降级链）；
+//   probe      —— 探针（D7：二进制存在/版本解析/干跑校验）。
+// capabilities() 同步无副作用——「调用前拒绝」（D11 处置三级）的判据。
+
+import type { ChildProcess } from "node:child_process";
+
+import type { ModelInfo } from "../model-resolver.ts";
+import type { SubagentStream } from "../stream-sink.ts";
+import type { AgentEvent } from "../types.ts";
+import type {
+  AgentOutcome,
+  AgentTaskSpec,
+  EngineCapabilities,
+  EngineHandle,
+  InteractAction,
+  InteractResult,
+  ProbeReport,
+  SessionView,
+} from "./types.ts";
+
+// ============================================================
+// RunContext（run 的运行期上下文）
+// ============================================================
+
+/**
+ * run 的运行期上下文。任务声明（AgentTaskSpec）与运行期句柄分离——signal/ctxModel/
+ * onComplete 从 ExecuteOptions 移出（设计 §3.3.5 删字段去向），因为它们是宿主注入的
+ * 运行期对象，不属于跨引擎持久化的任务声明。
+ *
+ * 常驻进程友好（D1）：onEvent 回调式（而非迭代器式）+ AbortSignal——引擎内部换常驻
+ * server 实现（未来 driver host）时接口不动。
+ */
+export interface RunContext {
+  /** = record.id（bg-N-xxx / run-N）——journal 文件名与池引用计数 key（P2 消费）。 */
+  taskId: string;
+  /** D5 隔离池（宿主分配，设计 §3.3.9；pi 无池化恒 'shared'）。 */
+  poolKey: string;
+  /** abort 分级入口（D1：引擎原生中断 → 公共杀链兜底）。 */
+  signal?: AbortSignal;
+  /** 事件流出口（host 消费后统一落 journal，D6 第②级）。 */
+  onEvent?: (event: AgentEvent) => void;
+  /** model 解析第三层兼底（现有 D-008 语义不变）。 */
+  ctxModel?: ModelInfo;
+  /**
+   * text_delta streaming 通道（宿主侧 UI widget）。与 onEvent 平行的 text_delta 出口：
+   * background 路径 onEvent=undefined 但流式仍需送达（双通道互斥设计，见 session-runner
+   * agentEvent 出口注释）。pi 回填期承载 AgentRunner port 的 stream 透传（行为零变化），
+   * 语义上是宿主设施而非引擎专有——未来引擎的 text_delta 同样可走此通道。
+   */
+  stream?: SubagentStream;
+  /**
+   * [P1 pi 回填透传] 调用方已持有的 schema 激活预编码值（AgentCallOpts.schemaEnv 直传
+   * 形态）。生产路径中 resolveAgentOpts 恒耦合产出 schema+schemaEnv（值 = JSON.stringify
+   * (schema)），引擎从 task.schema 派生即可逐字节等值；解耦形态（有 schemaEnv 无
+   * schema）生产不可达、仅见于直构调用，派生无源——本字段是其唯一透交通道。
+   * 引擎在 task.schema 存在时忽略此值（派生优先，设计 §3.3.5 删字段去向）。
+   */
+  schemaEnv?: string;
+  /**
+   * [P4 D9①] 引擎 fallback 留痕（probe 失败路由回默认引擎）。路由层（routing.ts）
+   * 产出，引擎投影到 outcome.engineFallback（zcode 等无 record 通路的引擎以此留痕；
+   * pi 引擎另经 ExecuteOptions 投影进 record）。
+   */
+  engineFallback?: { from: string; reason: string };
+  /**
+   * [P4 对齐点③] 引擎声明实际隔离池 key（journal 落盘路径权威）。宿主创建 journal
+   * writer 时只能用缺省占位 poolKey（pi 恒 'shared'），非池化稳定的引擎（zcode 按
+   * provider+model 池化）在 prepare 期确定 poolKey 后回调本方法重定向 writer——
+   * 保证 journal 落盘路径与 handle.poolKey 同源（单一权威，不再两边推导）。
+   * 契约：必须在首个事件 emit 之前调用（zcode coarse 事件在终态后合成，天然满足；
+   * 未来流式引擎需在事件出口前调用）。
+   */
+  onPoolResolved?: (poolKey: string) => void;
+  /**
+   * [U0 D10] 引擎 spawn 的子进程句柄注册钩子（宿主终止链记账）。引擎在 spawn 成功后
+   * 同步回调（与 pi runSpawn 的 spawnedChildren.set 同构时机）；宿主据此把 child 注册进
+   * session-runner 的 spawnedChildren Map（cancel SIGTERM / dispose 收割兜底 / killAll
+   * 全量清理对非 pi 引擎 record 生效）。close/error 后由宿主按句守卫移除。可选：引擎
+   * 内部不 spawn 进程（如未来常驻 driver host 实现）时不调用，宿主记账自然为空。
+   */
+  onChildSpawned?: (child: ChildProcess) => void;
+}
+
+// ============================================================
+// run 返回（handle + outcome）
+// ============================================================
+
+/**
+ * run 的返回：终态 + 可持久化 handle。
+ *
+ * handle 语义（设计 §3.3.5 run 错误语义三条）：prepare 期错误（credential_missing /
+ * model_not_available / prompt_too_large）在进程创建前 reject、不产生 handle；运行中
+ * 失败不 reject——合成 error outcome + 正常 handle 返回（record 必须收尾）；abort 走
+ * 完杀链后同前（exitCode=null + error 含杀链标记）。
+ */
+export interface EngineRunResult {
+  handle: EngineHandle;
+  outcome: AgentOutcome;
+}
+
+// ============================================================
+// EnginePort
+// ============================================================
+
+/**
+ * subagent 执行引擎的唯一契约点（D1）。实现方：PiEngine（回填）/ ZcodeEngine（P3）/
+ * 未来各引擎适配器。上层（工具面/workflow 引擎/GUI）只消费中立类型，不感知引擎。
+ *
+ * 贯穿纪律（设计 §3.3.1）：宿主编排——引擎只当单 agent 执行器，六家原生多 agent 机制
+ * 一律禁用不依赖。
+ */
+export interface EnginePort {
+  /** 注册表 key（'pi' | 'zcode' | ...）。 */
+  readonly id: string;
+
+  /** D3（同步无副作用——调用前拒绝的判据）。 */
+  capabilities(): EngineCapabilities;
+
+  /** D7（factory 初始化 + 版本变化检测触发；opts.force 跳过缓存强探）。 */
+  probe(opts?: { force?: boolean }): Promise<ProbeReport>;
+
+  /** D1 主语义：fire-to-completion。 */
+  run(task: AgentTaskSpec, ctx: RunContext): Promise<EngineRunResult>;
+
+  /**
+   * D1 可选面：交互控制面。pi 首期原生实现（现有 chatMode 行为直通）；不支持
+   * conversation 的引擎返回 engine_capability_unsupported（同步拒绝、不创建进程）。
+   */
+  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
+
+  /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
+  read(handle: EngineHandle): Promise<SessionView>;
+
+  /**
+   * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
+   * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段
+   * 与 GUI 引擎选择器消费。省略/返回 null = 「与主 agent 模型体系一致」（pi 的语义：
+   * system prompt 已有 <available_provider_models> 段，无需引擎再列）。
+   * engine-neutral：未来引擎（AcpEngine 等）实现本方法即自动获得注入与展示，宿主
+   * 侧零改动。
+   */
+  listModels?(): Array<{ id: string; name?: string }> | null;
+}

package/src/execution/engine/registry.ts

@@ -0,0 +1,123 @@
+// src/execution/engine/registry.ts
+//
+// 引擎注册表（P1）。设计权威源：docs/architecture/subagent-engine-abstraction.md
+// §3.3.1 分层总图（[引擎注册表 engine registry]（id → factory））与 §3.3.3 错误规格
+// 第 1 行（engine_not_found → 指向注册表清单 + 配置文件路径）。
+//
+// 为什么需要注册表：引擎身份是「spawn 细节的归属边界」（设计 §2.3 根因一）——上层
+// （配置路由/agent 解析，P4 接线）按 id 取引擎，不感知实现类；新引擎接入 = 新增一个
+// 适配器模块 + 注册表登记一行，不改上层与既有引擎（目标 5）。
+//
+// 依赖方向（设计 §3.3.1 贯穿纪律④）：registry 只依赖 port.ts 的类型，不 import 任何
+// 具体引擎——注册由组合根（index.ts）或引擎自己的 registration 模块完成，防循环依赖。
+
+import type { EnginePort } from "./port.ts";
+
+/** 引擎工厂：惰性创建引擎实例（getEngine 首次取用时执行）。 */
+export type EngineFactory = () => EnginePort;
+
+/**
+ * 缺省引擎 id（D9：缺省引擎 = 'pi'，回填期零风险默认）。
+ * P1 无 per-agent/调用级 engine 字段（P4 配置路由引入三层优先级），一切执行恒走缺省。
+ */
+export const DEFAULT_ENGINE_ID = "pi";
+
+/**
+ * engine_not_found（错误规格表第 1 行）：agent frontmatter 写了未注册 engine id。
+ * 错误文案契约：含已注册引擎清单 + 配置文件指引——配置错误前置暴露（agent 解析期），
+ * 不留到运行时神秘失败（设计目标 4）。
+ */
+export class EngineNotFoundError extends Error {
+  /** 结构化错误码（§3.3.3 错误规格表的 code 列，供调用方程序化分流）。 */
+  readonly code = "engine_not_found";
+  /** 请求的（未注册的）引擎 id。 */
+  readonly engineId: string;
+  /** 请求时刻的已注册清单快照（防错误对象跨时间读 Map 的失真）。 */
+  readonly registered: readonly string[];
+  /** 错误来源定位（agent .md 文件路径 / 配置键等；运行期 getEngine 无来源不传）。 */
+  readonly source: string | undefined;
+
+  constructor(engineId: string, registered: readonly string[], source?: string) {
+    super(
+      `engine_not_found: engine '${engineId}' is not registered. ` +
+        `Registered engines: ${registered.length > 0 ? registered.join(", ") : "(none)"}. ` +
+        `Recovery: check the engine id in the agent .md frontmatter (engine: field) or the global ` +
+        `default engine setting, fix the typo, or install/register the engine first ` +
+        `(registered engines are listed above).` +
+        (source !== undefined ? ` Source: ${source}.` : ""),
+    );
+    this.name = "EngineNotFoundError";
+    this.engineId = engineId;
+    this.registered = registered;
+    this.source = source;
+  }
+}
+
+/**
+ * id → factory（注册表本体）+ id → 惰性单例（getEngine 首次取用创建；registerEngine
+ * 覆盖时丢弃旧实例）。进程级单例状态，用 globalThis[Symbol.for] 持有防 jiti 双路径
+ * 加载分裂（development-guide §7.5），不用模块级 const。
+ */
+const ENGINE_REGISTRY_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagent-workflow.engineRegistry");
+
+/** 注册表槽位形状（同文件唯一写入点，运行时保证）。 */
+interface EngineRegistrySlot {
+  factories: Map<string, EngineFactory>;
+  singletons: Map<string, EnginePort>;
+}
+
+function getRegistrySlot(): EngineRegistrySlot {
+  // globalThis 无 symbol 索引签名，但运行时支持 symbol 键——用 Reflect 安全读写，
+  // 避免双重断言（同 model-config-service.ts 先例）。
+  let slot = Reflect.get(globalThis, ENGINE_REGISTRY_SLOT_KEY) as EngineRegistrySlot | undefined;
+  if (!slot) {
+    slot = { factories: new Map(), singletons: new Map() };
+    Reflect.set(globalThis, ENGINE_REGISTRY_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/**
+ * 登记引擎工厂。重复注册同一 id = 覆盖（组合根可能多次执行，如每次 session_start 重跑
+ * registerPiEngine——幂等覆盖保证不炸也不堆积），覆盖时丢弃缓存的旧单例，让下一次
+ * getEngine 用新工厂重建。
+ */
+export function registerEngine(id: string, factory: EngineFactory): void {
+  const slot = getRegistrySlot();
+  slot.factories.set(id, factory);
+  slot.singletons.delete(id);
+}
+
+/** 未注册 id 抛 EngineNotFoundError（含已注册清单与配置指引）。 */
+export function getEngine(id: string): EnginePort {
+  const slot = getRegistrySlot();
+  const cached = slot.singletons.get(id);
+  if (cached) return cached;
+  const factory = slot.factories.get(id);
+  if (!factory) {
+    throw new EngineNotFoundError(id, listEngines());
+  }
+  const engine = factory();
+  slot.singletons.set(id, engine);
+  return engine;
+}
+
+/** id 是否已注册（agent 解析期的配置校验入口，D9——不取实例、不触发工厂副作用）。 */
+export function hasEngine(id: string): boolean {
+  return getRegistrySlot().factories.has(id);
+}
+
+/** 已注册引擎 id 清单（稳定序 = 注册序；错误文案与 GUI 引擎选择器共用）。 */
+export function listEngines(): string[] {
+  return [...getRegistrySlot().factories.keys()];
+}
+
+/**
+ * 清空注册表（测试隔离专用：防止用例间工厂/单例泄漏串扰）。
+ * 生产代码禁用——进程内注册表是全局状态，清空会让已获取的引擎句柄与新注册表脱钩。
+ */
+export function clearEngines(): void {
+  const slot = getRegistrySlot();
+  slot.factories.clear();
+  slot.singletons.clear();
+}

package/src/execution/engine/routing.ts

@@ -0,0 +1,218 @@
+// src/execution/engine/routing.ts
+//
+// 配置路由与探针 fallback 编排（P4）。设计权威源：
+// docs/architecture/subagent-engine-abstraction.md D9（配置路由三层 + 故障 fallback
+// 三守卫 + model/engine 正交 + workflow 脚本不写死 engine）+ D7（探针分级与触发时机）
+// + §3.3.3 错误规格（engine_probe_failed / model_not_available 行）。
+//
+// 职责边界：本模块只做「选哪个引擎」的决策（纯路由 + probe 编排），不 spawn、不读
+// 任务正文。三层优先级与守卫的判定规则集中于此单一权威点——上层（SAR）只消费
+// routeEngine 的结果，散落的 if engine === ... 分派被结构性排除。
+//
+// probe 触发时机（D7「引擎 factory 初始化与版本变化检测时触发」的 P4 落地口径）：
+// 路由期触发、结果缓存于引擎实例（probeCache）。缺省引擎 'pi' 免探——pi 契约稳定
+// （rpc.md 官方，D7 稳定性光谱的轻探针端）且「缺省路径行为零变化」是 A1 硬约束
+// （每次 run 前强探会引入 pi --version 子进程开销与新的失败面）；显式 engine='pi'
+// 同样免探（fallback 无处可去，守卫 a 对 pi 不可达是自然结果而非缺口）。进程存活
+// 期间缓存不失效——版本变化（运行中 CLI 被升级）由 engine_run_failed 运行中兜底
+// （D11 规则②封边界的既有设计），重启进程 / registerEngine 覆盖后重探。
+
+import { EngineError } from "./common/errors.ts";
+import type { EnginePort } from "./port.ts";
+import { DEFAULT_ENGINE_ID, EngineNotFoundError, getEngine, hasEngine, listEngines } from "./registry.ts";
+import type { ProbeReport } from "./types.ts";
+
+// ============================================================
+// 三层优先级（D9）
+// ============================================================
+
+/** 三层路由的输入（各层值由调用方装配；undefined = 该层不指定）。 */
+export interface EngineRoutingInput {
+  /** 第一层：调用参数 engine（workflow step 级 / AgentCallOpts.engine）。 */
+  callEngine?: string;
+  /** 第二层：agent .md frontmatter engine（解析期已对注册表校验）。 */
+  agentEngine?: string;
+  /** 第三层：全局默认引擎（config.json defaultEngine；缺省 'pi'）。 */
+  globalDefaultEngine?: string;
+}
+
+/** 生效层标记（守卫 a 的判据：'call' = 显式指定，probe 失败不兜底）。 */
+export type EngineRoutingSource = "call" | "frontmatter" | "default";
+
+export interface EngineRouting {
+  engineId: string;
+  source: EngineRoutingSource;
+}
+
+/** 非空文本判据：路由层各配置入口统一口径——undefined 与空串同视为未指定。 */
+function hasText(v: string | undefined): v is string {
+  return v !== undefined && v !== "";
+}
+
+/**
+ * 纯三层解析：调用参数 > agent frontmatter > 全局默认（缺省 'pi'）。
+ * 不校验注册表（frontmatter 层已前置校验；调用参数层的校验归 routeEngine）——
+ * 保持纯函数可独立单测。
+ */
+export function resolveEngineRouting(input: EngineRoutingInput): EngineRouting {
+  if (hasText(input.callEngine)) {
+    return { engineId: input.callEngine, source: "call" };
+  }
+  if (hasText(input.agentEngine)) {
+    return { engineId: input.agentEngine, source: "frontmatter" };
+  }
+  if (hasText(input.globalDefaultEngine)) {
+    return { engineId: input.globalDefaultEngine, source: "default" };
+  }
+  return { engineId: DEFAULT_ENGINE_ID, source: "default" };
+}
+
+// ============================================================
+// routeEngine：probe 编排 + fallback 三守卫（D9①/D7）
+// ============================================================
+
+/** routeEngine 的参数（probe/getEngine 注入——测试可 mock，SAR 提供生产实现）。 */
+export interface EngineRouteOptions {
+  routing: EngineRoutingInput;
+  /**
+   * 显式 model（守卫 c 判据：model 与引擎 provider 体系绑定，D9②）。短名 model 的
+   * provider 缺省决策在 zcode preparer 的 defaultProviderForShortName——显式默认引擎
+   * 模型配置（config.json per-engine model）引入时，两处须同步让位配置值优先
+   * （对齐点⑦，详见 preparer.ts 该函数注释）。
+   */
+  taskModel?: string;
+  /** engineRouting.strict（config.json）：true = 一切 probe 失败直接报错。 */
+  strict: boolean;
+  /** 探针执行体（返回 ProbeReport；引擎实例内部有缓存语义）。 */
+  probe: (engineId: string) => Promise<ProbeReport>;
+  /** 引擎获取（缺省 registry.getEngine；测试/SAR 可注入）。 */
+  getEngineFn?: (engineId: string) => EnginePort;
+  /** 注册表存在性检查（缺省 registry.hasEngine）。 */
+  hasEngineFn?: (engineId: string) => boolean;
+  /** 注册表清单（缺省 registry.listEngines——engine_not_found 文案的数据源）。 */
+  listEnginesFn?: () => string[];
+}
+
+export interface EngineRouteResult {
+  engine: EnginePort;
+  /** 实际执行引擎 id（fallback 后可能 ≠ 请求值）。 */
+  engineId: string;
+  /** 路由决策时的请求引擎 id（fallback 留痕的 from 值）。 */
+  requestedEngineId: string;
+  /** 生效层（守卫 a 判据的留痕）。 */
+  source: EngineRoutingSource;
+  /** fallback 留痕（record/outcome 投影，GUI 警告条数据源）。无 fallback 缺省。 */
+  engineFallback?: { from: string; reason: string };
+}
+
+/**
+ * 路由 + 探针 + fallback 编排（SAR run 入口调用）。
+ *
+ * 失败形态（全部抛结构化错误，调用方转 AgentResult.error）：
+ *   - 未注册 id（调用参数层漏网）：EngineNotFoundError（engine_not_found）
+ *   - strict 或守卫命中：EngineError(engine_probe_failed)
+ *   - 守卫 c（显式 model + 将换引擎）：EngineError(model_not_available)
+ */
+export async function routeEngine(opts: EngineRouteOptions): Promise<EngineRouteResult> {
+  const has = opts.hasEngineFn ?? hasEngine;
+  const get = opts.getEngineFn ?? getEngine;
+  const routing = resolveEngineRouting(opts.routing);
+
+  // 调用参数层的注册表校验（frontmatter 层已在 agent 解析期抛过；这里兜调用参数
+  // 直传的未注册 id——错误含注册清单，配置错误前置到路由期而非 getEngine 深处）
+  if (!has(routing.engineId)) {
+    throw new EngineNotFoundError(routing.engineId, opts.listEnginesFn?.() ?? listEngines(), describeRoutingSource(opts.routing));
+  }
+
+  // 缺省引擎免探（见文件头「probe 触发时机」）——直接取引擎
+  if (routing.engineId === DEFAULT_ENGINE_ID) {
+    return {
+      engine: get(routing.engineId),
+      engineId: routing.engineId,
+      requestedEngineId: routing.engineId,
+      source: routing.source,
+    };
+  }
+
+  const report = await opts.probe(routing.engineId);
+  if (report.ok) {
+    return {
+      engine: get(routing.engineId),
+      engineId: routing.engineId,
+      requestedEngineId: routing.engineId,
+      source: routing.source,
+    };
+  }
+
+  // ── probe 失败：strict / 三守卫 / fallback（D9①）──
+  if (opts.strict) {
+    throw probeFailedError(routing.engineId, report, "engineRouting.strict=true：probe 失败一律报错（不 fallback）");
+  }
+  // 守卫 a/b（首期合流）：显式指定（调用参数或 step 级）= 能力依赖声明，静默换引擎
+  // 违反意图——沙箱类任务被静默卸除安全能力正是要防的形态（D9① 原文）。守卫 b 的
+  // 独立载体（AgentTaskSpec.requires）下钻后在本分支前独立判定，首期显式 engine 即声明。
+  if (routing.source === "call") {
+    throw probeFailedError(routing.engineId, report, "engine 来自调用参数显式指定（能力依赖声明）——不兜底");
+  }
+
+  const fallbackId = fallbackTargetId(opts.routing, routing);
+  // 守卫 c：显式 model 与引擎 provider 体系绑定（D9② model/engine 正交）——换引擎
+  // 后 model 可解析性无法保证，静默换引擎跑 = 「以为用了 X 实际用 Y」。判定取保守
+  // 口径（显式 model + 引擎切换即拒）：路由层无各引擎 provider 注册表的访问面，
+  // 精确可解析性判定归引擎 prepare 期（ZcodePrepareError.model_not_available 已有）。
+  if (hasText(opts.taskModel) && fallbackId !== routing.engineId) {
+    throw new EngineError(
+      "model_not_available",
+      `engine '${routing.engineId}' probe 失败且任务显式指定 model '${opts.taskModel}'——model 与引擎 provider 体系绑定，换引擎（fallback 到 '${fallbackId}'）不静默执行`,
+      `修复 engine '${routing.engineId}' 的探针失败（见上方恢复指引）后重试，或去掉 model 指定 / 显式传 engine: '${fallbackId}' 确认模型可用后再派发`,
+    );
+  }
+
+  return {
+    engine: get(fallbackId),
+    engineId: fallbackId,
+    requestedEngineId: routing.engineId,
+    source: "default",
+    engineFallback: { from: routing.engineId, reason: "engine_probe_failed" },
+  };
+}
+
+/**
+ * fallback 目标：请求来自 frontmatter/调用参数 → 全局默认引擎；请求即全局默认
+ * （defaultEngine 配了坏引擎，source='default'）→ 内置缺省 'pi'（零风险回退——设计
+ * 终态四口径：fallback 回「缺省 pi」而非原地重试坏引擎）。全局默认与请求引擎相同
+ * （frontmatter engine === defaultEngine，如 agent .md engine: zcode + config
+ * defaultEngine: zcode）同样回 'pi'——回退到刚 probe 失败的同一引擎 = 原地重试坏
+ * 引擎（from==to 误导留痕），违背「回缺省 pi」的设计意图。
+ */
+function fallbackTargetId(routingInput: EngineRoutingInput, resolved: EngineRouting): string {
+  // source 与 engineId 由 resolved 承载配对关系，杜绝调用方传错配对的口子
+  if (resolved.source === "default") return DEFAULT_ENGINE_ID;
+  const global = routingInput.globalDefaultEngine;
+  if (hasText(global) && global !== DEFAULT_ENGINE_ID && global !== resolved.engineId) {
+    return global;
+  }
+  return DEFAULT_ENGINE_ID;
+}
+
+/** engine_probe_failed 的结构化构造（detail 含逐 check 摘要，recovery 用探针产出）。 */
+function probeFailedError(engineId: string, report: ProbeReport, guard: string): EngineError {
+  const checks = report.checks.map((c) => `${c.name}:${c.ok ? "ok" : "FAIL"}`).join(", ");
+  return new EngineError(
+    "engine_probe_failed",
+    `engine '${engineId}' probe 失败（${guard}）。checks: [${checks}]`,
+    report.error?.recovery ??
+      `Confirm the engine binary and version, then re-run the probe (probe({force:true}) or re-initialize the engine).`,
+  );
+}
+
+/** 路由来源描述（EngineNotFoundError 的 source 定位）。 */
+function describeRoutingSource(routing: EngineRoutingInput): string | undefined {
+  if (hasText(routing.callEngine)) {
+    return `call parameter engine='${routing.callEngine}'`;
+  }
+  if (hasText(routing.agentEngine)) {
+    return `agent frontmatter engine='${routing.agentEngine}'`;
+  }
+  return undefined;
+}