@zhushanwen/subagent-engine-sdk 0.10.1 → 0.12.0

package/dist/journal-replay.d.ts

@@ -1,7 +1,18 @@
-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 AgentUsage, b as AgentUsageTotal, A as AgentEvent, S as SessionView, E as EngineHandleData, R as ReplayedTurn } from './contract-types-C1scOS_M.js';
 
 /**
- * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这四个字段）。
+ * 轮失败事实（subagent-observability §3.3.5：失败事实只追加进 errors 数组，
+ * lastError 由「最后一个非空轮失败」派生——数组只追加且空串不入账，
+ * 尾项即最后一个非空失败）。事实源记录，append-only，不因后续轮终清除。
+ */
+interface ErrorFact {
+    /** 错误消息原文（空串 / 缺席不入账——无信息失败事实不占位）。 */
+    message: string;
+    /** 事实落账墙钟（Date.now()，ms）。 */
+    at: number;
+}
+/**
+ * reducer 的 record 视图（core ExecutionRecord 的结构子集：reducer 只触碰这五个字段）。
  * core ExecutionRecord 满足本视图（W2 断言挂靠点）；SDK 内自持 createReplayRecord 产出。
  */
 interface ReplayRecordView {
@@ -9,19 +20,42 @@ interface ReplayRecordView {
     turnCount: number;
     totalTokens: number;
     lastError: string | undefined;
+    /**
+     * 轮失败事实只追加数组（§3.3.5）。缺省 undefined 视为空（磁盘重建的旧 record
+     * 兼容——reducer 以 `??=` 兜底初始化，不要求构造方预置）。
+     */
+    errors?: ErrorFact[];
 }
+/**
+ * 累加两个 AgentUsage（field-wise）。prev 为空时返回 next 的拷贝。
+ * 供 message_end 把 usage 增量并入 turn.usageDelta。
+ */
+declare function addUsage(prev: AgentUsage | undefined, next: AgentUsage): AgentUsage;
+/** 创建一个空 turn（text/thinking 空，无 toolCalls，未结束）。 */
+declare function emptyTurn(): Turn;
 /** 重放场景的 record 构造（对齐 core eventsToSessionView 内 createRecord 后的 reducer 视图）。 */
 declare function createReplayRecord(): ReplayRecordView;
 /**
- * 从 AgentEvent 更新 record。所有数据收口进 record.turns[]。
+ * [§3.3.5] 轮失败事实入账单点：append ErrorFact + lastError 派生刷新（唯一写点）。
+ * 空串 / 缺席不入账（无信息失败事实不占位）；`??=` 兜底磁盘重建的旧 record
+ * （无 errors 字段，缺省 undefined 视为空）。lastError = 最后追加的非空 message
+ * ——数组 append-only 且项非空，尾项即「最后一个非空轮失败」。
+ *
+ * [subagent-observability u3] 导出给 core 轮终写点（record-store-rounds 失败轮
+ * settlement）复用——u2 移交的「markRoundIdle 直写 rec.lastError 绕过 errors 数组」
+ * 收编：轮终失败事实与流内 error 事件走同一入账通道，写点单点（双写漂移防线）。
+ */
+declare function appendErrorFact(record: ReplayRecordView, message: string | undefined | null): void;
+/**
+ * 从 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（§3.3.5——error → turn_end 序后 lastError 仍可读）
  *   - message_end：usage 增量存进末 turn.usageDelta（直接写末 turn，不开新 turn）；
  *     totalTokens 累加
- *   - error：存 record.lastError（getEventLog 派生 error 条目用）
+ *   - error：经 appendErrorFact 入账（errors 只追加 + lastError 派生刷新）
  *
  * 唯一写点——replay 与 live 共用（重放等价性的实现体）。
  *
@@ -42,4 +76,4 @@ declare function eventsToSessionView(events: readonly AgentEvent[], engineId: st
 /** handle.sessionRef 的 sessionId 提取（引擎自定义键，运行时 guard）。 */
 declare function sessionIdFromHandle(handle: EngineHandleData): string | undefined;
 
-export { type ReplayRecordView, aggregateUsage, createReplayRecord, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };
+export { type ErrorFact, type ReplayRecordView, addUsage, aggregateUsage, appendErrorFact, createReplayRecord, emptyTurn, eventsToSessionView, sessionIdFromHandle, toReplayedTurn, updateFromEvent };

package/dist/journal-replay.js

@@ -1,15 +1,21 @@
 import {
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   createReplayRecord,
+  emptyTurn,
   eventsToSessionView,
   sessionIdFromHandle,
   toReplayedTurn,
   updateFromEvent
-} from "./chunk-SGAIDL63.js";
+} from "./chunk-U5MBAKS5.js";
 import "./chunk-JSBRDJBE.js";
 export {
+  addUsage,
   aggregateUsage,
+  appendErrorFact,
   createReplayRecord,
+  emptyTurn,
   eventsToSessionView,
   sessionIdFromHandle,
   toReplayedTurn,

package/dist/kill-chain.d.cts

@@ -1,4 +1,4 @@
-import { b as AgentCallOpts, c as AgentOutcome } from './contract-types-jSa1g28F.cjs';
+import { c as AgentCallOpts, d as AgentOutcome } from './contract-types-C1scOS_M.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 { c as AgentCallOpts, d as AgentOutcome } from './contract-types-C1scOS_M.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-BLxg4ZFr.d.cts → methods-BzvzcCrB.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, e as EngineCapabilities, g as ModelCatalogEntry, c as AgentCallOpts, f as ResumeAnchor, E as EngineHandleData, P as ProbeReport, d as AgentOutcome, S as SessionView } from './contract-types-C1scOS_M.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/{methods-C2zvZqhP.d.ts → methods-CPMc4cvF.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, e as EngineCapabilities, g as ModelCatalogEntry, c as AgentCallOpts, f as ResumeAnchor, E as EngineHandleData, P as ProbeReport, d as AgentOutcome, S as SessionView } from './contract-types-C1scOS_M.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/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,

package/dist/port-contract.d.cts

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

package/dist/port-contract.d.ts

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