@zhushanwen/subagent-engine-sdk 0.6.1 → 0.7.0

package/dist/protocol/index.d.ts

@@ -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-C9BOUI5H.js';
-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.js';
-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.js';
+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.js';
+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.js';
 import { UiRequest, UiResponse } from '../ui-types.js';
 
 /** 协议版本（引擎包 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 };

package/dist/protocol/index.js

@@ -16,14 +16,12 @@ import {
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-63ZNJHM5.js";
+} from "../chunk-W23PAAGX.js";
 import {
   CANCEL_SETTLE_GRACE_MS,
   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_VERSION,
   ENGINE_TIMEOUT_RECOVERY,
@@ -41,7 +39,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "../chunk-WMDMXP2F.js";
+} from "../chunk-SFNTX7Q3.js";
 import "../chunk-JSBRDJBE.js";
 export {
   AGENT_EVENT_TYPE_NAMES,
@@ -49,8 +47,6 @@ export {
   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/spawn.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var spawn_exports = {};
 __export(spawn_exports, {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS: () => DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_ABORT_KILL_GRACE_MS: () => ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV: () => ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct: () => armEngineSelfDestruct,
   pumpNdjsonLines: () => pumpNdjsonLines,
@@ -76,8 +77,77 @@ function getLogger(component) {
   return facade;
 }
 
+// src/error-message.ts
+function toErrorMessage(e) {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null) {
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
+  }
+  return String(e);
+}
+
+// src/kill-chain.ts
+var logger = getLogger("subagents");
+var MS_PER_SECOND = 1e3;
+var SIGKILL_REAP_TIMEOUT_MS = 1e4;
+async function killChain(child, opts) {
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+  const exited = waitForExit(child);
+  safeKill(child, "SIGTERM");
+  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
+  if (graceful === "settled") return "terminated";
+  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
+  if (opts.escalationNote !== void 0) {
+    logger.warn(
+      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`
+    );
+  }
+  safeKill(child, "SIGKILL");
+  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
+  return "killed";
+}
+function safeKill(child, signal) {
+  try {
+    child.kill(signal);
+  } catch (err) {
+    logger.debug(
+      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`
+    );
+  }
+}
+function waitForExit(child) {
+  return new Promise((resolve) => {
+    if (child.exitCode !== null || child.signalCode !== null) {
+      resolve();
+      return;
+    }
+    child.once("exit", () => resolve());
+  });
+}
+function raceTimeout(p, ms, unref = false) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve("timeout"), ms);
+    if (unref) timer.unref();
+    p.then(
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      },
+      () => {
+        clearTimeout(timer);
+        resolve("settled");
+      }
+    );
+  });
+}
+
 // src/spawn.ts
-var logger = getLogger("engine-sdk/spawn");
+var logger2 = getLogger("engine-sdk/spawn");
+var ENGINE_ABORT_KILL_GRACE_MS = 3e4;
 var FORBIDDEN_OPTION_KEYS = ["detached", "stdio", "stdin", "windowsHide"];
 function spawnEngineChild(opts) {
   for (const key of FORBIDDEN_OPTION_KEYS) {
@@ -98,7 +168,12 @@ function spawnEngineChild(opts) {
     opts.signal.addEventListener(
       "abort",
       () => {
-        child.kill("SIGTERM");
+        safeKill(child, "SIGCONT");
+        void killChain(child, {
+          graceMs: ENGINE_ABORT_KILL_GRACE_MS,
+          unrefTimers: true,
+          escalationNote: `engine child (pid ${child.pid ?? "unknown"}) abort`
+        });
       },
       { once: true }
     );
@@ -114,7 +189,7 @@ function resolveHostRequestTimeoutMs(opts) {
   if (raw === void 0 || raw === "") return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
   const parsed = Number(raw);
   if (!Number.isInteger(parsed) || parsed <= 0) {
-    logger.warn(
+    logger2.warn(
       `invalid ${ENGINE_HOST_REQUEST_TIMEOUT_ENV}=${JSON.stringify(raw)}, falling back to ${DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS}ms`
     );
     return DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS;
@@ -126,7 +201,7 @@ function killOwnProcessGroup() {
   try {
     process.kill(-pid, "SIGKILL");
   } catch (err) {
-    logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
+    logger2.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
     process.kill(pid, "SIGKILL");
   }
 }
@@ -141,7 +216,7 @@ function armEngineSelfDestruct(opts) {
     clearInterval(timer);
     opts.stdin.removeAllListeners?.("end");
     opts.stdin.removeAllListeners?.("close");
-    logger.warn(`engine self-destruct: ${reason}`);
+    logger2.warn(`engine self-destruct: ${reason}`);
     killSelf();
   };
   opts.stdin.once("end", () => destroy("host stdin EOF (end)"));
@@ -193,6 +268,7 @@ function pumpNdjsonLines(stream, onLine) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
   pumpNdjsonLines,

package/dist/spawn.d.cts

@@ -13,9 +13,20 @@ interface SpawnEngineChildOptions {
     /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
     stdout?: "pipe" | "ignore" | "inherit";
     stderr?: "pipe" | "ignore" | "inherit";
-    /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
+    /**
+     * AbortSignal 触发即杀子（缺省无）。杀链 = SIGCONT 前置 + SIGTERM →
+     * ENGINE_ABORT_KILL_GRACE_MS grace → SIGKILL 完整阶梯（killChain 单源）——
+     * 裸 SIGTERM 单发对忽略/冻结/卡死的子进程永不收敛，run 悬挂至宿主回收层兜底。
+     */
     signal?: AbortSignal;
 }
+/**
+ * abort 杀链的 SIGTERM 优雅窗口（ms）。量级对齐 pi 引擎 PI_KILL_GRACE_MS 现状
+ * 校准值 30s（pi 子进程 trap SIGTERM 后 graceful shutdown 的实测量级，race-F4）；
+ * zcode abort 路径由「裸 SIGTERM 单发、永不升级」升级为同窗有界兜底（任务级正常
+ * 路径不加墙钟、回收层统一有界兜底口径）。
+ */
+declare const ENGINE_ABORT_KILL_GRACE_MS = 30000;
 /**
  * 引擎任务子进程唯一 spawn 入口。
  *
@@ -77,4 +88,4 @@ declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): Reverse
  */
 declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
 
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.d.ts

@@ -13,9 +13,20 @@ interface SpawnEngineChildOptions {
     /** 子进程 stdout/stderr 形态；缺省 'pipe'（协议帧走 stdout，stderr 走日志/轮转） */
     stdout?: "pipe" | "ignore" | "inherit";
     stderr?: "pipe" | "ignore" | "inherit";
-    /** AbortSignal 触发即 SIGTERM 杀子（缺省无） */
+    /**
+     * AbortSignal 触发即杀子（缺省无）。杀链 = SIGCONT 前置 + SIGTERM →
+     * ENGINE_ABORT_KILL_GRACE_MS grace → SIGKILL 完整阶梯（killChain 单源）——
+     * 裸 SIGTERM 单发对忽略/冻结/卡死的子进程永不收敛，run 悬挂至宿主回收层兜底。
+     */
     signal?: AbortSignal;
 }
+/**
+ * abort 杀链的 SIGTERM 优雅窗口（ms）。量级对齐 pi 引擎 PI_KILL_GRACE_MS 现状
+ * 校准值 30s（pi 子进程 trap SIGTERM 后 graceful shutdown 的实测量级，race-F4）；
+ * zcode abort 路径由「裸 SIGTERM 单发、永不升级」升级为同窗有界兜底（任务级正常
+ * 路径不加墙钟、回收层统一有界兜底口径）。
+ */
+declare const ENGINE_ABORT_KILL_GRACE_MS = 30000;
 /**
  * 引擎任务子进程唯一 spawn 入口。
  *
@@ -77,4 +88,4 @@ declare function armEngineSelfDestruct(opts: EngineSelfDestructOptions): Reverse
  */
 declare function pumpNdjsonLines(stream: NodeJS.ReadableStream | null | undefined, onLine: (line: string) => void): void;
 
-export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };
+export { DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS, ENGINE_ABORT_KILL_GRACE_MS, ENGINE_HOST_REQUEST_TIMEOUT_ENV, type EngineChildEnv, type EngineSelfDestructOptions, type ReverseRequestClock, type SpawnEngineChildOptions, armEngineSelfDestruct, pumpNdjsonLines, spawnEngineChild };

package/dist/spawn.js

@@ -1,14 +1,19 @@
 import {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-CNQTJJF5.js";
+} from "./chunk-HERD6RIR.js";
+import "./chunk-RCT7L777.js";
+import "./chunk-PYO3YR7W.js";
+import "./chunk-SFNTX7Q3.js";
 import "./chunk-75QEMUGV.js";
 import "./chunk-JSBRDJBE.js";
 export {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
+  ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
   pumpNdjsonLines,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/subagent-engine-sdk",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Engine-side SDK for the subagent engine protocol: NDJSON stdio contract types, engine primitives (schema emulation, nesting guard, kill chain, journal replay projection, data-dir/paths resolution) — the shared contract root between subagent-core and engine CLI packages (engines import SDK only, never core)",
   "type": "module",
   "license": "MIT",

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

@@ -1,118 +0,0 @@
-import { b as AgentEvent, E as EngineCapabilities } from './contract-types-DaULkdpG.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;
-
-/** 协议核心错误码（引擎 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;
-
-export { ENGINE_ERROR_CODE_PREFIX as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, STDOUT_TAIL_ECHO_CHARS as S, ENGINE_PROTOCOL_ERROR_CODES as a, ENGINE_TIMEOUT_RECOVERY as b, type EngineProtocolErrorCode as c, EngineSdkError as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, type SuccessResponseFrame as j, assertChatConversationSupported as k, engineConversationUnsupportedError as l, engineProtocolMismatchError as m, engineTimeoutDetail as n, isEngineErrorPassthroughCode as o, isEngineProtocolErrorCode as p, isNotificationFrame as q, isRequestFrame as r, isResponseFrame as s, isReverseRequestFrame as t, schemaEmulationFailedDetail as u };