@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/schema-emulation.d.cts

@@ -0,0 +1,39 @@
+/** 原始输出尾部回显长度（结果对象的 tail 字段，供错误展示与重试 prompt 回灌）。 */
+declare const SCHEMA_EMULATION_TAIL_CHARS = 500;
+/**
+ * 构造 prompt 注入段：schema 声明 + 输出格式约定（emulated 引擎的 launcher 把它拼进
+ * 最终 prompt，替代引擎不存在的 schema 强制通道）。
+ *
+ * 文案风格对齐 structured-output 的 promptGuidelines（"Do not output JSON in text"：emulated 引擎没有工具可调，JSON 必须出现在文本里）。
+ */
+declare function buildSchemaEmulationSegment(schema: object): string;
+/** 提取结果联合：ok=true 携带通过校验的 parsed；ok=false 携带 error 简述 + 原始输出尾部。 */
+type StructuredOutputResult = {
+    ok: true;
+    parsed: unknown;
+} | {
+    ok: false;
+    error: string;
+    tail: string;
+};
+/**
+ * 从模型文本输出提取并校验结构化 JSON（三级容错 → ajv）。
+ *
+ * 三级容错（逐级降级，任一级提取成功即进 ajv）：
+ *   1. 直接 JSON.parse（trim 后整体是合法 JSON）；
+ *   2. 剥 markdown code fence（```json ... ``` / ``` ... ```）取围栏内内容；
+ *   3. 首尾括号扫描（首个 '{'/'[' 到末个 '}'/']' 的子串——容纳前后杂文本）。
+ *
+ * ajv 校验失败/三级提取失败返回 ok:false（不 throw）——重试与否是宿主编排层的
+ * 决策（见文件头重试语义），本函数每次调用独立无状态。
+ */
+declare function extractAndValidateStructuredOutput(text: string, schema: object): {
+    ok: true;
+    parsed: unknown;
+} | {
+    ok: false;
+    error: string;
+    tail: string;
+};
+
+export { SCHEMA_EMULATION_TAIL_CHARS, type StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput };

package/dist/schema-emulation.d.ts

@@ -0,0 +1,39 @@
+/** 原始输出尾部回显长度（结果对象的 tail 字段，供错误展示与重试 prompt 回灌）。 */
+declare const SCHEMA_EMULATION_TAIL_CHARS = 500;
+/**
+ * 构造 prompt 注入段：schema 声明 + 输出格式约定（emulated 引擎的 launcher 把它拼进
+ * 最终 prompt，替代引擎不存在的 schema 强制通道）。
+ *
+ * 文案风格对齐 structured-output 的 promptGuidelines（"Do not output JSON in text"：emulated 引擎没有工具可调，JSON 必须出现在文本里）。
+ */
+declare function buildSchemaEmulationSegment(schema: object): string;
+/** 提取结果联合：ok=true 携带通过校验的 parsed；ok=false 携带 error 简述 + 原始输出尾部。 */
+type StructuredOutputResult = {
+    ok: true;
+    parsed: unknown;
+} | {
+    ok: false;
+    error: string;
+    tail: string;
+};
+/**
+ * 从模型文本输出提取并校验结构化 JSON（三级容错 → ajv）。
+ *
+ * 三级容错（逐级降级，任一级提取成功即进 ajv）：
+ *   1. 直接 JSON.parse（trim 后整体是合法 JSON）；
+ *   2. 剥 markdown code fence（```json ... ``` / ``` ... ```）取围栏内内容；
+ *   3. 首尾括号扫描（首个 '{'/'[' 到末个 '}'/']' 的子串——容纳前后杂文本）。
+ *
+ * ajv 校验失败/三级提取失败返回 ok:false（不 throw）——重试与否是宿主编排层的
+ * 决策（见文件头重试语义），本函数每次调用独立无状态。
+ */
+declare function extractAndValidateStructuredOutput(text: string, schema: object): {
+    ok: true;
+    parsed: unknown;
+} | {
+    ok: false;
+    error: string;
+    tail: string;
+};
+
+export { SCHEMA_EMULATION_TAIL_CHARS, type StructuredOutputResult, buildSchemaEmulationSegment, extractAndValidateStructuredOutput };

package/dist/schema-emulation.js

@@ -0,0 +1,11 @@
+import {
+  SCHEMA_EMULATION_TAIL_CHARS,
+  buildSchemaEmulationSegment,
+  extractAndValidateStructuredOutput
+} from "./chunk-X24SFZYW.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  SCHEMA_EMULATION_TAIL_CHARS,
+  buildSchemaEmulationSegment,
+  extractAndValidateStructuredOutput
+};

package/dist/spawn.cjs

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/spawn.ts
+var spawn_exports = {};
+__export(spawn_exports, {
+  DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS: () => DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_HOST_REQUEST_TIMEOUT_ENV: () => ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  armEngineSelfDestruct: () => armEngineSelfDestruct,
+  pumpNdjsonLines: () => pumpNdjsonLines,
+  spawnEngineChild: () => spawnEngineChild
+});
+module.exports = __toCommonJS(spawn_exports);
+var import_node_child_process = require("child_process");
+
+// src/logger.ts
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+// src/spawn.ts
+var logger = getLogger("engine-sdk/spawn");
+var FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"];
+function spawnEngineChild(opts) {
+  for (const key of FORBIDDEN_OPTION_KEYS) {
+    if (key in opts) {
+      throw new Error(
+        `spawnEngineChild: option "${key}" is hardcoded by the engine spawn contract (detached:false / windowsHide:true / child stdin is always its own pipe); remove it from the call site`
+      );
+    }
+  }
+  const child = (0, import_node_child_process.spawn)(opts.command, [...opts.args], {
+    cwd: opts.cwd,
+    env: opts.env,
+    detached: false,
+    windowsHide: true,
+    stdio: ["pipe", opts.stdout ?? "pipe", opts.stderr ?? "pipe"]
+  });
+  if (opts.signal !== void 0) {
+    opts.signal.addEventListener(
+      "abort",
+      () => {
+        child.kill("SIGTERM");
+      },
+      { once: true }
+    );
+  }
+  return child;
+}
+var DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 3e4;
+var ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
+var SWEEP_INTERVAL_MS = 1e3;
+function resolveHostRequestTimeoutMs(opts) {
+  if (opts.hostRequestTimeoutMs !== void 0) return opts.hostRequestTimeoutMs;
+  const raw = (opts.timeoutEnv ?? process.env)[ENGINE_HOST_REQUEST_TIMEOUT_ENV];
+  if (raw === void 0 || raw === "") return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    logger.warn(
+      `invalid ${ENGINE_HOST_REQUEST_TIMEOUT_ENV}=${JSON.stringify(raw)}, falling back to ${DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS}ms`
+    );
+    return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
+  }
+  return parsed;
+}
+function killOwnProcessGroup() {
+  const pid = process.pid;
+  try {
+    process.kill(-pid, "SIGKILL");
+  } catch (err) {
+    logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
+    process.kill(pid, "SIGKILL");
+  }
+}
+function armEngineSelfDestruct(opts) {
+  const timeoutMs = resolveHostRequestTimeoutMs(opts);
+  const killSelf = opts.killSelf ?? killOwnProcessGroup;
+  const pending = /* @__PURE__ */ new Map();
+  let disposed = false;
+  const destroy = (reason) => {
+    if (disposed) return;
+    disposed = true;
+    clearInterval(timer);
+    opts.stdin.removeAllListeners?.("end");
+    opts.stdin.removeAllListeners?.("close");
+    logger.warn(`engine self-destruct: ${reason}`);
+    killSelf();
+  };
+  opts.stdin.once("end", () => destroy("host stdin EOF (end)"));
+  opts.stdin.once("close", () => destroy("host stdin closed"));
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const [id, startedAt] of pending) {
+      if (now - startedAt > timeoutMs) {
+        destroy(`unacked reverse request ${id} exceeded ${timeoutMs}ms without host ack`);
+        return;
+      }
+    }
+  }, SWEEP_INTERVAL_MS);
+  timer.unref?.();
+  return {
+    started(id) {
+      if (!disposed) pending.set(id, Date.now());
+    },
+    acked(id) {
+      pending.delete(id);
+    },
+    settled(id) {
+      pending.delete(id);
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      clearInterval(timer);
+      opts.stdin.removeAllListeners?.("end");
+      opts.stdin.removeAllListeners?.("close");
+    }
+  };
+}
+function pumpNdjsonLines(stream, onLine) {
+  if (stream === null || stream === void 0) return;
+  stream.setEncoding("utf8");
+  let buffer = "";
+  stream.on("data", (chunk) => {
+    buffer += chunk;
+    let nl = buffer.indexOf("\n");
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl);
+      buffer = buffer.slice(nl + 1);
+      onLine(line);
+      nl = buffer.indexOf("\n");
+    }
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  armEngineSelfDestruct,
+  pumpNdjsonLines,
+  spawnEngineChild
+});

package/dist/spawn.d.cts

@@ -0,0 +1,80 @@
+import { ChildProcess } from 'node:child_process';
+import { buildEngineChildEnv } from './env.cjs';
+
+/** spawnEngineChild 的 env 必须来自 buildEngineChildEnv（三层契约终态）。 */
+type EngineChildEnv = ReturnType<typeof buildEngineChildEnv>;
+/** 引擎子进程 spawn 选项（刻意不暴露 detached / stdio / stdin——形态硬编码，见文件头）。 */
+interface SpawnEngineChildOptions {
+    command: string;
+    args: readonly string[];
+    /** 须由 buildEngineChildEnv 构建（类型即契约：三层 env 终态） */
+    env: EngineChildEnv;
+    cwd?: string;
+    /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
+    stdout?: "pipe" | "ignore" | "inherit";
+    stderr?: "pipe" | "ignore" | "inherit";
+    /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
+    signal?: AbortSignal;
+}
+/**
+ * 引擎任务子进程唯一 spawn 入口。
+ *
+ * 形态硬编码：detached:false、windowsHide:true、子进程 stdin 恒 'pipe'（自有 pipe，
+ * 绝不继承引擎自身 stdin fd）。传入被禁止的形态键（detached/stdio/stdin/windowsHide）
+ * 直接抛错——契约破坏应在配置期出声，不静默降级。
+ */
+declare function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess;
+/** in-flight 未 ack 反向请求的计时超时缺省值（辅助判据，30s）。 */
+declare const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30000;
+/** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
+declare const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
+/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
+interface ReverseRequestClock {
+    /** 反向请求已发出（未 ack）——进入计时面。 */
+    started(id: string): void;
+    /**
+     * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
+     * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
+     * ADR-0047 静默 ≠ 卡死）。
+     */
+    acked(id: string): void;
+    /** 请求终结（应答完成/失败/取消）——彻底移出。 */
+    settled(id: string): void;
+    /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
+    dispose(): void;
+}
+interface EngineSelfDestructOptions {
+    /** 主判据数据源：宿主→引擎的协议 stdin（EOF = 宿主死亡 → 立即自灭）。 */
+    stdin: NodeJS.ReadableStream;
+    /** 辅助判据超时（缺省 30s；显式传值优先于 env XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS）。 */
+    hostRequestTimeoutMs?: number;
+    /** 计时超时的 env 覆盖源（缺省读 process.env；测试注入用）。 */
+    timeoutEnv?: Record<string, string | undefined>;
+    /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
+    killSelf?: () => void;
+}
+/**
+ * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
+ *
+ * 判据：
+ * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
+ *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
+ * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
+ *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
+ *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
+ *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
+ *
+ * 自灭执行 = 引擎自杀并杀自己进程组（spawnEngineChild 硬编码 detached:false，
+ * 任务子进程同组连带收割）。
+ */
+declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): ReverseRequestClock;
+/**
+ * 流式 NDJSON 行泵：utf8 解码 + 缓冲累积 + "\n" 拆行循环（S4 簇 5b 收编：pi
+ * spawn-run-pump 与 zcode connection 的逐字同构段单源化，实现以 pi 版为基线）。
+ * 末行无换行符时滞留缓冲（NDJSON 语义：行以 \n 定界）；不监听 end/close/error——
+ * 生命周期接线（close 收尾/error 兜底）由调用方自行挂接。stream 为 null/undefined
+ * （无 stdio）时无操作，与原调用点 `child.stdout?.` 可选链语义等价。
+ */
+declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
+
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.d.ts

@@ -0,0 +1,80 @@
+import { ChildProcess } from 'node:child_process';
+import { buildEngineChildEnv } from './env.js';
+
+/** spawnEngineChild 的 env 必须来自 buildEngineChildEnv（三层契约终态）。 */
+type EngineChildEnv = ReturnType<typeof buildEngineChildEnv>;
+/** 引擎子进程 spawn 选项（刻意不暴露 detached / stdio / stdin——形态硬编码，见文件头）。 */
+interface SpawnEngineChildOptions {
+    command: string;
+    args: readonly string[];
+    /** 须由 buildEngineChildEnv 构建（类型即契约：三层 env 终态） */
+    env: EngineChildEnv;
+    cwd?: string;
+    /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
+    stdout?: "pipe" | "ignore" | "inherit";
+    stderr?: "pipe" | "ignore" | "inherit";
+    /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
+    signal?: AbortSignal;
+}
+/**
+ * 引擎任务子进程唯一 spawn 入口。
+ *
+ * 形态硬编码：detached:false、windowsHide:true、子进程 stdin 恒 'pipe'（自有 pipe，
+ * 绝不继承引擎自身 stdin fd）。传入被禁止的形态键（detached/stdio/stdin/windowsHide）
+ * 直接抛错——契约破坏应在配置期出声，不静默降级。
+ */
+declare function spawnEngineChild(opts: SpawnEngineChildOptions): ChildProcess;
+/** in-flight 未 ack 反向请求的计时超时缺省值（辅助判据，30s）。 */
+declare const DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS = 30000;
+/** 计时超时覆盖 env 名（引擎 CLI 启动时读；非法值 warn + 回落缺省）。 */
+declare const ENGINE_HOST_REQUEST_TIMEOUT_ENV = "XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS";
+/** 反向请求计时面操作接口（消费方 = 引擎 CLI 的反向通道分发层）。 */
+interface ReverseRequestClock {
+    /** 反向请求已发出（未 ack）——进入计时面。 */
+    started(id: string): void;
+    /**
+     * 收到 ack（两阶段第一阶段：已 ack 的 host/askUser、HostBridge.executeAndAwait
+     * 的 ack）——移出计时面但不终结（R9-2：已 ack 的等待不计入 in-flight 超时，
+     * ADR-0047 静默 ≠ 卡死）。
+     */
+    acked(id: string): void;
+    /** 请求终结（应答完成/失败/取消）——彻底移出。 */
+    settled(id: string): void;
+    /** 卸载守卫（引擎正常 shutdown 路径；自灭后幂等）。 */
+    dispose(): void;
+}
+interface EngineSelfDestructOptions {
+    /** 主判据数据源：宿主→引擎的协议 stdin（EOF = 宿主死亡 → 立即自灭）。 */
+    stdin: NodeJS.ReadableStream;
+    /** 辅助判据超时（缺省 30s；显式传值优先于 env XYZ_ENGINE_HOST_REQUEST_TIMEOUT_MS）。 */
+    hostRequestTimeoutMs?: number;
+    /** 计时超时的 env 覆盖源（缺省读 process.env；测试注入用）。 */
+    timeoutEnv?: Record<string, string | undefined>;
+    /** 自灭执行器（缺省 = 杀自己进程组再杀自己；测试注入用）。 */
+    killSelf?: () => void;
+}
+/**
+ * 武装引擎侧自灭守卫。返回 ReverseRequestClock 给反向通道分发层登记请求生命周期。
+ *
+ * 判据：
+ * - 主判据 stdio EOF：stdin 'end'（数据面读尽）或 'close'（fd 关闭）→ 立即自灭
+ *   （宿主死后无人再写协议帧，引擎继续跑只烧 token）；
+ * - 辅助判据 in-flight 反向请求计时：未 ack 的反向请求超过 hostRequestTimeoutMs
+ *   仍无 ack → 宿主大概率已死（EOF 未达或正在关闭）→ 自灭。**排除面**：已 ack 的
+ *   host/askUser 与两阶段 ack 的长运行 HostBridge.executeAndAwait（ack 后等待任意
+ *   时长合法，漏此项即「>30s pi 任务被自灭」turnTimeoutMs 同型事故）。
+ *
+ * 自灭执行 = 引擎自杀并杀自己进程组（spawnEngineChild 硬编码 detached:false，
+ * 任务子进程同组连带收割）。
+ */
+declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): ReverseRequestClock;
+/**
+ * 流式 NDJSON 行泵：utf8 解码 + 缓冲累积 + "\n" 拆行循环（S4 簇 5b 收编：pi
+ * spawn-run-pump 与 zcode connection 的逐字同构段单源化，实现以 pi 版为基线）。
+ * 末行无换行符时滞留缓冲（NDJSON 语义：行以 \n 定界）；不监听 end/close/error——
+ * 生命周期接线（close 收尾/error 兜底）由调用方自行挂接。stream 为 null/undefined
+ * （无 stdio）时无操作，与原调用点 `child.stdout?.` 可选链语义等价。
+ */
+declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
+
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.js

@@ -0,0 +1,16 @@
+import {
+  DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  armEngineSelfDestruct,
+  pumpNdjsonLines,
+  spawnEngineChild
+} from "./chunk-3K2P2CM2.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  armEngineSelfDestruct,
+  pumpNdjsonLines,
+  spawnEngineChild
+};

package/dist/ui-channels.cjs

@@ -0,0 +1,120 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/ui-channels.ts
+var ui_channels_exports = {};
+__export(ui_channels_exports, {
+  createUiChannelRegistry: () => createUiChannelRegistry,
+  parseChannel: () => parseChannel
+});
+module.exports = __toCommonJS(ui_channels_exports);
+var NUL = "\0";
+function normalizeChannelName(markerLiteral) {
+  let name = markerLiteral;
+  if (name.startsWith("XYZ_")) {
+    name = name.slice("XYZ_".length);
+  }
+  if (name.endsWith(":")) {
+    name = name.slice(0, -1);
+  }
+  return name.toLowerCase();
+}
+function parseMarkerFromField(str) {
+  if (!str.startsWith(NUL)) return void 0;
+  const literal = str.slice(NUL.length);
+  if (literal === "") return void 0;
+  return normalizeChannelName(literal);
+}
+function parseInlineMarkerFromField(str) {
+  if (!str.startsWith(NUL)) return void 0;
+  const rest = str.slice(NUL.length);
+  const colonIdx = rest.indexOf(":");
+  let literal;
+  if (colonIdx >= 0) {
+    literal = rest.slice(0, colonIdx + 1);
+  } else {
+    literal = rest;
+  }
+  if (literal === "") return void 0;
+  return { channel: normalizeChannelName(literal) };
+}
+function parseFromMarkerString(title, options) {
+  if (title === void 0) return {};
+  const channel = parseMarkerFromField(title);
+  if (channel === void 0) return {};
+  let payload;
+  if (options !== void 0 && options.length > 0) {
+    try {
+      payload = JSON.parse(options[0]);
+    } catch {
+      payload = void 0;
+    }
+  }
+  return { channel, channelPayload: payload };
+}
+function parseFromMarkerArray(widgetLines) {
+  if (widgetLines === void 0 || widgetLines.length === 0) return {};
+  const firstLine = widgetLines[0];
+  if (typeof firstLine !== "string") return {};
+  const parsed = parseInlineMarkerFromField(firstLine);
+  if (parsed === void 0) return {};
+  let payload;
+  const rest = firstLine.slice(NUL.length);
+  const colonIdx = rest.indexOf(":");
+  if (colonIdx >= 0) {
+    const jsonStr = rest.slice(colonIdx + 1);
+    if (jsonStr !== "") {
+      try {
+        payload = JSON.parse(jsonStr);
+      } catch {
+        payload = void 0;
+      }
+    }
+  }
+  return { channel: parsed.channel, channelPayload: payload };
+}
+function parseChannel(req) {
+  switch (req.method) {
+    case "select":
+      return parseFromMarkerString(req.title, req.options);
+    case "setWidget":
+      return parseFromMarkerArray(req.widgetLines);
+    default:
+      return {};
+  }
+}
+function createUiChannelRegistry() {
+  const handlers = /* @__PURE__ */ new Map();
+  return {
+    register(channel, handler) {
+      handlers.set(channel, handler);
+    },
+    resolve(channel) {
+      return handlers.get(channel);
+    },
+    list() {
+      return Array.from(handlers.keys());
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createUiChannelRegistry,
+  parseChannel
+});

package/dist/ui-channels.d.cts

@@ -0,0 +1,60 @@
+/** channel 提取结果。channel 无 NUL 前缀、字段缺失、JSON parse 失败时
+ *  channel 与 channelPayload 均为 undefined（返回 {}）。 */
+interface ParsedChannel {
+    /** 规范化后的 channel 名（如 "ask_user"、"gui_widget"）。
+     *  无 marker 或解析失败时为 undefined。 */
+    channel?: string;
+    /** marker 标记的结构化 payload（已 JSON.parse）。
+     *  ask_user: {questions, allowCancel}；gui_widget: {component}。
+     *  payload 来源缺失或 JSON parse 失败时为 undefined（channel 仍可解析）。 */
+    channelPayload?: unknown;
+}
+/** parseChannel 入参的最小形状。
+ *  method 是判别字段；按 method 不同，对应字段（select 的 title/options、
+ *  setWidget 的 widgetLines）可选出现。其他 method 的字段统称 [key:string]。 */
+interface ExtensionUiRequestLike {
+    method: string;
+    /** select method：title 字段（可能含 ASK_USER_MARKER NUL 前缀）。 */
+    title?: string;
+    /** select method：options 数组（options[0] 可能是 channel payload 的 JSON）。 */
+    options?: string[];
+    /** setWidget method：widgetKey 字段。 */
+    widgetKey?: string;
+    /** setWidget method：widgetLines 数组（widgetLines[0] 可能含 GUI_WIDGET_MARKER）。 */
+    widgetLines?: string[] | undefined;
+    /** 其他 method 的任意字段（容错：允许测试和未来扩展传入额外字段）。 */
+    [key: string]: unknown;
+}
+/** channel handler 签名：接收 UiRequest，返回 UiResponse。
+ *  具体类型定义在 session-runner.ts（W2 工作），此处用最小形状避免循环依赖。
+ *  handler 实现方按 channel 注册，由 session-runner 按 req.channel 分派。 */
+type ChannelHandler = (req: unknown) => Promise<unknown>;
+/** channel 注册表接口。职责单一：只管业务路由，不管排队、不管透传判定。
+ *  - register(channel, handler)：注册 channel 对应的 handler（同名覆盖）
+ *  - resolve(channel)：取 channel 对应的 handler，未注册返回 undefined
+ *  - list()：列举所有已注册 channel 名 */
+interface UiChannelRegistry {
+    register(channel: string, handler: ChannelHandler): void;
+    resolve(channel: string): ChannelHandler | undefined;
+    list(): string[];
+}
+/** 按 method 分派解析 channel。
+ *
+ *  - select → 从 title 解析 NUL 前缀（payload 从 options[0]）
+ *  - setWidget → 从 widgetLines[0] 解析 NUL 前缀（payload 从同行 marker 后）
+ *  - 其他 method → {}（无 channel 提取位置）
+ *
+ *  边界（均不抛错）：
+ *    - title/widgetLines 字段缺失 → {}
+ *    - 无 NUL 前缀 → {}
+ *    - JSON parse 失败 → channel 仍解析，channelPayload 为 undefined
+ *
+ *  @param req ExtensionUiRequestLike（method + 对应字段）
+ *  @returns ParsedChannel（channel/channelPayload 可选） */
+declare function parseChannel(req: ExtensionUiRequestLike): ParsedChannel;
+/** 创建 channel 注册表实例。
+ *  进程级单例（通常由 SubagentService 持有一个实例，跨所有子进程共享）。
+ *  register 同名 channel 会覆盖旧 handler。 */
+declare function createUiChannelRegistry(): UiChannelRegistry;
+
+export { type ChannelHandler, type ExtensionUiRequestLike, type ParsedChannel, type UiChannelRegistry, createUiChannelRegistry, parseChannel };