@zhushanwen/subagent-engine-sdk 0.10.1 → 0.12.0

package/dist/{contract-types-jSa1g28F.d.ts → contract-types-C1scOS_M.d.ts}

@@ -17,7 +17,7 @@ interface AgentUsage {
     cost?: number;
 }
 interface AgentUsageTotal extends AgentUsage {
-    /** 四项之和。投影时不再手工求和。 */
+    /** 四项之和。派生时不再手工求和。 */
     total: number;
     /** 累计成本（USD）。无成本数据时为 0。 */
     cost: number;
@@ -50,14 +50,14 @@ interface Turn {
     toolCalls: InternalToolCall[];
     /** 本 turn message_end 的 token 增量（聚合得 usage 总量）。 */
     usageDelta?: AgentUsage;
-    /** turn_end 是否已到达。false=正在进行；true=已闭合。 */
+    /** turn_end 是否已到达。false=正在进行；true=已结束。 */
     closed: boolean;
     /** turn_end 到达时的墙钟时间戳（Date.now()，ms）。 */
     closedTs?: number;
 }
 /**
  * 引擎事件（10 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
+ * 兼容」不变量 3 的类型范围）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
  *
  * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
  * （core event-journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
@@ -106,6 +106,20 @@ type AgentEvent = {
     type: EventName<"armed">;
     schemaEnvVar: string;
     extensionPkg: string;
+} | {
+    type: EventName<"auto_retry">;
+    /** start = 失败尝试结束即将重跑；end = 重试波次收束（成功或最终失败）。 */
+    phase: "start" | "end";
+    /** 重试波次序号（pi 原生 _retryAttempt，1 起）。 */
+    attempt: number;
+    /** start 独有：重试上限与退避等待（pi _prepareRetry 发射事实）。 */
+    maxAttempts?: number;
+    delayMs?: number;
+    /** start 携带被重试的错误文本；end 失败波携带最终错误（成功波缺省）。 */
+    errorMessage?: string;
+    /** end 独有：该波重试最终是否恢复（true = 后续尝试成功，false = 重试耗尽）。 */
+    success?: boolean;
+    finalError?: string;
 };
 /**
  * 事件类型词表（协议事件全集 10 种，运行时 SSOT）：schema 事件 `type.enum` 从本表
@@ -115,7 +129,7 @@ type AgentEvent = {
  * 每个成员必须带一行 `// noop-safe: <论证>`：未知成员宽容语义四行①（ADR-0071）的
  * 逐变体登记——旧宿主 reducer 遇未知 event.type 走 default 分支零写入，标记后写
  * 「本变体被丢弃时状态无损」的一行论证（no-op 安全性属运行时消费语义，不可静态
- * 判定——守卫只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记守卫」）。
+ * 判定——检查只查标记存在不查内容，落点 contract-closure.test.ts「noop-safe 标记检查」）。
  *
  * 编译锁（漏改任一侧 typecheck 红，且错误指向漏点）：
  *   ① union 侧——成员 type 必须经 `EventName<"x">` 取名（约束 = 本词表）：union 加
@@ -123,13 +137,13 @@ type AgentEvent = {
  *   ② 词表侧——`satisfies readonly AgentEvent["type"][]`：词表加成员不加 union
  *      → 错误直接落在词表漏改的成员行；
  *   ③ 兜底——成员绕过 EventName 约束裸加字面量 → _EventVocabSyncLock 爆红。
- * 新增事件变体的同步面分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
- * 实证）：协议面两笔（词表 + union）即协议面全同步——schema enum 与遍历型测试断言
- * 自动跟随；同仓消费面另有两处编译期同步点——journal-replay reducer case（穷尽
+ * 新增事件变体的同步点分两层，漏改任一处 typecheck 均红且精确指路（验收 A1 演练
+ * 实证）：协议范围两笔（词表 + union）即协议范围全同步——schema enum 与遍历型测试断言
+ * 自动跟随；同仓消费方另有两处编译期同步点——journal-replay reducer case（穷尽
  * switch never 检查）与 contract-closure 构造冒烟（Record<AgentEventTypeName,…>
  * 漏键爆红）。不 bump 版本、不改任何引擎（演进政策 additive 面，判据全文见头注）。
  */
-declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed"];
+declare const AGENT_EVENT_TYPE_NAMES: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error", "armed", "auto_retry"];
 /** 词表派生的事件名联合（编译锁②/③的词表侧源；schema enum 与测试取值同源）。 */
 type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
 /**
@@ -138,6 +152,7 @@ type AgentEventTypeName = (typeof AGENT_EVENT_TYPE_NAMES)[number];
  * 结构与运行时语义零变化。
  */
 type EventName<T extends AgentEventTypeName> = T;
+declare const _EventVocabSyncLock: AssertMutuallyAssignable<AgentEvent["type"], AgentEventTypeName>;
 /**
  * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / read 的
  * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
@@ -160,7 +175,7 @@ interface EngineHandleData {
     adapterVersion: string;
 }
 /**
- * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
+ * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的派生子集（诊断字段
  * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。消费点：
  *   - run.params.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
  *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）。
@@ -199,7 +214,7 @@ interface SessionView {
  * 用户覆盖记账共用的模型指向形状（设计 subagent-model-switch §6.2/§7.3）。
  *
  * 刻意用结构化对象而非现役 wire 的字符串 canonical ref（`ctx.model` = "provider/id"）：
- * 切换操作的原生输入面就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
+ * 切换操作的原生输入范围就是「provider 选了哪个模型」两个独立选择（前端模型选择器 /
  * runtime `model.switch` 均平铺 provider/modelId），字符串拼接形态会在协议两侧各做一次
  * 拆/拼（拆分规则 = provider 含 '/' 时无法无歧义反转），结构化形状让拆装只发生在宿主
  * 编排层单点（U2 组帧时拼 canonical ref、读回执时拆 ref）。
@@ -230,7 +245,7 @@ type EngineProcessModel = "per-window" | "shared-service";
  * 引擎能力声明（11 必填位 + 1 可选位 setModel）。三级：native / emulated / unsupported。
  * 声明的是本仓 subagent 链路实际接通的能力，不是引擎 RPC 层的理论能力。
  * 同步权威 = manifest（注册期直读）；握手应答仅诊断（§3.3「同步成员清单」）。
- * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约面，不在本
+ * 进程形态声明是独立字段（上方 EngineProcessModel——manifest 契约范围，不在本
  * 接口内），两套字段服务不同裁决（任务能力 vs 宿主实例管理）。
  */
 interface EngineCapabilities {
@@ -242,7 +257,7 @@ interface EngineCapabilities {
      * [H1 D5 语义收窄 + modeless] 「怎么续」形态轴兼 message 资格轴：
      * 位非 'unsupported' = 引擎可续聊（core capability-gate 的 message 资格门消费），
      * 值区分续聊形态——native（原地续写）/ cold（冷恢复重建 + 新 run + resume 锚点）。
-     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
+     * 原名字沿用——conversation 位保留、语义从「interact 长驻控制范围」收窄为
      * 「resume 续聊能力」。[modeless 波2] 会话形态键只剩 run.params.resume（协议
      * task.conversation 已删），本轴不再是 per-run 模式开关——描述各引擎的真实
      * 续聊差异（gate 判据仍是 `=== "unsupported"` 拒绝，"cold" 与 "native" 等价
@@ -298,7 +313,139 @@ interface ProbeReport {
         recovery: string;
     };
 }
-/** 失败分诊结构化标签。unknown（含缺省）= 可重试（语义守恒）。 */
+/**
+ * [subagent-observability §3.3.2] 失败分类权威契约（五维正交，原位替换
+ * AgentFailureKind 三值词表——本文件是引擎协议词表家址）。
+ *
+ * 由收尾边沿（判定链）一次产出并写入轮收条，下游只读不可替换（三硬规则①②——
+ * 只有知道事实的层能填 class；写入后观察性事实降级 observations，不改写 cause）。
+ * 跨进程 wire 载体 = shared `SubagentRecord.lastRound.failure`（type-only re-export，
+ * 判别联合逐字序列化）。消费锚：轮应答恢复指引（§3.3.7）、run 终局 failedMembers[].cause
+ * （§3.3.8——序列化为 `"<class>.<kind>"` 点拼字符串，retryable/retryAfterMs 不进终局
+ * 事件、由成员轮收条承载）。
+ *
+ * cause 优先级（分类边沿裁决序，严格递减）：provider 事实 > harness 预算/契约 >
+ * agent 行为 > engine 崩溃 > unknown（未分类形态不产 FailureCause，落引擎停因原值）。
+ */
+type FailureCauseClass = "provider" | "harness" | "agent" | "engine" | "user";
+/**
+ * retryable 三态（§3.3.2 硬规则③，与重试规则 extension 的 verdict 同词表）：
+ *   true         = 等待后重发可恢复；
+ *   false        = 重发必然同样失败；
+ *   "conditional" = 条件恢复——等限额重置窗口或人/账户先动作（执行层对 conditional
+ *                   不自动重试，呈现层如实展示）。
+ */
+type FailureRetryability = true | false | "conditional";
+/**
+ * FailureCause 公共字段面（class×kind 判别联合各成员共享）。
+ *   retryable    — 三态（{@link FailureRetryability}）；429 不全可重试，禁止仅按
+ *                  HTTP 状态码判可重试（provider 业务码层裁决，§3.3.2 码表硬约束）；
+ *   retryAfterMs — 恢复等待毫秒（错误文本内重置时间字样提取——pi 消息模型不暴露
+ *                  HTTP 头，头通道结构性不可得，设计 §3.3.2 单文本通道），
+ *                  皆无 → 缺省 unknown（undefined，不产假 0）；
+ *   raw          — 分类输入的原始错误文本（取证链：分类不丢原文）。
+ */
+interface FailureCauseFields {
+    retryable: FailureRetryability;
+    retryAfterMs?: number;
+    raw: string;
+}
+/**
+ * class×kind 合法组合矩阵（判别联合构造性成立——非法组合写不出来）：
+ *   provider.rate_limited / provider.protocol_unsupported / harness.turn_budget_exhausted /
+ *   harness.timeout / agent.no_deliverable / user.cancelled / engine.*（`engine_${string}`
+ *   引擎自报透传族，开放前缀面——对齐 RunErrorCode 的 engine_ 透传契约，core 不解释文案）。
+ *
+ * kind 是封闭登记词表：新增成员同 commit 登记下方 {@link FAILURE_CAUSE_CLOSED_KINDS}
+ * （解析词表纪律），漏登记由 {@link FAILURE_CAUSE_KIND_VOCAB_LOCK} 编译锁拦截。
+ */
+type FailureCause = (FailureCauseFields & {
+    class: "provider";
+    kind: "rate_limited" | "protocol_unsupported";
+}) | (FailureCauseFields & {
+    class: "harness";
+    kind: "turn_budget_exhausted" | "timeout";
+    /**
+     * [subagent-observability §3.3.9/UC-10] turn 预算耗尽事实（limiter abort 边沿
+     * 一次产出）：used = abort 时轮数、limit = 显式 maxTurns 上界。undefined =
+     * 极端竞窗下收尾边沿只有 aborted 停因而 limiter 快照缺席（防御性同判形态，
+     * 事实不足不产结构——轮失败事实不受影响）。与 §3.3.6 查询侧 budget 分轴
+     * 结构（{maxTurns, ...}）同构的 {used, limit} 形态。仅 turn_budget_exhausted
+     * 承载；timeout（§3.3.6 超时轮失败分类，宿主结算点产出——timeoutMs 墙钟预算
+     * 耗尽是宿主独有事实，引擎收尾边沿只有「宿主取消 vs 引擎异常」两源判别）
+     * 不落本字段。
+     */
+    budget?: {
+        used: number;
+        limit: number;
+    };
+}) | (FailureCauseFields & {
+    class: "agent";
+    kind: "no_deliverable";
+}) | (FailureCauseFields & {
+    class: "user";
+    kind: "cancelled";
+}) | (FailureCauseFields & {
+    class: "engine";
+    kind: `engine_${string}`;
+});
+/**
+ * FailureCause.kind 闭合成员词表（运行时枚举完整性测试锚；engine 透传族
+ * `engine_${string}` 开放前缀面不进闭合表——逐成员断言见 failure-cause-vocabulary.test.ts）。
+ * 新增 kind 成员 = 联合与本元组同 commit 同批（编译锁双向拦截漏改）。
+ */
+declare const FAILURE_CAUSE_CLOSED_KINDS: readonly ["rate_limited", "protocol_unsupported", "turn_budget_exhausted", "timeout", "no_deliverable", "cancelled"];
+/**
+ * 词表编译锁（双向）：kind 联合闭合面 ⊆ 且 ⊇ FAILURE_CAUSE_CLOSED_KINDS。
+ * 联合扩值漏登元组（或元组多配联合外值）→ 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KIND_VOCAB_LOCK: AssertMutuallyAssignable<Exclude<FailureCause["kind"], `engine_${string}`>, (typeof FAILURE_CAUSE_CLOSED_KINDS)[number]>;
+/**
+ * per-class kind 合法值域（运行时可用——重试规则条目的 kind 字段按 class 校验的
+ * 唯一依据；消费方 = shared validateRetryRuleFields / retry-rules extension 侧镜像）。
+ * engine 透传族是 `engine_${string}` 开放前缀面（无闭合枚举），不进本表——engine 规则
+ * 的 kind 校验走前缀形态判定，由各消费方按 {@link FailureCause} 的 `engine_${string}`
+ * 契约自行落地。
+ *
+ * 词表编译锁：每个 class 的成员元组与 {@link FailureCause} 判别联合的对应 kind 联合
+ * 双向可赋值——判别联合扩值漏登本表（或本表多配联合外值）→ 对应行 tsc 红。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS: {
+    readonly provider: readonly ["rate_limited", "protocol_unsupported"];
+    readonly harness: readonly ["turn_budget_exhausted", "timeout"];
+    readonly agent: readonly ["no_deliverable"];
+    readonly user: readonly ["cancelled"];
+};
+/**
+ * per-class 词表编译锁（双向）：本表各 class 成员元组 ↔ 判别联合对应 kind 联合。
+ * 任一 class 漏登/多配 → 本赋值 tsc 红，错误指向漏改侧。
+ */
+declare const FAILURE_CAUSE_KINDS_BY_CLASS_LOCK: AssertMutuallyAssignable<{
+    provider: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["provider"][number];
+    harness: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["harness"][number];
+    agent: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["agent"][number];
+    user: (typeof FAILURE_CAUSE_KINDS_BY_CLASS)["user"][number];
+}, {
+    provider: Extract<FailureCause, {
+        class: "provider";
+    }>["kind"];
+    harness: Extract<FailureCause, {
+        class: "harness";
+    }>["kind"];
+    agent: Extract<FailureCause, {
+        class: "agent";
+    }>["kind"];
+    user: Extract<FailureCause, {
+        class: "user";
+    }>["kind"];
+}>;
+/**
+ * @deprecated [subagent-observability §3.3.2，ADR-0158 终态] 三值分诊词表已由
+ * {@link FailureCause} 取代（class×kind 封闭矩阵 + retryable 三态）。本类型保留为
+ * 历史解析兼容、不删——旧 record 帧与历史 journal 的 failureKind 解析仍依赖该
+ * 通道（设计 §3.4「历史解析兼容保留项」）；新写入方失败分类一律产 FailureCause，
+ * 产出侧分类器 classifyFailureKind 已退役。
+ */
 type AgentFailureKind = "stale_context" | "schema_deterministic" | "unknown";
 /**
  * AgentOutcome.usage 字段型（← core orchestration/models/types.ts AgentUsage 结构等价；
@@ -333,10 +480,28 @@ interface WorktreeHandle {
  * 一次引擎执行的终态（协议 run 终态应答的 outcome 载荷）。锚定 core
  * orchestration AgentResult 并追加引擎层字段（engineId / exitCode）。
  */
+/** [subagent-observability §3.3.3] 轮终停因引擎原值三态（引擎收尾边沿事实；宿主
+ *  ROUND_TERMINAL_STOP_REASONS 词表的协议侧同源镜像）。 */
+type EngineStopReason = "stop" | "error" | "aborted";
 interface AgentOutcome {
     content: string;
-    /** 失败分诊标签。产出侧 = 引擎；缺省 = unknown = 可重试。 */
+    /**
+     * 失败分诊标签（历史解析兼容残留）。
+     * @deprecated [subagent-observability §3.4，ADR-0158] 新写入方失败分类一律产
+     * {@link FailureCause}（下方 failure 字段）；本字段随 {@link AgentFailureKind} 保留为
+     * 旧 record 帧与历史 journal 的解析兼容。产出侧残留仅引擎送达错误码前缀确定性分诊
+     * （pi 引擎 output-collector，[D5-③ 改轨]）；缺省 = undefined（字段缺位），
+     * 不承载重试判定（重试判定在 FailureCause.retryable 三态）。
+     */
     failureKind?: AgentFailureKind;
+    /**
+     * [subagent-observability §3.3.8] 失败分类（收尾边沿一次产出——CollectedOutcome.failure
+     * 经引擎适配层 toOutcome 透传上协议）。run 终局成员交付结算消费本字段点拼
+     * `"<class>.<kind>"` 进 failedMembers[].cause；缺省 = 未分类（cause 回落
+     * error 前缀协议码 / "unknown"）。可选 = 读取面对旧格式应答放行（字段落地前
+     * 的引擎缺省，写侧契约由引擎适配层承担）。
+     */
+    failure?: FailureCause;
     /** native 引擎直传 / 仿真层 ajv 产出（D4 硬分流：native 路径宿主不做二次校验）。 */
     parsedOutput?: unknown;
     usage?: AgentOutcomeUsage;
@@ -354,7 +519,7 @@ interface AgentOutcome {
     /** null = 被信号杀死（杀链/abort 合成终态的判据）。 */
     exitCode?: number | null;
     /**
-     * [D5 诊断引用落账] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
+     * [D5 诊断引用写入记录] 失败时子进程 stderr tee 文件绝对路径（引擎侧 W11 已有落盘）。
      *
      * 通道裁决（协议演进宪法 ADR-0071 判据链，2026-09-22 一致性审查 P1 修复登记）：stderr
      * tee 路径是引擎产生的诊断事实，宿主不可靠推导（文件名格式/dataDir 解析/轮转
@@ -372,10 +537,42 @@ interface AgentOutcome {
      * 仅诊断引用——文件受引擎侧尺寸轮转与过期清理管辖，读侧不得假设其永存。
      */
     stderrTeePath?: string;
+    /**
+     * [subagent-observability §3.3.3] 轮终停因引擎原值（收尾边沿事实一次产出，值域
+     * 三态与宿主 ROUND_TERMINAL_STOP_REASONS 同源）。宿主 one-shot 轮收条
+     * rec.lastRound.engineStopReason 的数据源——「正常收尾」派生判据（stop 且无失败
+     * 分类 = completed）依赖本事实。additive 可选（宪法判据③同 stderrTeePath 先例）：
+     * 旧引擎缺省 = 宿主回落派生展示词，零行为差。
+     */
+    engineStopReason?: EngineStopReason;
+    /**
+     * [subagent-observability §3.3.3 P5] 本 run 内 pi 原生重试的失败尝试计数
+     * （auto_retry_start 帧数；引擎 >0 时上报）。宿主轮收条 lastRound.retryAttempts
+     * 的数据源——重试轨迹可观测（失败尝试不静默计入 turns/usage）。additive 可选：
+     * 旧引擎/无重试缺省不落键。
+     */
+    retryAttempts?: number;
+    /**
+     * [subagent-observability §3.3.1/§3.3.3] 本轮被人类接管收尾的标注（引擎判定链
+     * prompt-ack 命中 handled 时产出，值恒 "handled"）。宿主轮收条
+     * lastRound.promptDisposition 的数据源——被接管轮不产失败分类、结清走 no_result、
+     * 通知走接管分支、run 聚合按未交付非失败计。additive 可选（宪法判据③同
+     * engineStopReason 先例）：旧引擎缺省 = 无接管标注，零行为差。
+     */
+    promptDisposition?: "handled";
+    /**
+     * [subagent-observability §3.3.2/§3.3.10] 观察性事实数组（引擎产出侧摘要，如
+     * 「结构化输出未调用」）。宿主轮收条 lastRound.observations 的
+     * 数据源——查询出口 list lastRound.observations 直读。additive 可选：旧引擎
+     * 缺省不落键。注意承载分源：交付谓词缺项（deliverables 未满足）在 worker 脚本
+     * 侧执行，不经本字段——落脚本结果 observations / run 终局帧 partialMembers /
+     * workflow_control 成员行 missingDeliverables 三面（§3.3.10 分源表述）。
+     */
+    observations?: string[];
 }
 /**
  * 引擎模型目录条目（manifest `modelCatalog.models` 条目形态，设计 §3.4 示例）。
- * 协议面 = initialize 应答 models? 与 listModels 应答 models 的元素型；
+ * 协议范围 = initialize 应答 models? 与 listModels 应答 models 的元素型；
  * manifest 解析与生成（gen:model-catalog）归 W4/W5 实装。
  */
 interface ModelCatalogEntry {
@@ -384,15 +581,15 @@ interface ModelCatalogEntry {
     canonicalRef?: string;
 }
 /**
- * 单次 agent 调用的任务声明——引擎面子集（协议 run.params.task；core 全量
- * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费面）。
+ * 单次 agent 调用的任务声明——引擎侧子集（协议 run.params.task；core 全量
+ * AgentCallOpts 22 字段留 core，core 侧反向 re-export 保消费方）。
  *
  * 字段归属判据（协议演进宪法 ADR-0071 成文，权威源
  * docs/architecture/subagent-engine-protocolization.md §3.3「协议演进宪法」与
  * docs/adr/decisions.md ADR-0071；
- * 本注释是判据与存量结论的投影，新增字段按决策树依序裁决后在此登记）：
+ * 本注释是判据与存量结论的派生整理，新增字段按决策树依序裁决后在此登记）：
  *   ① 引擎不消费它任务能否正确完成？能 → 宿主自持不上协议（「正确」含满足字段
- *      声明携带的约束面——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
+ *      声明携带的约束侧——轮次预算/超时等约束被引擎忽略即任务语义受损，视为消费）；
  *   ② 描述「任务是什么」(what) 还是「在什么环境跑/怎么跑」(where/how)？
  *      what → task（预算/验收类约束 = 任务自带语义归 task，宿主偏好参数走③）；
  *   ③ 引擎能否自行推导该环境值且与宿主恒等？能 → 不上协议（推导权归引擎，设计期
@@ -464,4 +661,4 @@ interface AgentCallOpts {
     permissionMode?: string;
 }
 
-export { type AgentEvent as A, type EngineHandleData as E, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, type AgentUsageTotal as a, type AgentCallOpts as b, type AgentOutcome as c, type EngineCapabilities as d, type ResumeAnchor as e, type ModelCatalogEntry as f, AGENT_EVENT_TYPE_NAMES as g, type AgentEventTypeName as h, type AgentFailureKind as i, type AgentOutcomeUsage as j, type AgentUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type ToolCall as n, type ToolCallEntry as o, type ToolCallResult as p };
+export { type AgentEvent as A, type EngineHandleData as E, FAILURE_CAUSE_CLOSED_KINDS as F, type InternalToolCall as I, type ModelRef as M, type ProbeReport as P, type ReplayedTurn as R, type SessionView as S, type Turn as T, type WorktreeHandle as W, _EventVocabSyncLock as _, type AgentUsage as a, type AgentUsageTotal as b, type AgentCallOpts as c, type AgentOutcome as d, type EngineCapabilities as e, type ResumeAnchor as f, type ModelCatalogEntry as g, AGENT_EVENT_TYPE_NAMES as h, type AgentEventTypeName as i, type AgentFailureKind as j, type AgentOutcomeUsage as k, type AssertMutuallyAssignable as l, type EngineProcessModel as m, type EngineStopReason as n, FAILURE_CAUSE_KINDS_BY_CLASS as o, FAILURE_CAUSE_KINDS_BY_CLASS_LOCK as p, FAILURE_CAUSE_KIND_VOCAB_LOCK as q, type FailureCause as r, type FailureCauseClass as s, type FailureRetryability as t, type ToolCall as u, type ToolCallEntry as v, type ToolCallResult as w };

package/dist/env.cjs

@@ -94,8 +94,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",
@@ -106,9 +104,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) {
@@ -162,11 +162,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/env.d.cts

@@ -1,18 +1,9 @@
 /** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_PREFIXES: readonly string[];
-/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。
- *  互引（场景域分化，勿互混）：dev 装配器（apps/electron/scripts/dev-instance-lib.mjs
- *  `LEAK_ENV_KEYS`）仍剥 RELAY_STD* 三键——dev 宿主进程环境防泄漏口径独立于引擎
- *  spawn 面；本清单（引擎侧）已退役同名三键，写入方已清零。 */
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_DENY_LIST: readonly string[];
-/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+/** L0 注入的全部基础设施键（检查断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
 declare const ENGINE_ENV_L0_INFRA_KEYS: readonly string[];
-/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
-interface EngineRelayEnv {
-    socket: string;
-    node: string;
-    script: string;
-}
 /** buildEngineChildEnv 入参。 */
 interface EngineChildEnvOptions {
     /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
@@ -21,8 +12,6 @@ interface EngineChildEnvOptions {
     engineNode?: string;
     /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
     electronRunAsNode?: boolean;
-    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 TAIJI_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
-    relay?: EngineRelayEnv;
     /**
      * L0：引擎宿主（engine-host）进程的 env 透传通道。**注意它不是子代理身份通道**：
      * 引擎宿主是长驻进程（每窗口一个），而子代理身份（recordId / depth 等）是 per-run 的
@@ -46,9 +35,9 @@ interface EngineChildEnvOptions {
  *
  * 层规格（impl-plan §2.12 三层表）：
  * - L0 基础设施键：TAIJI_AGENT_DATA_DIR / TAIJI_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
- *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / identityEnv（injectL0InfraKeys）；
  * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
- *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ *   （deny 两键 + 凭证键 + 预设回落两键）；
  * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
  *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
  *
@@ -70,7 +59,7 @@ interface BuildOutboundChildEnvOptions {
  * 消费生命周期标志 / WS 令牌。
  *
  * 与 @taiji/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
- * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费方（zsw 宿主 /
  * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
  * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
  * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
@@ -80,4 +69,4 @@ interface BuildOutboundChildEnvOptions {
  */
 declare function buildOutboundChildEnv(opts: BuildOutboundChildEnvOptions): Record<string, string>;
 
-export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, type EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv };
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv };

package/dist/env.d.ts

@@ -1,18 +1,9 @@
 /** L2 manifest 放行的保留前缀拒绝表（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_PREFIXES: readonly string[];
-/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。
- *  互引（场景域分化，勿互混）：dev 装配器（apps/electron/scripts/dev-instance-lib.mjs
- *  `LEAK_ENV_KEYS`）仍剥 RELAY_STD* 三键——dev 宿主进程环境防泄漏口径独立于引擎
- *  spawn 面；本清单（引擎侧）已退役同名三键，写入方已清零。 */
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
 declare const ENGINE_ENV_DENY_LIST: readonly string[];
-/** L0 注入的全部基础设施键（守卫断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
+/** L0 注入的全部基础设施键（检查断言：与 ENGINE_ENV_DENY_LIST 交集 = ∅）。 */
 declare const ENGINE_ENV_L0_INFRA_KEYS: readonly string[];
-/** relay 三键形态（宿主 relay 激活时三值同时非空，全有或全无）。 */
-interface EngineRelayEnv {
-    socket: string;
-    node: string;
-    script: string;
-}
 /** buildEngineChildEnv 入参。 */
 interface EngineChildEnvOptions {
     /** L0：引擎数据根（隔离库/池/journal 都相对它推导；缺 env 且无注入引擎侧须显式报错） */
@@ -21,8 +12,6 @@ interface EngineChildEnvOptions {
     engineNode?: string;
     /** L0：执行器为 Electron 二进制 → 注入 ELECTRON_RUN_AS_NODE=1 */
     electronRunAsNode?: boolean;
-    /** L0：relay 三键（宿主 relay 激活时传；三键必经 L0——L1 拒绝 TAIJI_SUBAGENT_ 前缀、L2 是 manifest 面，两层都到不了） */
-    relay?: EngineRelayEnv;
     /**
      * L0：引擎宿主（engine-host）进程的 env 透传通道。**注意它不是子代理身份通道**：
      * 引擎宿主是长驻进程（每窗口一个），而子代理身份（recordId / depth 等）是 per-run 的
@@ -46,9 +35,9 @@ interface EngineChildEnvOptions {
  *
  * 层规格（impl-plan §2.12 三层表）：
  * - L0 基础设施键：TAIJI_AGENT_DATA_DIR / TAIJI_AGENT_ENGINE_NODE / ELECTRON_RUN_AS_NODE
- *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / relay 三键 / identityEnv（injectL0InfraKeys）；
+ *   （条件）/ TAIJI_AGENT_SUBAGENT=1 / identityEnv（injectL0InfraKeys）；
  * - L1 deny + 显式剥除（恒高于 manifest 放行）：ENGINE_ENV_DENY_LIST
- *   （deny 两键 + 凭证键 + 父身份键 + 防御性剥除三死名）；
+ *   （deny 两键 + 凭证键 + 预设回落两键）；
  * - L2 manifest 放行：envPrefixes 声明前缀的 processEnv 键（保留前缀拒绝、
  *   形态校验、未声明前缀不放行 + warn）（applyManifestAllowlist）。
  *
@@ -70,7 +59,7 @@ interface BuildOutboundChildEnvOptions {
  * 消费生命周期标志 / WS 令牌。
  *
  * 与 @taiji/shared 版 buildOutboundChildEnv 的刻意差异：**缺省不做白名单过滤**
- * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费面（zsw 宿主 /
+ * （prefixes 省略 = 全量继承父 env + deny 剥除）。理由：SDK 消费方（zsw 宿主 /
  * 引擎 CLI）不可 import shared 的 ENV_WHITELIST_PREFIXES；引擎 spawn 的基座由
  * 调用方先经 buildEngineChildEnv 组装（其 baseEnv 已是 core 过滤后的），而
  * ambient 场景（git 需要 GIT_* / proxy / ssh 等）必须保留继承面——deny-by-default
@@ -80,4 +69,4 @@ interface BuildOutboundChildEnvOptions {
  */
 declare function buildOutboundChildEnv(opts: BuildOutboundChildEnvOptions): Record<string, string>;
 
-export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, type EngineRelayEnv, buildEngineChildEnv, buildOutboundChildEnv };
+export { type BuildOutboundChildEnvOptions, ENGINE_ENV_DENY_LIST, ENGINE_ENV_L0_INFRA_KEYS, ENGINE_ENV_PREFIXES, type EngineChildEnvOptions, buildEngineChildEnv, buildOutboundChildEnv };

package/dist/env.js

@@ -4,7 +4,7 @@ import {
   ENGINE_ENV_PREFIXES,
   buildEngineChildEnv,
   buildOutboundChildEnv
-} from "./chunk-AF2ETADP.js";
+} from "./chunk-2L3I2TWJ.js";
 import "./chunk-NXNNXGTY.js";
 import "./chunk-JSBRDJBE.js";
 export {

package/dist/{error-codes-f-UO4a8D.d.cts → error-codes-CgcjlmeD.d.cts}

@@ -1,4 +1,4 @@
-import { A as AgentEvent, d as EngineCapabilities } from './contract-types-jSa1g28F.cjs';
+import { A as AgentEvent, e as EngineCapabilities } from './contract-types-C1scOS_M.cjs';
 
 /** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
 interface ProtocolError {
@@ -42,7 +42,7 @@ interface ReverseRequestFrame {
 }
 /** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
 type ReverseResponseResult = 
-/** 数据面类：处理确认。 */
+/** 数据范围类：处理确认。 */
 {
     ok: true;
 }
@@ -63,6 +63,42 @@ declare function isNotificationFrame(frame: unknown): frame is NotificationFrame
 /** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
 declare function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame;
 
+/**
+ * 引擎进程侧 spawn/送达窗口错误码（M1/M2 送达回执，设计 D10「engine 侧」）。
+ * 消费方 = pi-subagent-cli（u-m2-engine-ack 接线）：
+ * - prompt_not_delivered：prompt 写入后零 stdout（零输出判定）/ stdin 不可用 / EPIPE——
+ *   任务从未被真实 pi 受理，静默丢失的显式失败形态；
+ * - prompt_rejected：pi 对 prompt 命令回 success:false（已送达但被拒绝）——带 pi 的
+ *   error 文本，与 not_delivered 分型防误诊（D3 不采用合并条目）；
+ * - spawn_handshake_timeout：引擎 spawn 握手窗口超时——runtime/引擎停在
+ *   spawn/handshake 的显式失败（control 侧同类失败码 = engine_open_timeout）。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_CODES: readonly ["engine_prompt_not_delivered", "engine_prompt_rejected", "engine_spawn_handshake_timeout"];
+type EngineSpawnDeliveryErrorCode = (typeof ENGINE_SPAWN_DELIVERY_ERROR_CODES)[number];
+/**
+ * runtime 控制面传输错误码（M3 control 通道，设计 D8/D10「runtime 侧」）。
+ * 消费方 = EngineClient.connectOnce preserve 白名单（u-m3-local：来自
+ * RuntimeEngineTransport 的 EngineSdkError 原样保留 code 与 recovery，不再包装成
+ * engine_crashed——UC-20 的显式失败不被吞掉）。语义（设计 D5/D8）：
+ * - transport_unavailable：control socket connect / hello 失败——托管态 runtime 故障
+ *   显式可见，不静默回退 local spawn；
+ * - transport_lost：control 连接中途丢失（与 engine 自身 crash 区分）——标记不可用、
+ *   fan-out 该连接全部 in-flight，不在同一连接重试；
+ * - open_timeout：engine_open 超时（runtime spawn/归属卡住）；
+ * - frame_too_large：单帧（含 partial-line 缓冲）超 32MB 上限——不截断、按 channel
+ *   归因关闭；
+ * - backpressure_overflow：channel（32MB/4096 帧）或连接聚合（256MB）待写队列溢出——
+ *   不丢帧、不静默，溢出面（channel/connection）标注在 detail。
+ */
+declare const ENGINE_TRANSPORT_ERROR_CODES: readonly ["engine_transport_unavailable", "engine_transport_lost", "engine_open_timeout", "engine_frame_too_large", "engine_backpressure_overflow"];
+type EngineTransportErrorCode = (typeof ENGINE_TRANSPORT_ERROR_CODES)[number];
+/**
+ * 引擎侧 spawn/送达错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。
+ * detail 由消费方拼装（诊断五元组 / pi error 文本），文案只给恢复动作。
+ */
+declare const ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY: Record<EngineSpawnDeliveryErrorCode, string>;
+/** runtime 控制面传输错误码的 recovery 文案（键完整性由类型 Record + 测试锁定）。 */
+declare const ENGINE_TRANSPORT_ERROR_RECOVERY: Record<EngineTransportErrorCode, string>;
 /**
  * setModel 正向方法的错误码三型（引擎 error 帧给出；宿主消费分型）。
  * 追加进 ENGINE_PROTOCOL_ERROR_CODES 主词表（成员清单单源 = 本数组，主词表 spread）。
@@ -82,7 +118,7 @@ type SetModelErrorCode = (typeof SET_MODEL_ERROR_CODES)[number];
  * 四个竞态窗口内发现子进程已退出——**同一处置**按无活进程形态应答，引擎回本码
  * error 帧）。进主词表的依据与 SET_MODEL_ERROR_CODES 三型相同：宿主消费分型
  * （chat 域转已记账型应答 / run 级聚合落 not-active 成员态，§7.2 处置表），不是
- * 「core 不解释文案」的纯透传面。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
+ * 「core 不解释文案」的纯透传逻辑。刻意**不进** SET_MODEL_ERROR_CODES：聚合失败
  * 名单的分型值域只收「转发失败」三型，无活进程是成员三态之一（not-active），
  * 不是失败——两值域语义正交。
  */
@@ -92,7 +128,7 @@ declare const ENGINE_PROTOCOL_ERROR_CODES: readonly ["engine_not_found", "engine
 type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
 /** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
 declare function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode;
-/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+/** 其余引擎自报错误码的前缀契约（透传侧；core 不解释文案）。 */
 declare const ENGINE_ERROR_CODE_PREFIX = "engine_";
 declare function isEngineErrorPassthroughCode(value: string): boolean;
 
@@ -106,7 +142,7 @@ declare class EngineSdkError extends Error {
     readonly recovery: string;
     readonly data?: Record<string, unknown>;
     constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>);
-    /** 协议 error 帧载荷投影。 */
+    /** 协议 error 帧载荷派生视图。 */
     toStructured(): ProtocolError;
 }
 declare function engineProtocolMismatchError(engineVersion: number): EngineSdkError;
@@ -147,4 +183,4 @@ declare function engineTimeoutDetail(stdoutTail: string): string;
 /** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
 declare function schemaEmulationFailedDetail(error: string, tail: string): string;
 
-export { EngineSdkError as E, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_TIMEOUT_RECOVERY as c, type EngineProtocolErrorCode as d, type ErrorResponseFrame as e, type EventNotificationParams as f, type ResponseFrame as g, type ReverseRequestFrame as h, type ReverseResponseResult as i, SET_MODEL_NOT_ACTIVE_CODE as j, STDOUT_TAIL_ECHO_CHARS as k, type SetModelErrorCode as l, type SuccessResponseFrame as m, assertChatConversationSupported as n, engineConversationUnsupportedError as o, engineProtocolMismatchError as p, engineSetModelUnsupportedError as q, engineTimeoutDetail as r, isEngineErrorPassthroughCode as s, isEngineProtocolErrorCode as t, isNotificationFrame as u, isRequestFrame as v, isResponseFrame as w, isReverseRequestFrame as x, schemaEmulationFailedDetail as y };
+export { isNotificationFrame as A, isRequestFrame as B, isResponseFrame as C, isReverseRequestFrame as D, EngineSdkError as E, schemaEmulationFailedDetail as F, type NotificationFrame as N, type ProtocolError as P, type RequestFrame as R, SET_MODEL_ERROR_CODES as S, ENGINE_ERROR_CODE_PREFIX as a, ENGINE_PROTOCOL_ERROR_CODES as b, ENGINE_SPAWN_DELIVERY_ERROR_CODES as c, ENGINE_SPAWN_DELIVERY_ERROR_RECOVERY as d, ENGINE_TIMEOUT_RECOVERY as e, ENGINE_TRANSPORT_ERROR_CODES as f, ENGINE_TRANSPORT_ERROR_RECOVERY as g, type EngineProtocolErrorCode as h, type EngineSpawnDeliveryErrorCode as i, type EngineTransportErrorCode as j, type ErrorResponseFrame as k, type EventNotificationParams as l, type ResponseFrame as m, type ReverseRequestFrame as n, type ReverseResponseResult as o, SET_MODEL_NOT_ACTIVE_CODE as p, STDOUT_TAIL_ECHO_CHARS as q, type SetModelErrorCode as r, type SuccessResponseFrame as s, assertChatConversationSupported as t, engineConversationUnsupportedError as u, engineProtocolMismatchError as v, engineSetModelUnsupportedError as w, engineTimeoutDetail as x, isEngineErrorPassthroughCode as y, isEngineProtocolErrorCode as z };