@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/routing.ts

@@ -1,27 +1,91 @@
 // 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 行）。
+// 配置路由与探针 fallback 编排（P4；W3 协议化改造）。设计权威源（现行）：
+// docs/design/subagent-engine-protocolization.md §3.8 D4（缺省引擎与 fallback 目标）/
+// §3.5.3（路由与执行时序契约——跨进程后作废「run 内首个 await 前已触达 executeAndAwait」，
+// 改为「首个 await 前完成路由决策；执行经进程边界，时序契约由本设计放宽」）；
+// 历史权威源 docs/architecture/subagent-engine-abstraction.md D9（配置路由三层 + 故障
+// fallback 三守卫 + model/engine 正交 + workflow 脚本不写死 engine）+ D7（探针分级与
+// 触发时机）+ §3.3.3 错误规格仍然有效。
 //
 // 职责边界：本模块只做「选哪个引擎」的决策（纯路由 + 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 覆盖后重探。
+// probe 触发时机（D7 的落地口径）：路由期触发、结果缓存于引擎实例（probeCache）。
+// 内置缺省 pi 免探——pi 契约稳定且「缺省路径行为零变化」是 A1 硬约束（每次 run 前
+// 强探会引入 pi --version 子进程开销与新的失败面）；显式 engine='pi' 同样免探
+// （fallback 无处可去，守卫 a 对 pi 不可达是自然结果而非缺口）。协议化后 cli 形态
+// 引擎的首个 run 前强制 initialize（协议握手，EngineClient 承担），与 probe 分立。
+// 进程存活期间缓存不失效——版本变化（运行中 CLI 被升级）由 engine_run_failed 运行中
+// 兜底，重启进程 / 重新注册后重探。
+
+import { getLogger } from "../../core/logger.ts";
 
 import { EngineError } from "./common/errors.ts";
 import type { EnginePort } from "./port.ts";
-import { DEFAULT_ENGINE_ID, EngineNotFoundError, getEngine, hasEngine, listEngines } from "./registry.ts";
+import {
+  DEFAULT_ENGINE_ID,
+  EngineNotFoundError,
+  getEngine,
+  hasEngine,
+  listEngines,
+  listEnginesByDisplayName,
+} from "./registry.ts";
+import {
+  ensureEngineDiscovered,
+  type DiscoverEnginesOptions,
+} from "./engine-discovery-scan.ts";
 import type { ProbeReport } from "./types.ts";
 
+// core log facade（execution 层统一 "subagents" component，模块顶层缓存惯例）。
+const logger = getLogger("subagents");
+
+// ============================================================
+// [W8] hasEngine 补扫通道（W4 ensureEngineDiscovered 的存在性校验接线）
+// ============================================================
+
+// 补扫发现参数 slot（globalThis[Symbol.for]——防 jiti 双路径加载分裂，对齐 registry
+// slot 惯例）。写入方 = 宿主接线面（runtime 在 W8 subagent-engine-history 的
+// ensureRuntimeEngineWiring 装载；pi 壳接线归后续单元——slot 未设置时本通道与裸
+// hasEngine 等价，零行为变化）。参数与 session_start 发现扫描同源（hostKind/agentDir/
+// dataDir），补扫只读 manifest 不握手（DiscoverEnginesOptions 语义）。
+const RESCAN_OPTS_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagent-workflow.engineDiscoveryRescanOpts");
+
+/** 宿主接线：登记补扫发现参数（与发现扫描同源；重复登记覆盖，幂等）。 */
+export function setEngineDiscoveryRescanOptions(opts: DiscoverEnginesOptions): void {
+  Reflect.set(globalThis, RESCAN_OPTS_SLOT_KEY, { current: opts });
+}
+
+function getEngineDiscoveryRescanOptions(): DiscoverEnginesOptions | undefined {
+  const slot = Reflect.get(globalThis, RESCAN_OPTS_SLOT_KEY) as
+    | { current: DiscoverEnginesOptions }
+    | undefined;
+  return slot?.current;
+}
+
+/**
+ * 存在性校验（快照优先 + 一次补扫）：registry 快照命中零开销返回；未命中且宿主已
+ * 接线补扫参数 → ensureEngineDiscovered 同步补扫（只读 manifest 不 spawn）后复核；
+ * 宿主未接线 → 与裸 hasEngine 等价。补扫异常吞掉返回 false（发现失败 ≠ 配置错误，
+ * 由 routeEngine 的 engine_not_found 恢复指引收口）。
+ */
+export function hasEngineWithRescan(id: string): boolean {
+  if (hasEngine(id)) return true;
+  const opts = getEngineDiscoveryRescanOptions();
+  if (opts === undefined) return false;
+  try {
+    return ensureEngineDiscovered(id, opts);
+  } catch (err) {
+    logger.debug(
+      `[engine-routing] rescan for engine '${id}' failed (treated as not discovered): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return false;
+  }
+}
+
 // ============================================================
 // 三层优先级（D9）
 // ============================================================
@@ -91,6 +155,12 @@ export interface EngineRouteOptions {
   hasEngineFn?: (engineId: string) => boolean;
   /** 注册表清单（缺省 registry.listEngines——engine_not_found 文案的数据源）。 */
   listEnginesFn?: () => string[];
+  /**
+   * 可用引擎清单（D4 回落目标序：manifest displayName 稳定序；缺省
+   * registry.listEnginesByDisplayName）。清单内 id 即视为可用（发现且已注册）——
+   * 调用方负责排序口径；routeEngine 按序取第一个 ≠ 请求引擎的 id 作回落目标。
+   */
+  listAvailableEnginesFn?: () => string[];
 }
 
 export interface EngineRouteResult {
@@ -105,46 +175,128 @@ export interface EngineRouteResult {
   engineFallback?: { from: string; reason: string };
 }
 
+/**
+ * D4 缺省引擎回落（default 层专用）：配置的缺省引擎 id 不在已发现清单（引擎被卸载 /
+ * 未安装任何引擎包）→ warn + 回落第一个可用引擎（manifest displayName 稳定序）+
+ * engineFallback 留痕（record 投影）。全不可用（清单空）→ 返回 undefined，调用方抛
+ * engine_not_found（「未发现任何引擎包」+ 安装指引），不静默。
+ *
+ * 宽容回落只作用于 default 层：call/frontmatter 层显式指定的未知 id 是配置错误
+ * （agent 作者/调用方写错），保持 engine_not_found 前置暴露（错误规格表第 1 行）——
+ * 静默换引擎会违反显式意图（守卫 a 同源）。
+ */
+function resolveDefaultEngineFallback(
+  requestedId: string,
+  available: readonly string[],
+): { engineId: string; fallback: { from: string; reason: string } } | undefined {
+  if (available.length === 0) return undefined;
+  const target = available[0]!;
+  logger.warn(
+    `[engine-routing] default engine '${requestedId}' is not in the discovered engines ` +
+      `[${available.join(", ")}]; falling back to first available engine '${target}' (D4, recorded via engineFallback)`,
+  );
+  return { engineId: target, fallback: { from: requestedId, reason: "engine_not_found" } };
+}
+
 /**
  * 路由 + 探针 + fallback 编排（SAR run 入口调用）。
  *
  * 失败形态（全部抛结构化错误，调用方转 AgentResult.error）：
- *   - 未注册 id（调用参数层漏网）：EngineNotFoundError（engine_not_found）
+ *   - 未注册 id（call/frontmatter 层）：EngineNotFoundError（engine_not_found）
+ *   - default 层缺省引擎不在清单且无任何可用引擎：EngineNotFoundError
+ *     （「未发现任何引擎包」+ 安装指引，D4）
  *   - 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 { has, get, available } = resolveRouteHelpers(opts);
   const routing = resolveEngineRouting(opts.routing);
 
-  // 调用参数层的注册表校验（frontmatter 层已在 agent 解析期抛过；这里兜调用参数
-  // 直传的未注册 id——错误含注册清单，配置错误前置到路由期而非 getEngine 深处）
+  // 注册表校验：call/frontmatter 层未知 id 直接报（配置错误前置暴露）；default 层走
+  // D4 宽容回落（配置的缺省引擎被卸载 ≠ 用户写错 id——环境变化，回落 + 留痕）。
   if (!has(routing.engineId)) {
-    throw new EngineNotFoundError(routing.engineId, opts.listEnginesFn?.() ?? listEngines(), describeRoutingSource(opts.routing));
+    return resolveUnregisteredEngine(opts, routing, get, available);
   }
 
-  // 缺省引擎免探（见文件头「probe 触发时机」）——直接取引擎
+  // 内置缺省 pi 免探（见文件头「probe 触发时机」）——直接取引擎
   if (routing.engineId === DEFAULT_ENGINE_ID) {
-    return {
-      engine: get(routing.engineId),
-      engineId: routing.engineId,
-      requestedEngineId: routing.engineId,
-      source: routing.source,
-    };
+    return directRoute(get(routing.engineId), routing);
   }
 
   const report = await opts.probe(routing.engineId);
   if (report.ok) {
-    return {
-      engine: get(routing.engineId),
-      engineId: routing.engineId,
-      requestedEngineId: routing.engineId,
-      source: routing.source,
-    };
+    return directRoute(get(routing.engineId), routing);
   }
 
-  // ── probe 失败：strict / 三守卫 / fallback（D9①）──
+  return resolveProbeFailedRoute(opts, routing, get, available, report);
+}
+
+/**
+ * routeEngine 的注入解析。[W8 补扫接线] 缺省存在性校验经 hasEngineWithRescan（快照
+ * 未命中触发一次三级补扫，W4 ensureEngineDiscovered 通道——「装了包 → 下次解析即可用」）；
+ * 宿主显式注入 hasEngineFn 时以注入值为准（测试 / 宿主自定义通道不变）。
+ */
+function resolveRouteHelpers(opts: EngineRouteOptions): {
+  has: (engineId: string) => boolean;
+  get: (engineId: string) => EnginePort;
+  available: () => string[];
+} {
+  return {
+    has: opts.hasEngineFn ?? hasEngineWithRescan,
+    get: opts.getEngineFn ?? getEngine,
+    available: opts.listAvailableEnginesFn ?? listEnginesByDisplayName,
+  };
+}
+
+/**
+ * 注册表校验失败（请求 id 未发现）的收口：default 层 D4 宽容回落（清单空 → throw
+ * 「未发现任何引擎包」+ 安装指引，不静默）；call/frontmatter 层配置错误前置暴露。
+ */
+function resolveUnregisteredEngine(
+  opts: EngineRouteOptions,
+  routing: EngineRouting,
+  get: (engineId: string) => EnginePort,
+  available: () => string[],
+): EngineRouteResult {
+  if (routing.source !== "default") {
+    throw new EngineNotFoundError(routing.engineId, opts.listEnginesFn?.() ?? listEngines(), describeRoutingSource(opts.routing));
+  }
+  const fallback = resolveDefaultEngineFallback(routing.engineId, available());
+  if (fallback === undefined) {
+    // 全不可用：派发期 engine_not_found（「未发现任何引擎包」+ 安装指引，D4）
+    throw new EngineNotFoundError(routing.engineId, [], describeRoutingSource(opts.routing));
+  }
+  const fallbackTrace = fallback.fallback;
+  // 回落目标直接取用不探（probe 已失败一次不重复；目标引擎不可用由 run 期显式失败）
+  return {
+    engine: get(fallback.engineId),
+    engineId: fallback.engineId,
+    requestedEngineId: fallbackTrace.from,
+    source: routing.source,
+    engineFallback: fallbackTrace,
+  };
+}
+
+/** 直接取用形态（pi 免探 / probe 通过）：请求即执行，无 fallback 留痕。 */
+function directRoute(engine: EnginePort, routing: EngineRouting): EngineRouteResult {
+  return {
+    engine,
+    engineId: routing.engineId,
+    requestedEngineId: routing.engineId,
+    source: routing.source,
+  };
+}
+
+/**
+ * probe 失败收口：strict / 三守卫 / fallback（D9① + D4 回落目标改「首个可用引擎」）。
+ */
+function resolveProbeFailedRoute(
+  opts: EngineRouteOptions,
+  routing: EngineRouting,
+  get: (engineId: string) => EnginePort,
+  available: () => string[],
+  report: ProbeReport,
+): EngineRouteResult {
   if (opts.strict) {
     throw probeFailedError(routing.engineId, report, "engineRouting.strict=true：probe 失败一律报错（不 fallback）");
   }
@@ -156,7 +308,11 @@ export async function routeEngine(opts: EngineRouteOptions): Promise<EngineRoute
     throw probeFailedError(routing.engineId, report, "engine 来自调用参数显式指定（能力依赖声明）——不兜底");
   }
 
-  const fallbackId = fallbackTargetId(opts.routing, routing);
+  const fallbackId = fallbackTargetId(opts.routing, routing, available());
+  // D4：无可用引擎则不 fallback（直接报错）——回「未发现任何引擎包」口径，不静默
+  if (fallbackId === undefined) {
+    throw probeFailedError(routing.engineId, report, "probe 失败且无其他可用引擎可兜底（D4：不原地重试坏引擎）");
+  }
   // 守卫 c：显式 model 与引擎 provider 体系绑定（D9② model/engine 正交）——换引擎
   // 后 model 可解析性无法保证，静默换引擎跑 = 「以为用了 X 实际用 Y」。判定取保守
   // 口径（显式 model + 引擎切换即拒）：路由层无各引擎 provider 注册表的访问面，
@@ -179,21 +335,28 @@ export async function routeEngine(opts: EngineRouteOptions): Promise<EngineRoute
 }
 
 /**
- * fallback 目标：请求来自 frontmatter/调用参数 → 全局默认引擎；请求即全局默认
- * （defaultEngine 配了坏引擎，source='default'）→ 内置缺省 'pi'（零风险回退——设计
- * 终态四口径：fallback 回「缺省 pi」而非原地重试坏引擎）。全局默认与请求引擎相同
- * （frontmatter engine === defaultEngine，如 agent .md engine: zcode + config
- * defaultEngine: zcode）同样回 'pi'——回退到刚 probe 失败的同一引擎 = 原地重试坏
- * 引擎（from==to 误导留痕），违背「回缺省 pi」的设计意图。
+ * fallback 目标（D4 终态语义：恒 'pi' 改「首个可用引擎」，无可用引擎返回 undefined
+ * 由调用方直接报错不 fallback）。available = D4 排序清单（manifest displayName 稳定序）。
+ *
+ * - 请求来自 frontmatter/调用参数：优先全局默认引擎（可用且 ≠ 刚失败引擎时）；
+ *   全局默认不可用/未配置/即请求引擎 → 首个可用引擎（排除 from——回退到刚 probe
+ *   失败的同一引擎 = 原地重试坏引擎，from==to 误导留痕）。
+ * - 请求即全局默认（defaultEngine 配了坏引擎，source='default'）：首个可用引擎。
+ * - 清单排除 from 后为空 → undefined（无可用引擎，直接报错）。
  */
-function fallbackTargetId(routingInput: EngineRoutingInput, resolved: EngineRouting): string {
+function fallbackTargetId(
+  routingInput: EngineRoutingInput,
+  resolved: EngineRouting,
+  available: readonly string[],
+): string | undefined {
   // 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;
+  if (resolved.source !== "default") {
+    const global = routingInput.globalDefaultEngine;
+    if (hasText(global) && global !== resolved.engineId && available.includes(global)) {
+      return global;
+    }
   }
-  return DEFAULT_ENGINE_ID;
+  return available.find((id) => id !== resolved.engineId);
 }
 
 /** engine_probe_failed 的结构化构造（detail 含逐 check 摘要，recovery 用探针产出）。 */
@@ -237,7 +400,7 @@ export interface HostRouteOptions {
   probe: (engineId: string) => Promise<ProbeReport>;
   /**
    * 本地 pi 引擎实例（chat 域 = Service 的 chatPiEngine；workflow 域 = SAR 的 per-session
-   * DI 实例）。pi 请求与「非 pi 兜底回 pi」两种形态都由它接管——不依赖 registry 全局
+   * DI 实例）。pi 请求与「兜底回 pi」两种形态都由它接管——不依赖 registry 全局
    * 注册态（单测注入 mock 时全局单例不可见；生产环境两者是同一进程单例对象）。
    */
   piEngine: EnginePort;
@@ -247,17 +410,21 @@ export interface HostRouteOptions {
   hasEngineFn?: (engineId: string) => boolean;
   /** 非 pi 注册表清单（缺省 registry.listEngines）。 */
   listEnginesFn?: () => string[];
+  /** D4 可用引擎清单（缺省 registry.listEnginesByDisplayName；透传 routeEngine）。 */
+  listAvailableEnginesFn?: () => string[];
 }
 
 /**
  * 宿主侧统一路由编排（D3-②：唯一实现，两调用点——SubagentService.execute 与
  * SAR.run）。把原先散在两调用点的「pi 同步短路 + registry 注入（本地 pi 恒可用，
- * engine_not_found 文案不把本地 pi 漏报成未注册）+ 兜底回 pi 时换本地实例」收敛到本函数。
+ * engine_not_found 文案不把本地 pi 漏报成未注册）+ 兜底换本地实例」收敛到本函数。
  *
- * 返回值形态（时序契约）：pi 请求路径**同步返回** EngineRouteResult（非 Promise）——
- * 不引入微任务边界，SAR 的「run 内首个 await 前已触达 executeAndAwait」缺省路径时序
- * 与旧形态逐字节一致；非 pi 路径返回 Promise（probe 编排固有异步），调用方统一用
- * `routed instanceof Promise ? await routed : routed` 消费（pi 路径零 await）。
+ * 时序契约（W3 改写，设计 §3.5.3）：pi 请求路径**同步返回** EngineRouteResult（非
+ * Promise）——**首个 await 前完成路由决策**（engine id 已定，A2 观测点）；其后的执行
+ * 经进程边界（cli 形态 spawn + 握手 + 帧往返必经 await），「run 内首个 await 前已触达
+ * `executeAndAwait`」的旧时序契约由本设计**作废放宽**。非 pi 路径返回 Promise（probe
+ * 编排固有异步），调用方统一用 `routed instanceof Promise ? await routed : routed` 消费
+ * （pi 路径零 await）。
  */
 export function routeEngineForHost(opts: HostRouteOptions): EngineRouteResult | Promise<EngineRouteResult> {
   const routing = resolveEngineRouting(opts.routing);
@@ -279,7 +446,7 @@ export function routeEngineForHost(opts: HostRouteOptions): EngineRouteResult |
     strict: opts.strict,
     probe: opts.probe,
     // 本地 pi 恒可用（per-session DI 绑定）——get/has/list 注入同一口径：
-    // probe 失败兜底回 pi 时取本地实例接管，engine_not_found 文案不漏报本地 pi。
+    // probe 失败兜底时取本地实例接管，engine_not_found 文案不漏报本地 pi。
     getEngineFn: (engineId) =>
       engineId === DEFAULT_ENGINE_ID ? opts.piEngine : (opts.getEngineFn?.(engineId) ?? getEngine(engineId)),
     hasEngineFn: (engineId) =>
@@ -288,5 +455,11 @@ export function routeEngineForHost(opts: HostRouteOptions): EngineRouteResult |
       const listed = opts.listEnginesFn?.() ?? listEngines();
       return listed.includes(DEFAULT_ENGINE_ID) ? listed : [DEFAULT_ENGINE_ID, ...listed];
     },
+    // D4 可用清单透传（缺省 displayName 稳定序；注入缺失时本地 pi 仍须在清单内，
+    // 否则 fallback「首个可用引擎」会把本地 pi 漏掉）
+    listAvailableEnginesFn: () => {
+      const available = opts.listAvailableEnginesFn?.() ?? listEnginesByDisplayName();
+      return available.includes(DEFAULT_ENGINE_ID) ? available : [DEFAULT_ENGINE_ID, ...available];
+    },
   });
 }

package/src/execution/engine/types.ts

@@ -3,111 +3,48 @@
 // 引擎中立类型层（P1）。设计权威源：docs/architecture/subagent-engine-abstraction.md
 // §3.3.5（EnginePort 与中立类型完整契约）+ §3.3.6（EngineHandle/journal/SessionView 格式）。
 //
-// 为什么单独一层：执行层现有四个核心类型（ExecuteOptions/AgentEvent/AgentResult/AgentRunner
-// port）的中立是「碰巧的，不是设计的」——thinkingLevel 是 pi 7 档枚举、skillPath 假设引擎有
-// --skill flag、conversation/idleTimeoutMs 是 pi chatMode 专属形态（设计 §2.1）。本文件把
-// 「agent 调用」的引擎无关语义显式化为 AgentOutcome 等类型，EnginePort（port.ts）与其下
-// 各引擎适配器都以本层为唯一契约点。
-//
-// [D6 任务形状合流] 原本层的任务声明类型 AgentTaskSpec/PersonaSpec 已并入
-// orchestration/models/types.ts 的 AgentCallOpts（单一任务形状，SAR 直产、pi 边界一次
-// 直出——docs/design/subagent-dual-track-convergence.md §3.3 D6）。本文件不再定义任务
-// 声明；EnginePort.run 的入参即 AgentCallOpts（字段裁定与裁撤记录见其类型注释）。
+// [S4 簇 3 收编] 契约类型单源化（type-only）：AgentOutcome / EngineHandleData /
+// ReplayedTurn / SessionView / EngineCapabilities / ProbeReport / InteractAction /
+// InteractResult 的本地定义已删除，自 @zhushanwen/subagent-engine-sdk re-export
+// （SDK protocol/contract-types.ts 是类型闭包 SSOT，core 反向 re-export 保上层消费面
+// ——import 方路径零改动；结构等价由 protocol-closure.test.ts 断言族守卫）。
+// EngineHandle 留守本地：SDK 无此类型（协议面用裸 data 载荷），宿主侧句柄包装接口
+// 是 core 域概念。
 //
 // AgentResult 消歧（设计 §2.1/§3.3.5）：仓内有两个同名 AgentResult——
 //   ① orchestration 层 workflow 消费的那份（orchestration/models/types.ts，主字段
-//      content/parsedOutput/usage/error）——中立层锚定这份，AgentOutcome 的字段就是它的
-//      超集（+ engineId/engineFallback/exitCode）；
+//      content/parsedOutput/usage/error）——SDK AgentOutcome 锚定这份；
 //   ② execution 层的同名类型（execution/types.ts，主字段 text/turns/sessionId/toolCalls）
 //      ——record 内部投影，保持原名不动。
 // 引擎层终态命名 AgentOutcome，与两者不同名，消除「同名不同义」。
 
-import type { AgentFailureKind, AgentUsage, ToolCallEntry } from "../../orchestration/models/types.ts";
-import type { AgentUsageTotal, ToolCall } from "../types.ts";
+import type { EngineHandleData } from "@zhushanwen/subagent-engine-sdk";
 
-// AgentEvent 8 种事件原样保留，唯一权威定义仍是 execution/types.ts——引擎层 re-export
-// 不复制第二份（设计 §3.3.5）；经 shared/agent-event.ts 的既有出口转发，维持「shared/
-// 是类型共享层」的架构约定。新增粗粒度约束（coarse 引擎至少合成一次 message_end +
-// 一次 turn_end）由 conformance 套件断言（P4），不在类型层编码。
+// AgentEvent 8 种事件：权威定义在 SDK contract-types，经 execution/types.ts re-export
+// → shared/agent-event.ts 转发层 → 本文件（链条保持，维持「shared/ 是类型共享层」的
+// 架构约定）。新增粗粒度约束（coarse 引擎至少合成一次 message_end + 一次 turn_end）
+// 由 conformance 套件断言（P4），不在类型层编码。
 export type { AgentEvent } from "../../shared/agent-event.ts";
 
 // ============================================================
-// AgentOutcome（锚定 orchestration 层 AgentResult，§3.3.5）
+// SDK 契约类型 re-export（单源收编，S4 簇 3）
 // ============================================================
 
-/**
- * 一次引擎执行的终态。锚定 orchestration/models/types.ts 的 AgentResult（workflow
- * 引擎消费的那份——content/parsedOutput/usage/error）并追加引擎层字段；见文件头消歧说明。
- */
-export interface AgentOutcome {
-  /** 原样（AgentResult.content）。 */
-  content: string;
-  /**
-   * 原样（AgentResult.failureKind，D5-③ 失败分诊结构化标签）。产出侧唯一识别点 =
-   * engines/pi/output-collector（collectResult 分类写入）；缺省 = unknown = 可重试
-   * （消费侧 executeAgentCall 只读字段分诊，不扫 error 文案）。非 pi 引擎不产出，
-   * 恒缺省（unknown 语义）。
-   */
-  failureKind?: AgentFailureKind;
-  /**
-   * 原样（AgentResult.parsedOutput）。native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：
-   * native 路径公共层不做二次校验、不改写其结果）。
-   */
-  parsedOutput?: unknown;
-  /** 原样（AgentResult.usage，orchestration 版 AgentUsage：含 contextTokens/turns）。 */
-  usage?: AgentUsage;
-  /** 原样（AgentResult.durationMs）。 */
-  durationMs?: number;
-  /** 原样（AgentResult.error，错误码前缀格式见设计 §3.3.3 错误规格表）。 */
-  error?: string;
-  /** 原样（AgentResult.sessionId，引擎语义 session id）。 */
-  sessionId?: string;
-  /** 原样（AgentResult.sessionFile）。 */
-  sessionFile?: string;
-  /** 原样（AgentResult.worktreePath，仅诊断——目录可能已被 finalize 清理）。 */
-  worktreePath?: string;
-  /** 原样（AgentResult.toolCalls，ToolCallEntry[]）。 */
-  toolCalls?: ToolCallEntry[];
-  /** 新增：实际执行引擎（fallback 后可能 ≠ 请求值，D9①）。 */
-  engineId: string;
-  /** 新增：fallback 留痕（record 同步投影，GUI 警告条数据源）。P1 恒缺省（无 fallback 路由）。 */
-  engineFallback?: { from: string; reason: string };
-  /** 新增：null = 被信号杀死（杀链/abort 合成终态的判据）。P1 pi 链路不暴露 exit code，恒缺省。 */
-  exitCode?: number | null;
-}
+export type {
+  AgentOutcome,
+  EngineCapabilities,
+  EngineHandleData,
+  InteractAction,
+  InteractResult,
+  ProbeReport,
+  ReplayedTurn,
+  SessionView,
+} from "@zhushanwen/subagent-engine-sdk";
 
 // ============================================================
-// EngineHandle（run/interact/read 三面的连接件，D1/§3.3.6）
+// EngineHandle（run/interact/read 三面的连接件，D1/§3.3.6）——core 域类型留宿主侧
 // ============================================================
 
-/**
- * EngineHandle 的持久化形态（设计 §3.3.6，JSON v1）。
- * 内存态 EngineHandle = 本数据 + 引擎运行时引用（各引擎自持）。
- */
-export interface EngineHandleData {
-  v: 1;
-  /** 引擎 id（'pi' | 'zcode' | ...，registry key）。 */
-  engineId: string;
-  /**
-   * 引擎自定义键值（定位符）。pi = { recordId?, sessionFile? }——recordId 是
-   * interact 控制面的 key（subagent record id），sessionFile 是 read 第①级（JSONL
-   * 直读）的定位符；zcode = { sessionId, dbPath }。
-   */
-  sessionRef: Record<string, string>;
-  /** 隔离池定位（设计 §3.3.9）。pi 无池化（PI_CODING_AGENT_DIR 全局一份）恒 'shared'。 */
-  poolKey: string;
-  /**
-   * journal 绝对路径（read 第②级数据源；runtime 读前校验前缀白名单）。
-   * P2 event journal 落地后由宿主回填；P1 无 journal 写入者，缺省 undefined——
-   * read 降级链第②级不可达，直接走 ①/③。
-   */
-  journalPath?: string;
-  /** probe 实测版本（漂移排查锚点）。 */
-  engineVersion?: string;
-  /** 适配器版本（golden 样本对齐排查）。 */
-  adapterVersion: string;
-}
-
 /**
  * 引擎会话句柄（run 返回、interact/read 入参）。
  *
@@ -122,115 +59,3 @@ export interface EngineHandle {
   /** 持久化数据。上层不得解构其内部字段（见契约三条）。 */
   readonly data: EngineHandleData;
 }
-
-// ============================================================
-// SessionView（read 返回，D6/§3.3.6）
-// ============================================================
-
-/**
- * read(handle) 的返回：turns[] 派生数据。与 Turn 同构但无内部态（_status/startedTs
- * 剥离，closed 恒 true）。
- */
-export interface ReplayedTurn {
-  text: string;
-  thinking: string;
-  /** 导出的纯净形状（execution 层 ToolCall，无 _status）。 */
-  toolCalls: ToolCall[];
-  closed: true;
-}
-
-/**
- * session 历史的引擎中立视图。降级链三级（D6）：①引擎原生读取（pi JSONL / zcode
- * sqlite）→ ②宿主 event journal 重放（P2）→ ③outcome-only。source 字段是 GUI 降级
- * 标记数据源（A8）。
- */
-export interface SessionView {
-  engineId: string;
-  sessionId?: string;
-  /** turns[] 派生数据（重放/重建产物）。 */
-  turns: ReplayedTurn[];
-  /** 各 turn usageDelta 聚合（execution 层 AgentUsageTotal）。 */
-  usage?: AgentUsageTotal;
-  source: "native" | "journal" | "outcome-only";
-}
-
-// ============================================================
-// EngineCapabilities（D3，三级声明）
-// ============================================================
-
-/**
- * 引擎能力声明（设计 D3 原样落地）。三级：native / emulated / unsupported。
- *
- * 易错点（D3）：声明的是**本仓 subagent 链路实际接通的能力**，不是引擎 RPC 层的理论
- * 能力——pi 的 RPC 有 steer 但现有 spawn 链路未接通（session-runner steer no-op），
- * 故 PiEngine 声明 unsupported，接通后再升级。上层据声明选择策略（schema 为 emulated
- * 时自动走公共降级层；steer/conversation unsupported 时 UI 隐藏对应入口），而非
- * try-catch 运行时试错。
- */
-export interface EngineCapabilities {
-  /** native: --json-schema/--output-schema/env 注入（pi = PI_WORKFLOW_SCHEMA 链路）。 */
-  schemaEnforcement: "native" | "emulated";
-  /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
-  steer: "native" | "emulated" | "unsupported";
-  /** interact 控制面（message/close/cancel + idle）。 */
-  conversation: "native" | "unsupported";
-  /** 决定 persona 路由策略（公共降级层按此选择 file/flag/prompt 通道）。 */
-  personaInjection: "file" | "flag" | "prompt";
-  /** 粗粒度引擎：GUI 显示降级为阶段态。 */
-  eventGranularity: "stream" | "coarse";
-  /** emulated = worktree 隔离（无 OS sandbox 的引擎用文件写维度隔离补齐）。 */
-  sandbox: "native" | "emulated" | "none";
-  /** 重建历史的能力（read 降级链第①级的保真度上限）。 */
-  sessionRead: "full" | "partial" | "outcome-only";
-  resume: "native" | "cold" | "unsupported";
-  /** 优雅中断 or 只能杀进程（公共杀链兜底，见 D1 abort 分级）。 */
-  interrupt: "native" | "kill-only";
-  /** kimi headless 固定 auto = ignored；GUI 据此隐藏/提示。 */
-  permissionMode: "native" | "fixed" | "ignored";
-  /**
-   * [D3-④ r3 裁定] maxTurns 轮数上限的执行能力位（pi = true：turn limiter + spawn
-   * watchdog 估算兑现；zcode = false：无 turn_end 语义，静默丢弃会造成「传了上限却
-   * 失控」假象）。调用前预检（common/capability-gate）按本位拦「声明不支持的能力」
-   * ——pi 不拦 maxTurns（已支持能力，由 turn-limiter 执行）、zcode 同步拒绝。
-   * 现状 11 个能力位无可承载 maxTurns 的语义位（fork 拦截可借 session 分叉通道族判，
-   * maxTurns 无可借位），故扩位而非保留引擎内硬编码 shape 检查。
-   */
-  maxTurns: boolean;
-}
-
-// ============================================================
-// probe（D7）与 interact（D1）的负载类型
-// ============================================================
-
-/** 引擎探针报告（probe() 返回）。探针在引擎 factory 初始化与版本变化检测时触发（P4 接线）。 */
-export interface ProbeReport {
-  ok: boolean;
-  /** 实测版本（handle.engineVersion 数据源）。探测不到时为空串。 */
-  engineVersion: string;
-  /** 二进制存在/版本解析/干跑回归逐项。 */
-  checks: Array<{ name: string; ok: boolean; detail?: string }>;
-  /** engine_probe_failed 的恢复指引（设计 §3.3.3 终态四样例；ok=false 时必填）。 */
-  error?: { code: string; recovery: string };
-}
-
-/**
- * interact 的 action（D1 交互控制面）。pi 首期原生实现（现有 chatMode 行为直通）；
- * 声明 conversation unsupported 的引擎调用前拒绝（engine_capability_unsupported）。
- */
-export type InteractAction =
-  /**
-   * interrupt：true = steer（抢占）/ false|缺省 = followUp（排队）——pi streamingBehavior
-   * 语义的中立承载（D1 §3.3.5「后续 wave 如需抢占语义再扩展 InteractAction」的兑现，
-   * chat 域投递经 engine.interact 接通时落地；不支持抢占的引擎忽略）。
-   */
-  | { kind: "message"; payload: string; interrupt?: boolean }
-  | { kind: "close"; payload?: { force: boolean } }
-  | { kind: "cancel" };
-
-/**
- * interact 的结果。失败码取自设计 §3.3.3：engine_session_not_resumable（死 handle）/
- * engine_capability_unsupported（能力声明拒绝）等。
- */
-export type InteractResult =
-  | { ok: true; delivered: true }
-  | { ok: false; code: string; message: string };