@zhushanwen/subagent-engine-sdk 0.10.0 → 0.11.0

package/dist/port-contract.d.cts

@@ -1,8 +1,8 @@
-import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.cjs';
-import { S as SetModelParams, a as SetModelResult } from './methods-BLxg4ZFr.cjs';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-BUHUMF9R.cjs';
+import { S as SetModelParams, a as SetModelResult } from './methods-CHiDwvRK.cjs';
 
 /**
- * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
+ * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎侧子集 + 协议 ctx 还原字段（model/
  * cwd——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
  * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
  */
@@ -12,7 +12,7 @@ type EngineAgentCallOpts = AgentCallOpts & {
 };
 /**
  * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
- * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
+ * 消费，name/reasoning 等字段透传保留防测试/未来消费方漂移）。
  */
 interface EngineCtxModel {
     id: string;
@@ -30,11 +30,11 @@ interface EngineStream {
  * journal 固定分组 key（值锚定，**只承载、不透传**）：journal 落盘路径
  * `<dataDir>/engines/<engineId>/<本值>/journal-<taskId>.jsonl` 的第二段，两引擎恒
  * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
- * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
+ * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议范围（RunContext/run.params.ctx/
  * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
  * 三类消费：① journal 落盘路径构造（core event-journal-wiring）；② 存量 record 兼容
  * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
- * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
+ * record-store 读侧检查要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
  * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
  */
 declare const SHARED_POOL_KEY = "shared";
@@ -47,7 +47,7 @@ interface RunContext {
     stream?: EngineStream;
     /**
      * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
-     * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+     * engine_open 归属键的权威来源。additive 可选：宿主缺省不传。
      */
     sessionRootId?: string;
     /**
@@ -75,7 +75,7 @@ interface RunContext {
         mode?: string;
     };
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
-    /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
+    /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议范围）。 */
     onChildSpawned?: (child: {
         pid: number | undefined;
         killed: boolean;
@@ -127,7 +127,7 @@ interface EnginePort {
         canonicalRef: string;
     };
     /**
-     * [subagent-model-switch §7.3] 可选面：执行中模型热切换（协议 setModel 正向方法的
+     * [subagent-model-switch §7.3] 可选能力：执行中模型热切换（协议 setModel 正向方法的
      * 进程内承载）。实现引擎须 capabilities.setModel = 'native' 同批声明（位与方法
      * 成对进出——capabilities 注释的消费点登记）；server 分发行在位非 native 时回
      * engineSetModelUnsupportedError 结构化错误（契约行为 = 明确错误而非崩）。

package/dist/port-contract.d.ts

@@ -1,8 +1,8 @@
-import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.js';
-import { S as SetModelParams, a as SetModelResult } from './methods-C2zvZqhP.js';
+import { b as AgentCallOpts, E as EngineHandleData, d as EngineCapabilities, P as ProbeReport, A as AgentEvent, e as ResumeAnchor, c as AgentOutcome, S as SessionView } from './contract-types-BUHUMF9R.js';
+import { S as SetModelParams, a as SetModelResult } from './methods-BdIH3FwS.js';
 
 /**
- * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
+ * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎侧子集 + 协议 ctx 还原字段（model/
  * cwd——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
  * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
  */
@@ -12,7 +12,7 @@ type EngineAgentCallOpts = AgentCallOpts & {
 };
 /**
  * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
- * 消费，name/reasoning 等字段透传保留防测试/未来消费面漂移）。
+ * 消费，name/reasoning 等字段透传保留防测试/未来消费方漂移）。
  */
 interface EngineCtxModel {
     id: string;
@@ -30,11 +30,11 @@ interface EngineStream {
  * journal 固定分组 key（值锚定，**只承载、不透传**）：journal 落盘路径
  * `<dataDir>/engines/<engineId>/<本值>/journal-<taskId>.jsonl` 的第二段，两引擎恒
  * 本值（pi / zcode 均无池化实现——pi = PI_CODING_AGENT_DIR 全局一份，zcode = 共享
- * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议面（RunContext/run.params.ctx/
+ * 宿主 HOME）。[池抽象降级 2026-09-13] poolKey 协议范围（RunContext/run.params.ctx/
  * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
  * 三类消费：① journal 落盘路径构造（core event-journal-wiring）；② 存量 record 兼容
  * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
- * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
+ * record-store 读侧检查要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
  * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
  */
 declare const SHARED_POOL_KEY = "shared";
@@ -47,7 +47,7 @@ interface RunContext {
     stream?: EngineStream;
     /**
      * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
-     * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+     * engine_open 归属键的权威来源。additive 可选：宿主缺省不传。
      */
     sessionRootId?: string;
     /**
@@ -75,7 +75,7 @@ interface RunContext {
         mode?: string;
     };
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
-    /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
+    /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议范围）。 */
     onChildSpawned?: (child: {
         pid: number | undefined;
         killed: boolean;
@@ -127,7 +127,7 @@ interface EnginePort {
         canonicalRef: string;
     };
     /**
-     * [subagent-model-switch §7.3] 可选面：执行中模型热切换（协议 setModel 正向方法的
+     * [subagent-model-switch §7.3] 可选能力：执行中模型热切换（协议 setModel 正向方法的
      * 进程内承载）。实现引擎须 capabilities.setModel = 'native' 同批声明（位与方法
      * 成对进出——capabilities 注释的消费点登记）；server 分发行在位非 native 时回
      * engineSetModelUnsupportedError 结构化错误（契约行为 = 明确错误而非崩）。

package/dist/protocol/index.cjs

@@ -26,7 +26,11 @@ __export(protocol_exports, {
   ENGINE_PROTOCOL_ERROR_CODES: () => ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS: () => ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION: () => ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES: () => ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: () => ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY: () => ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES: () => ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY: () => ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError: () => EngineSdkError,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: () => FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS: () => HANDSHAKE_TIMEOUT_MS,
@@ -40,6 +44,9 @@ __export(protocol_exports, {
   SET_MODEL_STAGE_TIMEOUT_MS: () => SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS: () => SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS: () => SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION: () => SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUPPORTED_PROTOCOL_RANGE: () => SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported: () => assertChatConversationSupported,
   engineConversationUnsupportedError: () => engineConversationUnsupportedError,
@@ -54,6 +61,8 @@ __export(protocol_exports, {
   isRequestFrame: () => isRequestFrame,
   isResponseFrame: () => isResponseFrame,
   isReverseRequestFrame: () => isReverseRequestFrame,
+  isSubagentControlClosedReason: () => isSubagentControlClosedReason,
+  isSubagentControlFrameKind: () => isSubagentControlFrameKind,
   notificationFrameSchema: () => notificationFrameSchema,
   protocolErrorSchema: () => protocolErrorSchema,
   requestFrameSchema: () => requestFrameSchema,
@@ -132,6 +141,30 @@ var REVERSE_CHANNEL_TIMEOUT_CLASS = {
 };
 
 // src/protocol/error-codes.ts
+var ENGINE_SPAWN_DELIVERY_ERROR_CODES = [
+  "engine_prompt_not_delivered",
+  "engine_prompt_rejected",
+  "engine_spawn_handshake_timeout"
+];
+var ENGINE_TRANSPORT_ERROR_CODES = [
+  "engine_transport_unavailable",
+  "engine_transport_lost",
+  "engine_open_timeout",
+  "engine_frame_too_large",
+  "engine_backpressure_overflow"
+];
+var ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY = {
+  engine_prompt_not_delivered: "The task never reached the child pi (zero stdout after the prompt write, or the engine stdin was unavailable). Re-run the task; if it recurs, inspect the engine/pi logs (the failure carries the delivery diagnostics) and the runtime log.",
+  engine_prompt_rejected: "The child pi explicitly rejected the prompt command (success:false). Check the pi-side reason carried in the error detail (busy/queue/extension takeover states are reported by pi itself), then re-run.",
+  engine_spawn_handshake_timeout: "The engine spawn handshake did not complete in time. Check the runtime log for a spawn/handshake stall, then restart taiji and re-run the task."
+};
+var ENGINE_TRANSPORT_ERROR_RECOVERY = {
+  engine_transport_unavailable: "The runtime control socket is unreachable (connect or hello failed). The runtime side is failing explicitly instead of silently falling back to local spawn \u2014 restart taiji and re-run the task.",
+  engine_transport_lost: "The control connection to the runtime was lost mid-flight (runtime restart or crash). In-flight requests were rejected; restart taiji (or wait for the runtime to come back) and re-run the task \u2014 the connection is not retried in place.",
+  engine_open_timeout: "The runtime did not finish opening the engine channel in time (spawn/attribution stalled). Check the runtime log (engine opened / kill decision lines), then re-run the task.",
+  engine_frame_too_large: "A single frame exceeded the control-plane size limit and the channel was closed without truncation. Shrink the task/result payload (e.g. point the agent at files instead of inlining them) and re-run.",
+  engine_backpressure_overflow: "The control-plane write queue overflowed (engine consumed frames too slowly) and the overflowed scope was torn down without dropping frames silently. Re-run the task; if it recurs, reduce concurrent subagent fan-out."
+};
 var SET_MODEL_ERROR_CODES = [
   /** 目标模型不在当前进程快照（子进程模型快照冻结于 spawn 时刻——模型本身有效，
    *  下一轮 spawn 现取目录即可用；宿主按「写覆盖意图」处置，设计 §7.2 快照型失败行）。 */
@@ -176,7 +209,7 @@ var EngineSdkError = class extends Error {
     this.recovery = recovery;
     this.data = data;
   }
-  /** 协议 error 帧载荷投影。 */
+  /** 协议 error 帧载荷派生视图。 */
   toStructured() {
     return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
   }
@@ -227,12 +260,39 @@ function schemaEmulationFailedDetail(error, tail) {
   return `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. Recovery: retry with a strengthened prompt or relax the schema; if it still fails switch to a schema-native engine (engine: pi).`;
 }
 
+// src/protocol/control-protocol.ts
+var SUBAGENT_CONTROL_PROTOCOL_VERSION = 1;
+var SUBAGENT_CONTROL_FRAME_KINDS = {
+  hello: "hello",
+  helloOk: "hello_ok",
+  helloReject: "hello_reject",
+  engineOpen: "engine_open",
+  engineOpened: "engine_opened",
+  engineOpenFailed: "engine_open_failed",
+  engineFrame: "engine_frame",
+  engineClose: "engine_close",
+  engineClosed: "engine_closed",
+  error: "error"
+};
+function isSubagentControlFrameKind(value) {
+  return typeof value === "string" && Object.values(SUBAGENT_CONTROL_FRAME_KINDS).includes(value);
+}
+var SUBAGENT_CONTROL_CLOSED_REASONS = {
+  engineExit: "engine_exit",
+  engineSignal: "engine_signal",
+  killedByControl: "killed_by_control",
+  openTimeout: "open_timeout"
+};
+function isSubagentControlClosedReason(value) {
+  return typeof value === "string" && Object.values(SUBAGENT_CONTROL_CLOSED_REASONS).includes(value);
+}
+
 // src/protocol/contract-types.ts
 var AGENT_EVENT_TYPE_NAMES = [
   "tool_start",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 tool 起始占位（显示降级），turn 结构不受损
   "tool_end",
-  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 result，turn 收口由 turn_end/message_end 承担
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 result，turn 收尾由 turn_end/message_end 承担
   "text_delta",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺正文增量，不产生半解析状态
   "thinking_delta",
@@ -240,7 +300,7 @@ var AGENT_EVENT_TYPE_NAMES = [
   "turn_end",
   // noop-safe: 旧宿主 default 分支零写入——丢弃则该 turn 滞留进行态，journal 重放仍按序重建
   "message_end",
-  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 usage 聚合与闭合计量，已累积内容不回滚
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 usage 聚合与结束计量，已累积内容不回滚
   "compaction",
   // noop-safe: 事件无载荷且现行 reducer 即直接 return——丢弃与处理零差异
   "activity",
@@ -322,7 +382,7 @@ var notificationFrameSchema = {
             type: {
               type: "string",
               // 事件 enum 从词表 SSOT 派生（U2 词表锁：union⟷词表互证后，此处不再
-              // 手写字面量集合——手写即漂移面，病灶 1 的第三处同步点）
+              // 手写字面量集合——手写即漂移点，问题点 1 的第三处同步点）
               enum: [...AGENT_EVENT_TYPE_NAMES]
             }
           }
@@ -387,7 +447,11 @@ var runSessionParamsSchema = {
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
   ENGINE_TIMEOUT_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   EngineSdkError,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   HANDSHAKE_TIMEOUT_MS,
@@ -401,6 +465,9 @@ var runSessionParamsSchema = {
   SET_MODEL_STAGE_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUPPORTED_PROTOCOL_RANGE,
   assertChatConversationSupported,
   engineConversationUnsupportedError,
@@ -415,6 +482,8 @@ var runSessionParamsSchema = {
   isRequestFrame,
   isResponseFrame,
   isReverseRequestFrame,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,

package/dist/protocol/index.d.cts

@@ -1,7 +1,7 @@
-export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from '../error-codes-f-UO4a8D.cjs';
-export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-BLxg4ZFr.cjs';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_SPAWN_DELIVERY_ERROR_CODES, d as ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY, e as ENGINE_TIMEOUT_RECOVERY, f as ENGINE_TRANSPORT_ERROR_CODES, g as ENGINE_TRANSPORT_ERROR_RECOVERY, h as EngineProtocolErrorCode, E as EngineSdkError, i as EngineSpawnDeliveryErrorCode, j as EngineTransportErrorCode, k as ErrorResponseFrame, l as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, m as ResponseFrame, n as ReverseRequestFrame, o as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, p as SET_MODEL_NOT_ACTIVE_CODE, q as STDOUT_TAIL_ECHO_CHARS, r as SetModelErrorCode, s as SuccessResponseFrame, t as assertChatConversationSupported, u as engineConversationUnsupportedError, v as engineProtocolMismatchError, w as engineSetModelUnsupportedError, x as engineTimeoutDetail, y as isEngineErrorPassthroughCode, z as isEngineProtocolErrorCode, A as isNotificationFrame, B as isRequestFrame, C as isResponseFrame, D as isReverseRequestFrame, F as schemaEmulationFailedDetail } from '../error-codes-D_aPibUt.cjs';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-CHiDwvRK.cjs';
 import { UiRequest, UiResponse } from '../ui-types.cjs';
-export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-jSa1g28F.cjs';
+export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-BUHUMF9R.cjs';
 
 /** 协议版本（引擎包 manifest `taiji.subagentEngine.protocol` 与 initialize 应答同值）。 */
 declare const ENGINE_PROTOCOL_VERSION = 1;
@@ -15,7 +15,7 @@ declare const SUPPORTED_PROTOCOL_RANGE: {
 };
 /** 版本兼容判定（core 握手判据；引擎侧对称用于拒绝过旧/过新宿主）。 */
 declare function isProtocolVersionCompatible(version: number): boolean;
-/** 正向数据面反向请求（帧④数据面类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
+/** 正向数据范围反向请求（帧④数据范围类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
 declare const REVERSE_REQUEST_TIMEOUT_MS = 10000;
 /** initialize 握手超时（ms）：超时 → engine_handshake_timeout，该引擎不可用。 */
 declare const HANDSHAKE_TIMEOUT_MS = 10000;
@@ -24,22 +24,22 @@ declare const CANCEL_SETTLE_GRACE_MS = 3000;
 /**
  * setModel 引擎侧单阶段控制窗（ms）：pi 实现等子进程 `set_model` 应答、等
  * `get_state` 回读各占一窗（设计 subagent-model-switch §7.3——命令与回读全程带
- * 存活检查，超时上限复用现役取消收敛窗量级：控制面单请求 = 秒级）。窗满且进程
+ * 存活检查，超时上限复用现役取消收敛窗量级：控制范围单请求 = 秒级）。窗满且进程
  * 仍存活 → `engine_state_readback_failed`；窗满时进程已退出 → 无活进程形态
  * （`SET_MODEL_NOT_ACTIVE_CODE`）——两种处置不可混淆。
  */
 declare const SET_MODEL_STAGE_TIMEOUT_MS = 3000;
 /**
  * setModel 正向方法的宿主侧单请求上界（ms）：≥ 引擎侧两阶段最坏时延
- * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据面单请求
- * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制面单请求必须秒级有界——宿主不悬挂）。
+ * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据范围单请求
+ * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制范围单请求必须秒级有界——宿主不悬挂）。
  */
 declare const SET_MODEL_REQUEST_TIMEOUT_MS = 10000;
 /** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
 declare const STDERR_TAIL_CHARS = 400;
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/handleReady /
+ * - 数据范围类（host/log / host/streamDelta / host/handleReady /
  *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
  * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
@@ -55,11 +55,11 @@ type ReverseChannel = "host/log" | "host/askUser" | "host/streamDelta" | "host/h
  */
 declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
 /**
- * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
+ * 超时二分归属（10s 数据范围 / 不设统一超时的人机交互通道）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
  */
 declare const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass>;
-/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
+/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用范围）。 */
 interface HostLogParams {
     level: "debug" | "warn" | "error";
     component: string;
@@ -87,7 +87,7 @@ interface HostStreamDeltaParams {
 /**
  * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
  * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
- * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议面 poolKey 退役删除。
+ * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议范围 poolKey 退役删除。
  */
 interface HostHandleReadyParams {
     runId: string;
@@ -103,7 +103,7 @@ interface HostChildSpawnedParams {
     recordId: string;
 }
 /**
- * host/childStateChanged：childSpawned 的状态面（core 侧镜像数据源，
+ * host/childStateChanged：childSpawned 的状态侧（core 侧镜像数据源，
  * hasLiveProcessHandle/isResumable 同步读镜像，不跨进程查询）。
  * **killed 必含**（判据 `child !== undefined && !child.killed`）——类型层 required。
  */
@@ -117,6 +117,49 @@ interface HostChildStateChangedParams {
     signal?: string;
 }
 
+/** control 协议版本（帧 v 字段；runtime 与 extension 同包分发，未知 v → hello_reject {reason:"version"}，D9 版本矩阵）。 */
+declare const SUBAGENT_CONTROL_PROTOCOL_VERSION = 1;
+/**
+ * 帧 kind 判别值词表（10 成员）。as const 值即字面量类型——类型位置同样可用。
+ * 方向语义见文件头帧表：hello/engine_open/engine_frame/engine_close 为 C→R，
+ * hello_ok/hello_reject/engine_opened/engine_open_failed/engine_closed/error 为 R→C，
+ * engine_frame 双向。
+ */
+declare const SUBAGENT_CONTROL_FRAME_KINDS: {
+    readonly hello: "hello";
+    readonly helloOk: "hello_ok";
+    readonly helloReject: "hello_reject";
+    readonly engineOpen: "engine_open";
+    readonly engineOpened: "engine_opened";
+    readonly engineOpenFailed: "engine_open_failed";
+    readonly engineFrame: "engine_frame";
+    readonly engineClose: "engine_close";
+    readonly engineClosed: "engine_closed";
+    readonly error: "error";
+};
+type SubagentControlFrameKind = (typeof SUBAGENT_CONTROL_FRAME_KINDS)[keyof typeof SUBAGENT_CONTROL_FRAME_KINDS];
+/** unknown → control 帧 kind 收窄（外部输入携带 kind 时的运行时 guard）。 */
+declare function isSubagentControlFrameKind(value: unknown): value is SubagentControlFrameKind;
+/**
+ * engine_closed 帧 reason 值域（引擎通道终局归因，D8/D10）：
+ * - engine_exit：引擎进程自行退出（code 承载退出码）；
+ * - engine_signal：被信号终止（signal 承载信号名）；
+ * - killed_by_control：runtime 主动杀组（engine_close 有界等待超时 / 背压溢出 /
+ *   连接关闭 fan-out 等控制面裁决）；
+ * - open_timeout：engine_open 超时被 runtime 中止杀组（迟到 engine_opened 丢弃）。
+ * 意外退出（engine_exit/engine_signal）→ runtime 无条件 killEngineGroup（D7）；
+ * runtime transport 把 reason 映射进 onExit info（stderrTail 同帧携带）。
+ */
+declare const SUBAGENT_CONTROL_CLOSED_REASONS: {
+    readonly engineExit: "engine_exit";
+    readonly engineSignal: "engine_signal";
+    readonly killedByControl: "killed_by_control";
+    readonly openTimeout: "open_timeout";
+};
+type SubagentControlClosedReason = (typeof SUBAGENT_CONTROL_CLOSED_REASONS)[keyof typeof SUBAGENT_CONTROL_CLOSED_REASONS];
+/** unknown → engine_closed reason 收窄（外部输入携带 reason 时的运行时 guard）。 */
+declare function isSubagentControlClosedReason(value: unknown): value is SubagentControlClosedReason;
+
 /** 协议错误对象 schema。 */
 declare const protocolErrorSchema: {
     readonly $schema: "http://json-schema.org/draft-07/schema#";
@@ -404,7 +447,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
     };
 };
 /**
- * 协议面凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型面
+ * 协议范围凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型范围
  * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
  */
 declare const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: readonly ["apikey", "api_key", "token", "credential", "password", "secret"];
@@ -446,4 +489,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUBAGENT_CONTROL_CLOSED_REASONS, SUBAGENT_CONTROL_FRAME_KINDS, SUBAGENT_CONTROL_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_RANGE, type SubagentControlClosedReason, type SubagentControlFrameKind, errorResponseFrameSchema, isProtocolVersionCompatible, isSubagentControlClosedReason, isSubagentControlFrameKind, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };

package/dist/protocol/index.d.ts

@@ -1,7 +1,7 @@
-export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_TIMEOUT_RECOVERY, d as EngineProtocolErrorCode, E as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, j as SET_MODEL_NOT_ACTIVE_CODE, k as STDOUT_TAIL_ECHO_CHARS, l as SetModelErrorCode, m as SuccessResponseFrame, n as assertChatConversationSupported, o as engineConversationUnsupportedError, p as engineProtocolMismatchError, q as engineSetModelUnsupportedError, r as engineTimeoutDetail, s as isEngineErrorPassthroughCode, t as isEngineProtocolErrorCode, u as isNotificationFrame, v as isRequestFrame, w as isResponseFrame, x as isReverseRequestFrame, y as schemaEmulationFailedDetail } from '../error-codes-DnFru4L4.js';
-export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-C2zvZqhP.js';
+export { a as ENGINE_ERROR_CODE_PREFIX, b as ENGINE_PROTOCOL_ERROR_CODES, c as ENGINE_SPAWN_DELIVERY_ERROR_CODES, d as ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY, e as ENGINE_TIMEOUT_RECOVERY, f as ENGINE_TRANSPORT_ERROR_CODES, g as ENGINE_TRANSPORT_ERROR_RECOVERY, h as EngineProtocolErrorCode, E as EngineSdkError, i as EngineSpawnDeliveryErrorCode, j as EngineTransportErrorCode, k as ErrorResponseFrame, l as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, m as ResponseFrame, n as ReverseRequestFrame, o as ReverseResponseResult, S as SET_MODEL_ERROR_CODES, p as SET_MODEL_NOT_ACTIVE_CODE, q as STDOUT_TAIL_ECHO_CHARS, r as SetModelErrorCode, s as SuccessResponseFrame, t as assertChatConversationSupported, u as engineConversationUnsupportedError, v as engineProtocolMismatchError, w as engineSetModelUnsupportedError, x as engineTimeoutDetail, y as isEngineErrorPassthroughCode, z as isEngineProtocolErrorCode, A as isNotificationFrame, B as isRequestFrame, C as isResponseFrame, D as isReverseRequestFrame, F as schemaEmulationFailedDetail } from '../error-codes-DrNf0gwT.js';
+export { C as CancelParams, c as CancelResult, D as DisposeParams, d as DisposeResult, b as InitializeParams, I as InitializeResult, L as ListModelsParams, e as ListModelsResult, P as PROTOCOL_METHODS, f as PingParams, g as PingResult, h as ProbeParams, i as ProtocolMethod, j as ProtocolParamsMap, k as ProtocolResultMap, l as ReadParams, R as RunContextParams, m as RunParams, n as RunResult, o as RunResumeParams, S as SetModelParams, a as SetModelResult, V as ValidateModelParams, p as ValidateModelResult } from '../methods-BdIH3FwS.js';
 import { UiRequest, UiResponse } from '../ui-types.js';
-export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-jSa1g28F.js';
+export { g as AGENT_EVENT_TYPE_NAMES, b as AgentCallOpts, A as AgentEvent, h as AgentEventTypeName, i as AgentFailureKind, c as AgentOutcome, j as AgentOutcomeUsage, k as AgentUsage, a as AgentUsageTotal, l as AssertMutuallyAssignable, d as EngineCapabilities, E as EngineHandleData, m as EngineProcessModel, I as InternalToolCall, f as ModelCatalogEntry, M as ModelRef, P as ProbeReport, R as ReplayedTurn, e as ResumeAnchor, S as SessionView, n as ToolCall, o as ToolCallEntry, p as ToolCallResult, T as Turn, W as WorktreeHandle } from '../contract-types-BUHUMF9R.js';
 
 /** 协议版本（引擎包 manifest `taiji.subagentEngine.protocol` 与 initialize 应答同值）。 */
 declare const ENGINE_PROTOCOL_VERSION = 1;
@@ -15,7 +15,7 @@ declare const SUPPORTED_PROTOCOL_RANGE: {
 };
 /** 版本兼容判定（core 握手判据；引擎侧对称用于拒绝过旧/过新宿主）。 */
 declare function isProtocolVersionCompatible(version: number): boolean;
-/** 正向数据面反向请求（帧④数据面类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
+/** 正向数据范围反向请求（帧④数据范围类）未应答容忍时长：10s 未答 = 引擎故障 → 杀进程 + 在途 run 失败。 */
 declare const REVERSE_REQUEST_TIMEOUT_MS = 10000;
 /** initialize 握手超时（ms）：超时 → engine_handshake_timeout，该引擎不可用。 */
 declare const HANDSHAKE_TIMEOUT_MS = 10000;
@@ -24,22 +24,22 @@ declare const CANCEL_SETTLE_GRACE_MS = 3000;
 /**
  * setModel 引擎侧单阶段控制窗（ms）：pi 实现等子进程 `set_model` 应答、等
  * `get_state` 回读各占一窗（设计 subagent-model-switch §7.3——命令与回读全程带
- * 存活检查，超时上限复用现役取消收敛窗量级：控制面单请求 = 秒级）。窗满且进程
+ * 存活检查，超时上限复用现役取消收敛窗量级：控制范围单请求 = 秒级）。窗满且进程
  * 仍存活 → `engine_state_readback_failed`；窗满时进程已退出 → 无活进程形态
  * （`SET_MODEL_NOT_ACTIVE_CODE`）——两种处置不可混淆。
  */
 declare const SET_MODEL_STAGE_TIMEOUT_MS = 3000;
 /**
  * setModel 正向方法的宿主侧单请求上界（ms）：≥ 引擎侧两阶段最坏时延
- * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据面单请求
- * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制面单请求必须秒级有界——宿主不悬挂）。
+ * （2 × SET_MODEL_STAGE_TIMEOUT_MS）+ 协议余量；量级锚 = 数据范围单请求
+ * REVERSE_REQUEST_TIMEOUT_MS 的 10s 先例（控制范围单请求必须秒级有界——宿主不悬挂）。
  */
 declare const SET_MODEL_REQUEST_TIMEOUT_MS = 10000;
 /** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
 declare const STDERR_TAIL_CHARS = 400;
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/handleReady /
+ * - 数据范围类（host/log / host/streamDelta / host/handleReady /
  *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
  * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
@@ -55,11 +55,11 @@ type ReverseChannel = "host/log" | "host/askUser" | "host/streamDelta" | "host/h
  */
 declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
 /**
- * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
+ * 超时二分归属（10s 数据范围 / 不设统一超时的人机交互通道）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
  */
 declare const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass>;
-/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
+/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用范围）。 */
 interface HostLogParams {
     level: "debug" | "warn" | "error";
     component: string;
@@ -87,7 +87,7 @@ interface HostStreamDeltaParams {
 /**
  * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
  * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
- * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议面 poolKey 退役删除。
+ * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议范围 poolKey 退役删除。
  */
 interface HostHandleReadyParams {
     runId: string;
@@ -103,7 +103,7 @@ interface HostChildSpawnedParams {
     recordId: string;
 }
 /**
- * host/childStateChanged：childSpawned 的状态面（core 侧镜像数据源，
+ * host/childStateChanged：childSpawned 的状态侧（core 侧镜像数据源，
  * hasLiveProcessHandle/isResumable 同步读镜像，不跨进程查询）。
  * **killed 必含**（判据 `child !== undefined && !child.killed`）——类型层 required。
  */
@@ -117,6 +117,49 @@ interface HostChildStateChangedParams {
     signal?: string;
 }
 
+/** control 协议版本（帧 v 字段；runtime 与 extension 同包分发，未知 v → hello_reject {reason:"version"}，D9 版本矩阵）。 */
+declare const SUBAGENT_CONTROL_PROTOCOL_VERSION = 1;
+/**
+ * 帧 kind 判别值词表（10 成员）。as const 值即字面量类型——类型位置同样可用。
+ * 方向语义见文件头帧表：hello/engine_open/engine_frame/engine_close 为 C→R，
+ * hello_ok/hello_reject/engine_opened/engine_open_failed/engine_closed/error 为 R→C，
+ * engine_frame 双向。
+ */
+declare const SUBAGENT_CONTROL_FRAME_KINDS: {
+    readonly hello: "hello";
+    readonly helloOk: "hello_ok";
+    readonly helloReject: "hello_reject";
+    readonly engineOpen: "engine_open";
+    readonly engineOpened: "engine_opened";
+    readonly engineOpenFailed: "engine_open_failed";
+    readonly engineFrame: "engine_frame";
+    readonly engineClose: "engine_close";
+    readonly engineClosed: "engine_closed";
+    readonly error: "error";
+};
+type SubagentControlFrameKind = (typeof SUBAGENT_CONTROL_FRAME_KINDS)[keyof typeof SUBAGENT_CONTROL_FRAME_KINDS];
+/** unknown → control 帧 kind 收窄（外部输入携带 kind 时的运行时 guard）。 */
+declare function isSubagentControlFrameKind(value: unknown): value is SubagentControlFrameKind;
+/**
+ * engine_closed 帧 reason 值域（引擎通道终局归因，D8/D10）：
+ * - engine_exit：引擎进程自行退出（code 承载退出码）；
+ * - engine_signal：被信号终止（signal 承载信号名）；
+ * - killed_by_control：runtime 主动杀组（engine_close 有界等待超时 / 背压溢出 /
+ *   连接关闭 fan-out 等控制面裁决）；
+ * - open_timeout：engine_open 超时被 runtime 中止杀组（迟到 engine_opened 丢弃）。
+ * 意外退出（engine_exit/engine_signal）→ runtime 无条件 killEngineGroup（D7）；
+ * runtime transport 把 reason 映射进 onExit info（stderrTail 同帧携带）。
+ */
+declare const SUBAGENT_CONTROL_CLOSED_REASONS: {
+    readonly engineExit: "engine_exit";
+    readonly engineSignal: "engine_signal";
+    readonly killedByControl: "killed_by_control";
+    readonly openTimeout: "open_timeout";
+};
+type SubagentControlClosedReason = (typeof SUBAGENT_CONTROL_CLOSED_REASONS)[keyof typeof SUBAGENT_CONTROL_CLOSED_REASONS];
+/** unknown → engine_closed reason 收窄（外部输入携带 reason 时的运行时 guard）。 */
+declare function isSubagentControlClosedReason(value: unknown): value is SubagentControlClosedReason;
+
 /** 协议错误对象 schema。 */
 declare const protocolErrorSchema: {
     readonly $schema: "http://json-schema.org/draft-07/schema#";
@@ -404,7 +447,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
     };
 };
 /**
- * 协议面凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型面
+ * 协议范围凭据禁区键名（不变量 5 的测试断言依据）：帧 schema 与深载荷 TS 类型范围
  * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
  */
 declare const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: readonly ["apikey", "api_key", "token", "credential", "password", "secret"];
@@ -446,4 +489,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { CANCEL_SETTLE_GRACE_MS, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReverseChannel, type ReverseRequestTimeoutClass, SET_MODEL_REQUEST_TIMEOUT_MS, SET_MODEL_STAGE_TIMEOUT_MS, STDERR_TAIL_CHARS, SUBAGENT_CONTROL_CLOSED_REASONS, SUBAGENT_CONTROL_FRAME_KINDS, SUBAGENT_CONTROL_PROTOCOL_VERSION, SUPPORTED_PROTOCOL_RANGE, type SubagentControlClosedReason, type SubagentControlFrameKind, errorResponseFrameSchema, isProtocolVersionCompatible, isSubagentControlClosedReason, isSubagentControlFrameKind, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };