@zhushanwen/subagent-engine-sdk 0.10.1 → 0.11.0

package/dist/index.js

@@ -1,14 +1,3 @@
-import {
-  RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES,
-  RELAY_PROTOCOL_VERSION,
-  isRelayActive,
-  readRelayForwardEnv
-} from "./chunk-GSW3DMN6.js";
 import {
   bestEffort
 } from "./chunk-QMEHSKNR.js";
@@ -52,22 +41,23 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-AF2ETADP.js";
+} from "./chunk-2L3I2TWJ.js";
 import {
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   ENGINE_ABORT_KILL_GRACE_MS,
   ENGINE_HOST_REQUEST_TIMEOUT_ENV,
   armEngineSelfDestruct,
+  killOwnProcessGroup,
   pumpNdjsonLines,
   spawnEngineChild
-} from "./chunk-HSNDUHFH.js";
+} from "./chunk-3MCOZY3Z.js";
 import {
   ENGINE_NODE_ENV,
   hostKindOf,
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-NTOLHLCL.js";
+} from "./chunk-QGXILDWB.js";
 import {
   DEFAULT_STDERR_KEEP_DAYS,
   DEFAULT_STDERR_MAX_BYTES,
@@ -86,14 +76,19 @@ import {
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   errorResponseFrameSchema,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "./chunk-LM7P7OTA.js";
+} from "./chunk-QBXDEF4N.js";
 import {
   isNotificationFrame,
   isRequestFrame,
@@ -122,7 +117,7 @@ import {
   probePidAlive,
   safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-CNCFMPEH.js";
+} from "./chunk-TJMS3YOR.js";
 import {
   toErrorMessage
 } from "./chunk-PYO3YR7W.js";
@@ -131,7 +126,11 @@ import {
   ENGINE_ERROR_CODE_PREFIX,
   ENGINE_PROTOCOL_ERROR_CODES,
   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,
   HANDSHAKE_TIMEOUT_MS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -151,7 +150,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "./chunk-JZN76I3S.js";
+} from "./chunk-NVF3PADP.js";
 import {
   configureLoggerSink,
   getLogger,
@@ -164,7 +163,7 @@ import {
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-SGAIDL63.js";
+} from "./chunk-YFSNX3N3.js";
 import "./chunk-JSBRDJBE.js";
 
 // src/identity-env.ts
@@ -194,37 +193,19 @@ var SUBAGENT_IDENTITY_ENV = {
   /** worktree 隔离标志（"true" = 是）。 */
   worktree: "PI_SUBAGENT_WORKTREE"
 };
+var PI_SUBAGENT_TASK_MAX_CHARS = 2e3;
 
-// src/relay-frames.ts
-var RELAY_FRAME_KINDS = {
-  handshake: "handshake",
-  accept: "accept",
-  reject: "reject",
-  data: "data",
-  exit: "exit",
-  /**
-   * goodbye（代理 → runtime，v1）：代理被宿主终止（SIGTERM/SIGINT）前的预告帧——
-   * 宿主侧的正常收割（agent_settled 后杀代理）与异常断连（宿主崩溃/主 pi 死）在
-   * runtime 侧都表现为 socket close，无法区分；goodbye 让正常收割显式自报，runtime
-   * 据此把后续 close 的日志从 warn（kill-on-disconnect）降级为 info（reaped，正常
-   * teardown）。kill 行为本身不变（预告后 child 仍由 runtime 收割）。
-   */
-  goodbye: "goodbye"
-};
-var RELAY_FRAME_DIRS = {
-  down: "down",
-  up: "up",
-  upStderr: "up-stderr"
-};
-var RELAY_REJECT_REASONS = {
-  version: "version",
-  identity: "identity",
-  duplicate: "duplicate",
-  malformed: "malformed"
-};
+// src/control-env.ts
+var CONTROL_ENV_SOCKET = "TAIJI_SUBAGENT_CONTROL_SOCKET";
+var CONTROL_ENV_ROOT_SESSION_ID = "TAIJI_SUBAGENT_CONTROL_ROOT_SESSION_ID";
+function isControlEnvActive(env) {
+  return Boolean(env[CONTROL_ENV_SOCKET]);
+}
 export {
   AGENT_EVENT_TYPE_NAMES,
   CANCEL_SETTLE_GRACE_MS,
+  CONTROL_ENV_ROOT_SESSION_ID,
+  CONTROL_ENV_SOCKET,
   DEFAULT_ENGINE_HOST_REQUEST_TIMEOUT_MS,
   DEFAULT_KILL_GRACE_MS,
   DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
@@ -240,7 +221,11 @@ export {
   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,
   ExecutionNestingContext,
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
@@ -248,17 +233,8 @@ export {
   HOST_TIMEOUT_ABORT_REASON,
   NESTED_SPAWN_ENV,
   NestedSpawnRejectedError,
+  PI_SUBAGENT_TASK_MAX_CHARS,
   PROTOCOL_METHODS,
-  RELAY_ENV_NODE,
-  RELAY_ENV_RECORD_ID,
-  RELAY_ENV_SCRIPT,
-  RELAY_ENV_SESSION_ID,
-  RELAY_ENV_SOCKET,
-  RELAY_EXIT_CODES,
-  RELAY_FRAME_DIRS,
-  RELAY_FRAME_KINDS,
-  RELAY_PROTOCOL_VERSION,
-  RELAY_REJECT_REASONS,
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
@@ -270,6 +246,9 @@ export {
   SHARED_POOL_KEY,
   STDERR_TAIL_CHARS,
   STDOUT_TAIL_ECHO_CHARS,
+  SUBAGENT_CONTROL_CLOSED_REASONS,
+  SUBAGENT_CONTROL_FRAME_KINDS,
+  SUBAGENT_CONTROL_PROTOCOL_VERSION,
   SUBAGENT_IDENTITY_ENV,
   SUPPORTED_PROTOCOL_RANGE,
   TAIJI_DATA_DIR_ENV,
@@ -300,17 +279,20 @@ export {
   extractAndValidateStructuredOutput,
   getLogger,
   hostKindOf,
+  isControlEnvActive,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
   isNotificationFrame,
   isPidAlive,
   isProtocolVersionCompatible,
-  isRelayActive,
   isRequestFrame,
   isResponseFrame,
   isReverseRequestFrame,
+  isSubagentControlClosedReason,
+  isSubagentControlFrameKind,
   isUiResponse,
   killChain,
+  killOwnProcessGroup,
   killPidChain,
   notificationFrameSchema,
   parseChannel,
@@ -319,7 +301,6 @@ export {
   probePidAlive,
   protocolErrorSchema,
   pumpNdjsonLines,
-  readRelayForwardEnv,
   replayJournal,
   requestFrameSchema,
   resetDataDirWarnForTests,

package/dist/journal-io.d.cts

@@ -1,4 +1,4 @@
-import { A as AgentEvent } from './contract-types-jSa1g28F.cjs';
+import { A as AgentEvent } from './contract-types-BUHUMF9R.cjs';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-io.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentEvent } from './contract-types-jSa1g28F.js';
+import { A as AgentEvent } from './contract-types-BUHUMF9R.js';
 
 /**
  * 重放 journal：读取路径下全部事件，重放即得 AgentEvent 流（read 第②级）。

package/dist/journal-replay.cjs

@@ -181,7 +181,7 @@ 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 累加 ──
@@ -197,7 +197,7 @@ 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;

package/dist/journal-replay.d.cts

@@ -1,4 +1,4 @@
-import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-jSa1g28F.cjs';
+import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-BUHUMF9R.cjs';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
@@ -13,12 +13,12 @@ interface ReplayRecordView {
 /** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
 declare function createReplayRecord(): ReplayRecordView;
 /**
- * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ * 从 AgentEvent 更新 record。所有数据收敛进 record.turns[]。
  *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
  *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
  *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
- *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
- *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - turn_end：结束当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     正常结束清 lastError（瞬态 error 恢复后不应误判 success=false）
  *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
  *     totalTokens 累加
  *   - error：存 record.lastError（getEventLog 派生 error 条目用）

package/dist/journal-replay.d.ts

@@ -1,4 +1,4 @@
-import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-jSa1g28F.js';
+import { T as Turn, a as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-BUHUMF9R.js';
 
 /**
  * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
@@ -13,12 +13,12 @@ interface ReplayRecordView {
 /** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
 declare function createReplayRecord(): ReplayRecordView;
 /**
- * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ * 从 AgentEvent 更新 record。所有数据收敛进 record.turns[]。
  *   - text/thinking：流式累积进 currentTurn()（完整内容，非切片）
  *   - tool_start/end：push 进 currentTurn().toolCalls（含完整 result）
  *     tool_end 跨 turn 扫描找 running 同名 toolCall（兜底滞后事件）
- *   - turn_end：闭合当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
- *     正常闭合清 lastError（瞬态 error 恢复后不应误判 success=false）
+ *   - turn_end：结束当前 turn，记 closedTs（真实墙钟，供 getEventLog）；
+ *     正常结束清 lastError（瞬态 error 恢复后不应误判 success=false）
  *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
  *     totalTokens 累加
  *   - error：存 record.lastError（getEventLog 派生 error 条目用）

package/dist/journal-replay.js

@@ -5,7 +5,7 @@ import {
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-SGAIDL63.js";
+} from "./chunk-YFSNX3N3.js";
 import "./chunk-JSBRDJBE.js";
 export {
   aggregateUsage,

package/dist/kill-chain.d.cts

@@ -1,4 +1,4 @@
-import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-jSa1g28F.cjs';
+import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-BUHUMF9R.cjs';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
@@ -49,7 +49,7 @@ declare function killChain(child: KillableChild, opts: KillChainOptions): Promis
 /**
  * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
  * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
- * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ * no-op）。收敛自 zcode launcher 的内联实现（对齐点②：单一权威）。
  */
 declare function safeKill(child: KillableChild, signal: NodeJS.Signals): void;
 /**
@@ -64,7 +64,7 @@ declare function probePidAlive(pid: number): boolean | undefined;
 interface PidChainOptions {
     /**
      * SIGTERM 优雅窗口（ms）。缺省 DEFAULT_KILL_GRACE_MS。回收场景的调用方通常
-     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用组杀
+     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用按进程组终止
      * 收割惯例（5s）。
      */
     graceMs?: number;
@@ -73,8 +73,8 @@ interface PidChainOptions {
 }
 /**
  * [D9-2 半径收窄原语] run 级 pid 杀链：SIGTERM → graceMs → 仍存活则 SIGKILL，
- * **只打单 pid，绝不组杀**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
- * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 组杀不可达；
+ * **只打单 pid，绝不按进程组终止**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
+ * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 按进程组终止不可达；
  * 本原语逐 pid 退化单杀，语义 = 「该 run 的进程拓扑」而非引擎组）。
  *
  * fire-and-forget：宿主非进程持有方，无 exit 事件可等（对齐 core reaper 的

package/dist/kill-chain.d.ts

@@ -1,4 +1,4 @@
-import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-jSa1g28F.js';
+import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-BUHUMF9R.js';
 
 /**
  * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
@@ -49,7 +49,7 @@ declare function killChain(child: KillableChild, opts: KillChainOptions): Promis
 /**
  * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
  * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
- * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
+ * no-op）。收敛自 zcode launcher 的内联实现（对齐点②：单一权威）。
  */
 declare function safeKill(child: KillableChild, signal: NodeJS.Signals): void;
 /**
@@ -64,7 +64,7 @@ declare function probePidAlive(pid: number): boolean | undefined;
 interface PidChainOptions {
     /**
      * SIGTERM 优雅窗口（ms）。缺省 DEFAULT_KILL_GRACE_MS。回收场景的调用方通常
-     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用组杀
+     * 已先行优雅停止（cancel 帧 SIGTERM），本窗只是宿主侧升级兜底，量级沿用按进程组终止
      * 收割惯例（5s）。
      */
     graceMs?: number;
@@ -73,8 +73,8 @@ interface PidChainOptions {
 }
 /**
  * [D9-2 半径收窄原语] run 级 pid 杀链：SIGTERM → graceMs → 仍存活则 SIGKILL，
- * **只打单 pid，绝不组杀**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
- * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 组杀不可达；
+ * **只打单 pid，绝不按进程组终止**（宿主对引擎孙进程只持镜像 pid、不持 ChildProcess——
+ * 引擎以 detached:true 自成进程组，孙进程在其组内而非自任组长，负 pid 按进程组终止不可达；
  * 本原语逐 pid 退化单杀，语义 = 「该 run 的进程拓扑」而非引擎组）。
  *
  * fire-and-forget：宿主非进程持有方，无 exit 事件可等（对齐 core reaper 的

package/dist/kill-chain.js

@@ -8,9 +8,9 @@ import {
   probePidAlive,
   safeKill,
   synthesizeTimeoutOutcome
-} from "./chunk-CNCFMPEH.js";
+} from "./chunk-TJMS3YOR.js";
 import "./chunk-PYO3YR7W.js";
-import "./chunk-JZN76I3S.js";
+import "./chunk-NVF3PADP.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {

package/dist/logger.d.cts

@@ -6,7 +6,7 @@ interface LoggerSink {
 }
 /** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
 type LogLevel = "debug" | "warn" | "error";
-/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
+/** logger 接口。与 core CoreLogger 结构兼容——迁移调用范围（方法名/参数序）逐文件等价。 */
 interface CoreLogger {
     debug(msg: string, data?: unknown): void;
     warn(msg: string, data?: unknown): void;

package/dist/logger.d.ts

@@ -6,7 +6,7 @@ interface LoggerSink {
 }
 /** 日志级别。对齐 core logger 的 LogLevel（三值，无 info）。 */
 type LogLevel = "debug" | "warn" | "error";
-/** logger 接口。与 core CoreLogger 结构兼容——迁移调用面（方法名/参数序）逐文件等价。 */
+/** logger 接口。与 core CoreLogger 结构兼容——迁移调用范围（方法名/参数序）逐文件等价。 */
 interface CoreLogger {
     debug(msg: string, data?: unknown): void;
     warn(msg: string, data?: unknown): void;

package/dist/logs/stderr-rotation.d.cts

@@ -1,12 +1,12 @@
 declare const DEFAULT_STDERR_MAX_BYTES: number;
 /** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
 declare const DEFAULT_STDERR_KEEP_DAYS = 7;
-/** 轮转参数（env 覆盖面 = 宿主 logger 同款 TAIJI_LOG_* 两键）。 */
+/** 轮转参数（env 覆盖范围 = 宿主 logger 同款 TAIJI_LOG_* 两键）。 */
 interface StderrRotationParams {
     maxBytes: number;
     keepDays: number;
 }
-/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
+/** 读 env 解析轮转参数（非法值回缺省——取证侧配置不拖垮主通道）。 */
 declare function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams;
 /** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
 declare function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string;
@@ -17,7 +17,7 @@ declare function isPidAlive(pid: number): boolean;
 /**
  * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
  * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
- * 文件——轮转是取证面优化，不是主通道）。
+ * 文件——轮转是取证侧优化，不是主通道）。
  */
 declare function rotateStderrLogIfNeeded(path: string, params: StderrRotationParams): boolean;
 interface CleanupResult {
@@ -28,7 +28,7 @@ interface CleanupResult {
 }
 /**
  * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
- * 零删除（取证面 best-effort）。
+ * 零删除（取证侧 best-effort）。
  */
 declare function cleanupStaleStderrLogs(logsDir: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
 /** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */

package/dist/logs/stderr-rotation.d.ts

@@ -1,12 +1,12 @@
 declare const DEFAULT_STDERR_MAX_BYTES: number;
 /** 缺省保留天数（与宿主 logger 同源缺省：7 天）。 */
 declare const DEFAULT_STDERR_KEEP_DAYS = 7;
-/** 轮转参数（env 覆盖面 = 宿主 logger 同款 TAIJI_LOG_* 两键）。 */
+/** 轮转参数（env 覆盖范围 = 宿主 logger 同款 TAIJI_LOG_* 两键）。 */
 interface StderrRotationParams {
     maxBytes: number;
     keepDays: number;
 }
-/** 读 env 解析轮转参数（非法值回缺省——取证面配置不拖垮主通道）。 */
+/** 读 env 解析轮转参数（非法值回缺省——取证侧配置不拖垮主通道）。 */
 declare function stderrRotationParams(env: NodeJS.ProcessEnv): StderrRotationParams;
 /** 实例维度 stderr tee 路径：<engineDataDir>/logs/<prefix><pid>.log。 */
 declare function stderrLogPathFor(engineDataDir: string, pid: number, prefix: string): string;
@@ -17,7 +17,7 @@ declare function isPidAlive(pid: number): boolean;
 /**
  * 尺寸轮转：当前文件超过 maxBytes 时 rename 为 `<path>.<时间戳>` 副本并返回
  * true（调用方懒重开新文件继续 append）。rename 失败返回 false（继续 append 原
- * 文件——轮转是取证面优化，不是主通道）。
+ * 文件——轮转是取证侧优化，不是主通道）。
  */
 declare function rotateStderrLogIfNeeded(path: string, params: StderrRotationParams): boolean;
 interface CleanupResult {
@@ -28,7 +28,7 @@ interface CleanupResult {
 }
 /**
  * 过期清理：扫描 logsDir 下同前缀文件，三判据同时成立才删。目录缺失/读失败返回
- * 零删除（取证面 best-effort）。
+ * 零删除（取证侧 best-effort）。
  */
 declare function cleanupStaleStderrLogs(logsDir: string, env: NodeJS.ProcessEnv, prefix: string, now?: number): CleanupResult;
 /** 便捷入口：对 tee 路径所在 logs 目录做过期清理（流打开时机调用，每代一次）。 */

package/dist/{methods-C2zvZqhP.d.ts → methods-BdIH3FwS.d.ts}

@@ -1,4 +1,4 @@
-import { M as ModelRef, d as EngineCapabilities, f as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.js';
+import { M as ModelRef, d as EngineCapabilities, f as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-BUHUMF9R.js';
 
 /**
  * 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。
@@ -24,7 +24,7 @@ interface RunContextParams {
     /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
     streamMode?: "stream" | "coarse";
     /**
-     * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+     * [F6] 根 session id——pi 引擎 engine_open 归属键的权威来源（生产三来源
      * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
      * 未知字段，undefined 不上 wire。
      */
@@ -94,14 +94,14 @@ interface InitializeParams {
     };
     engineConfig: Record<string, string>;
 }
-/** initialize 应答（仅诊断面：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
+/** initialize 应答（仅诊断范围：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
 interface InitializeResult {
     protocolVersion: number;
     engineId: string;
     engineVersion: string;
     adapterVersion: string;
     capabilities: EngineCapabilities;
-    /** 模型目录（诊断面；省略/null = 无枚举面语义）。 */
+    /** 模型目录（诊断范围；省略/null = 无枚举情形语义）。 */
     models?: ModelCatalogEntry[] | null;
 }
 interface ProbeParams {
@@ -147,7 +147,7 @@ interface ListModelsParams {
     _placeholder?: never;
 }
 interface ListModelsResult {
-    /** 数组 = 有枚举面；null = 无枚举面（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
+    /** 数组 = 有枚举；null = 无枚举情形（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
     models: ModelCatalogEntry[] | null;
 }
 interface ValidateModelParams {

package/dist/{methods-BLxg4ZFr.d.cts → methods-CHiDwvRK.d.cts}

@@ -1,4 +1,4 @@
-import { M as ModelRef, d as EngineCapabilities, f as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-jSa1g28F.cjs';
+import { M as ModelRef, d as EngineCapabilities, f as ModelCatalogEntry, b as AgentCallOpts, e as ResumeAnchor, E as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from './contract-types-BUHUMF9R.cjs';
 
 /**
  * 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。
@@ -24,7 +24,7 @@ interface RunContextParams {
     /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
     streamMode?: "stream" | "coarse";
     /**
-     * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+     * [F6] 根 session id——pi 引擎 engine_open 归属键的权威来源（生产三来源
      * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
      * 未知字段，undefined 不上 wire。
      */
@@ -94,14 +94,14 @@ interface InitializeParams {
     };
     engineConfig: Record<string, string>;
 }
-/** initialize 应答（仅诊断面：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
+/** initialize 应答（仅诊断范围：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
 interface InitializeResult {
     protocolVersion: number;
     engineId: string;
     engineVersion: string;
     adapterVersion: string;
     capabilities: EngineCapabilities;
-    /** 模型目录（诊断面；省略/null = 无枚举面语义）。 */
+    /** 模型目录（诊断范围；省略/null = 无枚举情形语义）。 */
     models?: ModelCatalogEntry[] | null;
 }
 interface ProbeParams {
@@ -147,7 +147,7 @@ interface ListModelsParams {
     _placeholder?: never;
 }
 interface ListModelsResult {
-    /** 数组 = 有枚举面；null = 无枚举面（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
+    /** 数组 = 有枚举；null = 无枚举情形（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
     models: ModelCatalogEntry[] | null;
 }
 interface ValidateModelParams {

package/dist/node-executor.cjs

@@ -67,7 +67,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 };
   }

package/dist/node-executor.d.cts

@@ -1,14 +1,14 @@
-/** L0 注入的引擎执行器路径 env（与 relay 的 TAIJI_SUBAGENT_RELAY_NODE 不复用）。 */
+/** L0 注入的引擎执行器路径 env。 */
 declare const ENGINE_NODE_ENV = "TAIJI_AGENT_ENGINE_NODE";
 /**
- * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
+ * 探针：验证执行器能以纯 node 语义执行 JS。
  *
  * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
  * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
  * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
  */
 declare function probeNodeExecutor(execPath: string, isElectron: boolean): Promise<boolean>;
-/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
+/** 测试钩子：清探针缓存（生产无调用方）。 */
 declare function resetEngineNodeProbeCache(): void;
 /** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
 type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
@@ -41,7 +41,7 @@ interface EngineNodeLaunch {
  * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
  *
  * 判定序（与规格逐行对应）：
- *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
+ *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入通道）；
  *   pi-extension → 注入执行器（env TAIJI_AGENT_ENGINE_NODE），缺失/探针失败 =
  *     engine_not_found + 指引；
  *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；

package/dist/node-executor.d.ts

@@ -1,14 +1,14 @@
-/** L0 注入的引擎执行器路径 env（与 relay 的 TAIJI_SUBAGENT_RELAY_NODE 不复用）。 */
+/** L0 注入的引擎执行器路径 env。 */
 declare const ENGINE_NODE_ENV = "TAIJI_AGENT_ENGINE_NODE";
 /**
- * 探针：验证执行器能以纯 node 语义执行 JS（先例 = runtime relay-env.ts:47-90）。
+ * 探针：验证执行器能以纯 node 语义执行 JS。
  *
  * 为什么需要：打包态 pi 宿主的候选执行器可能是 Electron 二进制——直接当 node 用会
  * 拉起 GUI，必须同 env 注入 ELECTRON_RUN_AS_NODE=1 才是纯 node 模式；探针被证伪则
  * 按矩阵① 报 engine_not_found（带可操作指引），不静默回落 PATH 探测。
  */
 declare function probeNodeExecutor(execPath: string, isElectron: boolean): Promise<boolean>;
-/** 测试钩子：清探针缓存（生产无调用方；与 relay-env resetRelayNodeProbeCache 同款）。 */
+/** 测试钩子：清探针缓存（生产无调用方）。 */
 declare function resetEngineNodeProbeCache(): void;
 /** 宿主形态（矩阵行；EngineClient 的 hostKind 自由字符串经 hostKindOf 归一）。 */
 type EngineNodeHostKind = "pi-extension" | "runtime-sidecar" | "standalone";
@@ -41,7 +41,7 @@ interface EngineNodeLaunch {
  * （EngineClient / runtime）持有各自的平台参数（detached / 进程组收割语义）。
  *
  * 判定序（与规格逐行对应）：
- *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入面）；
+ *   Windows + entry .cmd → cmd.exe /c 显式形态（禁 shell:true 的注入通道）；
  *   pi-extension → 注入执行器（env TAIJI_AGENT_ENGINE_NODE），缺失/探针失败 =
  *     engine_not_found + 指引；
  *   runtime-sidecar → process.execPath（Electron 时 electronRunAsNode，探针先行）；

package/dist/node-executor.js

@@ -4,8 +4,8 @@ import {
   probeNodeExecutor,
   resetEngineNodeProbeCache,
   resolveEngineNodeLaunch
-} from "./chunk-NTOLHLCL.js";
-import "./chunk-JZN76I3S.js";
+} from "./chunk-QGXILDWB.js";
+import "./chunk-NVF3PADP.js";
 import "./chunk-JSBRDJBE.js";
 export {
   ENGINE_NODE_ENV,