@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/config.ts

@@ -0,0 +1,151 @@
+// src/execution/engine/config.ts
+//
+// [W4] subagents/config.json 的 engines{} 段（三级发现的 L3 显式配置，设计 §3.4）。
+//
+// 契约（impl-plan §2.4）：
+//   `engines: {"<id>": {command, args, config, cwd, enabled}}`
+//   - 无 `env` 键（v6 已删 extras 层——引擎 env 放行面归 manifest envPrefixes，L3 不重开）；
+//   - `config` 经 initialize.engineConfig 透传（引擎不实现消费即死键，不校验内容）；
+//   - `enabled: false` → 该引擎不装载（A12⑤：不进清单 + 派发报错含恢复指引）。
+//
+// 与 execution/config.ts 的关系：那边是全局配置的 sanitize 权威（maxConcurrent /
+// defaultEngine / engineRouting / collectSync），其 SubagentsGlobalConfig 类型不含
+// engines 键（sanitize 未知键忽略）。本模块只取 engines 段并逐条目校验——独立解析
+// 避免 execution/config.ts 类型面为发现器扩键（发现器消费 raw 形态，字段级容错在本
+// 模块内做，坏条目 warn 跳过、不影响其他条目）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getLogger } from "../../core/logger.ts";
+
+const logger = getLogger("subagents");
+
+/** L3 显式引擎配置条目（config.json engines.<id>，字段级校验后形态）。 */
+export interface ExplicitEngineEntry {
+  /** 引擎 CLI 命令（相对 PATH 的命令名或绝对/相对路径；装载期解析为可执行路径）。 */
+  command: string;
+  /** 引擎 CLI 参数（不含 command 本身；缺省 []）。 */
+  args: string[];
+  /** initialize.engineConfig 透传（Record<string,string>，缺省无）。 */
+  config?: Record<string, string>;
+  /** 引擎进程 cwd（缺省继承宿主进程）。 */
+  cwd?: string;
+}
+
+/**
+ * 读 config.json 的 engines 段（已启用条目，键 = 引擎 id）。
+ *
+ * 容错契约（与 config.json 用户手编文件定位一致，execution/config.ts 同判）：
+ * 文件缺失 / 坏 JSON / engines 段非对象 → 静默空表（L3 缺席是常态，不 warn——绝大多数
+ * 安装无显式配置）；单条目形态坏 → warn 跳过该条目（不影响其他条目，A12②「其他引擎
+ * 正常」的 L3 版）。
+ */
+export function readExplicitEngines(agentDir: string): Record<string, ExplicitEngineEntry> {
+  const configPath = path.join(agentDir, "subagents", "config.json");
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+  if (typeof parsed !== "object" || parsed === null) return {};
+  const engines = (parsed as Record<string, unknown>)["engines"];
+  if (typeof engines !== "object" || engines === null || Array.isArray(engines)) {
+    if (engines !== undefined) {
+      logger.warn(
+        `[engine-discovery] config.json engines section must be an object keyed by engine id, got ${jsonKindOf(engines)} — ignoring L3 explicit engines`,
+      );
+    }
+    return {};
+  }
+  const out: Record<string, ExplicitEngineEntry> = {};
+  for (const [id, raw] of Object.entries(engines as Record<string, unknown>)) {
+    const entry = sanitizeExplicitEntry(id, raw);
+    if (entry !== undefined) out[id] = entry;
+  }
+  return out;
+}
+
+/** 单条目字段级校验：command 必需非空字符串；args/config/cwd 形态坏 → 丢弃该字段 + warn。 */
+function sanitizeExplicitEntry(id: string, raw: unknown): ExplicitEngineEntry | undefined {
+  const v = requireEntryObject(id, raw);
+  if (v === undefined) return undefined;
+  if (v["enabled"] === false) return undefined; // A12⑤：显式禁用 = 不装载不进清单（非错误，不 warn）
+  const command = requireCommand(id, v["command"]);
+  if (command === undefined) return undefined;
+  return {
+    command,
+    ...normalizeArgs(id, v["args"]),
+    ...normalizeConfig(id, v["config"]),
+    ...normalizeCwd(id, v["cwd"]),
+  };
+}
+
+/** 条目形态守卫：非对象（含数组/null）→ warn 跳过整条。 */
+function requireEntryObject(id: string, raw: unknown): Record<string, unknown> | undefined {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    logger.warn(
+      `[engine-discovery] config.json engines.${id} must be an object, got ${jsonKindOf(raw)} — skipping entry`,
+    );
+    return undefined;
+  }
+  return raw as Record<string, unknown>;
+}
+
+/** command 校验：必需非空字符串，形态坏 → warn 跳过整条。 */
+function requireCommand(id: string, command: unknown): string | undefined {
+  if (typeof command !== "string" || command.trim() === "") {
+    logger.warn(
+      `[engine-discovery] config.json engines.${id}.command is required (non-empty string) — skipping entry`,
+    );
+    return undefined;
+  }
+  return command;
+}
+
+/** args 字段：形态坏 warn 丢弃该字段；合法（或缺省）→ 条件 spread 形态。 */
+function normalizeArgs(id: string, args: unknown): { args: string[] } {
+  if (args !== undefined && !isStringArray(args)) {
+    logger.warn(
+      `[engine-discovery] config.json engines.${id}.args must be a string array — ignoring args`,
+    );
+  }
+  return { args: isStringArray(args) ? args : [] };
+}
+
+/** config 字段：形态坏 warn 丢弃该字段；合法 → 条件 spread 形态。 */
+function normalizeConfig(id: string, config: unknown): { config?: Record<string, string> } {
+  if (config !== undefined && !isStringRecord(config)) {
+    logger.warn(
+      `[engine-discovery] config.json engines.${id}.config must be a Record<string, string> — ignoring config`,
+    );
+  }
+  return isStringRecord(config) ? { config } : {};
+}
+
+/** cwd 字段：形态坏 warn 丢弃该字段；合法 → 条件 spread 形态。 */
+function normalizeCwd(id: string, cwd: unknown): { cwd?: string } {
+  if (cwd !== undefined && typeof cwd !== "string") {
+    logger.warn(
+      `[engine-discovery] config.json engines.${id}.cwd must be a string — ignoring cwd`,
+    );
+  }
+  return typeof cwd === "string" ? { cwd } : {};
+}
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function isStringRecord(value: unknown): value is Record<string, string> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value as Record<string, unknown>).every((item) => typeof item === "string");
+}
+
+/** unknown 值的 JSON 类型名（warn 文案用；不用 JSON.stringify——循环引用会炸）。 */
+function jsonKindOf(value: unknown): string {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}

package/src/execution/engine/d8-compat.ts

@@ -0,0 +1,346 @@
+// src/execution/engine/d8-compat.ts
+//
+// [W8] D8 兼容公共面薄壳（设计 §3.6 D8 表 + impl-plan §2.8）：宿主零改动的机械保证。
+// 三个符号的兼容形态：
+//   - registerZcodeEngine(engineDataDir) 薄壳：确保 id 'zcode' 的 cli descriptor 已
+//     注册，engineDataDir 经合成 env（XYZ_AGENT_DATA_DIR）记入 descriptor portFactory；
+//   - createZcodeEngine(deps) → RemoteEngine('zcode')：deps → 协议客户端映射
+//     （engineDataDir → dataDir / cliPath → command / processEnv → baseEnv /
+//     sources 不跨进程——不变量 5「引擎不落盘宿主数据、自行解析凭据」）；
+//   - killAllSpawnedChildren 收敛在 engine/host/spawned-children 公共面（[W3][F-7
+//     注释纠偏] 仅镜像记账——core 侧 spawnedChildren 镜像整体置死，不发进程信号；
+//     引擎进程回收 = stdin-EOF 自灭链（正常路径）+ disposeEngines() 显式触发
+//     cli 引擎 dispose（宿主 shutdown 链预留 API，现无生产接线），非「进程组收割」）。
+//
+// vendored 定位（设计 §3.6 二选一通道①）：core 相对自身定位
+// `<coreDir>/../<engine>-subagent-cli`（与 zsw core-ref.js:15 同款相对解析，零配置）；
+// 通道②（宿主注入 XYZ_AGENT_ENGINE_ROOTS）由发现器承载，薄壳在注册表已有 descriptor
+// 时直接保留（发现器快照权威）。定位失败（打包态 staging 前 / 引擎包未安装）：
+// registerZcodeEngine 回退 inproc 注册（过渡期可用性优先，W11 删 inproc 后该分支
+// 一并删除）；createZcodeEngine 返回 command = 期望路径的 RemoteEngine——首次协议
+// 调用 engine_crashed 显式报错（不变量 6「失败不静默」，构造同步不 throw，§3.5.3）。
+//
+// hostKind：registerZcodeEngine 缺省 'pi'（现调用方 = xyz-agent 扩展宿主组合根）；
+// createZcodeEngine 恒 'zsw'（消费方 = zsw CLI vendored 形态）——pidfile 实例维度
+// 命名段（engine.<hostKind>.<hostPid>.pid），不同宿主进程 pid 不同不互误杀。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { EngineClient } from "./client/engine-client.ts";
+import { RemoteEngine, type RemoteEngineManifestSnapshot } from "./client/remote-engine.ts";
+import {
+  readRelayForwardEnv,
+} from "../relay-env.ts";
+import { getEngineDataDir } from "./common/data-dir.ts";
+import {
+  CONSERVATIVE_CAPABILITIES,
+  parseCapabilities,
+  parseEnvPrefixes,
+  parseModelCatalog,
+  resolveManifestBin,
+} from "./engine-manifest.ts";
+import { inspectEnginePackage } from "./engine-discovery-scan.ts";
+import { hasEngine, registerEngineDescriptor, type CliEngineDescriptor } from "./registry.ts";
+import type { EngineCapabilities } from "./types.ts";
+import type { EnginePort } from "./port.ts";
+import type { ModelCatalogEntry } from "@zhushanwen/subagent-engine-sdk";
+import { getLogger } from "../../core/logger.ts";
+
+const logger = getLogger("subagents");
+
+/** D8 薄壳服务的引擎 id（设计 §3.6 D8 表硬编码面；不用 engines/zcode/constants 的
+ *  ZCODE_ENGINEID——薄壳生命周期跨 W11（inproc 目录删除后薄壳仍在），不绑内部模块）。 */
+const D8_ZCODE_ENGINE_ID = "zcode";
+
+/** createZcodeEngine 消费宿主（zsw CLI vendored 形态）——pidfile hostKind 命名段。 */
+const D8_ZSW_HOST_KIND = "zsw";
+
+/** registerZcodeEngine 缺省宿主（xyz-agent 扩展宿主组合根是现调用方）。 */
+const D8_PI_HOST_KIND = "pi";
+
+/** deps.sources 忽略的 warn-once（跨进程不可达面，重复注册不刷屏）。 */
+let warnedSourcesIgnored = false;
+
+/**
+ * D8 兼容 deps 形状（zsw runner-core.js:163 实测调用面 {engineDataDir, cliPath?}）。
+ * 与 engines/zcode ZcodeEngineDeps 结构兼容：zsw 传入对象可直接赋值；sources /
+ * probeVersion 为兼容残留字段——协议形态下不跨进程（忽略 + warn）。
+ */
+export interface D8CompatZcodeEngineDeps {
+  /** 引擎数据根（→ 引擎子进程 env XYZ_AGENT_DATA_DIR，见设计 §3.6 注入矩阵）。 */
+  engineDataDir: () => string;
+  /** 引擎 CLI 入口覆盖（L3 等价；缺省 = vendored 相对定位）。 */
+  cliPath?: string;
+  /** 兼容残留：模型来源/凭据路径——不跨进程（不变量 5），忽略。 */
+  sources?: unknown;
+  /** 兼容残留：版本探测执行器——协议 probe 由引擎实现承担，忽略。 */
+  probeVersion?: unknown;
+  /** env 基底合并（buildEngineChildEnv baseEnv；缺省 {...process.env}）。 */
+  processEnv?: NodeJS.ProcessEnv;
+}
+
+/**
+ * [W11 收口] 旧 ZcodeEngineDeps 的兼容别名：barrel 原类型导出（zsw 调用面的 deps
+ * 形状契约）与 D8CompatZcodeEngineDeps 合并——结构同源（engineDataDir/cliPath/
+ * sources/probeVersion/processEnv），别名保留免 zsw 侧机械改名。
+ */
+export type ZcodeEngineDeps = D8CompatZcodeEngineDeps;
+
+/** vendored 引擎包定位结果。 */
+interface LocatedEnginePkg {
+  pkgDir: string;
+  /** manifest bin 解析后的引擎 CLI 入口绝对路径（已过可执行校验）。 */
+  binPath: string;
+}
+
+/** 引擎包 manifest 的薄壳消费面（capabilities/envPrefixes/modelCatalog 快照）。 */
+interface ManifestInfo {
+  capabilities: EngineCapabilities;
+  envPrefixes: string[];
+  modelCatalog?: { dynamic: boolean; models: ModelCatalogEntry[] } | null;
+}
+
+// ============================================================
+// vendored 定位（通道①）
+// ============================================================
+
+/**
+ * core 包根目录：本模块文件目录上 3 级（src 与 dist 同构——
+ * <pkg>/src/execution/engine/d8-compat.ts 与 <pkg>/dist/execution/engine/d8-compat.js
+ * 的 dirname 上 3 级都是包根）。不可得（bundle 进宿主无文件位置语义）→ undefined，
+ * 调用方走通道②（宿主注入发现根）或显式 cliPath。
+ */
+function corePackageDir(): string | undefined {
+  let moduleDir: string | undefined;
+  try {
+    moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  } catch {
+    moduleDir = undefined;
+  }
+  if (moduleDir === undefined && typeof __dirname !== "undefined") {
+    moduleDir = __dirname;
+  }
+  if (moduleDir === undefined) return undefined;
+  return path.resolve(moduleDir, "..", "..", "..");
+}
+
+/** 引擎包 npm 名（D8 vendored 布局约定 <engineId>-subagent-cli）。 */
+function enginePkgName(engineId: string): string {
+  return `@zhushanwen/${engineId}-subagent-cli`;
+}
+
+/** 期望的 vendored bin 路径（定位失败时 createZcodeEngine 的 command 占位——spawn 时
+ *  engine_crashed 显式报错附恢复指引，不留静默）。 */
+function expectedVendoredBinPath(engineId: string): string {
+  const pkgDir = attemptVendoredPkgDir(engineId);
+  return path.join(pkgDir, "bin", `${engineId}-subagent-cli.mjs`);
+}
+
+function attemptVendoredPkgDir(engineId: string): string {
+  const coreDir = corePackageDir();
+  const packagesDir = coreDir !== undefined ? path.dirname(coreDir) : path.resolve("packages");
+  return path.join(packagesDir, `${engineId}-subagent-cli`);
+}
+
+/**
+ * vendored package.json 的 manifest 段原始解析（单一来源，locateVendoredEnginePkg 与
+ * readEngineManifest 共用）：读取 pkgDir/package.json 并 duck-typed 三段下降
+ * pkg["xyz-agent"]["subagentEngine"]。读文件/JSON 解析失败或 manifest 段缺失/非对象
+ * （含 null 与数组）→ undefined。数组拒绝上收到共用守卫对两个调用点均结局等价：
+ * JSON.parse 产物为数组时不可能携带字符串键（JSON 语法限制），bin 提取路径对数组取
+ * ["bin"] 恒 undefined——与拒绝分支同收敛为定位失败。pkg 一并返回供调用方做 name
+ * 精确匹配与 bin 相对路径解析（单次解析，不重复读盘）。
+ */
+function readSubagentEngineManifestRaw(
+  pkgDir: string,
+): { pkg: Record<string, unknown>; manifest: Record<string, unknown> } | undefined {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(pkgDir, "package.json"), "utf8")) as Record<string, unknown>;
+    const agentNs = pkg["xyz-agent"];
+    const raw =
+      typeof agentNs === "object" && agentNs !== null
+        ? (agentNs as Record<string, unknown>)["subagentEngine"]
+        : undefined;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined;
+    return { pkg, manifest: raw as Record<string, unknown> };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * vendored 相对定位：`<coreDir>/../<engineId>-subagent-cli`。三重校验防同名目录冒充：
+ * package.json 可读 + name 精确匹配 + manifest bin 可执行。任一不成立 → undefined
+ * （调用方按通道②/显式 cliPath/期望路径降级）。
+ */
+function locateVendoredEnginePkg(engineId: string): LocatedEnginePkg | undefined {
+  const pkgDir = attemptVendoredPkgDir(engineId);
+  const parsed = readSubagentEngineManifestRaw(pkgDir);
+  if (parsed === undefined) return undefined;
+  const { pkg, manifest } = parsed;
+  if (pkg["name"] !== enginePkgName(engineId)) return undefined;
+  const manifestBin = manifest["bin"];
+  if (typeof manifestBin !== "string" || manifestBin.trim() === "") return undefined;
+  const binPath = resolveManifestBin(pkgDir, pkg, manifestBin);
+  if (binPath === undefined || !canExecute(binPath)) return undefined;
+  return { pkgDir, binPath };
+}
+
+/** manifest 薄壳消费面解析（复用 W4 engine-manifest 字段级解析器——单源，不复制规则）。 */
+function readEngineManifest(pkgDir: string): ManifestInfo | undefined {
+  const parsed = readSubagentEngineManifestRaw(pkgDir);
+  if (parsed === undefined) return undefined;
+  const manifest = parsed.manifest;
+  const id = typeof manifest["id"] === "string" ? manifest["id"] : D8_ZCODE_ENGINE_ID;
+  const modelCatalog = parseModelCatalog(id, manifest["modelCatalog"]);
+  return {
+    capabilities: parseCapabilities(id, manifest["capabilities"]),
+    envPrefixes: parseEnvPrefixes(id, manifest["envPrefixes"]),
+    ...(modelCatalog !== undefined ? { modelCatalog } : {}),
+  };
+}
+
+function canExecute(p: string): boolean {
+  try {
+    fs.accessSync(p, fs.constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================
+// registerZcodeEngine 薄壳
+// ============================================================
+
+/**
+ * D8 薄壳：确保 id 'zcode' 的引擎 descriptor 已注册，engineDataDir 记入 descriptor。
+ *
+ * 注册表已有 descriptor（W4 发现器先装载 / 重复调用）→ 直接保留——发现器 cli
+ * descriptor 携带完整 manifest 快照，权威高于薄壳构造。未注册 → vendored 定位构造
+ * cli descriptor（经 W4 inspectEnginePackage 全量 manifest 解析；engineDataDir 经
+ * 合成 env XYZ_AGENT_DATA_DIR 被 portFactory 捕获——「以显式值为准」）。[W11/DoD#5]
+ * 定位/解析失败保持未注册（inproc 回退已删，不变量 6「失败不静默」——派发期
+ * engine_not_found 显式报错 + 恢复指引；XYZ_ZCODE_CLI 覆盖通道由 createZcodeEngine
+ * 的 deps.cliPath 等价承载）。
+ */
+export function registerZcodeEngine(engineDataDir: () => string = getEngineDataDir): void {
+  const id = D8_ZCODE_ENGINE_ID;
+  if (hasEngine(id)) return;
+  // [W11/DoD#5] inproc 回退分支已删（不变量 6「失败不静默」）：定位/解析失败保持
+  // 未注册——派发期 engine_not_found 显式报错（含「安装/发现引擎包」恢复指引），
+  // XYZ_ZCODE_CLI 覆盖通道由 createZcodeEngine 的 deps.cliPath 等价承载。
+  const located = locateVendoredEnginePkg(id);
+  if (located === undefined) {
+    logger.warn(
+      `[d8-compat] engine '${id}' vendored package not located (enginePkg ${enginePkgName(id)}); ` +
+        "left unregistered — dispatch will fail with engine_not_found + recovery guidance",
+    );
+    return;
+  }
+  // 合成 env：显式 engineDataDir 写进 XYZ_AGENT_DATA_DIR，portFactory 闭包经
+  // getEngineDataDir(env) 解析即取显式值（W4 inspectEnginePackage 原样复用，零改动）。
+  const syntheticEnv: NodeJS.ProcessEnv = { ...process.env, XYZ_AGENT_DATA_DIR: engineDataDir() };
+  const inspection = inspectEnginePackage(located.pkgDir, "d8-compat", D8_PI_HOST_KIND, syntheticEnv);
+  if (inspection.status !== "ok") {
+    logger.warn(
+      `[d8-compat] engine '${id}' vendored package inspection failed (${inspection.reason}); ` +
+        "left unregistered — dispatch will fail with engine_not_found + recovery guidance",
+    );
+    return;
+  }
+  registerEngineDescriptor(id, inspection.entry.descriptor as CliEngineDescriptor);
+}
+
+// ============================================================
+// createZcodeEngine 薄壳
+// ============================================================
+
+/** deps.sources 忽略的 warn-once（跨进程不可达面，重复注册不刷屏）。 */
+function warnSourcesIgnoredOnce(deps: D8CompatZcodeEngineDeps): void {
+  if (deps.sources === undefined || warnedSourcesIgnored) return;
+  warnedSourcesIgnored = true;
+  logger.warn(
+    "[d8-compat] createZcodeEngine deps.sources is ignored (model/credential sources do not " +
+      "cross the process boundary — the engine resolves its own credentials, protocol invariant 5)",
+  );
+}
+
+/**
+ * manifest 薄壳消费面解析 + 回退合成：vendored 包未定位/manifest 不可读 → capabilities
+ * 全保守 + envPrefixes 空（gate 同步拦生成，失败显式发生在首次协议调用）。
+ */
+function resolveManifestInfo(located: LocatedEnginePkg | undefined): ManifestInfo {
+  const info = located !== undefined ? readEngineManifest(located.pkgDir) : undefined;
+  return {
+    capabilities: info?.capabilities ?? { ...CONSERVATIVE_CAPABILITIES },
+    envPrefixes: info?.envPrefixes ?? [],
+    ...(info?.modelCatalog !== undefined && info.modelCatalog !== null ? { modelCatalog: info.modelCatalog } : {}),
+  };
+}
+
+/** RemoteEngine manifest 快照：capabilities 恒有；modelCatalog 三态语义（无枚举面不注入）。 */
+function buildManifestSnapshot(manifestInfo: ManifestInfo): RemoteEngineManifestSnapshot {
+  return {
+    capabilities: manifestInfo.capabilities,
+    ...(manifestInfo.modelCatalog !== undefined && manifestInfo.modelCatalog !== null
+      ? { modelCatalog: manifestInfo.modelCatalog }
+      : {}),
+  };
+}
+
+/** 协议客户端装配（H12 relay 透传 + manifestDiagnostics 诊断快照）。 */
+function buildZcodeEngineClient(
+  id: string,
+  command: string,
+  dataDir: string,
+  baseEnv: NodeJS.ProcessEnv,
+  manifestInfo: ManifestInfo,
+): EngineClient {
+  return new EngineClient({
+    engineId: id,
+    command,
+    args: [],
+    hostKind: D8_ZSW_HOST_KIND,
+    dataDir,
+    baseEnv,
+    envPrefixes: manifestInfo.envPrefixes,
+    // H12 relay 透传（zsw 宿主链路）：宿主 env 的 relay 连接三键原样提取走 L0 注入；
+    // 身份键 SESSION_ID/RECORD_ID 由 buildEngineChildEnv L1 deny 剥除（引擎按
+    // run.params.ctx 重写，不靠 env 继承）。relay 未激活 → undefined → 不注入。
+    ...(readRelayForwardEnv(baseEnv) !== undefined ? { relay: readRelayForwardEnv(baseEnv) } : {}),
+    manifestDiagnostics: {
+      capabilities: manifestInfo.capabilities,
+      models:
+        manifestInfo.modelCatalog === undefined || manifestInfo.modelCatalog === null
+          ? null
+          : manifestInfo.modelCatalog.models,
+    },
+  });
+}
+
+/**
+ * D8 薄壳：deps → 协议客户端映射，返回 RemoteEngine('zcode')（implements EnginePort，
+ * 对 zsw 透传结构兼容）。构造同步、不 throw（§3.5.3 代理形态）——引擎包缺失时
+ * command = 期望路径，失败显式发生在首次协议调用（engine_crashed + 恢复指引）。
+ */
+export function createZcodeEngine(deps: D8CompatZcodeEngineDeps): EnginePort {
+  const id = D8_ZCODE_ENGINE_ID;
+  warnSourcesIgnoredOnce(deps);
+  const dataDir = deps.engineDataDir();
+  const baseEnv: NodeJS.ProcessEnv = { ...process.env, ...(deps.processEnv ?? {}) };
+  const located = deps.cliPath !== undefined ? undefined : locateVendoredEnginePkg(id);
+  const command = deps.cliPath ?? located?.binPath ?? expectedVendoredBinPath(id);
+  const manifestInfo = resolveManifestInfo(located);
+  const manifestSnapshot = buildManifestSnapshot(manifestInfo);
+  const client = buildZcodeEngineClient(id, command, dataDir, baseEnv, manifestInfo);
+  return new RemoteEngine({
+    engineId: id,
+    client,
+    manifest: manifestSnapshot,
+    dataDir,
+    hostKind: D8_ZSW_HOST_KIND,
+  });
+}

package/src/execution/engine/engine-discovery-roots.ts

@@ -0,0 +1,107 @@
+// src/execution/engine/engine-discovery-roots.ts
+//
+// [W4] 三级发现的搜索路径域（L1 env 根解析 / L2 node 解析域推导 / 发现根扫描）。
+// 自 engine-discovery-scan.ts 拆出（max-lines 纪律）——路径收集与目录遍历是发现
+// 主链的无状态前置面。设计权威源：§3.4 搜索路径表 + impl-plan §2.4。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { getLogger } from "../../core/logger.ts";
+
+const logger = getLogger("subagents");
+
+/** L1 引擎发现根 env（设计 §3.4；值形态 = path.delimiter 分隔的绝对路径列表）。 */
+export const ENGINE_ROOTS_ENV = "XYZ_AGENT_ENGINE_ROOTS";
+
+/** L1 env 根解析：path.delimiter 分隔；空段跳过；非绝对路径丢弃 + warn；去重（大小写敏感）。 */
+export function parseEngineRootsEnv(env: NodeJS.ProcessEnv): string[] {
+  const raw = env[ENGINE_ROOTS_ENV];
+  if (raw === undefined || raw.trim() === "") return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const part of raw.split(path.delimiter)) {
+    const dir = part.trim();
+    if (dir === "") continue;
+    if (!path.isAbsolute(dir)) {
+      logger.warn(
+        `[engine-discovery] ${ENGINE_ROOTS_ENV} entry '${dir}' is not an absolute path — dropping entry`,
+      );
+      continue;
+    }
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    out.push(dir);
+  }
+  return out;
+}
+
+/**
+ * L2 根推导：宿主进程入口（process.argv[1]）所在目录逐级上溯的 node_modules——与
+ * createRequire(<宿主入口>) 的 require.resolve 候选目录链同构（「宿主 node_modules
+ * require.resolve」的扫描化：零枚举发现要求扫目录而非 resolve 具体包名）。打包态
+ * （staged 扩展 / Bun standalone 无 node_modules 结构）与 zsw vendor 态自然为空——
+ * 规格明确两态 L2 无效。argv[1] 不可得（嵌入式 / worker）→ L2 缺席。
+ */
+export function deriveNodeModuleRoots(argvEntry: string | undefined = process.argv[1]): string[] {
+  if (!argvEntry || argvEntry.trim() === "") return [];
+  const roots: string[] = [];
+  let dir = path.dirname(path.resolve(argvEntry));
+  while (true) {
+    const nm = path.join(dir, "node_modules");
+    if (isDirectory(nm)) roots.push(nm);
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return roots;
+}
+
+/**
+ * 扫描单个发现根：一级子目录直接含 package.json 即候选包；无 package.json 的目录
+ * 再下钻一层（org 分组布局：npm @scope/name、pi npm 安装位的 <org>/<pkg>）。二层封顶。
+ * 根不存在/不可读 → 静默（L2 上溯链多数层级无 node_modules，warn 会刷屏）。
+ */
+export function scanEngineRoot(root: string, visit: (pkgDir: string) => void): void {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const item of entries) {
+    if (!item.isDirectory()) continue;
+    const dir = path.join(root, item.name);
+    if (isFile(path.join(dir, "package.json"))) {
+      visit(dir);
+      continue;
+    }
+    let sub: fs.Dirent[];
+    try {
+      sub = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const child of sub) {
+      if (!child.isDirectory()) continue;
+      const subDir = path.join(dir, child.name);
+      if (isFile(path.join(subDir, "package.json"))) visit(subDir);
+    }
+  }
+}
+
+function isDirectory(p: string): boolean {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false; // ENOENT 等 → 非目录
+  }
+}
+
+function isFile(p: string): boolean {
+  try {
+    return fs.statSync(p).isFile();
+  } catch {
+    return false; // ENOENT 等 → 非文件
+  }
+}