@zhushanwen/subagent-engine-sdk 0.4.0 → 0.5.1

package/src/node-executor.ts

@@ -1,272 +0,0 @@
-// src/node-executor.ts
-//
-// 引擎 CLI 启动解析（W9，impl-plan §2.9「启动解析（宿主 × 平台二维矩阵）」）。
-//
-// 为什么在 SDK：core/引擎包都不可 import runtime（runtime 包只存在于 xyz-agent 宿主
-// 链），而矩阵的三宿主（pi 扩展 / runtime sidecar / standalone）两侧都要消费同一套
-// 解析规则——探针逻辑在 SDK 侧复刻 runtime 先例
-// packages/runtime/src/infra/relay/relay-env.ts:47-90（行为保持一致：同超时、同
-// --eval process.exit(0) 探针体、同 PATH/HOME 最小 env、同 Electron RUN_AS_NODE 条件）。
-//
-// 矩阵（规格逐行对应）：
-//   ① pi 扩展宿主（打包）：process.execPath 是 Bun standalone binary，再拉就是又起
-//      一个 pi——必须用注入执行器 XYZ_AGENT_ENGINE_NODE（与 relay 的
-//      XYZ_SUBAGENT_RELAY_NODE 不复用，单一名字）；执行器为 Electron 二进制时同时带
-//      ELECTRON_RUN_AS_NODE=1；首次使用前跑探针，失败 → engine_not_found + 指引。
-//   ② runtime sidecar：process.execPath + ELECTRON_RUN_AS_NODE=1（sidecar 本身由主进程
-//      以该形态 spawn，其 execPath 即宿主 Electron / dev node）。
-//   ③ standalone pi / zsw：PATH node（缺 node → engine_not_found + 安装指引）。
-//   Windows：入口 .mjs 不需 shim；引擎声明 .cmd → 禁 shell:true，改显式
-//   cmd.exe /c + 参数数组。
-//
-// env 名常量与 packages/shared/src/constants.ts 的 W9 挂载块同源（SDK 不 import
-// shared——F9，见 env.ts 头注释同款理由）。
-
-import { spawn } from "node:child_process";
-
-import { EngineSdkError } from "./protocol/error-codes.ts";
-
-/** L0 注入的引擎执行器路径 env（与 relay 的 XYZ_SUBAGENT_RELAY_NODE 不复用）。 */
-export const ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
-
-/** 探针超时（与 relay-env.ts 先例一致：spawn 执行器跑 --eval "process.exit(0)" 的上限）。 */
-const PROBE_TIMEOUT_MS = 5_000;
-
-/**
- * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
- *
- * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
- * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
- * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
- */
-export function probeNodeExecutor(
-  execPath: string,
-  isElectron: boolean,
-): Promise<boolean> {
-  return new Promise((resolve) => {
-    let settled = false;
-    let child: ReturnType<typeof spawn> | null = null;
-    const finish = (ok: boolean): void => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      try {
-        child?.kill("SIGKILL");
-      } catch {
-        // 已退出，正常路径
-        void 0;
-      }
-      resolve(ok);
-    };
-    const env: Record<string, string> = {};
-    if (process.env.PATH !== undefined) env.PATH = process.env.PATH;
-    if (process.env.HOME !== undefined) env.HOME = process.env.HOME;
-    if (isElectron) env.ELECTRON_RUN_AS_NODE = "1";
-
-    try {
-      child = spawn(execPath, ["--eval", "process.exit(0)"], {
-        env,
-        stdio: "ignore",
-        windowsHide: true,
-      });
-    } catch {
-      resolve(false);
-      return;
-    }
-    const timer = setTimeout(() => finish(false), PROBE_TIMEOUT_MS);
-    timer.unref();
-    child.on("error", () => finish(false));
-    child.on("exit", (code) => finish(code === 0));
-  });
-}
-
-/** 探针结果缓存（key = execPath:isElectron）。失败也缓存——重试窗口留给宿主重启。 */
-const probeCache = new Map<string, Promise<boolean>>();
-
-function probeCached(execPath: string, isElectron: boolean): Promise<boolean> {
-  const key = `${execPath}:${isElectron}`;
-  let p = probeCache.get(key);
-  if (!p) {
-    p = probeNodeExecutor(execPath, isElectron);
-    probeCache.set(key, p);
-  }
-  return p;
-}
-
-/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
-export function resetEngineNodeProbeCache(): void {
-  probeCache.clear();
-}
-
-/** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
-export type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
-
-/** resolveEngineNodeLaunch 的可注入项（测试隔离用；生产全部走缺省推导）。 */
-export interface EngineNodeLaunchOptions {
-  /** 引擎 CLI 入口绝对路径（descriptor command / staged bin 解析结果）。 */
-  entryPath: string;
-  /** 入口附加参数（descriptor args；缺省 []）。 */
-  args?: readonly string[];
-  /** 宿主形态。 */
-  hostKind: EngineNodeHostKind;
-  /** 读取 XYZ_AGENT_ENGINE_NODE 的 env 快照（矩阵① 的注入通道）。 */
-  env?: Record<string, string | undefined>;
-  /** 宿主 process.execPath（缺省 process.execPath）。 */
-  execPath?: string;
-  /** 宿主自身是否 Electron（缺省 process.versions.electron !== undefined）。 */
-  isElectronHost?: boolean;
-  /** 平台覆盖（缺省 process.platform）。 */
-  platform?: NodeJS.Platform;
-}
-
-/** 解析结果：spawn(command, args) 形态 + buildEngineChildEnv 的 electronRunAsNode 输入。 */
-export interface EngineNodeLaunch {
-  command: string;
-  args: string[];
-  /** 执行器为 Electron 二进制 → true（L0 注入 ELECTRON_RUN_AS_NODE=1）。 */
-  electronRunAsNode: boolean;
-}
-
-function engineNotFound(detail: string, recovery: string): EngineSdkError {
-  return new EngineSdkError("engine_not_found", detail, recovery);
-}
-
-/** 传入 opts.env 的快照（矩阵① env 缺省 = 宿主 process.env）。 */
-function launchEnvOf(opts: EngineNodeLaunchOptions): Record<string, string | undefined> {
-  return opts.env ?? process.env;
-}
-
-/**
- * 矩阵①：pi 扩展宿主（打包）——必须用注入执行器 XYZ_AGENT_ENGINE_NODE
- * （env 缺失 = engine_not_found；执行器探针失败 = engine_not_found + 指引）。
- */
-async function resolvePiExtensionLaunch(
-  entryPath: string,
-  entryArgs: string[],
-  env: Record<string, string | undefined>,
-): Promise<EngineNodeLaunch> {
-  const engineNode = env[ENGINE_NODE_ENV]?.trim();
-  if (engineNode === undefined || engineNode === "") {
-    throw engineNotFound(
-      `pi extension host must spawn engines via injected executor ${ENGINE_NODE_ENV}, `
-        + `but it is not set (host process.execPath is the pi binary, not a node executor)`,
-      `The xyz-agent runtime injects ${ENGINE_NODE_ENV} when spawning the pi host. `
-        + `If you are running the extension inside a packaged app, report this as a packaging `
-        + `regression; standalone pi installs do not use the pi-extension host kind.`,
-    );
-  }
-  // 执行器为 Electron 二进制时宿主会同时注入 ELECTRON_RUN_AS_NODE=1（矩阵① 同点注入）
-  const isElectron = env.ELECTRON_RUN_AS_NODE === "1";
-  if (!(await probeCached(engineNode, isElectron))) {
-    throw engineNotFound(
-      `injected node executor failed the probe: ${engineNode} (isElectron=${isElectron})`,
-      `Verify the executor exists and can run plain node semantics `
-        + `(Electron binaries need ELECTRON_RUN_AS_NODE=1). The host re-probes after restart.`,
-    );
-  }
-  return { command: engineNode, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
-}
-
-/**
- * 矩阵②：runtime sidecar——process.execPath + ELECTRON_RUN_AS_NODE=1（Electron 宿主时，
- * 探针先行）。
- */
-async function resolveRuntimeSidecarLaunch(
-  entryPath: string,
-  entryArgs: string[],
-  opts: EngineNodeLaunchOptions,
-): Promise<EngineNodeLaunch> {
-  const execPath = opts.execPath ?? process.execPath;
-  const isElectron = opts.isElectronHost ?? process.versions.electron !== undefined;
-  if (!(await probeCached(execPath, isElectron))) {
-    throw engineNotFound(
-      `runtime sidecar executor failed the probe: ${execPath} (isElectron=${isElectron})`,
-      `The sidecar process.execPath must run plain node semantics (ELECTRON_RUN_AS_NODE=1 `
-        + `for Electron binaries). Check how the runtime sidecar was spawned.`,
-    );
-  }
-  return { command: execPath, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
-}
-
-/** 矩阵③：standalone——PATH node（探针被证伪 = engine_not_found + 安装指引）。 */
-async function resolveStandaloneLaunch(
-  entryPath: string,
-  entryArgs: string[],
-): Promise<EngineNodeLaunch> {
-  if (!(await probeCached("node", false))) {
-    throw engineNotFound(
-      `no usable 'node' on PATH for standalone engine launch (entry: ${entryPath})`,
-      `Install Node.js >= 22 and ensure 'node' is on PATH `
-        + `(https://nodejs.org/), or configure the engine explicitly via subagents/config.json.`,
-    );
-  }
-  return { command: "node", args: [entryPath, ...entryArgs], electronRunAsNode: false };
-}
-
-/**
- * 宿主 × 平台二维矩阵解析（W9 §2.9）。返回 spawn argv；不直接 spawn——调用方
- * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
- *
- * 判定序（与规格逐行对应）：
- *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
- *   pi-extension → 注入执行器（env XYZ_AGENT_ENGINE_NODE），缺失/探针失败 =
- *     engine_not_found + 指引；
- *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；
- *   standalone → PATH node（探针失败 = engine_not_found + 安装指引）；
- *   其余（dev 形态、非 Windows 非 .cmd、无矩阵命中的兜底）→ 直接 spawn 入口本体
- *   （shebang `#!/usr/bin/env node` 走 PATH node——引擎 bin 均带 shebang，dev/独立
- *   安装形态与现状一致）。
- */
-export async function resolveEngineNodeLaunch(
-  opts: EngineNodeLaunchOptions,
-): Promise<EngineNodeLaunch> {
-  const platform = opts.platform ?? process.platform;
-  const entryArgs = [...(opts.args ?? [])];
-
-  // Windows 规则：入口 .cmd → 显式 cmd.exe /c + 参数数组（禁 shell:true）
-  if (platform === "win32" && opts.entryPath.toLowerCase().endsWith(".cmd")) {
-    return {
-      command: "cmd.exe",
-      args: ["/c", opts.entryPath, ...entryArgs],
-      electronRunAsNode: false,
-    };
-  }
-
-  // 非 JS 入口（原生二进制 / shell 脚本形态的引擎或测试 fixture）自管理执行体：
-  // 不经 node 执行器改写、不探针——直接 spawn 入口本体（shebang/原生入口语义）。
-  if (!/\.(?:js|mjs|cjs|ts)$/i.test(opts.entryPath)) {
-    return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
-  }
-
-  if (opts.hostKind === "pi-extension") {
-    return resolvePiExtensionLaunch(opts.entryPath, entryArgs, launchEnvOf(opts));
-  }
-
-  if (opts.hostKind === "runtime-sidecar") {
-    return resolveRuntimeSidecarLaunch(opts.entryPath, entryArgs, opts);
-  }
-
-  if (opts.hostKind === "standalone") {
-    return resolveStandaloneLaunch(opts.entryPath, entryArgs);
-  }
-
-  // 非矩阵形态（理论不可达——hostKind 是封闭联合）；保守回落直接 spawn 入口本体。
-  return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
-}
-
-/**
- * EngineClient 的自由字符串 hostKind（'pi' / 'runtime' / …）→ 矩阵行归一：
- *   'runtime*' → runtime-sidecar（②：sidecar execPath 权威）；
- *   env 已注入 XYZ_AGENT_ENGINE_NODE（打包态 runtime 注入主 pi 进程的通道）→
- *     pi-extension（①：必须用注入执行器——pi 宿主自身 execPath 是 pi binary）；
- *   其余 → standalone（③：PATH node）。
- */
-export function hostKindOf(
-  hostKind: string,
-  env: Record<string, string | undefined> = process.env,
-): EngineNodeHostKind {
-  if (hostKind.startsWith("runtime")) return "runtime-sidecar";
-  const engineNode = env[ENGINE_NODE_ENV]?.trim();
-  if (engineNode !== undefined && engineNode !== "") return "pi-extension";
-  return "standalone";
-}

package/src/paths.ts

@@ -1,48 +0,0 @@
-import { join } from 'node:path';
-
-/**
- * 引擎数据目录布局 SSOT（引擎侧原语，自 core execution/engine/paths.ts 移入
- * @zhushanwen/subagent-engine-sdk，实现体逐字等价）。
- * 迁移处置（impl-plan §2.1 paths 行）：纯 `node:path` 模块 → **移入 SDK**（引擎侧需
- * 自算池/journal 路径）；core 侧引用切换已完成（core execution/engine/paths.ts 为
- * re-export shim，子入口 ./engine/paths 解析路径不变）。
- *
- * 设计权威源：constraints.json C-ext-15（原 subagent-engine-abstraction.md D5/D6，已删，git 可追溯）。
- *
- * 为什么独立成模块：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/port-contract.ts

@@ -1,150 +0,0 @@
-// src/port-contract.ts
-//
-// 引擎进程内契约面七符号 + parseCtxModel 单源（S4 簇 1 收编：pi/zcode 两包
-// port-types.ts 的逐字等价本地镜像收编——两包原地改 re-export shim，18 个 import
-// 点零改写；server.ts 的 parseCtxModel 模块级纯函数同批收编，实现以 pi 版为基线
-// 逐字迁移）。
-//
-// 为什么现在能收（W5/W7 双轨沉淀后的收编，不翻「SDK 类型闭包只收跨进程协议面」
-// 的原始裁决）：两包过渡期镜像经 W10 conformance 套件验证字段逐字等价、双轨已
-// 稳定，收编即消除克隆而非改变边界语义。RunContext 含 AbortSignal/回调/EngineStream
-// 等非序列化成员，跨进程面经各包 server.ts 帧映射——故收主 barrel，不进 protocol/
-// 子入口（protocol/ 是 semver 收窄的跨进程可序列化面）。
-//
-// 命名：全量任务声明在 SDK 侧名 EngineAgentCallOpts（主 barrel 已有 protocol 的
-// AgentCallOpts 引擎面子集——16 字段协议 run.params.task 形态，两者是子集/全量
-// 关系，不可同名共存；两包 shim 转名 re-export 保本包消费面 AgentCallOpts 不变）。
-//
-// onChildSpawned 统一采窄载荷形态（host/childSpawned 载荷形态；ChildProcess 句柄
-// 不跨协议面）——zcode 侧生产零调用（D6），形态统一无行为影响。
-//
-// 第三份镜像登记：core execution/engine/port.ts 的 RunContext 是宿主侧独立契约
-// （onChildSpawned 全 ChildProcess 句柄，概念域 = 宿主进程内），不收编、不 import
-// 本模块；漂移面由 W10 conformance 套件继续覆盖。
-
-import type {
-  AgentCallOpts as SdkAgentCallOpts,
-  AgentEvent,
-  AgentOutcome,
-  EngineCapabilities,
-  EngineHandleData,
-  ProbeReport,
-  ResumeAnchor,
-  SessionView,
-} from "./protocol/contract-types.ts";
-
-/**
- * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
- * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
- * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
- */
-export type EngineAgentCallOpts = SdkAgentCallOpts & {
-  model?: string;
-  cwd?: string;
-  schemaEnv?: string;
-};
-
-/**
- * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
- * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
- */
-export interface EngineCtxModel {
-  id: string;
-  provider: string;
-  name?: string;
-  reasoning?: boolean;
-  thinkingLevelMap?: Record<string, unknown>;
-  contextWindow?: number;
-}
-
-/** text_delta streaming 出口（协议 host/streamDelta 的本地承载）。 */
-export interface EngineStream {
-  onDelta(delta: string): void;
-}
-
-/**
- * journal 固定分组 key（值锚定，**只承载、不透传**）：journal 落盘路径
- * `<dataDir>/engines/<engineId>/<本值>/journal-<taskId>.jsonl` 的第二段，两引擎恒
- * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
- * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
- * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
- * 三类消费：① journal 落盘路径构造（core journal-wiring）；② 存量 record 兼容
- * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
- * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
- * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
- */
-export const SHARED_POOL_KEY = "shared";
-
-/** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
-export interface RunContext {
-  taskId: string;
-  signal?: AbortSignal;
-  onEvent?: (event: AgentEvent) => void;
-  ctxModel?: EngineCtxModel;
-  stream?: EngineStream;
-  schemaEnv?: string;
-  engineFallback?: { from: string; reason: string };
-  /**
-   * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
-   * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
-   */
-  sessionRootId?: string;
-  /**
-   * [Option C 协议化] 权威 subagent session 目录（协议 run.params.ctx.sessionDir 的
-   * 进程内还原）——pi 引擎组装 `--session-dir` 的唯一权威值（宿主
-   * getSubagentSessionDir 推导，引擎不自推导）。additive 可选：缺省走引擎内
-   * [LEGACY] fallback（独立运行/测试形态）。
-   */
-  sessionDir?: string;
-  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
-  /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
-  onChildSpawned?: (child: { pid: number | undefined; killed: boolean }) => void;
-  /**
-   * 子进程退出态上报（host/childStateChanged 载荷形态；SR-4 接线：宿主镜像据此取消
-   * 该 pid 的挂起 dialog）。引擎侧只在 exited 相位上报——running 由 onChildSpawned 覆盖。
-   */
-  onChildStateChanged?: (p: {
-    pid: number;
-    recordId: string;
-    state: "running" | "exited";
-    killed: boolean;
-    exitCode?: number;
-    signal?: string;
-  }) => void;
-  /**
-   * [H1 U6 终态] resume 续聊参数（协议 run.params.resume 的进程内还原；唯一会话形态
-   * 键——原 v1.x `chat` 字段已随键切换退役）。recordId = 轮次关联键与镜像帧锚定键；
-   * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。缺省 =
-   * 一次性任务形态。
-   */
-  resume?: { recordId: string; resume?: ResumeAnchor };
-}
-
-export interface EngineHandle {
-  readonly data: EngineHandleData;
-}
-
-export interface EngineRunResult {
-  handle: EngineHandle;
-  outcome: AgentOutcome;
-}
-
-/** 引擎进程内的引擎契约点（core EnginePort 的结构等价镜像）。 */
-export interface EnginePort {
-  readonly id: string;
-  capabilities(): EngineCapabilities;
-  probe(opts?: { force?: boolean }): Promise<ProbeReport>;
-  run(task: EngineAgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
-  read(handle: EngineHandle): Promise<SessionView>;
-  listModels?(): Array<{ id: string; name?: string }> | null;
-  validateModel?(modelRef: string | undefined): { canonicalRef: string };
-  dispose?(): Promise<void>;
-}
-
-/** ctx.ctxModel（"provider/id" canonical 词形）→ EngineCtxModel。 */
-export function parseCtxModel(ref: string | undefined): EngineCtxModel | undefined {
-  if (ref === undefined || ref.trim() === "") return undefined;
-  const slash = ref.indexOf("/");
-  if (slash <= 0 || slash === ref.length - 1) return undefined;
-  return { provider: ref.slice(0, slash), id: ref.slice(slash + 1) };
-}