@zhushanwen/subagent-engine-sdk 0.10.1 → 0.12.0

package/dist/{chunk-AF2ETADP.js → chunk-2L3I2TWJ.js}

@@ -13,8 +13,6 @@ var ENGINE_ENV_DENY_LIST = [
   "TAIJI_AGENT_PACKAGED",
   "TAIJI_RUNTIME_TOKEN",
   "TAIJI_AGENT_API_KEY",
-  "TAIJI_SUBAGENT_RELAY_SESSION_ID",
-  "TAIJI_SUBAGENT_RELAY_RECORD_ID",
   // 预设回落事实（env 名 SSOT = shared PRESET_FALLBACK_ENV_KEYS）：「本进程本次运行」
   // 事实只对 runtime 直接 spawn 的 pi 成立，引擎一跳继承会造成子 agent pi 假披露
   "TAIJI_PRESET_FALLBACK_FROM",
@@ -25,9 +23,11 @@ var ENGINE_ENV_L0_INFRA_KEYS = [
   "TAIJI_AGENT_ENGINE_NODE",
   "ELECTRON_RUN_AS_NODE",
   "TAIJI_AGENT_SUBAGENT",
-  "TAIJI_SUBAGENT_RELAY_SOCKET",
-  "TAIJI_SUBAGENT_RELAY_NODE",
-  "TAIJI_SUBAGENT_RELAY_SCRIPT"
+  // [M3] control 两键（键名 SSOT = src/control-env.ts）：runtime 注入主 pi 与引擎的
+  // L0 基础设施键，嵌套 task pi 经引擎出站 env 继承同值。刻意不进 ENGINE_ENV_DENY_LIST：
+  // 引擎/嵌套 extension 是合法读者（transport 选择谓词 + engine_open 归属键）。
+  "TAIJI_SUBAGENT_CONTROL_SOCKET",
+  "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID"
 ];
 var ENV_PREFIX_SHAPE_RE = /^[A-Za-z0-9_]+$/;
 function deleteEnvKeysCaseInsensitive(env, names) {
@@ -81,11 +81,6 @@ function injectL0InfraKeys(env, opts) {
   if (opts.engineNode !== void 0) env.TAIJI_AGENT_ENGINE_NODE = opts.engineNode;
   if (opts.electronRunAsNode === true) env.ELECTRON_RUN_AS_NODE = "1";
   env.TAIJI_AGENT_SUBAGENT = "1";
-  if (opts.relay !== void 0) {
-    env.TAIJI_SUBAGENT_RELAY_SOCKET = opts.relay.socket;
-    env.TAIJI_SUBAGENT_RELAY_NODE = opts.relay.node;
-    env.TAIJI_SUBAGENT_RELAY_SCRIPT = opts.relay.script;
-  }
   if (opts.identityEnv !== void 0) {
     for (const [key, value] of Object.entries(opts.identityEnv)) {
       if (value !== void 0) env[key] = value;

package/dist/{chunk-HSNDUHFH.js → chunk-3MCOZY3Z.js}

@@ -1,7 +1,7 @@
 import {
   killChain,
   safeKill
-} from "./chunk-CNCFMPEH.js";
+} from "./chunk-TJMS3YOR.js";
 import {
   getLogger
 } from "./chunk-NXNNXGTY.js";
@@ -58,13 +58,40 @@ function resolveHostRequestTimeoutMs(opts) {
   }
   return parsed;
 }
-function killOwnProcessGroup() {
+function killOwnProcessGroup(deps = {}) {
   const pid = process.pid;
+  const kill = deps.killFn ?? ((targetPid, signal) => process.kill(targetPid, signal));
+  if ((deps.platform ?? process.platform) === "win32") {
+    const fallbackSelfKill = (reason) => {
+      logger.warn(`taskkill self-tree failed (${reason}); falling back to self SIGKILL`);
+      try {
+        kill(pid, "SIGKILL");
+      } catch (err) {
+        logger.warn(
+          `self SIGKILL fallback failed (${String(err)}); descendant pi may linger until runtime sweep`
+        );
+      }
+    };
+    const spawnFn = deps.spawnFn ?? ((command, args, options) => spawn(command, [...args], options));
+    try {
+      const child = spawnFn("taskkill", ["/PID", String(pid), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      child.on("error", (err) => {
+        fallbackSelfKill(String(err));
+      });
+      child.unref?.();
+    } catch (err) {
+      fallbackSelfKill(`spawn threw: ${String(err)}`);
+    }
+    return;
+  }
   try {
-    process.kill(-pid, "SIGKILL");
+    kill(-pid, "SIGKILL");
   } catch (err) {
     logger.warn(`process-group kill failed (${String(err)}), falling back to self kill`);
-    process.kill(pid, "SIGKILL");
+    kill(pid, "SIGKILL");
   }
 }
 function armEngineSelfDestruct(opts) {
@@ -133,6 +160,7 @@ export {
   spawnEngineChild,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
+  killOwnProcessGroup,
   armEngineSelfDestruct,
   pumpNdjsonLines
 };

package/dist/{chunk-LM7P7OTA.js → chunk-7R6HYT2A.js}

@@ -30,12 +30,39 @@ var REVERSE_CHANNEL_TIMEOUT_CLASS = {
   "host/askUser": "interaction"
 };
 
+// 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",
@@ -43,16 +70,35 @@ 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",
   // noop-safe: 纯活性信号，双侧 reducer 恒 no-op（协议语义见 AgentEvent 头注），丢弃零差异
   "error",
   // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺 lastError 诊断留痕，已写状态不回滚
-  "armed"
+  "armed",
   // noop-safe: 旧宿主无武装等待窗消费点（fail-fast 属宿主新增逻辑），丢弃仅缺武装留痕，schema 强制第一道防线（引擎自查断言）不受损
+  "auto_retry"
+  // noop-safe: 旧宿主 default 分支零写入——丢弃仅缺重试边界留痕（journal 不可查失败尝试轨迹），轮成败判定与 turns/usage 计账不受损（P5 计账锚在引擎侧收尾快照，不依赖宿主消费本帧）
 ];
+var _EventVocabSyncLock = true;
+var FAILURE_CAUSE_CLOSED_KINDS = [
+  "rate_limited",
+  "protocol_unsupported",
+  "turn_budget_exhausted",
+  "timeout",
+  "no_deliverable",
+  "cancelled"
+];
+var FAILURE_CAUSE_KIND_VOCAB_LOCK = true;
+var FAILURE_CAUSE_KINDS_BY_CLASS = {
+  provider: ["rate_limited", "protocol_unsupported"],
+  harness: ["turn_budget_exhausted", "timeout"],
+  agent: ["no_deliverable"],
+  user: ["cancelled"]
+};
+var FAILURE_CAUSE_KINDS_BY_CLASS_LOCK = true;
 
 // src/protocol/schema.ts
 var ANY_JSON = {};
@@ -125,7 +171,7 @@ var notificationFrameSchema = {
             type: {
               type: "string",
               // 事件 enum 从词表 SSOT 派生（U2 词表锁：union⟷词表互证后，此处不再
-              // 手写字面量集合——手写即漂移面，病灶 1 的第三处同步点）
+              // 手写字面量集合——手写即漂移点，问题点 1 的第三处同步点）
               enum: [...AGENT_EVENT_TYPE_NAMES]
             }
           }
@@ -187,7 +233,17 @@ export {
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  isSubagentControlFrameKind,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  isSubagentControlClosedReason,
   AGENT_EVENT_TYPE_NAMES,
+  _EventVocabSyncLock,
+  FAILURE_CAUSE_CLOSED_KINDS,
+  FAILURE_CAUSE_KIND_VOCAB_LOCK,
+  FAILURE_CAUSE_KINDS_BY_CLASS,
+  FAILURE_CAUSE_KINDS_BY_CLASS_LOCK,
   protocolErrorSchema,
   requestFrameSchema,
   successResponseFrameSchema,

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

@@ -12,6 +12,30 @@ var SET_MODEL_REQUEST_TIMEOUT_MS = 1e4;
 var STDERR_TAIL_CHARS = 400;
 
 // 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 快照型失败行）。 */
@@ -56,7 +80,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 };
   }
@@ -117,6 +141,10 @@ export {
   SET_MODEL_STAGE_TIMEOUT_MS,
   SET_MODEL_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
+  ENGINE_SPAWN_DELIVERY_ERROR_CODES,
+  ENGINE_TRANSPORT_ERROR_CODES,
+  ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY,
+  ENGINE_TRANSPORT_ERROR_RECOVERY,
   SET_MODEL_ERROR_CODES,
   SET_MODEL_NOT_ACTIVE_CODE,
   ENGINE_PROTOCOL_ERROR_CODES,

package/dist/{chunk-NTOLHLCL.js → chunk-QGXILDWB.js}

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

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

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

package/dist/{chunk-SGAIDL63.js → chunk-U5MBAKS5.js}

@@ -31,7 +31,8 @@ function createReplayRecord() {
     turns: [emptyTurn()],
     turnCount: 0,
     totalTokens: 0,
-    lastError: void 0
+    lastError: void 0,
+    errors: []
   };
 }
 function currentTurn(record) {
@@ -125,7 +126,11 @@ function applyTurnEnd(record) {
   turn.closed = true;
   turn.closedTs = Date.now();
   record.turnCount += 1;
-  record.lastError = void 0;
+}
+function appendErrorFact(record, message) {
+  if (!message) return;
+  (record.errors ??= []).push({ message, at: Date.now() });
+  record.lastError = message;
 }
 function applyMessageEnd(record, event) {
   if (event.usage) {
@@ -134,11 +139,11 @@ function applyMessageEnd(record, event) {
     record.totalTokens += (event.usage.input ?? 0) + (event.usage.output ?? 0) + (event.usage.cacheRead ?? 0) + (event.usage.cacheWrite ?? 0);
   }
   if (event.error) {
-    record.lastError = event.error;
+    appendErrorFact(record, event.error);
   }
 }
 function applyErrorEvent(record, event) {
-  record.lastError = event.message;
+  appendErrorFact(record, event.message);
 }
 function updateFromEvent(record, event) {
   switch (event.type) {
@@ -152,13 +157,13 @@ function updateFromEvent(record, event) {
       return applyToolStart(record, event);
     case "tool_end":
       return applyToolEnd(record, event);
-    // ── turn_end：闭合当前 turn ──
+    // ── turn_end：结束当前 turn ──
     case "turn_end":
       return applyTurnEnd(record);
     // ── message_end：usage 增量累加 + totalTokens 累加 ──
     case "message_end":
       return applyMessageEnd(record, event);
-    // ── error：存 record.lastError ──
+    // ── error：appendErrorFact 入账（errors 只追加 + lastError 派生）──
     case "error":
       return applyErrorEvent(record, event);
     // ── compaction：不产生数据（不变）──
@@ -168,10 +173,16 @@ function updateFromEvent(record, event) {
     case "activity":
       return;
     // ── armed：武装确认回执（[D3 协议版 P6]，协议语义见 contract-types）——监控
-    //    信号不进 record 投影，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
+    //    信号不进 record 派生视图，消费方 = 宿主等待门 + run 事件 journal（C3 第④步
     //    双侧 reducer no-op 义务的 SDK 侧）
     case "armed":
       return;
+    // ── auto_retry：pi 原生重试边界帧（[subagent-observability §3.3.1 P5]）——
+    //    观测面（journal 留痕失败尝试轨迹），不进 record 派生视图：失败尝试的
+    //    turns/usage 切片与 retryAttempts 计数由引擎收尾快照一次产出（outcome
+    //    字段承载），reducer 写入会让失败尝试静默混进 turns 聚合，恰违背 P5 计账。
+    case "auto_retry":
+      return;
     default: {
       const _exhaustive = event;
       return _exhaustive;
@@ -226,7 +237,10 @@ function sessionIdFromHandle(handle) {
 }
 
 export {
+  addUsage,
+  emptyTurn,
   createReplayRecord,
+  appendErrorFact,
   updateFromEvent,
   toReplayedTurn,
   aggregateUsage,

package/dist/cli-entry.d.cts

@@ -5,7 +5,7 @@
 interface CliProtocolServerSink {
     /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
     handleFrame(frame: unknown): void;
-    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    /** 数据范围反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
     reverseRequest(method: string, params: unknown): Promise<unknown>;
 }
 /** runEngineCliEntry 参数。 */

package/dist/cli-entry.d.ts

@@ -5,7 +5,7 @@
 interface CliProtocolServerSink {
     /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
     handleFrame(frame: unknown): void;
-    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    /** 数据范围反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
     reverseRequest(method: string, params: unknown): Promise<unknown>;
 }
 /** runEngineCliEntry 参数。 */