@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/env.cjs

@@ -0,0 +1,205 @@
+"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/env.ts
+var env_exports = {};
+__export(env_exports, {
+  ENGINE_ENV_DENY_LIST: () => ENGINE_ENV_DENY_LIST,
+  ENGINE_ENV_L0_INFRA_KEYS: () => ENGINE_ENV_L0_INFRA_KEYS,
+  ENGINE_ENV_PREFIXES: () => ENGINE_ENV_PREFIXES,
+  buildEngineChildEnv: () => buildEngineChildEnv,
+  buildOutboundChildEnv: () => buildOutboundChildEnv
+});
+module.exports = __toCommonJS(env_exports);
+
+// 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/env.ts
+var logger = getLogger("engine-sdk/env");
+var ENGINE_ENV_PREFIXES = [
+  "XYZ_",
+  "XYZ_AGENT_",
+  "XYZ_SUBAGENT_"
+];
+var ENGINE_ENV_DENY_LIST = [
+  "XYZ_AGENT_PACKAGED",
+  "XYZ_RUNTIME_TOKEN",
+  "XYZ_AGENT_API_KEY",
+  "XYZ_SUBAGENT_RELAY_SESSION_ID",
+  "XYZ_SUBAGENT_RELAY_RECORD_ID",
+  "XYZ_SUBAGENT_RELAY_STDIN",
+  "XYZ_SUBAGENT_RELAY_STDOUT",
+  "XYZ_SUBAGENT_RELAY_STDERR"
+];
+var ENGINE_ENV_L0_INFRA_KEYS = [
+  "XYZ_AGENT_DATA_DIR",
+  "XYZ_AGENT_ENGINE_NODE",
+  "ELECTRON_RUN_AS_NODE",
+  "XYZ_AGENT_SUBAGENT",
+  "XYZ_SUBAGENT_RELAY_SOCKET",
+  "XYZ_SUBAGENT_RELAY_NODE",
+  "XYZ_SUBAGENT_RELAY_SCRIPT"
+];
+var ENV_PREFIX_SHAPE_RE = /^[A-Za-z0-9_]+$/;
+function deleteEnvKeysCaseInsensitive(env, names) {
+  const lowered = new Set(names.map((n) => n.toLowerCase()));
+  for (const key of Object.keys(env)) {
+    if (lowered.has(key.toLowerCase())) delete env[key];
+  }
+}
+function compileManifestPrefixes(prefixes) {
+  const compiled = [];
+  for (const raw of prefixes) {
+    if (!ENV_PREFIX_SHAPE_RE.test(raw)) {
+      logger.warn(
+        `envPrefixes entry dropped (invalid shape, expected ^[A-Za-z0-9_]+$): ${JSON.stringify(raw)}`
+      );
+      continue;
+    }
+    const lowered = raw.toLowerCase();
+    if (ENGINE_ENV_PREFIXES.some((reserved) => lowered.startsWith(reserved.toLowerCase()))) {
+      logger.warn(
+        `envPrefixes entry dropped (reserved prefix, infra keys are L0-only): ${JSON.stringify(raw)}`
+      );
+      continue;
+    }
+    compiled.push(lowered);
+  }
+  return compiled.length > 0 ? compiled : null;
+}
+function applyManifestAllowlist(env, opts) {
+  if (opts.processEnv !== void 0 && opts.envPrefixes !== void 0) {
+    const compiled = compileManifestPrefixes(opts.envPrefixes);
+    if (compiled !== null) {
+      for (const [key, value] of Object.entries(opts.processEnv)) {
+        if (value === void 0) continue;
+        const loweredKey = key.toLowerCase();
+        if (compiled.some((prefix) => loweredKey.startsWith(prefix))) {
+          env[key] = value;
+        } else {
+          logger.warn(`processEnv key not allowed (no declared envPrefix matches): ${key}`);
+        }
+      }
+    }
+  } else if (opts.processEnv !== void 0) {
+    for (const key of Object.keys(opts.processEnv)) {
+      logger.warn(`processEnv key not allowed (manifest declares no envPrefixes): ${key}`);
+    }
+  }
+}
+function injectL0InfraKeys(env, opts) {
+  env.XYZ_AGENT_DATA_DIR = opts.dataDir;
+  if (opts.engineNode !== void 0) env.XYZ_AGENT_ENGINE_NODE = opts.engineNode;
+  if (opts.electronRunAsNode === true) env.ELECTRON_RUN_AS_NODE = "1";
+  env.XYZ_AGENT_SUBAGENT = "1";
+  if (opts.relay !== void 0) {
+    env.XYZ_SUBAGENT_RELAY_SOCKET = opts.relay.socket;
+    env.XYZ_SUBAGENT_RELAY_NODE = opts.relay.node;
+    env.XYZ_SUBAGENT_RELAY_SCRIPT = opts.relay.script;
+  }
+  if (opts.identityEnv !== void 0) {
+    for (const [key, value] of Object.entries(opts.identityEnv)) {
+      if (value !== void 0) env[key] = value;
+    }
+  }
+}
+function buildEngineChildEnv(baseEnv, opts) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (value !== void 0) env[key] = value;
+  }
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+  applyManifestAllowlist(env, opts);
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+  injectL0InfraKeys(env, opts);
+  return env;
+}
+function buildOutboundChildEnv(opts) {
+  const out = {};
+  const loweredPrefixes = opts.prefixes !== void 0 ? opts.prefixes.map((p) => p.toLowerCase()) : null;
+  for (const [key, value] of Object.entries(opts.parentEnv)) {
+    if (value === void 0) continue;
+    if (loweredPrefixes !== null) {
+      const loweredKey = key.toLowerCase();
+      if (!loweredPrefixes.some((prefix) => loweredKey.startsWith(prefix))) continue;
+    }
+    out[key] = value;
+  }
+  if (opts.extras !== void 0) {
+    for (const [key, value] of Object.entries(opts.extras)) {
+      if (value !== void 0) out[key] = value;
+      else delete out[key];
+    }
+  }
+  deleteEnvKeysCaseInsensitive(out, ENGINE_ENV_DENY_LIST);
+  return out;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ENGINE_ENV_DENY_LIST,
+  ENGINE_ENV_L0_INFRA_KEYS,
+  ENGINE_ENV_PREFIXES,
+  buildEngineChildEnv,
+  buildOutboundChildEnv
+});

package/dist/env.d.cts

@@ -0,0 +1,73 @@
+/** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
+declare const ENGINE_ENV_PREFIXES: readonly string[];
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
+declare const ENGINE_ENV_DENY_LIST: readonly string[];
+/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+declare const ENGINE_ENV_L0_INFRA_KEYS: readonly string[];
+/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
+interface EngineRelayEnv {
+    socket: string;
+    node: string;
+    script: string;
+}
+/** buildEngineChildEnv 入参。 */
+interface EngineChildEnvOptions {
+    /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
+    dataDir: string;
+    /** L0：执行器路径（descriptor command 的执行体；Electron 二进制时另置 electronRunAsNode） */
+    engineNode?: string;
+    /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
+    electronRunAsNode?: boolean;
+    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 XYZ_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
+    relay?: EngineRelayEnv;
+    /** L0：引擎侧身份 env（PI_SUBAGENT_ROOT_SESSION_ID 等，base-tool-enhance / 递归可见性消费） */
+    identityEnv?: Record<string, string | undefined>;
+    /** L2：manifest 声明的 envPrefixes 放行清单（保留前缀拒绝 + 形态校验） */
+    envPrefixes?: readonly string[];
+    /** L2：引擎私有 env 候选（descriptor processEnv；未声明前缀不放行 + warn） */
+    processEnv?: Record<string, string | undefined>;
+}
+/**
+ * `buildEngineChildEnv(baseEnv, opts)`：引擎子进程 env 三层契约（高者覆盖低者）。
+ *
+ * 写死次序 = 先过滤（L1 deny/剥除 → L2 manifest 放行）后 L0 显式注入——
+ * 「core 过滤之后显式注入」即此语义：baseEnv 是调用方（core/宿主）已过滤的基座，
+ * L0 键在最后写入故不受 L1 剥除影响（交集为 ∅ 由测试断言兜底）。
+ *
+ * 层规格（impl-plan §2.12 三层表）：
+ * - L0 基础设施键：XYZ_AGENT_DATA_DIR / XYZ_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
+ *   （条件）/ XYZ_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
+ *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
+ *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+declare function buildEngineChildEnv(baseEnv: Record<string, string | undefined>, opts: EngineChildEnvOptions): Record<string, string>;
+/** buildOutboundChildEnv 入参（SDK 版；语义见函数头注释）。 */
+interface BuildOutboundChildEnvOptions {
+    /** 父进程 env 快照（调用方显式注入；本函数绝不改写它） */
+    parentEnv: Record<string, string | undefined>;
+    /** 强制注入/覆盖的键；值为 undefined 时执行删除语义 */
+    extras?: Record<string, string | undefined>;
+    /** 基座前缀白名单；缺省 = 全量继承父 env（与 shared 版的差异，见函数头注释） */
+    prefixes?: readonly string[];
+}
+/**
+ * 通用子进程出站 env 构建器（deny 剥离终态），供非引擎 spawn 面（worktree git
+ * execFile 等）复用——R3 MF-C：deny 键不进 git 子进程，git hooks 等后代不再可能
+ * 消费生命周期标志 / WS 令牌。
+ *
+ * 与 @xyz-agent/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
+ * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
+ * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
+ * 兜底语义与 shared 版一致。需要白名单形态时调用方显式传 prefixes。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+declare function buildOutboundChildEnv(opts: BuildOutboundChildEnvOptions): Record<string, string>;
+
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, type EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv };

package/dist/env.d.ts

@@ -0,0 +1,73 @@
+/** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
+declare const ENGINE_ENV_PREFIXES: readonly string[];
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
+declare const ENGINE_ENV_DENY_LIST: readonly string[];
+/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+declare const ENGINE_ENV_L0_INFRA_KEYS: readonly string[];
+/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
+interface EngineRelayEnv {
+    socket: string;
+    node: string;
+    script: string;
+}
+/** buildEngineChildEnv 入参。 */
+interface EngineChildEnvOptions {
+    /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
+    dataDir: string;
+    /** L0：执行器路径（descriptor command 的执行体；Electron 二进制时另置 electronRunAsNode） */
+    engineNode?: string;
+    /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
+    electronRunAsNode?: boolean;
+    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 XYZ_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
+    relay?: EngineRelayEnv;
+    /** L0：引擎侧身份 env（PI_SUBAGENT_ROOT_SESSION_ID 等，base-tool-enhance / 递归可见性消费） */
+    identityEnv?: Record<string, string | undefined>;
+    /** L2：manifest 声明的 envPrefixes 放行清单（保留前缀拒绝 + 形态校验） */
+    envPrefixes?: readonly string[];
+    /** L2：引擎私有 env 候选（descriptor processEnv；未声明前缀不放行 + warn） */
+    processEnv?: Record<string, string | undefined>;
+}
+/**
+ * `buildEngineChildEnv(baseEnv, opts)`：引擎子进程 env 三层契约（高者覆盖低者）。
+ *
+ * 写死次序 = 先过滤（L1 deny/剥除 → L2 manifest 放行）后 L0 显式注入——
+ * 「core 过滤之后显式注入」即此语义：baseEnv 是调用方（core/宿主）已过滤的基座，
+ * L0 键在最后写入故不受 L1 剥除影响（交集为 ∅ 由测试断言兜底）。
+ *
+ * 层规格（impl-plan §2.12 三层表）：
+ * - L0 基础设施键：XYZ_AGENT_DATA_DIR / XYZ_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
+ *   （条件）/ XYZ_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
+ *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
+ *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+declare function buildEngineChildEnv(baseEnv: Record<string, string | undefined>, opts: EngineChildEnvOptions): Record<string, string>;
+/** buildOutboundChildEnv 入参（SDK 版；语义见函数头注释）。 */
+interface BuildOutboundChildEnvOptions {
+    /** 父进程 env 快照（调用方显式注入；本函数绝不改写它） */
+    parentEnv: Record<string, string | undefined>;
+    /** 强制注入/覆盖的键；值为 undefined 时执行删除语义 */
+    extras?: Record<string, string | undefined>;
+    /** 基座前缀白名单；缺省 = 全量继承父 env（与 shared 版的差异，见函数头注释） */
+    prefixes?: readonly string[];
+}
+/**
+ * 通用子进程出站 env 构建器（deny 剥离终态），供非引擎 spawn 面（worktree git
+ * execFile 等）复用——R3 MF-C：deny 键不进 git 子进程，git hooks 等后代不再可能
+ * 消费生命周期标志 / WS 令牌。
+ *
+ * 与 @xyz-agent/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
+ * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
+ * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
+ * 兜底语义与 shared 版一致。需要白名单形态时调用方显式传 prefixes。
+ *
+ * 红线：纯函数，不读写 process.env 本体，不 mutate 入参。
+ */
+declare function buildOutboundChildEnv(opts: BuildOutboundChildEnvOptions): Record<string, string>;
+
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, type EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv };

package/dist/env.js

@@ -0,0 +1,16 @@
+import {
+  ENGINE_ENV_DENY_LIST,
+  ENGINE_ENV_L0_INFRA_KEYS,
+  ENGINE_ENV_PREFIXES,
+  buildEngineChildEnv,
+  buildOutboundChildEnv
+} from "./chunk-ZXEAW25V.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  ENGINE_ENV_DENY_LIST,
+  ENGINE_ENV_L0_INFRA_KEYS,
+  ENGINE_ENV_PREFIXES,
+  buildEngineChildEnv,
+  buildOutboundChildEnv
+};

package/dist/error-codes-DHco5-i_.d.cts

@@ -0,0 +1,118 @@
+import { a as AgentEvent, E as EngineCapabilities } from './contract-types-sSlgppBC.cjs';
+
+/** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
+interface ProtocolError {
+    /** 错误码（error-codes.ts 词表 + 其余 engine_* 引擎自报透传）。 */
+    code: string;
+    /** 人类可读详情。 */
+    message: string;
+    /** 恢复指引：指向具体下一步（命令 / 配置路径 / 升级动作），非安慰性文案。 */
+    recovery: string;
+    /** 结构化附参（如 engine_protocol_mismatch 的双方版本）。 */
+    data?: Record<string, unknown>;
+}
+interface RequestFrame {
+    id: number;
+    method: string;
+    params: unknown;
+}
+interface SuccessResponseFrame {
+    id: number | string;
+    result: unknown;
+}
+interface ErrorResponseFrame {
+    id: number | string;
+    error: ProtocolError;
+}
+type ResponseFrame = SuccessResponseFrame | ErrorResponseFrame;
+/** event 通知载荷：runId 关联在途 run；seq 单调递增（基线①结构等价断言对象）。 */
+interface EventNotificationParams {
+    runId: string;
+    seq: number;
+    event: AgentEvent;
+}
+interface NotificationFrame {
+    method: "event";
+    params: EventNotificationParams;
+}
+interface ReverseRequestFrame {
+    id: string;
+    method: string;
+    params: unknown;
+}
+/** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
+type ReverseResponseResult = 
+/** 数据面类：处理确认。 */
+{
+    ok: true;
+}
+/** 人机交互类（askUser/permission）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+type AnyFrame = RequestFrame | ResponseFrame | NotificationFrame | ReverseRequestFrame;
+/** ① 请求：有数字 id + method + params，且无 result/error（与②应答区分）。 */
+declare function isRequestFrame(frame: unknown): frame is RequestFrame;
+/** ② 应答：有 id（number|string）且 result/error 二选一。 */
+declare function isResponseFrame(frame: unknown): frame is ResponseFrame;
+/** ③ 通知：无 id，method === "event"，params 含 runId/seq/event。 */
+declare function isNotificationFrame(frame: unknown): frame is NotificationFrame;
+/** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
+declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
+
+/** 协议核心错误码（引擎 error 帧 + core 同步拦截共用的固定词表）。 */
+declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine_protocol_mismatch", "engine_capability_unsupported", "engine_capability_mismatch", "engine_model_unknown", "engine_model_mismatch", "engine_handshake_timeout", "engine_crashed", "engine_probe_failed"];
+type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
+/** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
+declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
+/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
+declare function isEngineErrorPassthroughCode(value: string): boolean;
+
+/**
+ * 结构化引擎错误（message 恒为 `<code>: <detail>` 前缀格式——AgentOutcome.error 与
+ * 协议 error 帧共用的错误码前缀约定）；recovery 指向恢复动作。
+ * toStructured() 产出即协议 ProtocolError 形态（error 帧载荷直用）。
+ */
+declare class EngineSdkError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly data?: Record<string, unknown>;
+    constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
+    /** 协议 error 帧载荷投影。 */
+    toStructured(): ProtocolError;
+}
+declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
+/**
+ * [v1.x] chat 会话形态的 gate 拒绝具名错误（chat-domain 设计 §3.2 D1-A +
+ * 验收 A6：manifest 无 conversation gate 位的引擎收到 chat 请求 → 同步拒）。
+ * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
+ * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
+ * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * [v1.x] chat 会话形态（run.params.chat / task.conversation=true）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
+ * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
+ * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支
+ * 覆盖同一能力位，协议客户端路径（W3 接线）消费本函数，防两处判据漂移。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+declare const STDOUT_TAIL_ECHO_CHARS = 2000;
+/** engine_timeout 的恢复指引（kill-chain 超时杀链收尾文案）。 */
+declare const ENGINE_TIMEOUT_RECOVERY: string;
+/**
+ * engine_timeout 的 outcome.error 文案：含 stdout 尾部 2000 字 + 恢复指引
+ * （kill-chain synthesizeTimeoutOutcome 消费；与 core errors.ts engineTimeoutDetail 逐字等价）。
+ */
+declare function engineTimeoutDetail(stdoutTail: string): string;
+/** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
+declare function schemaEmulationFailedDetail(error: string, tail: string): string;
+
+export { type AnyFrame as A, ENGINE_ERROR_CODE_PREFIX as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, STDOUT_TAIL_ECHO_CHARS as S, ENGINE_PROTOCOL_ERROR_CODES as a, ENGINE_TIMEOUT_RECOVERY as b, type EngineProtocolErrorCode as c, EngineSdkError as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, type SuccessResponseFrame as j, assertChatConversationSupported as k, engineConversationUnsupportedError as l, engineProtocolMismatchError as m, engineTimeoutDetail as n, isEngineErrorPassthroughCode as o, isEngineProtocolErrorCode as p, isNotificationFrame as q, isRequestFrame as r, isResponseFrame as s, isReverseRequestFrame as t, schemaEmulationFailedDetail as u };

package/dist/error-codes-Dhss2Kmk.d.ts

@@ -0,0 +1,118 @@
+import { a as AgentEvent, E as EngineCapabilities } from './contract-types-sSlgppBC.js';
+
+/** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
+interface ProtocolError {
+    /** 错误码（error-codes.ts 词表 + 其余 engine_* 引擎自报透传）。 */
+    code: string;
+    /** 人类可读详情。 */
+    message: string;
+    /** 恢复指引：指向具体下一步（命令 / 配置路径 / 升级动作），非安慰性文案。 */
+    recovery: string;
+    /** 结构化附参（如 engine_protocol_mismatch 的双方版本）。 */
+    data?: Record<string, unknown>;
+}
+interface RequestFrame {
+    id: number;
+    method: string;
+    params: unknown;
+}
+interface SuccessResponseFrame {
+    id: number | string;
+    result: unknown;
+}
+interface ErrorResponseFrame {
+    id: number | string;
+    error: ProtocolError;
+}
+type ResponseFrame = SuccessResponseFrame | ErrorResponseFrame;
+/** event 通知载荷：runId 关联在途 run；seq 单调递增（基线①结构等价断言对象）。 */
+interface EventNotificationParams {
+    runId: string;
+    seq: number;
+    event: AgentEvent;
+}
+interface NotificationFrame {
+    method: "event";
+    params: EventNotificationParams;
+}
+interface ReverseRequestFrame {
+    id: string;
+    method: string;
+    params: unknown;
+}
+/** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
+type ReverseResponseResult = 
+/** 数据面类：处理确认。 */
+{
+    ok: true;
+}
+/** 人机交互类（askUser/permission）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+type AnyFrame = RequestFrame | ResponseFrame | NotificationFrame | ReverseRequestFrame;
+/** ① 请求：有数字 id + method + params，且无 result/error（与②应答区分）。 */
+declare function isRequestFrame(frame: unknown): frame is RequestFrame;
+/** ② 应答：有 id（number|string）且 result/error 二选一。 */
+declare function isResponseFrame(frame: unknown): frame is ResponseFrame;
+/** ③ 通知：无 id，method === "event"，params 含 runId/seq/event。 */
+declare function isNotificationFrame(frame: unknown): frame is NotificationFrame;
+/** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
+declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
+
+/** 协议核心错误码（引擎 error 帧 + core 同步拦截共用的固定词表）。 */
+declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine_protocol_mismatch", "engine_capability_unsupported", "engine_capability_mismatch", "engine_model_unknown", "engine_model_mismatch", "engine_handshake_timeout", "engine_crashed", "engine_probe_failed"];
+type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
+/** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
+declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
+/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
+declare function isEngineErrorPassthroughCode(value: string): boolean;
+
+/**
+ * 结构化引擎错误（message 恒为 `<code>: <detail>` 前缀格式——AgentOutcome.error 与
+ * 协议 error 帧共用的错误码前缀约定）；recovery 指向恢复动作。
+ * toStructured() 产出即协议 ProtocolError 形态（error 帧载荷直用）。
+ */
+declare class EngineSdkError extends Error {
+    readonly code: string;
+    readonly recovery: string;
+    readonly data?: Record<string, unknown>;
+    constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
+    /** 协议 error 帧载荷投影。 */
+    toStructured(): ProtocolError;
+}
+declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
+/**
+ * [v1.x] chat 会话形态的 gate 拒绝具名错误（chat-domain 设计 §3.2 D1-A +
+ * 验收 A6：manifest 无 conversation gate 位的引擎收到 chat 请求 → 同步拒）。
+ * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
+ * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
+ * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * [v1.x] chat 会话形态（run.params.chat / task.conversation=true）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
+ * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
+ * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支
+ * 覆盖同一能力位，协议客户端路径（W3 接线）消费本函数，防两处判据漂移。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+declare const STDOUT_TAIL_ECHO_CHARS = 2000;
+/** engine_timeout 的恢复指引（kill-chain 超时杀链收尾文案）。 */
+declare const ENGINE_TIMEOUT_RECOVERY: string;
+/**
+ * engine_timeout 的 outcome.error 文案：含 stdout 尾部 2000 字 + 恢复指引
+ * （kill-chain synthesizeTimeoutOutcome 消费；与 core errors.ts engineTimeoutDetail 逐字等价）。
+ */
+declare function engineTimeoutDetail(stdoutTail: string): string;
+/** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
+declare function schemaEmulationFailedDetail(error: string, tail: string): string;
+
+export { type AnyFrame as A, ENGINE_ERROR_CODE_PREFIX as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, STDOUT_TAIL_ECHO_CHARS as S, ENGINE_PROTOCOL_ERROR_CODES as a, ENGINE_TIMEOUT_RECOVERY as b, type EngineProtocolErrorCode as c, EngineSdkError as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, type SuccessResponseFrame as j, assertChatConversationSupported as k, engineConversationUnsupportedError as l, engineProtocolMismatchError as m, engineTimeoutDetail as n, isEngineErrorPassthroughCode as o, isEngineProtocolErrorCode as p, isNotificationFrame as q, isRequestFrame as r, isResponseFrame as s, isReverseRequestFrame as t, schemaEmulationFailedDetail as u };

package/dist/error-message.cjs

@@ -0,0 +1,40 @@
+"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/error-message.ts
+var error_message_exports = {};
+__export(error_message_exports, {
+  toErrorMessage: () => toErrorMessage
+});
+module.exports = __toCommonJS(error_message_exports);
+function toErrorMessage(e) {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null) {
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
+  }
+  return String(e);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  toErrorMessage
+});

package/dist/error-message.d.cts

@@ -0,0 +1,3 @@
+declare function toErrorMessage(e: unknown): string;
+
+export { toErrorMessage };

package/dist/error-message.d.ts

@@ -0,0 +1,3 @@
+declare function toErrorMessage(e: unknown): string;
+
+export { toErrorMessage };

package/dist/error-message.js

@@ -0,0 +1,7 @@
+import {
+  toErrorMessage
+} from "./chunk-PYO3YR7W.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  toErrorMessage
+};