@zhushanwen/subagent-engine-sdk 0.10.1 → 0.11.0

package/dist/env.d.ts

@@ -1,18 +1,9 @@
 /** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_PREFIXES: readonly string[];
-/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。
- *  互引（场景域分化，勿互混）：dev 装配器（apps/electron/scripts/dev-instance-lib.mjs
- *  `LEAK_ENV_KEYS`）仍剥 RELAY_STD* 三键——dev 宿主进程环境防泄漏口径独立于引擎
- *  spawn 面；本清单（引擎侧）已退役同名三键，写入方已清零。 */
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_DENY_LIST: readonly string[];
-/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+/** 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 且无注入引擎侧须显式报错） */
@@ -21,8 +12,6 @@ interface EngineChildEnvOptions {
     engineNode?: string;
     /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
     electronRunAsNode?: boolean;
-    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 TAIJI_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
-    relay?: EngineRelayEnv;
     /**
      * L0：引擎宿主（engine-host）进程的 env 透传通道。**注意它不是子代理身份通道**：
      * 引擎宿主是长驻进程（每窗口一个），而子代理身份（recordId / depth 等）是 per-run 的
@@ -46,9 +35,9 @@ interface EngineChildEnvOptions {
  *
  * 层规格（impl-plan §2.12 三层表）：
  * - L0 基础设施键：TAIJI_AGENT_DATA_DIR / TAIJI_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
- *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / identityEnv（injectL0InfraKeys）；
  * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
- *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ *   （deny 两键 + 凭证键 + 预设回落两键）；
  * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
  *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
  *
@@ -70,7 +59,7 @@ interface BuildOutboundChildEnvOptions {
  * 消费生命周期标志 / WS 令牌。
  *
  * 与 @taiji/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
- * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费方（zsw 宿主 /
  * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
  * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
  * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
@@ -80,4 +69,4 @@ interface BuildOutboundChildEnvOptions {
  */
 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 };
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv };

package/dist/env.js

@@ -4,7 +4,7 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-AF2ETADP.js";
+} from "./chunk-2L3I2TWJ.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {

package/dist/{error-codes-f-UO4a8D.d.cts → error-codes-D_aPibUt.d.cts}

@@ -1,4 +1,4 @@
-import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.cjs';
+import { A as AgentEvent, d as EngineCapabilities } from './contract-types-BUHUMF9R.cjs';
 
 /** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
 interface ProtocolError {
@@ -42,7 +42,7 @@ interface ReverseRequestFrame {
 }
 /** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
 type ReverseResponseResult = 
-/** 数据面类：处理确认。 */
+/** 数据范围类：处理确认。 */
 {
     ok: true;
 }
@@ -63,6 +63,42 @@ declare function isNotificationFrame(frame: unknown): frame is NotificationFrame
 /** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
 declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
 
+/**
+ * 引擎进程侧 spawn/送达窗口错误码（M1/M2 送达回执，设计 D10「engine 侧」）。
+ * 消费方 = pi-subagent-cli（u-m2-engine-ack 接线）：
+ * - prompt_not_delivered：prompt 写入后零 stdout（零输出判定）/ stdin 不可用 / EPIPE——
+ *   任务从未被真实 pi 受理，静默丢失的显式失败形态；
+ * - prompt_rejected：pi 对 prompt 命令回 success:false（已送达但被拒绝）——带 pi 的
+ *   error 文本，与 not_delivered 分型防误诊（D3 不采用合并条目）；
+ * - spawn_handshake_timeout：引擎 spawn 握手窗口超时——runtime/引擎停在
+ *   spawn/handshake 的显式失败（control 侧同类失败码 = engine_open_timeout）。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_CODES: readonly ["engine_prompt_not_delivered", "engine_prompt_rejected", "engine_spawn_handshake_timeout"];
+type EngineSpawnDeliveryErrorCode = (typeof ENGINE_SPAWN_DELIVERY_ERROR_CODES)[number];
+/**
+ * runtime 控制面传输错误码（M3 control 通道，设计 D8/D10「runtime 侧」）。
+ * 消费方 = EngineClient.connectOnce preserve 白名单（u-m3-local：来自
+ * RuntimeEngineTransport 的 EngineSdkError 原样保留 code 与 recovery，不再包装成
+ * engine_crashed——UC-20 的显式失败不被吞掉）。语义（设计 D5/D8）：
+ * - transport_unavailable：control socket connect / hello 失败——托管态 runtime 故障
+ *   显式可见，不静默回退 local spawn；
+ * - transport_lost：control 连接中途丢失（与 engine 自身 crash 区分）——标记不可用、
+ *   fan-out 该连接全部 in-flight，不在同一连接重试；
+ * - open_timeout：engine_open 超时（runtime spawn/归属卡住）；
+ * - frame_too_large：单帧（含 partial-line 缓冲）超 32MB 上限——不截断、按 channel
+ *   归因关闭；
+ * - backpressure_overflow：channel（32MB/4096 帧）或连接聚合（256MB）待写队列溢出——
+ *   不丢帧、不静默，溢出面（channel/connection）标注在 detail。
+ */
+declare const ENGINE_TRANSPORT_ERROR_CODES: readonly ["engine_transport_unavailable", "engine_transport_lost", "engine_open_timeout", "engine_frame_too_large", "engine_backpressure_overflow"];
+type EngineTransportErrorCode = (typeof ENGINE_TRANSPORT_ERROR_CODES)[number];
+/**
+ * 引擎侧 spawn/送达错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。
+ * detail 由消费方拼装（诊断五元组 / pi error 文本），文案只给恢复动作。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: Record<EngineSpawnDeliveryErrorCode, string>;
+/** runtime 控制面传输错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。 */
+declare const ENGINE_TRANSPORT_ERROR_RECOVERY: Record<EngineTransportErrorCode, string>;
 /**
  * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
  * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
@@ -82,7 +118,7 @@ type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
  * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
  * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
  * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
- * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 「core 不解释文案」的纯透传逻辑。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
  * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
  * 不是失败——两值域语义正交。
  */
@@ -92,7 +128,7 @@ declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine
 type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
 /** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
 declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
-/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+/** 其余引擎自报错误码的前缀契约（透传侧；core 不解释文案）。 */
 declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
 declare function isEngineErrorPassthroughCode(value: string): boolean;
 
@@ -106,7 +142,7 @@ declare class EngineSdkError extends Error {
     readonly recovery: string;
     readonly data?: Record<string, unknown>;
     constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
-    /** 协议 error 帧载荷投影。 */
+    /** 协议 error 帧载荷派生视图。 */
     toStructured(): ProtocolError;
 }
 declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
@@ -147,4 +183,4 @@ 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 };
+export { isNotificationFrame as A, isRequestFrame as B, isResponseFrame as C, isReverseRequestFrame as D, EngineSdkError as E, schemaEmulationFailedDetail as F, 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_SPAWN_DELIVERY_ERROR_CODES as c, ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY as d, ENGINE_TIMEOUT_RECOVERY as e, ENGINE_TRANSPORT_ERROR_CODES as f, ENGINE_TRANSPORT_ERROR_RECOVERY as g, type EngineProtocolErrorCode as h, type EngineSpawnDeliveryErrorCode as i, type EngineTransportErrorCode as j, type ErrorResponseFrame as k, type EventNotificationParams as l, type ResponseFrame as m, type ReverseRequestFrame as n, type ReverseResponseResult as o, SET_MODEL_NOT_ACTIVE_CODE as p, STDOUT_TAIL_ECHO_CHARS as q, type SetModelErrorCode as r, type SuccessResponseFrame as s, assertChatConversationSupported as t, engineConversationUnsupportedError as u, engineProtocolMismatchError as v, engineSetModelUnsupportedError as w, engineTimeoutDetail as x, isEngineErrorPassthroughCode as y, isEngineProtocolErrorCode as z };

package/dist/{error-codes-DnFru4L4.d.ts → error-codes-DrNf0gwT.d.ts}

@@ -1,4 +1,4 @@
-import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.js';
+import { A as AgentEvent, d as EngineCapabilities } from './contract-types-BUHUMF9R.js';
 
 /** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
 interface ProtocolError {
@@ -42,7 +42,7 @@ interface ReverseRequestFrame {
 }
 /** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
 type ReverseResponseResult = 
-/** 数据面类：处理确认。 */
+/** 数据范围类：处理确认。 */
 {
     ok: true;
 }
@@ -63,6 +63,42 @@ declare function isNotificationFrame(frame: unknown): frame is NotificationFrame
 /** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
 declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
 
+/**
+ * 引擎进程侧 spawn/送达窗口错误码（M1/M2 送达回执，设计 D10「engine 侧」）。
+ * 消费方 = pi-subagent-cli（u-m2-engine-ack 接线）：
+ * - prompt_not_delivered：prompt 写入后零 stdout（零输出判定）/ stdin 不可用 / EPIPE——
+ *   任务从未被真实 pi 受理，静默丢失的显式失败形态；
+ * - prompt_rejected：pi 对 prompt 命令回 success:false（已送达但被拒绝）——带 pi 的
+ *   error 文本，与 not_delivered 分型防误诊（D3 不采用合并条目）；
+ * - spawn_handshake_timeout：引擎 spawn 握手窗口超时——runtime/引擎停在
+ *   spawn/handshake 的显式失败（control 侧同类失败码 = engine_open_timeout）。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_CODES: readonly ["engine_prompt_not_delivered", "engine_prompt_rejected", "engine_spawn_handshake_timeout"];
+type EngineSpawnDeliveryErrorCode = (typeof ENGINE_SPAWN_DELIVERY_ERROR_CODES)[number];
+/**
+ * runtime 控制面传输错误码（M3 control 通道，设计 D8/D10「runtime 侧」）。
+ * 消费方 = EngineClient.connectOnce preserve 白名单（u-m3-local：来自
+ * RuntimeEngineTransport 的 EngineSdkError 原样保留 code 与 recovery，不再包装成
+ * engine_crashed——UC-20 的显式失败不被吞掉）。语义（设计 D5/D8）：
+ * - transport_unavailable：control socket connect / hello 失败——托管态 runtime 故障
+ *   显式可见，不静默回退 local spawn；
+ * - transport_lost：control 连接中途丢失（与 engine 自身 crash 区分）——标记不可用、
+ *   fan-out 该连接全部 in-flight，不在同一连接重试；
+ * - open_timeout：engine_open 超时（runtime spawn/归属卡住）；
+ * - frame_too_large：单帧（含 partial-line 缓冲）超 32MB 上限——不截断、按 channel
+ *   归因关闭；
+ * - backpressure_overflow：channel（32MB/4096 帧）或连接聚合（256MB）待写队列溢出——
+ *   不丢帧、不静默，溢出面（channel/connection）标注在 detail。
+ */
+declare const ENGINE_TRANSPORT_ERROR_CODES: readonly ["engine_transport_unavailable", "engine_transport_lost", "engine_open_timeout", "engine_frame_too_large", "engine_backpressure_overflow"];
+type EngineTransportErrorCode = (typeof ENGINE_TRANSPORT_ERROR_CODES)[number];
+/**
+ * 引擎侧 spawn/送达错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。
+ * detail 由消费方拼装（诊断五元组 / pi error 文本），文案只给恢复动作。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: Record<EngineSpawnDeliveryErrorCode, string>;
+/** runtime 控制面传输错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。 */
+declare const ENGINE_TRANSPORT_ERROR_RECOVERY: Record<EngineTransportErrorCode, string>;
 /**
  * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
  * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
@@ -82,7 +118,7 @@ type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
  * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
  * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
  * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
- * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 「core 不解释文案」的纯透传逻辑。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
  * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
  * 不是失败——两值域语义正交。
  */
@@ -92,7 +128,7 @@ declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine
 type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
 /** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
 declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
-/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+/** 其余引擎自报错误码的前缀契约（透传侧；core 不解释文案）。 */
 declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
 declare function isEngineErrorPassthroughCode(value: string): boolean;
 
@@ -106,7 +142,7 @@ declare class EngineSdkError extends Error {
     readonly recovery: string;
     readonly data?: Record<string, unknown>;
     constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
-    /** 协议 error 帧载荷投影。 */
+    /** 协议 error 帧载荷派生视图。 */
     toStructured(): ProtocolError;
 }
 declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
@@ -147,4 +183,4 @@ 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 };
+export { isNotificationFrame as A, isRequestFrame as B, isResponseFrame as C, isReverseRequestFrame as D, EngineSdkError as E, schemaEmulationFailedDetail as F, 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_SPAWN_DELIVERY_ERROR_CODES as c, ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY as d, ENGINE_TIMEOUT_RECOVERY as e, ENGINE_TRANSPORT_ERROR_CODES as f, ENGINE_TRANSPORT_ERROR_RECOVERY as g, type EngineProtocolErrorCode as h, type EngineSpawnDeliveryErrorCode as i, type EngineTransportErrorCode as j, type ErrorResponseFrame as k, type EventNotificationParams as l, type ResponseFrame as m, type ReverseRequestFrame as n, type ReverseResponseResult as o, SET_MODEL_NOT_ACTIVE_CODE as p, STDOUT_TAIL_ECHO_CHARS as q, type SetModelErrorCode as r, type SuccessResponseFrame as s, assertChatConversationSupported as t, engineConversationUnsupportedError as u, engineProtocolMismatchError as v, engineSetModelUnsupportedError as w, engineTimeoutDetail as x, isEngineErrorPassthroughCode as y, isEngineProtocolErrorCode as z };