@zhushanwen/subagent-engine-sdk 0.6.1 → 0.7.0

package/dist/kill-chain.d.cts

@@ -1,5 +1,4 @@
-export { S as STDOUT_TAIL_ECHO_CHARS } from './error-codes-CFTOAxva.cjs';
-import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DaULkdpG.cjs';
+import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DiWyGRXr.cjs';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
@@ -47,6 +46,42 @@ interface KillChainOptions {
  * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
  */
 declare function killChain(child: KillableChild, opts: KillChainOptions): Promise<"terminated" | "killed">;
+/**
+ * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
+ * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
+ * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ */
+declare function safeKill(child: KillableChild, signal: NodeJS.Signals): void;
+/**
+ * 单 pid 存活探针（`process.kill(pid, 0)`）。
+ *
+ * 返回三态：true = 存活；false = 已死（ESRCH）；undefined = 不可判定（EPERM =
+ * 进程存在但属他人 / 探针异常）——undefined 按存活保守处理（杀链对已死进程发信号
+ * 本就是 no-op，误判存活只多一次空信号，误判死亡会漏杀）。
+ */
+declare function probePidAlive(pid: number): boolean | undefined;
+/** killPidChain 参数形状。 */
+interface PidChainOptions {
+    /**
+     * SIGTERM 优雅窗口（ms）。缺省 DEFAULT_KILL_GRACE_MS。回收场景的调用方通常
+     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用组杀
+     * 收割惯例（5s）。
+     */
+    graceMs?: number;
+    /** SIGKILL 升级时的 warn 留痕语境（如 `run run-a topology kill`）。不传则静默升级。 */
+    note?: string;
+}
+/**
+ * [D9-2 半径收窄原语] run 级 pid 杀链：SIGTERM → graceMs → 仍存活则 SIGKILL，
+ * **只打单 pid，绝不组杀**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
+ * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 组杀不可达；
+ * 本原语逐 pid 退化单杀，语义 = 「该 run 的进程拓扑」而非引擎组）。
+ *
+ * fire-and-forget：宿主非进程持有方，无 exit 事件可等（对齐 core reaper 的
+ * killProcessTree 形态——升级 timer unref，不阻塞调用方；收尸由 OS 完成）。
+ * 对已死 pid 全程 no-op（信号幂等吞掉）。
+ */
+declare function killPidChain(pid: number, opts?: PidChainOptions): void;
 /**
  * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
  * 含 stdout 尾部 2000 字 + 恢复指引（§3.3.3 第 6 行）；exitCode: null = 被信号杀死
@@ -71,4 +106,4 @@ declare function abortWithFallback(child: KillableChild, signal: AbortSignal, tr
     nativeGraceMs?: number;
 }): Promise<"terminated" | "killed">;
 
-export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome };
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, type PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome };

package/dist/kill-chain.d.ts

@@ -1,5 +1,4 @@
-export { S as STDOUT_TAIL_ECHO_CHARS } from './error-codes-C9BOUI5H.js';
-import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DaULkdpG.js';
+import { a as AgentCallOpts, e as AgentOutcome } from './contract-types-DiWyGRXr.js';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
@@ -47,6 +46,42 @@ interface KillChainOptions {
  * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
  */
 declare function killChain(child: KillableChild, opts: KillChainOptions): Promise<"terminated" | "killed">;
+/**
+ * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
+ * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
+ * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ */
+declare function safeKill(child: KillableChild, signal: NodeJS.Signals): void;
+/**
+ * 单 pid 存活探针（`process.kill(pid, 0)`）。
+ *
+ * 返回三态：true = 存活；false = 已死（ESRCH）；undefined = 不可判定（EPERM =
+ * 进程存在但属他人 / 探针异常）——undefined 按存活保守处理（杀链对已死进程发信号
+ * 本就是 no-op，误判存活只多一次空信号，误判死亡会漏杀）。
+ */
+declare function probePidAlive(pid: number): boolean | undefined;
+/** killPidChain 参数形状。 */
+interface PidChainOptions {
+    /**
+     * SIGTERM 优雅窗口（ms）。缺省 DEFAULT_KILL_GRACE_MS。回收场景的调用方通常
+     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用组杀
+     * 收割惯例（5s）。
+     */
+    graceMs?: number;
+    /** SIGKILL 升级时的 warn 留痕语境（如 `run run-a topology kill`）。不传则静默升级。 */
+    note?: string;
+}
+/**
+ * [D9-2 半径收窄原语] run 级 pid 杀链：SIGTERM → graceMs → 仍存活则 SIGKILL，
+ * **只打单 pid，绝不组杀**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
+ * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 组杀不可达；
+ * 本原语逐 pid 退化单杀，语义 = 「该 run 的进程拓扑」而非引擎组）。
+ *
+ * fire-and-forget：宿主非进程持有方，无 exit 事件可等（对齐 core reaper 的
+ * killProcessTree 形态——升级 timer unref，不阻塞调用方；收尸由 OS 完成）。
+ * 对已死 pid 全程 no-op（信号幂等吞掉）。
+ */
+declare function killPidChain(pid: number, opts?: PidChainOptions): void;
 /**
  * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
  * 含 stdout 尾部 2000 字 + 恢复指引（§3.3.3 第 6 行）；exitCode: null = 被信号杀死
@@ -71,4 +106,4 @@ declare function abortWithFallback(child: KillableChild, signal: AbortSignal, tr
     nativeGraceMs?: number;
 }): Promise<"terminated" | "killed">;
 
-export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, abortWithFallback, killChain, synthesizeTimeoutOutcome };
+export { DEFAULT_KILL_GRACE_MS, DEFAULT_NATIVE_INTERRUPT_GRACE_MS, HOST_TIMEOUT_ABORT_REASON, type KillChainOptions, type KillableChild, type PidChainOptions, abortWithFallback, killChain, killPidChain, probePidAlive, safeKill, synthesizeTimeoutOutcome };

package/dist/kill-chain.js

@@ -4,20 +4,23 @@ import {
   HOST_TIMEOUT_ABORT_REASON,
   abortWithFallback,
   killChain,
+  killPidChain,
+  probePidAlive,
+  safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-QOEXD2FT.js";
+} from "./chunk-RCT7L777.js";
 import "./chunk-PYO3YR7W.js";
-import {
-  STDOUT_TAIL_ECHO_CHARS
-} from "./chunk-WMDMXP2F.js";
+import "./chunk-SFNTX7Q3.js";
 import "./chunk-75QEMUGV.js";
 import "./chunk-JSBRDJBE.js";
 export {
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
   HOST_TIMEOUT_ABORT_REASON,
-  STDOUT_TAIL_ECHO_CHARS,
   abortWithFallback,
   killChain,
+  killPidChain,
+  probePidAlive,
+  safeKill,
   synthesizeTimeoutOutcome
 };

package/dist/node-executor.js

@@ -4,8 +4,8 @@ import {
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-W3BKI2BP.js";
-import "./chunk-WMDMXP2F.js";
+} from "./chunk-3WC36CHI.js";
+import "./chunk-SFNTX7Q3.js";
 import "./chunk-JSBRDJBE.js";
 export {
   ENGINE_NODE_ENV,

package/dist/port-contract.d.cts

@@ -1,14 +1,13 @@
-import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, k as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DaULkdpG.cjs';
+import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, l as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DiWyGRXr.cjs';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
- * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
+ * cwd——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
  * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
  */
 type EngineAgentCallOpts = AgentCallOpts & {
     model?: string;
     cwd?: string;
-    schemaEnv?: string;
 };
 /**
  * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
@@ -45,7 +44,6 @@ interface RunContext {
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
     stream?: EngineStream;
-    schemaEnv?: string;
     engineFallback?: {
         from: string;
         reason: string;
@@ -62,6 +60,13 @@ interface RunContext {
      * [LEGACY] fallback（独立运行/测试形态）。
      */
     sessionDir?: string;
+    /**
+     * [D2 扩展加载显式化] 孙进程显式加载的扩展路径集（协议 run.params.ctx.extensionPaths
+     * 的进程内还原）——pi 引擎侧逐项拼 `--extension` argv，取代已废弃的 argv 镜像
+     * 机制（镜像前提「引擎进程从主 pi 进程 spawn」已不存在，协议化后引擎进程 argv
+     * 恒无扩展 flag）。additive 可选：宿主缺省不传。
+     */
+    extensionPaths?: string[];
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {

package/dist/port-contract.d.ts

@@ -1,14 +1,13 @@
-import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, k as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DaULkdpG.js';
+import { a as AgentCallOpts, j as EngineHandleData, E as EngineCapabilities, P as ProbeReport, b as AgentEvent, l as ResumeAnchor, e as AgentOutcome, S as SessionView } from './contract-types-DiWyGRXr.js';
 
 /**
  * 引擎进程内全量任务声明 = SDK AgentCallOpts 引擎面子集 + 协议 ctx 还原字段（model/
- * cwd/schemaEnv——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
+ * cwd——SDK 契约把它们从 task 移到 run.params.ctx，进程内接口合回单对象；
  * server.ts 做 ctx→task 还原，与 core RemoteEngine.toSdkTaskSubset 镜像）。
  */
 type EngineAgentCallOpts = AgentCallOpts & {
     model?: string;
     cwd?: string;
-    schemaEnv?: string;
 };
 /**
  * 引擎进程内的 ctxModel 形态（core ModelInfo 的结构等价镜像——仅 id/provider 被引擎
@@ -45,7 +44,6 @@ interface RunContext {
     onEvent?: (event: AgentEvent) => void;
     ctxModel?: EngineCtxModel;
     stream?: EngineStream;
-    schemaEnv?: string;
     engineFallback?: {
         from: string;
         reason: string;
@@ -62,6 +60,13 @@ interface RunContext {
      * [LEGACY] fallback（独立运行/测试形态）。
      */
     sessionDir?: string;
+    /**
+     * [D2 扩展加载显式化] 孙进程显式加载的扩展路径集（协议 run.params.ctx.extensionPaths
+     * 的进程内还原）——pi 引擎侧逐项拼 `--extension` argv，取代已废弃的 argv 镜像
+     * 机制（镜像前提「引擎进程从主 pi 进程 spawn」已不存在，协议化后引擎进程 argv
+     * 恒无扩展 flag）。additive 可选：宿主缺省不传。
+     */
+    extensionPaths?: string[];
     onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
     /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
     onChildSpawned?: (child: {

package/dist/protocol/index.cjs

@@ -25,8 +25,6 @@ __export(protocol_exports, {
   CRASH_REBUILD_BACKOFF_MS: () => CRASH_REBUILD_BACKOFF_MS,
   CRASH_REBUILD_MAX_ATTEMPTS: () => CRASH_REBUILD_MAX_ATTEMPTS,
   ENGINE_ERROR_CODE_PREFIX: () => ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT: () => ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV: () => ENGINE_EVENT_COALESCE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES: () => ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS: () => ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION: () => ENGINE_PROTOCOL_VERSION,
@@ -82,8 +80,6 @@ var CRASH_REBUILD_BACKOFF_MS = [
   CRASH_REBUILD_BACKOFF_STEP_3_MS
 ];
 var STDERR_TAIL_CHARS = 400;
-var ENGINE_EVENT_COALESCE_ENV = "TAIJI_ENGINE_EVENT_COALESCE";
-var ENGINE_EVENT_COALESCE_DEFAULT = "0";
 
 // src/protocol/frames.ts
 function isRecord(v) {
@@ -229,8 +225,10 @@ var AGENT_EVENT_TYPE_NAMES = [
   // noop-safe: 事件无载荷且现行 reducer 即直接 return——丢弃与处理零差异
   "activity",
   // noop-safe: 纯活性信号，双侧 reducer 恒 no-op（协议语义见 AgentEvent 头注），丢弃零差异
-  "error"
+  "error",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 lastError 诊断留痕，已写状态不回滚
+  "armed"
+  // noop-safe: 旧宿主无武装等待窗消费点（fail-fast 属宿主新增逻辑），丢弃仅缺武装留痕，schema 强制第一道防线（引擎自查断言）不受损
 ];
 
 // src/protocol/schema.ts
@@ -368,8 +366,6 @@ var runSessionParamsSchema = {
   CRASH_REBUILD_BACKOFF_MS,
   CRASH_REBUILD_MAX_ATTEMPTS,
   ENGINE_ERROR_CODE_PREFIX,
-  ENGINE_EVENT_COALESCE_DEFAULT,
-  ENGINE_EVENT_COALESCE_ENV,
   ENGINE_PROTOCOL_ERROR_CODES,
   ENGINE_PROTOCOL_SCHEMAS,
   ENGINE_PROTOCOL_VERSION,

package/dist/protocol/index.d.cts

@@ -1,6 +1,5 @@
-export { E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d 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 STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-CFTOAxva.cjs';
-import { E as EngineCapabilities, M as ModelCatalogEntry, a as AgentCallOpts, k as ResumeAnchor, j as EngineHandleData, P as ProbeReport, e as AgentOutcome, S as SessionView } from '../contract-types-DaULkdpG.cjs';
-export { A as AGENT_EVENT_TYPE_NAMES, b as AgentEvent, c as AgentEventTypeName, d as AgentFailureKind, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, I as InternalToolCall, R as ReplayedTurn, T as ToolCall, l as ToolCallEntry, m as ToolCallResult, n as Turn, W as WorktreeHandle } from '../contract-types-DaULkdpG.cjs';
+import { b as AgentEvent, E as EngineCapabilities, M as ModelCatalogEntry, a as AgentCallOpts, l as ResumeAnchor, j as EngineHandleData, P as ProbeReport, e as AgentOutcome, S as SessionView } from '../contract-types-DiWyGRXr.cjs';
+export { A as AGENT_EVENT_TYPE_NAMES, c as AgentEventTypeName, d as AgentFailureKind, f as AgentOutcomeUsage, g as AgentUsage, h as AgentUsageTotal, i as AssertMutuallyAssignable, k as EngineProcessModel, I as InternalToolCall, R as ReplayedTurn, T as ToolCall, m as ToolCallEntry, n as ToolCallResult, o as Turn, W as WorktreeHandle } from '../contract-types-DiWyGRXr.cjs';
 import { UiRequest, UiResponse } from '../ui-types.cjs';
 
 /** 协议版本（引擎包 manifest `taiji.subagentEngine.protocol` 与 initialize 应答同值）。 */
@@ -26,9 +25,6 @@ declare const CRASH_REBUILD_MAX_ATTEMPTS = 3;
 declare const CRASH_REBUILD_BACKOFF_MS: readonly [1000, 2000, 4000];
 /** stderr 内存环形缓冲保留的尾部字符数（engine_crashed 帧携带崩溃现场）。 */
 declare const STDERR_TAIL_CHARS = 400;
-/** 事件合并开关 env 名（设计级默认关闭 = 值 "0"；A1 要求事件逐字段等价，合并不可开）。 */
-declare const ENGINE_EVENT_COALESCE_ENV = "TAIJI_ENGINE_EVENT_COALESCE";
-declare const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
  * - 数据面类（host/log / host/streamDelta / host/handleReady /
@@ -38,6 +34,69 @@ declare const ENGINE_EVENT_COALESCE_DEFAULT = "0";
  */
 type ReverseRequestTimeoutClass = "data-plane" | "interaction";
 
+/** 协议错误对象（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;
+
 /**
  * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
  * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
@@ -55,8 +114,6 @@ interface RunContextParams {
     cwd?: string;
     /** 请求模型 ref（未传 = 引擎缺省模型）。 */
     model?: string;
-    /** 结构化输出 schema 的 env 注入形态（schemaEnv 降级通道）。 */
-    schemaEnv?: string;
     /** 上下文模型 ref（与 run 模型分离的 ctx 模型）。 */
     ctxModel?: string;
     /** fallback 留痕（引擎回填 outcome.engineFallback 的种子）。 */
@@ -80,6 +137,14 @@ interface RunContextParams {
      * 未知字段，undefined 不上 wire。
      */
     sessionDir?: string;
+    /**
+     * [D2 扩展加载显式化] 孙进程显式加载的扩展路径集（pi 引擎侧逐项拼
+     * `--extension` argv）。per-host 常量而非 per-run 变量，故落 ctx。宿主侧来源
+     * 双形态：taiji 宿主 = extension-service 下发的白名单收窄集（经 pi-host 注入）；
+     * 独立 pi = subagent-workflow 自身 optional peerDep 解析回退。additive 可选：
+     * 旧引擎忽略未知字段，undefined 不上 wire。
+     */
+    extensionPaths?: string[];
 }
 /**
  * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
@@ -150,7 +215,10 @@ interface CancelResult {
 }
 interface ReadParams {
     handle: EngineHandleData;
-    /** 数据根必填：存量池时代引擎自算池/journal 相对 dbPath 的定位需要它（设计钉死）。 */
+    /** 数据根（core 每次 read 都发送——remote-engine 构造注入的数据目录）。两引擎
+     *  server 现行均不消费该字段：定位走 handle.data（journalPath 等）或引擎自身
+     *  数据目录。保留为协议帧字段（历史：存量池时代引擎自算池/journal 相对 dbPath
+     *  的定位需要它）。 */
     dataDir: string;
 }
 interface ListModelsParams {
@@ -277,6 +345,58 @@ interface HostChildStateChangedParams {
     signal?: string;
 }
 
+/** 协议核心错误码（引擎 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;
+/**
+ * 引擎 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;
+/** 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;
+
 /** 协议错误对象 schema。 */
 declare const protocolErrorSchema: {
     readonly $schema: "http://json-schema.org/draft-07/schema#";
@@ -395,7 +515,7 @@ declare const notificationFrameSchema: {
                     readonly properties: {
                         readonly type: {
                             readonly type: "string";
-                            readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error"];
+                            readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed"];
                         };
                     };
                 };
@@ -515,7 +635,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
                         readonly properties: {
                             readonly type: {
                                 readonly type: "string";
-                                readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error"];
+                                readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed"];
                             };
                         };
                     };
@@ -606,4 +726,4 @@ declare const runSessionParamsSchema: {
     };
 };
 
-export { AgentCallOpts, AgentOutcome, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseRequestTimeoutClass, type RunContextParams, type RunParams, type RunResult, type RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };
+export { AgentCallOpts, AgentEvent, AgentOutcome, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_ERROR_CODE_PREFIX, ENGINE_PROTOCOL_ERROR_CODES, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, ENGINE_TIMEOUT_RECOVERY, EngineCapabilities, EngineHandleData, type EngineProtocolErrorCode, EngineSdkError, type ErrorResponseFrame, type EventNotificationParams, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, type NotificationFrame, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, type ProtocolError, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, type RequestFrame, type ResponseFrame, ResumeAnchor, type ReverseChannel, type ReverseRequestFrame, type ReverseRequestTimeoutClass, type ReverseResponseResult, type RunContextParams, type RunParams, type RunResult, type RunResumeParams, STDERR_TAIL_CHARS, STDOUT_TAIL_ECHO_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type SuccessResponseFrame, type ValidateModelParams, type ValidateModelResult, assertChatConversationSupported, engineConversationUnsupportedError, engineProtocolMismatchError, engineTimeoutDetail, errorResponseFrameSchema, isEngineErrorPassthroughCode, isEngineProtocolErrorCode, isNotificationFrame, isProtocolVersionCompatible, isRequestFrame, isResponseFrame, isReverseRequestFrame, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, schemaEmulationFailedDetail, successResponseFrameSchema };