@zhushanwen/subagent-core 0.2.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,158 @@
+// src/execution/engine/model-prompt.ts
+//
+// [U7] 引擎模型段 system prompt 注入（模型可发现性）。
+// [engine-awareness U2] 引擎恒在状态段 <current_subagent_engine>（设计权威源：
+// docs/design/subagent-engine-awareness-injection.md §3.1 终态逐字基准 / §3.3 D6、D7）。
+//
+// 背景：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 段形成「一段一引擎」的分界标注。
+//
+// 恒在状态段（D6）：现状 AI 对「当前默认引擎」无权威信息源，只能从「zcode 段缺失
+// 与否」反推（pi 时完全无声明）。<current_subagent_engine> 恒在段显式声明当前引擎
+// 并裁决「AGENTS.md 路由表的 pi-registry id 在非 pi 引擎下不适用」的指令冲突。
+//
+// engine-neutral：遍历注册表驱动，未来引擎实现 listModels 即自动注入，宿主零改动。
+
+import { DEFAULT_ENGINE_ID, getEngine, hasEngine, normalizeEngineId } 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");
+}
+
+/**
+ * 恒在状态段 <current_subagent_engine>（设计 D6：pi 引擎也声明——AI 不需要
+ * 「从段缺失反推」当前引擎）。三种形态（§3.1 终态逐字基准 + 失败路径表）：
+ *   - 缺省 / pi：声明 pi + 指向上方核心段 <available_provider_models>（无冲突 bullet）；
+ *   - 非 pi 且已注册：指向下方该引擎清单段 + 「pi registry id 不适用」+ AGENTS.md
+ *     冲突裁决 bullet + 省略 model 用引擎默认；
+ *   - 未注册引擎（如配置手误 "ghost"）：如实显示配置值 + 警告行（派发将报
+ *     engine_not_found，指引修 subagents/config.json）——G4 诚实降级：不静默、不伪造。
+ *
+ * 字节稳定（D7）：纯字符串确定性拼装（无 localeCompare / 无随机序 / 无时间态）；
+ * 引擎注册与否经 hasEngine 只读判断（不取实例、不触发工厂副作用），同输入恒同输出。
+ */
+export function buildSubagentEngineSection(defaultEngine: string | undefined): string {
+  // 归一走 registry.normalizeEngineId 单一权威源：本函数与 buildEngineModelsPromptAppend
+  // （及引擎感知检测 diff）必须对同一读取结果给出同一引擎 id，否则两处会说谎
+  const engineId = normalizeEngineId(defaultEngine);
+  const lines = [
+    "<current_subagent_engine>",
+    "Default engine for subagent dispatches when neither the call's `engine` param",
+    `nor an agent .md \`engine\` frontmatter overrides: ${engineId}`,
+  ];
+  if (engineId === CORE_ENGINE_ID) {
+    // pi：清单在上方核心段，无需引擎侧清单段，也无 AGENTS.md 冲突（路由表 id 本就是 pi 的）
+    lines.push(
+      "- Model ids for pi dispatches are the ids in <available_provider_models> above.",
+      "- Omit `model` to use the engine default.",
+    );
+  } else if (hasEngine(engineId)) {
+    lines.push(
+      `- Model ids for ${engineId} dispatches are listed in <available_${engineId}_models> below.`,
+      `  Ids in <available_provider_models> do NOT apply to ${engineId} dispatches.`,
+      "- Omit `model` to use the engine default.",
+      // AGENTS.md 冲突裁决 bullet（§3.1 逐字基准）：全局路由表给的绝对 pi id 是 2026-08-28
+      // 事故根因——更强的指令源必须被段内显式裁决约束
+      "- If AGENTS.md or other standing guidance names model ids from the pi registry",
+      "  (e.g. zai-coding-cn/*), those ids apply to pi-engine dispatches ONLY — when",
+      "  the current engine is not pi, use only ids from the engine section below.",
+    );
+  } else {
+    // 失败路径表「未注册引擎」行：文案逐字为恢复指引（与 dispatch 期 engine_not_found 对齐）
+    lines.push(
+      `- engine '${engineId}' is not registered — dispatches will fail at routing; fix subagents/config.json`,
+    );
+  }
+  lines.push("</current_subagent_engine>");
+  return lines.join("\n");
+}
+
+/**
+ * 清单段「无凭据模型」提示行形态（§3.1 失败路径表：状态段正常、清单段显示提示行）。
+ * 为什么不返回空串：状态段（恒在）声明「ids listed in <available_<engine>_models>
+ * below」，段缺失会让该声明说谎；提示行保持段存在且如实声明当前无任何可派发的
+ * 显式模型（G4 诚实降级）。文案逐字取自设计失败路径表恢复指引列。
+ *
+ * 仅服务「引擎实现了 listModels 但当前空清单 / 抛异常」两种形态——引擎侧 provider
+ * 体系存在、只是暂时没有可用模型，恢复动作是去宿主配置凭据。
+ */
+function buildEmptyModelsHint(engineId: string): string {
+  return [
+    `<available_${engineId}_models>`,
+    `engine '${engineId}' has no credentialed models right now — configure the provider in ZCode desktop first`,
+    `</available_${engineId}_models>`,
+  ].join("\n");
+}
+
+/**
+ * 清单段「与主 agent 模型体系一致」声明行形态（U2 一致性审查修订：未实现 ≠ 无模型）。
+ * port 契约（port.ts listModels JSDoc）：引擎省略 listModels 或返回 null = 引擎没有
+ * 自己的 provider 枚举面，模型 id 沿用主 agent 的 <available_provider_models>——
+ * 与「引擎有 provider 体系但无凭据模型」（buildEmptyModelsHint）是两种不同事实，
+ * 文案必须区分：此处若复用「no credentialed models + ZCode desktop 指引」会让 AI
+ * 误以为引擎不可派发、且 ZCode desktop 指引无处落地。
+ * 段仍保留 <available_<engine>_models> 包裹：状态段恒在声明「listed in ... below」，
+ * 段缺失会让该声明说谎（与 buildEmptyModelsHint 同理）。
+ */
+function buildCoreAlignedHint(engineId: string): string {
+  return [
+    `<available_${engineId}_models>`,
+    `engine '${engineId}' uses the same model registry as the main agent — use ids from <available_provider_models> above`,
+    `</available_${engineId}_models>`,
+  ].join("\n");
+}
+
+/**
+ * 依据全局 defaultEngine 生成追加段（不含前导换行）。
+ *
+ * 规则（设计 §3.1 失败路径表 + G4 + U2 一致性审查修订）：
+ *   - defaultEngine 为 pi / 缺省 → 不注入（pi 段已由核心提供）；
+ *   - 引擎未注册 → 不注入（状态段 <current_subagent_engine> 已有警告行，避免双份）；
+ *   - 已注册且 listModels 有清单 → 注入该引擎段（渲染不变）；
+ *   - 已注册但 listModels 未实现 / 返回 null → 「与主 agent 模型体系一致」声明段
+ *     （port 契约语义：引擎无自有 provider 枚举面，id 见上方核心段，见
+ *     buildCoreAlignedHint）；
+ *   - 已注册但空清单 / listModels 抛异常 → 「无凭据模型」提示行段（引擎 provider
+ *     体系存在但当前无可用模型，见 buildEmptyModelsHint；从「静默不注入」改为如实
+ *     声明——空清单返回空串会让 AI 误以为没有任何引擎清单可看）。
+ * fail-safe：listModels 异常同样落提示行段、不向外抛（注入失败不阻塞 agent loop——
+ * 与 system-prompt extension 的 before_agent_start 处置一致）。
+ */
+export function buildEngineModelsPromptAppend(defaultEngine: string | undefined): string {
+  // 归一走 registry.normalizeEngineId 单一权威源（与状态段渲染同一 normalize，见上文）
+  const engineId = normalizeEngineId(defaultEngine);
+  if (engineId === CORE_ENGINE_ID) return "";
+  // hasEngine 只读判断（不触发工厂）；未注册时状态段负责警告，这里保持空串
+  if (!hasEngine(engineId)) return "";
+  try {
+    const engine = getEngine(engineId);
+    if (engine.listModels === undefined) return buildCoreAlignedHint(engineId);
+    const models = engine.listModels();
+    if (models === null) return buildCoreAlignedHint(engineId);
+    if (models.length === 0) return buildEmptyModelsHint(engineId);
+    return buildEngineSection(engineId, models);
+  } catch {
+    // listModels 抛异常（如 v2 config 损坏）＝引擎枚举面存在但读取失败，与空清单
+    // 同属「暂无可派发的显式模型」：降级为无凭据提示行而非静默
+    return buildEmptyModelsHint(engineId);
+  }
+}
+
+/** 测试口：段格式导出（避免测试依赖注册表组装全链）。 */
+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,133 @@
+// 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";
+
+/**
+ * defaultEngine 缺省归一（单一权威源）：空白 / undefined 归一到缺省引擎（'pi'）。
+ * 引擎感知检测 diff 与状态段渲染必须对同一读取结果给出同一引擎 id——若两处各自
+ * 内联归一，一致性只靠注释人工耦合，漂移即两处说谎；故收敛到本函数供各处调用。
+ * sanitize 保证透传值非空，但可能带首尾空格，故 trim 后再判。
+ */
+export function normalizeEngineId(engine: string | undefined): string {
+  return engine?.trim() || DEFAULT_ENGINE_ID;
+}
+
+/**
+ * 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();
+}