@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/port.ts

@@ -23,6 +23,11 @@
 
 import type { ChildProcess } from "node:child_process";
 
+import type {
+  HostRoundLifecycleParams,
+  ResumeAnchor,
+} from "@zhushanwen/subagent-engine-sdk";
+
 import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ModelInfo } from "../model-resolver.ts";
 import type { SubagentStream } from "../stream-sink.ts";
@@ -120,6 +125,34 @@ export interface RunContext {
    * SIGTERM / 单任务 abort 误杀共享进程）。
    */
   onChildSpawned?: (child: ChildProcess) => void;
+  /**
+   * [W3 v1.x] chat 会话形态参数（协议 run.params.chat 的 RunContext 承载位）：
+   *   - recordId：core 预建 record 的关联键（引擎据此上报首轮 runId 键之外的反向
+     *     载荷与 interact 定位）——task.conversation === true 的 chat 轮必传；
+   *   - resume：冷续锚点（重开已 idle 的 session 续聊；pi 消费 sessionRef.sessionFile
+     *     ——对照协议化设计前 SpawnResumeOpts.sessionFile 的锚点面）。
+   * 类型权威 = SDK RunChatParams（remote-engine 直传，结构互证由 implements 关系
+   * 在 typecheck 期承载）。非 chat 轮不传，wire 上不出现该键。
+   */
+  chat?: { recordId: string; resume?: ResumeAnchor };
+  /**
+   * [W3 v1.x] host/roundLifecycle 轮次生命周期消费口（第 9 反向通道，settled/idle/
+   * failed 三相位；关联键 runId|recordId 互斥）。首轮（run 会话形态）经 run 作用域
+   * 路由到达（runId 键）；续聊轮（interact）无 runId——经 EnginePort
+   * registerChatRoundRoute 的 recordId 键路由到达（见下）。消费语义（arm/disarm/
+   * settled 交棒）归宿主编排层（settled-watchdog 协议事件面接线，W4 三入口）。
+   */
+  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void;
+}
+
+/**
+ * [W3 v1.x] chat 轮次反向通道路由（recordId 键）——interact 续聊轮的 streamDelta /
+ * roundLifecycle 分发目标（协议关联键裁定 D1-A：续聊轮无独立 runId）。与 run 作用域
+ * RunRoute 同构的薄消费面；注册/注销时机归宿主 chat 编排（轮开始注册、record 终态注销）。
+ */
+export interface ChatRoundRoute {
+  onStreamDelta?: (delta: string) => void | Promise<void>;
+  onRoundLifecycle?: (phase: HostRoundLifecycleParams) => void | Promise<void>;
 }
 
 // ============================================================
@@ -173,6 +206,17 @@ export interface EnginePort {
   /** D6 三级降级链：①引擎原生读取 → ②宿主 event journal（P2）→ ③outcome-only。 */
   read(handle: EngineHandle): Promise<SessionView>;
 
+  /**
+   * [W3 v1.x] 可选面：chat 轮次反向通道路由注册（recordId 键）。interact 续聊轮的
+   * streamDelta / roundLifecycle 按 recordId 关联（无 runId，D1-A），引擎进程发射后
+   * 经协议客户端分发到本路由。与 validateModel/listModels 同款的 additively-optional
+   * 演进：宿主 feature-detect（`typeof registerChatRoundRoute === "function"`），
+   * 未实现的引擎（不支持 chat 域或旧客户端）续聊轮 delta/生命周期静默不可达——
+   * conversation gate 已在派发前拦住无 chat 能力的引擎，本缺省只在「能力声明与
+   * 客户端实现错位」的诊断形态出现。返回注销函数（record 终态时宿主调用）。
+   */
+  registerChatRoundRoute?(recordId: string, route: ChatRoundRoute): () => void;
+
   /**
    * [U7] 可选面：模型可发现性——引擎自带 provider/model 体系时（如 zcode 的 v2 桌面
    * 登录态），列出当前环境实际可用的模型清单（带凭据校验），供 system prompt 引擎段
@@ -190,8 +234,10 @@ export interface EnginePort {
    * 「引擎与模型不配套」错误，见 engine/model-validation.ts）。
    *
    * modelRef undefined = 查询引擎缺省模型（D2-1：主 agent 的 pi id 不透传给非 pi 引擎，
-   * 缺省语义归引擎——zcode 落 ZCODE_FALLBACK_DEFAULT_MODEL）。返回 canonical 全名供
-   * record.model 留痕。
+   * 缺省语义归引擎——zcode 落 ZCODE_FALLBACK_DEFAULT_MODEL）。返回 canonical ref 供
+   * record.model 留痕。[W3 契约变更④] 协议化后 canonicalRef 允许**无斜杠**形态
+   * （引擎原样返回的 ref）——core 侧按 provider=""/id=ref/整串进 name 拆分留痕
+   * （splitEngineModelRef 单一权威），不落 "<ref>/" 畸形。
    *
    * 未实现：model 透传，引擎自身 prepare 期校验兜底（现状语义）；pi 不实现（pi 链走
    * 既有三层解析 + assertCanonicalModelRef 裁决，搬迁是大重构，设计 D2-2 被否②）。

package/src/execution/engine/registry.ts

@@ -1,19 +1,31 @@
 // 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 → 指向注册表清单 + 配置文件路径）。
+// 引擎注册表（P1；W3 协议化改造）。设计权威源（现行）：
+// docs/design/subagent-engine-protocolization.md §3.4 发现与注册 / §3.8 D1（EngineDescriptor
+// 双模）+ D4（缺省引擎与 fallback 目标）；实现级规格 impl-plan §2.3。历史权威源
+// docs/architecture/subagent-engine-abstraction.md §3.3.1/§3.3.3（engine_not_found 错误
+// 规格第 1 行）仍然有效。
 //
-// 为什么需要注册表：引擎身份是「spawn 细节的归属边界」（设计 §2.3 根因一）——上层
-// （配置路由/agent 解析，P4 接线）按 id 取引擎，不感知实现类；新引擎接入 = 新增一个
-// 适配器模块 + 注册表登记一行，不改上层与既有引擎（目标 5）。
+// 为什么需要注册表：引擎身份是「spawn 细节的归属边界」——上层（配置路由/agent 解析）
+// 按 id 取引擎，不感知实现类；新引擎接入 = 装一个引擎包（manifest 自注册，W4 发现器
+// 装载）或登记一行 inproc 工厂（过渡期），不改上层与既有引擎。
 //
-// 依赖方向（设计 §3.3.1 贯穿纪律④）：registry 只依赖 port.ts 的类型，不 import 任何
-// 具体引擎——注册由组合根（index.ts）或引擎自己的 registration 模块完成，防循环依赖。
-// （core/logger 是 facade 基础设施非引擎，dispose best-effort 记日志需要它，不违反本纪律。）
+// 双模 descriptor（D1）：`{kind:"inproc", factory}`（过渡期——内建 pi/zcode，DoD#5 后
+// 随 inproc 分支删除）与 `{kind:"cli", command, args, capabilities, portFactory}`（目标——
+// 独立引擎 CLI 包，port 由 W2 RemoteEngine 承担）。上层 getEngine(id) 返回代理，两形态
+// 透明：cli descriptor 首次使用才经 portFactory 解析（构造同步、缺包/坏包不在构造期
+// throw，§3.5.3 代理形态），失败形态 = 首次协议调用的结构化错误。
+//
+// 依赖方向（贯穿纪律，协议化后不变）：registry 只依赖 port/types 的类型与 SDK 的
+// modelCatalog 条目类型，不 import 任何具体引擎或协议客户端（client/）——cli 形态的
+// port 装配（RemoteEngine + EngineClient + 宿主侧参数）归 portFactory 注入方（W4 发现器
+// 装载 descriptor 时装配），registry 只持类型与惰性代理。（core/logger 是 facade 基础
+// 设施非引擎，dispose best-effort 记日志需要它，不违反本纪律。）
 
 import { getLogger } from "../../core/logger.ts";
+import type { ModelCatalogEntry } from "@zhushanwen/subagent-engine-sdk";
 
+import type { EngineCapabilities } from "./types.ts";
 import type { EnginePort } from "./port.ts";
 
 // core log facade（execution 层统一 "subagents" component，模块顶层缓存惯例）。
@@ -23,8 +35,60 @@ const logger = getLogger("subagents");
 export type EngineFactory = () => EnginePort;
 
 /**
- * 缺省引擎 id（D9：缺省引擎 = 'pi'，回填期零风险默认）。
- * P1 无 per-agent/调用级 engine 字段（P4 配置路由引入三层优先级），一切执行恒走缺省。
+ * 引擎包 manifest 注册期快照（session_start 扫描所得，非握手缓存——设计 §3.3「同步
+ * 成员清单」单一同步源原则）。descriptor 携带，cli 形态 port（RemoteEngine）的同步
+ * 成员（capabilities/listModels/validateModel）直读本快照。
+ *
+ * 与 client/remote-engine.ts 的 RemoteEngineManifestSnapshot 是结构闭包（后者多出
+ * core 中立类型包装；漂移由 protocol-closure 同族结构互证断言守卫）。
+ */
+export interface EngineManifestSnapshot {
+  /** manifest `capabilities`（同步能力位权威，注册期读，无缓存）。 */
+  capabilities: EngineCapabilities;
+  /**
+   * manifest `modelCatalog` 三态（W4 §2.4：缺省 = 不注入保持 undefined；null 合法等价
+   * 省略；`models: []` 仅作者显式声明）。解析器不得把省略填成 `[]`——否则「无枚举面」
+   * 语义不可达。
+   */
+  modelCatalog?: { dynamic: boolean; models: ModelCatalogEntry[] } | null;
+  /** manifest `displayName`（可选，缺省 = id；D4 缺省引擎回落序的排序键）。 */
+  displayName?: string;
+}
+
+/** cli 形态 descriptor（目标形态）：引擎 CLI 启动参数 + manifest 快照 + port 装配器。 */
+export interface CliEngineDescriptor {
+  kind: "cli";
+  /** 引擎 CLI 命令（发现器解析后的绝对路径/可执行名；不依赖 PATH）。 */
+  command: string;
+  /** 引擎 CLI 参数（不含 command 本身）。 */
+  args: readonly string[];
+  /** manifest `capabilities`（同步能力位权威——gate 同步消费，无缓存）。 */
+  capabilities: EngineCapabilities;
+  /**
+   * cli 形态 EnginePort 实例装配器（core 侧接线通道，非 manifest 面）。生产 = W4
+   * 发现器装载 descriptor 时装配（W2 `RemoteEngine` + `EngineClient` + 宿主侧参数
+   * dataDir/hostKind/engineConfig 等——registry 不越权猜宿主形态）。必须构造同步、
+   * 不 throw（§3.5.3 代理形态：缺包/坏包的失败推迟到首次协议调用）。
+   */
+  portFactory: EngineFactory;
+  /** manifest 快照余项（modelCatalog/displayName；capabilities 已提升为直读字段）。 */
+  manifest?: Omit<EngineManifestSnapshot, "capabilities">;
+}
+
+/** inproc 形态 descriptor（过渡期）：内建引擎工厂。DoD#5 后随 inproc 分支删除。 */
+export interface InprocEngineDescriptor {
+  kind: "inproc";
+  factory: EngineFactory;
+}
+
+/** D1 双模引擎描述符：inproc（过渡期）/ cli（目标）。上层经 getEngine 拿代理，两形态透明。 */
+export type EngineDescriptor = InprocEngineDescriptor | CliEngineDescriptor;
+
+/**
+ * 缺省引擎 id（D4 重定义：**配置的缺省引擎 id**——config defaultEngine 未配置时的
+ * 归一名，不再表达「内置 pi 永久兜底」）。配置值不在已发现清单 → warn + 回落第一个
+ * 可用引擎（manifest displayName 稳定序，D4）；全不可用 → 派发期 engine_not_found
+ * （「未发现任何引擎包」+ 安装指引）。
  */
 export const DEFAULT_ENGINE_ID = "pi";
 
@@ -39,12 +103,15 @@ export function normalizeEngineId(engine: string | undefined): string {
 }
 
 /**
- * engine_not_found（错误规格表第 1 行）：agent frontmatter 写了未注册 engine id。
+ * engine_not_found（错误规格表第 1 行）：请求的引擎 id 无对应注册/发现结果。
  * 错误文案契约：含已注册引擎清单 + 配置文件指引——配置错误前置暴露（agent 解析期），
- * 不留到运行时神秘失败（设计目标 4）。
+ * 不留到运行时神秘失败。
+ *
+ * D4 全不可用文案：清单为空（未发现任何引擎包）时追加安装指引——此时问题不是 id
+ * 写错，而是环境里没有任何引擎包可派发，恢复动作 = 装引擎包/配发现根，不是改 typo。
  */
 export class EngineNotFoundError extends Error {
-  /** 结构化错误码（§3.3.3 错误规格表的 code 列，供调用方程序化分流）。 */
+  /** 结构化错误码（错误规格表的 code 列，供调用方程序化分流）。 */
   readonly code = "engine_not_found";
   /** 请求的（未注册的）引擎 id。 */
   readonly engineId: string;
@@ -57,9 +124,13 @@ export class EngineNotFoundError extends Error {
     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).` +
+        (registered.length === 0
+          ? `No engine packages were discovered. ` +
+            `Recovery: install an engine package (e.g. @zhushanwen/pi-subagent-cli / @zhushanwen/zcode-subagent-cli), ` +
+            `or add its location to XYZ_AGENT_ENGINE_ROOTS / subagents/config.json engines section.`
+          : `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";
@@ -70,7 +141,7 @@ export class EngineNotFoundError extends Error {
 }
 
 /**
- * id → factory（注册表本体）+ id → 惰性单例（getEngine 首次取用创建；registerEngine
+ * id → descriptor（注册表本体）+ id → 惰性单例（getEngine 首次取用创建；重复注册
  * 覆盖时丢弃旧实例）。进程级单例状态，用 globalThis[Symbol.for] 持有防 jiti 双路径
  * 加载分裂（development-guide §7.5），不用模块级 const。
  */
@@ -78,7 +149,7 @@ const ENGINE_REGISTRY_SLOT_KEY = Symbol.for("@zhushanwen/pi-subagent-workflow.en
 
 /** 注册表槽位形状（同文件唯一写入点，运行时保证）。 */
 interface EngineRegistrySlot {
-  factories: Map<string, EngineFactory>;
+  descriptors: Map<string, EngineDescriptor>;
   singletons: Map<string, EnginePort>;
 }
 
@@ -87,12 +158,17 @@ function getRegistrySlot(): EngineRegistrySlot {
   // 避免双重断言（同 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() };
+    slot = { descriptors: new Map(), singletons: new Map() };
     Reflect.set(globalThis, ENGINE_REGISTRY_SLOT_KEY, slot);
   }
   return slot;
 }
 
+/** descriptor → port 装配器（两形态透明收敛点：inproc = factory，cli = portFactory）。 */
+function portFactoryOf(descriptor: EngineDescriptor): EngineFactory {
+  return descriptor.kind === "inproc" ? descriptor.factory : descriptor.portFactory;
+}
+
 /**
  * [R1 D6] 触发引擎 dispose：同步调用拿 Promise 不 await（「触发不等待」，D6①——
  * dispose 的同步面〔fire close 帧 + 同步 SIGTERM〕由引擎实现保证在返回 Promise 前
@@ -120,18 +196,27 @@ function triggerEngineDispose(engine: EnginePort, source: string): void {
 }
 
 /**
- * 登记引擎工厂。重复注册同一 id = 覆盖（组合根可能多次执行，如每次 session_start 重跑
- * registerPiEngine——幂等覆盖保证不炸也不堆积），覆盖时丢弃缓存的旧单例，让下一次
- * getEngine 用新工厂重建。
+ * 登记引擎工厂（inproc 快捷形态，等价 registerEngineDescriptor(id, {kind:"inproc", factory})）。
+ * 重复注册同一 id = 覆盖（组合根可能多次执行，如每次 session_start 重跑 registerPiEngine
+ * ——幂等覆盖保证不炸也不堆积），覆盖时丢弃缓存的旧单例，让下一次 getEngine 用新
+ * descriptor 重建。
  *
  * [R1 D6②] 覆盖前对已实例化的旧单例触发 dispose（防泄漏——旧实例可能持有常驻进程/
  * 长连接）；触发不等待 + 失败不阻断（见 triggerEngineDispose），幂等覆盖语义不变。
  */
 export function registerEngine(id: string, factory: EngineFactory): void {
+  registerEngineDescriptor(id, { kind: "inproc", factory });
+}
+
+/**
+ * 登记引擎 descriptor（D1 双模注册入口）。inproc（过渡期内建引擎）与 cli（引擎包，
+ * portFactory 由发现器装配）两形态；覆盖语义与 dispose 触发同 registerEngine。
+ */
+export function registerEngineDescriptor(id: string, descriptor: EngineDescriptor): void {
   const slot = getRegistrySlot();
   const previous = slot.singletons.get(id);
-  if (previous) triggerEngineDispose(previous, `registerEngine('${id}') overwrite`);
-  slot.factories.set(id, factory);
+  if (previous) triggerEngineDispose(previous, `registerEngineDescriptor('${id}') overwrite`);
+  slot.descriptors.set(id, descriptor);
   slot.singletons.delete(id);
 }
 
@@ -151,36 +236,70 @@ export function disposeEngines(): void {
   }
 }
 
-/** 未注册 id 抛 EngineNotFoundError（含已注册清单与配置指引）。 */
+/**
+ * 按 id 取引擎代理（两形态透明）。惰性单例：descriptor 首次使用才解析（inproc 工厂
+ * / cli portFactory 都是此刻才调用——构造同步、缺包/坏包不在本函数期 throw，§3.5.3
+ * 代理形态；cli 形态实例 = W2 RemoteEngine，失败形态是首次协议调用的结构化错误）。
+ */
 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) {
+  const descriptor = slot.descriptors.get(id);
+  if (!descriptor) {
     throw new EngineNotFoundError(id, listEngines());
   }
-  const engine = factory();
+  const engine = portFactoryOf(descriptor)();
   slot.singletons.set(id, engine);
   return engine;
 }
 
-/** id 是否已注册（agent 解析期的配置校验入口，D9——不取实例、不触发工厂副作用）。 */
+/** id 是否已注册（agent 解析期的配置校验入口——不取实例、不触发 port 装配副作用）。 */
 export function hasEngine(id: string): boolean {
-  return getRegistrySlot().factories.has(id);
+  return getRegistrySlot().descriptors.has(id);
 }
 
 /** 已注册引擎 id 清单（稳定序 = 注册序；错误文案与 GUI 引擎选择器共用）。 */
 export function listEngines(): string[] {
-  return [...getRegistrySlot().factories.keys()];
+  return [...getRegistrySlot().descriptors.keys()];
+}
+
+/**
+ * 已发现引擎按 manifest `displayName` 稳定序排序（D4 缺省引擎回落序的单一权威）。
+ * displayName 缺省 = id（inproc 形态无 manifest 恒用 id）；排序 = 码点序（不用
+ * localeCompare——跨环境字节稳定，同 model-prompt.ts 字节稳定先例）；displayName
+ * 相同按 id 决胜，保证全序确定。
+ */
+export function listEnginesByDisplayName(): string[] {
+  const slot = getRegistrySlot();
+  const keyed = [...slot.descriptors.entries()].map(([id, descriptor]) => {
+    const displayName =
+      descriptor.kind === "cli" ? (descriptor.manifest?.displayName ?? id) : id;
+    return { id, displayName };
+  });
+  keyed.sort((a, b) =>
+    a.displayName !== b.displayName
+      ? a.displayName < b.displayName ? -1 : 1
+      : a.id < b.id ? -1 : a.id > b.id ? 1 : 0,
+  );
+  return keyed.map((k) => k.id);
+}
+
+/**
+ * 第一个可用引擎 id（D4 回落目标：缺省引擎不在清单 / fallback 目标的「首个可用」）。
+ * 空注册表返回 undefined——调用方按 D4 转 engine_not_found（「未发现任何引擎包」+
+ * 安装指引），不静默。
+ */
+export function firstAvailableEngineId(): string | undefined {
+  return listEnginesByDisplayName()[0];
 }
 
 /**
- * 清空注册表（测试隔离专用：防止用例间工厂/单例泄漏串扰）。
+ * 清空注册表（测试隔离专用：防止用例间 descriptor/单例泄漏串扰）。
  * 生产代码禁用——进程内注册表是全局状态，清空会让已获取的引擎句柄与新注册表脱钩。
  */
 export function clearEngines(): void {
   const slot = getRegistrySlot();
-  slot.factories.clear();
+  slot.descriptors.clear();
   slot.singletons.clear();
 }