@zhushanwen/subagent-engine-sdk 0.8.0 → 0.10.0

package/dist/{chunk-F7VDVSBZ.js → chunk-CNCFMPEH.js}

@@ -3,7 +3,7 @@ import {
 } from "./chunk-PYO3YR7W.js";
 import {
   engineTimeoutDetail
-} from "./chunk-SFNTX7Q3.js";
+} from "./chunk-JZN76I3S.js";
 import {
   getLogger
 } from "./chunk-NXNNXGTY.js";

package/dist/{chunk-MQPASWMA.js → chunk-HSNDUHFH.js}

@@ -1,7 +1,7 @@
 import {
   killChain,
   safeKill
-} from "./chunk-F7VDVSBZ.js";
+} from "./chunk-CNCFMPEH.js";
 import {
   getLogger
 } from "./chunk-NXNNXGTY.js";

package/dist/{chunk-SFNTX7Q3.js → chunk-JZN76I3S.js}

@@ -7,18 +7,24 @@ function isProtocolVersionCompatible(version) {
 var REVERSE_REQUEST_TIMEOUT_MS = 1e4;
 var HANDSHAKE_TIMEOUT_MS = 1e4;
 var CANCEL_SETTLE_GRACE_MS = 3e3;
-var CRASH_REBUILD_MAX_ATTEMPTS = 3;
-var CRASH_REBUILD_BACKOFF_STEP_1_MS = 1e3;
-var CRASH_REBUILD_BACKOFF_STEP_2_MS = 2e3;
-var CRASH_REBUILD_BACKOFF_STEP_3_MS = 4e3;
-var CRASH_REBUILD_BACKOFF_MS = [
-  CRASH_REBUILD_BACKOFF_STEP_1_MS,
-  CRASH_REBUILD_BACKOFF_STEP_2_MS,
-  CRASH_REBUILD_BACKOFF_STEP_3_MS
-];
+var SET_MODEL_STAGE_TIMEOUT_MS = 3e3;
+var SET_MODEL_REQUEST_TIMEOUT_MS = 1e4;
 var STDERR_TAIL_CHARS = 400;
 
 // src/protocol/error-codes.ts
+var SET_MODEL_ERROR_CODES = [
+  /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
+   *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
+  "engine_model_not_in_snapshot",
+  /** 凭据校验失败（子进程 set_model checkAuth 抛错——宿主预检通过后 registry 态漂移
+   *  的权威兜底；宿主按校验型失败处置，设计 §7.5 凭据行）。 */
+  "engine_credential_missing",
+  /** 命令已发出（set_model 可能已执行）但读应答 / get_state 回读无回执、生效值未知
+   *  （非进程退出情形——退出归无活进程路径；宿主按「写覆盖意图 + 错误应答」处置，
+   *  设计 §7.5 回读失败行）。 */
+  "engine_state_readback_failed"
+];
+var SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
 var ENGINE_PROTOCOL_ERROR_CODES = [
   "engine_not_found",
   "engine_protocol_mismatch",
@@ -28,7 +34,9 @@ var ENGINE_PROTOCOL_ERROR_CODES = [
   "engine_model_mismatch",
   "engine_handshake_timeout",
   "engine_crashed",
-  "engine_probe_failed"
+  "engine_probe_failed",
+  ...SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE
 ];
 function isEngineProtocolErrorCode(value) {
   return typeof value === "string" && ENGINE_PROTOCOL_ERROR_CODES.includes(value);
@@ -78,6 +86,14 @@ function assertChatConversationSupported(engineId, capabilities) {
     throw engineConversationUnsupportedError(engineId);
   }
 }
+function engineSetModelUnsupportedError(engineId, declared) {
+  return new EngineSdkError(
+    "engine_capability_unsupported",
+    `engine '${engineId}' does not support hot model switching (capabilities.setModel = ${declared ?? "unsupported (undeclared)"}); the host pre-check (design \xA77.2 step 2) must not dispatch setModel to it`,
+    `Route the switch to an engine that declares capabilities.setModel = 'native', or record the override for the next run instead. If this engine actually supports hot switching, fix the manifest capabilities declaration.`,
+    { engineId, capability: "setModel", declared: declared ?? "unsupported" }
+  );
+}
 var DETAIL_ECHO_MAX_CHARS = 200;
 var STDOUT_TAIL_ECHO_CHARS = 2e3;
 function truncate(text, max) {
@@ -98,9 +114,11 @@ export {
   REVERSE_REQUEST_TIMEOUT_MS,
   HANDSHAKE_TIMEOUT_MS,
   CANCEL_SETTLE_GRACE_MS,
-  CRASH_REBUILD_MAX_ATTEMPTS,
-  CRASH_REBUILD_BACKOFF_MS,
+  SET_MODEL_STAGE_TIMEOUT_MS,
+  SET_MODEL_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
+  SET_MODEL_ERROR_CODES,
+  SET_MODEL_NOT_ACTIVE_CODE,
   ENGINE_PROTOCOL_ERROR_CODES,
   isEngineProtocolErrorCode,
   ENGINE_ERROR_CODE_PREFIX,
@@ -109,6 +127,7 @@ export {
   engineProtocolMismatchError,
   engineConversationUnsupportedError,
   assertChatConversationSupported,
+  engineSetModelUnsupportedError,
   STDOUT_TAIL_ECHO_CHARS,
   ENGINE_TIMEOUT_RECOVERY,
   engineTimeoutDetail,

package/dist/{chunk-DIIYVO4O.js → chunk-LM7P7OTA.js}

@@ -8,7 +8,8 @@ var PROTOCOL_METHODS = [
   "listModels",
   "validateModel",
   "dispose",
-  "ping"
+  "ping",
+  "setModel"
 ];
 
 // src/protocol/reverse-channels.ts

package/dist/{chunk-3WC36CHI.js → chunk-NTOLHLCL.js}

@@ -1,6 +1,6 @@
 import {
   EngineSdkError
-} from "./chunk-SFNTX7Q3.js";
+} from "./chunk-JZN76I3S.js";
 
 // src/node-executor.ts
 import { spawn } from "child_process";

package/dist/{contract-types-DqOD58r-.d.cts → contract-types-jSa1g28F.d.cts}

@@ -194,6 +194,25 @@ interface SessionView {
     usage?: AgentUsageTotal;
     source: "native" | "journal" | "outcome-only";
 }
+/**
+ * 模型 ref（provider + modelId 二元组）——setModel 正向方法请求/应答与宿主侧
+ * 用户覆盖记账共用的模型指向形状（设计 subagent-model-switch §6.2/§7.3）。
+ *
+ * 刻意用结构化对象而非现役 wire 的字符串 canonical ref（`ctx.model` = "provider/id"）：
+ * 切换操作的原生输入面就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
+ * runtime `model.switch` 均平铺 provider/modelId），字符串拼接形态会在协议两侧各做一次
+ * 拆/拼（拆分规则 = provider 含 '/' 时无法无歧义反转），结构化形状让拆装只发生在宿主
+ * 编排层单点（U2 组帧时拼 canonical ref、读回执时拆 ref）。
+ *
+ * 消费方：u-foundation 定形 → U2（宿主编排组帧）/ U3（引擎实现读帧）/ U5（聚合应答
+ * effectiveModel）/ U1（前端 wire 应答）按本形状传递，禁止各写一份等价形状。
+ */
+interface ModelRef {
+    /** 模型 provider id（前端 ProviderId 词表，如 "zai-coding-cn"）。 */
+    provider: string;
+    /** provider 内的模型 id（如 "glm-5.3-flash"）。 */
+    modelId: string;
+}
 /**
  * 引擎进程形态（manifest `taiji.subagentEngine.processModel` 声明字面量；设计
  * pi-workflow-run-resource-model §3.3 决策 3）。语义：
@@ -208,7 +227,7 @@ interface SessionView {
  */
 type EngineProcessModel = "per-window" | "shared-service";
 /**
- * 引擎能力声明（11 位）。三级：native / emulated / unsupported。
+ * 引擎能力声明（11 必填位 + 1 可选位 setModel）。三级：native / emulated / unsupported。
  * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
  * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
  * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约面，不在本
@@ -245,6 +264,22 @@ interface EngineCapabilities {
     permissionMode: "native" | "fixed" | "ignored";
     /** maxTurns 轮数上限执行能力位（pi=true / zcode=false）。 */
     maxTurns: boolean;
+    /**
+     * [ADR-0071 判据 7 消费点/载体登记——能力位演进先例 steer 之后的第二登记条目]
+     * 执行中模型热切换位（设计 subagent-model-switch §7.3）。
+     *
+     * - **wire 载体**：capabilities manifest 位声明；配套执行通道 = setModel 正向方法
+     *   （methods.ts，与 steer「声明 unsupported、无独立执行通道」的缺失登记不同——
+     *   本位声明与执行通道同批进协议，宿主不发 unsupported 引擎的调用）。
+     * - **消费点**：宿主编排的发送前预检（设计 §7.2 步骤②）——位非 'native' 时宿主
+     *   不发 setModel 方法调用，转覆盖记账路径 + 提示性应答（避免把
+     *   engine_protocol_unknown_method 原样抛给用户）。
+     * - **缺省最弱档**：可选键，undefined 与 'unsupported' 同义（旧 manifest 未声明 =
+     *   不可热切；additive 演进——旧引擎忽略未知键，宿主预检不放行即零行为差）。
+     * - **值域无 emulated**：热切换无宿主侧仿真形态（覆盖记账本身引擎无关、不属本位
+     *   语义），只有「引擎内即时生效（native）/ 不支持（unsupported）」两态。
+     */
+    setModel?: "native" | "unsupported";
 }
 /** 引擎探针报告（probe 应答）。ok=false 时 error 必填（恢复指引）。 */
 interface ProbeReport {
@@ -429,4 +464,4 @@ interface AgentCallOpts {
     permissionMode?: string;
 }
 
-export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelCatalogEntry as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, AGENT_EVENT_TYPE_NAMES as f, type AgentEventTypeName as g, type AgentFailureKind as h, type AgentOutcomeUsage as i, type AgentUsage as j, type AssertMutuallyAssignable as k, type EngineProcessModel as l, type ToolCall as m, type ToolCallEntry as n, type ToolCallResult as o };
+export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, type ModelCatalogEntry as f, AGENT_EVENT_TYPE_NAMES as g, type AgentEventTypeName as h, type AgentFailureKind as i, type AgentOutcomeUsage as j, type AgentUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type ToolCall as n, type ToolCallEntry as o, type ToolCallResult as p };

package/dist/{contract-types-DqOD58r-.d.ts → contract-types-jSa1g28F.d.ts}

@@ -194,6 +194,25 @@ interface SessionView {
     usage?: AgentUsageTotal;
     source: "native" | "journal" | "outcome-only";
 }
+/**
+ * 模型 ref（provider + modelId 二元组）——setModel 正向方法请求/应答与宿主侧
+ * 用户覆盖记账共用的模型指向形状（设计 subagent-model-switch §6.2/§7.3）。
+ *
+ * 刻意用结构化对象而非现役 wire 的字符串 canonical ref（`ctx.model` = "provider/id"）：
+ * 切换操作的原生输入面就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
+ * runtime `model.switch` 均平铺 provider/modelId），字符串拼接形态会在协议两侧各做一次
+ * 拆/拼（拆分规则 = provider 含 '/' 时无法无歧义反转），结构化形状让拆装只发生在宿主
+ * 编排层单点（U2 组帧时拼 canonical ref、读回执时拆 ref）。
+ *
+ * 消费方：u-foundation 定形 → U2（宿主编排组帧）/ U3（引擎实现读帧）/ U5（聚合应答
+ * effectiveModel）/ U1（前端 wire 应答）按本形状传递，禁止各写一份等价形状。
+ */
+interface ModelRef {
+    /** 模型 provider id（前端 ProviderId 词表，如 "zai-coding-cn"）。 */
+    provider: string;
+    /** provider 内的模型 id（如 "glm-5.3-flash"）。 */
+    modelId: string;
+}
 /**
  * 引擎进程形态（manifest `taiji.subagentEngine.processModel` 声明字面量；设计
  * pi-workflow-run-resource-model §3.3 决策 3）。语义：
@@ -208,7 +227,7 @@ interface SessionView {
  */
 type EngineProcessModel = "per-window" | "shared-service";
 /**
- * 引擎能力声明（11 位）。三级：native / emulated / unsupported。
+ * 引擎能力声明（11 必填位 + 1 可选位 setModel）。三级：native / emulated / unsupported。
  * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
  * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
  * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约面，不在本
@@ -245,6 +264,22 @@ interface EngineCapabilities {
     permissionMode: "native" | "fixed" | "ignored";
     /** maxTurns 轮数上限执行能力位（pi=true / zcode=false）。 */
     maxTurns: boolean;
+    /**
+     * [ADR-0071 判据 7 消费点/载体登记——能力位演进先例 steer 之后的第二登记条目]
+     * 执行中模型热切换位（设计 subagent-model-switch §7.3）。
+     *
+     * - **wire 载体**：capabilities manifest 位声明；配套执行通道 = setModel 正向方法
+     *   （methods.ts，与 steer「声明 unsupported、无独立执行通道」的缺失登记不同——
+     *   本位声明与执行通道同批进协议，宿主不发 unsupported 引擎的调用）。
+     * - **消费点**：宿主编排的发送前预检（设计 §7.2 步骤②）——位非 'native' 时宿主
+     *   不发 setModel 方法调用，转覆盖记账路径 + 提示性应答（避免把
+     *   engine_protocol_unknown_method 原样抛给用户）。
+     * - **缺省最弱档**：可选键，undefined 与 'unsupported' 同义（旧 manifest 未声明 =
+     *   不可热切；additive 演进——旧引擎忽略未知键，宿主预检不放行即零行为差）。
+     * - **值域无 emulated**：热切换无宿主侧仿真形态（覆盖记账本身引擎无关、不属本位
+     *   语义），只有「引擎内即时生效（native）/ 不支持（unsupported）」两态。
+     */
+    setModel?: "native" | "unsupported";
 }
 /** 引擎探针报告（probe 应答）。ok=false 时 error 必填（恢复指引）。 */
 interface ProbeReport {
@@ -429,4 +464,4 @@ interface AgentCallOpts {
     permissionMode?: string;
 }
 
-export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelCatalogEntry as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, AGENT_EVENT_TYPE_NAMES as f, type AgentEventTypeName as g, type AgentFailureKind as h, type AgentOutcomeUsage as i, type AgentUsage as j, type AssertMutuallyAssignable as k, type EngineProcessModel as l, type ToolCall as m, type ToolCallEntry as n, type ToolCallResult as o };
+export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, type ModelCatalogEntry as f, AGENT_EVENT_TYPE_NAMES as g, type AgentEventTypeName as h, type AgentFailureKind as i, type AgentOutcomeUsage as j, type AgentUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type ToolCall as n, type ToolCallEntry as o, type ToolCallResult as p };

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

@@ -0,0 +1,150 @@
+import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.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）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现或宿主未知的通道（宽容语义③：由 askUser 语境泛化到全通道——宿主对未知 host/* 通道回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+/** ① 请求：有数字 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;
+
+/**
+ * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
+ * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
+ *
+ * 三型定名经 ADR-0071 评审（u-foundation 实施期裁决）：统一 engine_ 前缀——
+ * 协议 error 帧的 code 词法约束是 ^engine_（schema.ts protocolErrorSchema pattern，
+ * 全部引擎应答错误共用），且现役词表 9 码全部 engine_ 前缀（error-codes.ts 头注
+ * 「对齐现役错误码词表风格」）；设计文档 §7.3 的第一型字面名 model_not_in_snapshot
+ * 不满足 pattern，按约束加前缀定名 engine_model_not_in_snapshot。第三型采纳设计
+ * 候选名 engine_state_readback_failed。
+ */
+declare const SET_MODEL_ERROR_CODES: readonly ["engine_model_not_in_snapshot", "engine_credential_missing", "engine_state_readback_failed"];
+/** setModel 错误分型值域（聚合失败名单 reason 字段的类型源；词表扩位时同步跟随）。 */
+type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
+/**
+ * setModel「无活进程」应答码（设计 §7.3/§7.5：定位时 / 命令写入 / 读应答 / 回读
+ * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
+ * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
+ * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
+ * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
+ * 不是失败——两值域语义正交。
+ */
+declare const SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
+/** 协议核心错误码（引擎 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", "engine_model_not_in_snapshot", "engine_credential_missing", "engine_state_readback_failed", "engine_run_not_active"];
+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;
+/**
+ * 引擎 conversation 位拒绝的具名错误（[modeless 波2] 语义：无 resume 续聊通道的
+ * 引擎，message 续聊资格被拒——manifest conversation 能力轴消费；[modeless 波5
+ * 收尾] core capability-gate 的显式参数分支随派发参数删除退役，本构造器消费方 =
+ * 引擎侧 resume gate（assertChatConversationSupported）与 message 资格门）。
+ * 文案契约：错误码 engine_capability_unsupported + 「换引擎续聊 / 修 manifest /
+ * 升级引擎包」恢复指引，两侧一致防漂移。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * resume 会话形态（run.params.resume——唯一会话形态键）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError
+ * ——进程/record 创建前同步拒（A6 方向防御：manifest/实装漂移时引擎侧自拒，
+ * 与 core capability-gate 同一能力位，防两侧判据漂移）。[modeless 波2] 协议
+ * task 的 conversation 键已删，本 gate 只对 resume 形态键生效。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/**
+ * 引擎 setModel 能力位负向的具名错误（A6 方向防御同族——对照
+ * engineConversationUnsupportedError 先例）：引擎 server 收到 setModel 请求但本引擎
+ * capabilities.setModel 非 'native'（含缺省 undefined = unsupported）时同步拒。
+ * 宿主侧发送前预检（§7.2 步骤②）正常不会发出该调用——本错误是 manifest/实装漂移
+ * 时引擎侧的自拒兜底，契约行为 = 结构化错误帧而非崩溃。
+ */
+declare function engineSetModelUnsupportedError(engineId: string, declared: EngineCapabilities["setModel"]): EngineSdkError;
+/** 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 { EngineSdkError as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_TIMEOUT_RECOVERY as c, type EngineProtocolErrorCode as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, SET_MODEL_NOT_ACTIVE_CODE as j, STDOUT_TAIL_ECHO_CHARS as k, type SetModelErrorCode as l, type SuccessResponseFrame as m, assertChatConversationSupported as n, engineConversationUnsupportedError as o, engineProtocolMismatchError as p, engineSetModelUnsupportedError as q, engineTimeoutDetail as r, isEngineErrorPassthroughCode as s, isEngineProtocolErrorCode as t, isNotificationFrame as u, isRequestFrame as v, isResponseFrame as w, isReverseRequestFrame as x, schemaEmulationFailedDetail as y };

package/dist/error-codes-f-UO4a8D.d.cts

@@ -0,0 +1,150 @@
+import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.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）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+ | {
+    ack: true;
+}
+/** 未实现或宿主未知的通道（宽容语义③：由 askUser 语境泛化到全通道——宿主对未知 host/* 通道回 unsupported，引擎自行降级）。 */
+ | {
+    unsupported: true;
+};
+/** ① 请求：有数字 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;
+
+/**
+ * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
+ * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
+ *
+ * 三型定名经 ADR-0071 评审（u-foundation 实施期裁决）：统一 engine_ 前缀——
+ * 协议 error 帧的 code 词法约束是 ^engine_（schema.ts protocolErrorSchema pattern，
+ * 全部引擎应答错误共用），且现役词表 9 码全部 engine_ 前缀（error-codes.ts 头注
+ * 「对齐现役错误码词表风格」）；设计文档 §7.3 的第一型字面名 model_not_in_snapshot
+ * 不满足 pattern，按约束加前缀定名 engine_model_not_in_snapshot。第三型采纳设计
+ * 候选名 engine_state_readback_failed。
+ */
+declare const SET_MODEL_ERROR_CODES: readonly ["engine_model_not_in_snapshot", "engine_credential_missing", "engine_state_readback_failed"];
+/** setModel 错误分型值域（聚合失败名单 reason 字段的类型源；词表扩位时同步跟随）。 */
+type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
+/**
+ * setModel「无活进程」应答码（设计 §7.3/§7.5：定位时 / 命令写入 / 读应答 / 回读
+ * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
+ * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
+ * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
+ * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
+ * 不是失败——两值域语义正交。
+ */
+declare const SET_MODEL_NOT_ACTIVE_CODE = "engine_run_not_active";
+/** 协议核心错误码（引擎 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", "engine_model_not_in_snapshot", "engine_credential_missing", "engine_state_readback_failed", "engine_run_not_active"];
+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;
+/**
+ * 引擎 conversation 位拒绝的具名错误（[modeless 波2] 语义：无 resume 续聊通道的
+ * 引擎，message 续聊资格被拒——manifest conversation 能力轴消费；[modeless 波5
+ * 收尾] core capability-gate 的显式参数分支随派发参数删除退役，本构造器消费方 =
+ * 引擎侧 resume gate（assertChatConversationSupported）与 message 资格门）。
+ * 文案契约：错误码 engine_capability_unsupported + 「换引擎续聊 / 修 manifest /
+ * 升级引擎包」恢复指引，两侧一致防漂移。
+ */
+declare function engineConversationUnsupportedError(engineId: string): EngineSdkError;
+/**
+ * resume 会话形态（run.params.resume——唯一会话形态键）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError
+ * ——进程/record 创建前同步拒（A6 方向防御：manifest/实装漂移时引擎侧自拒，
+ * 与 core capability-gate 同一能力位，防两侧判据漂移）。[modeless 波2] 协议
+ * task 的 conversation 键已删，本 gate 只对 resume 形态键生效。
+ */
+declare function assertChatConversationSupported(engineId: string, capabilities: Pick<EngineCapabilities, "conversation">): void;
+/**
+ * 引擎 setModel 能力位负向的具名错误（A6 方向防御同族——对照
+ * engineConversationUnsupportedError 先例）：引擎 server 收到 setModel 请求但本引擎
+ * capabilities.setModel 非 'native'（含缺省 undefined = unsupported）时同步拒。
+ * 宿主侧发送前预检（§7.2 步骤②）正常不会发出该调用——本错误是 manifest/实装漂移
+ * 时引擎侧的自拒兜底，契约行为 = 结构化错误帧而非崩溃。
+ */
+declare function engineSetModelUnsupportedError(engineId: string, declared: EngineCapabilities["setModel"]): EngineSdkError;
+/** 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 { EngineSdkError as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_TIMEOUT_RECOVERY as c, type EngineProtocolErrorCode as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, SET_MODEL_NOT_ACTIVE_CODE as j, STDOUT_TAIL_ECHO_CHARS as k, type SetModelErrorCode as l, type SuccessResponseFrame as m, assertChatConversationSupported as n, engineConversationUnsupportedError as o, engineProtocolMismatchError as p, engineSetModelUnsupportedError as q, engineTimeoutDetail as r, isEngineErrorPassthroughCode as s, isEngineProtocolErrorCode as t, isNotificationFrame as u, isRequestFrame as v, isResponseFrame as w, isReverseRequestFrame as x, schemaEmulationFailedDetail as y };