@zhushanwen/subagent-engine-sdk 0.2.1 → 0.4.0

package/dist/protocol/index.d.ts

@@ -1,7 +1,6 @@
-import { P as ProtocolError } from '../error-codes-Dhss2Kmk.js';
-export { A as AnyFrame, E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-Dhss2Kmk.js';
-import { E as EngineCapabilities, M as ModelCatalogEntry, h as EngineHandleData, I as InteractAction, A as AgentCallOpts, k as ResumeAnchor, P as ProbeReport, c as AgentOutcome, i as InteractResult, S as SessionView, e as AgentUsage } from '../contract-types-sSlgppBC.js';
-export { a as AgentEvent, b as AgentFailureKind, d as AgentOutcomeUsage, f as AgentUsageTotal, g as AssertMutuallyAssignable, j as InternalToolCall, R as ReplayedTurn, T as ToolCall, l as ToolCallEntry, m as ToolCallResult, n as Turn, W as WorktreeHandle } from '../contract-types-sSlgppBC.js';
+export { E as ENGINE_ERROR_CODE_PREFIX, a as ENGINE_PROTOCOL_ERROR_CODES, b as ENGINE_TIMEOUT_RECOVERY, c as EngineProtocolErrorCode, d as EngineSdkError, e as ErrorResponseFrame, f as EventNotificationParams, N as NotificationFrame, P as ProtocolError, R as RequestFrame, g as ResponseFrame, h as ReverseRequestFrame, i as ReverseResponseResult, S as STDOUT_TAIL_ECHO_CHARS, j as SuccessResponseFrame, k as assertChatConversationSupported, l as engineConversationUnsupportedError, m as engineProtocolMismatchError, n as engineTimeoutDetail, o as isEngineErrorPassthroughCode, p as isEngineProtocolErrorCode, q as isNotificationFrame, r as isRequestFrame, s as isResponseFrame, t as isReverseRequestFrame, u as schemaEmulationFailedDetail } from '../error-codes-D5YlWaBx.js';
+import { E as EngineCapabilities, M as ModelCatalogEntry, A as AgentCallOpts, i as ResumeAnchor, h as EngineHandleData, P as ProbeReport, c as AgentOutcome, S as SessionView } from '../contract-types-C71Sqq8d.js';
+export { a as AgentEvent, b as AgentFailureKind, d as AgentOutcomeUsage, e as AgentUsage, f as AgentUsageTotal, g as AssertMutuallyAssignable, I as InternalToolCall, R as ReplayedTurn, T as ToolCall, j as ToolCallEntry, k as ToolCallResult, l as Turn, W as WorktreeHandle } from '../contract-types-C71Sqq8d.js';
 import { UiRequest, UiResponse } from '../ui-types.js';
 
 /** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
@@ -32,24 +31,25 @@ declare const ENGINE_EVENT_COALESCE_ENV = "XYZ_ENGINE_EVENT_COALESCE";
 declare const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
- *   host/childSpawned / host/childStateChanged / host/roundLifecycle[v1.x]）：10s 未答 =
- *   引擎故障；
- * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ * - 数据面类（host/log / host/streamDelta / host/handleReady /
+ *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
+ * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */
 type ReverseRequestTimeoutClass = "data-plane" | "interaction";
 
-/** 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。 */
-type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "interact" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
+/**
+ * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
+ */
+type ProtocolMethod = "initialize" | "probe" | "run" | "cancel" | "read" | "listModels" | "validateModel" | "dispose" | "ping";
 /** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
-declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+declare const PROTOCOL_METHODS: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
 /**
  * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
  */
 interface RunContextParams {
-    /** 隔离池归属（journal 归属错 = 缺失后果）。 */
-    poolKey: string;
     /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
     cwd: string;
     /** 请求模型 ref（未传 = 引擎缺省模型）。 */
@@ -65,19 +65,35 @@ interface RunContextParams {
     };
     /** 事件粒度请求（引擎按 capabilities.eventGranularity 实际能力执行）。 */
     streamMode?: "stream" | "coarse";
+    /**
+     * [F6] 根 session id——pi 引擎 relay 归属键 SESSION_ID 的权威来源（生产三来源
+     * ①本字段 ②宿主 env ③根进程 env 中，宿主派发恒走①）。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionRootId?: string;
+    /**
+     * [Option C 协议化] 权威 subagent session 目录——宿主以 getSubagentSessionDir
+     * (agentDir, rootCwd) 推导（宿主单一权威，Fix Gate B S6：引擎本地推导与宿主布局
+     * 三处不等价 → 跨重启续聊链断裂）。引擎用它组装 pi `--session-dir`，不自推导；
+     * 缺省（独立运行/测试）走引擎内 [LEGACY] fallback。additive 可选：旧引擎忽略
+     * 未知字段，undefined 不上 wire。
+     */
+    sessionDir?: string;
 }
 /**
- * [v1.x] chat 会话形态参数——HostChatRoundTicket 五字段过协议映射中「record」的
- * 承载位（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1 五字段映射）：
+ * [H1] run 的 resume 会话形态参数（设计 docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D3 + §5 U1/U6 行）：原 RunChatParams（v1.x chat 会话形态参数）的泛化改名终态，
+ * 载荷同形（recordId + resume 锚点，ResumeAnchor 不变），仅键名从「chat 会话形态」
+ * 泛化为「resume 续聊」。
  *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
- *     host/childSpawned|childStateChanged 与 host/roundLifecycle 的 record 键形态）；
+ *     host/childSpawned|childStateChanged 的 record 键形态）；
  *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
  *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
  *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
- * task.conversation === true 时必传（chat 路由前置 gate：manifest conversation 位
- * unsupported 的引擎同步拒 engine_capability_unsupported——见 error-codes.ts）。
+ * [H1 U6 已切换] `chat` 键整体退役（读写端同批切换，无「写新读旧」窗口），本键为
+ * 唯一会话形态参数。载荷 schema 权威 = runSessionParamsSchema（schema.ts）。
  */
-interface RunChatParams {
+interface RunResumeParams {
     recordId: string;
     resume?: ResumeAnchor;
 }
@@ -109,11 +125,11 @@ interface RunParams {
     task: AgentCallOpts;
     ctx: RunContextParams;
     /**
-     * [v1.x 可选增量] chat 会话形态参数（task.conversation=true 的 chat 路由承载）。
-     * 缺省 = 一次性任务形态，v1 引擎/宿主语义不变（向后兼容：旧引擎忽略未知字段，
-     * 帧级 schema params 不做深校验）。续聊/关断不经此参数——走既有 interact。
+     * [H1 U6 终态] resume 续聊参数（唯一会话形态键；原 v1.x `chat` 键已随键切换退役，
+     * 见 RunResumeParams）。缺省 = 一次性任务形态（向后兼容：旧引擎忽略未知字段，
+     * 帧级 schema params 不做深校验）。additive 可选：undefined 不上 wire。
      */
-    chat?: RunChatParams;
+    resume?: RunResumeParams;
 }
 /** run 终态应答（期间事件经 event 通知；长运行方法，应答到达即终态）。 */
 interface RunResult {
@@ -131,10 +147,6 @@ interface CancelParams {
 interface CancelResult {
     ok: true;
 }
-interface InteractParams {
-    handle: EngineHandleData;
-    action: InteractAction;
-}
 interface ReadParams {
     handle: EngineHandleData;
     /** 数据根必填：存量池时代引擎自算池/journal 相对 dbPath 的定位需要它（设计钉死）。 */
@@ -174,7 +186,6 @@ interface ProtocolParamsMap {
     probe: ProbeParams;
     run: RunParams;
     cancel: CancelParams;
-    interact: InteractParams;
     read: ReadParams;
     listModels: ListModelsParams;
     validateModel: ValidateModelParams;
@@ -187,7 +198,6 @@ interface ProtocolResultMap {
     probe: ProbeReport;
     run: RunResult;
     cancel: CancelResult;
-    interact: InteractResult;
     read: SessionView;
     listModels: ListModelsResult;
     validateModel: ValidateModelResult;
@@ -195,13 +205,17 @@ interface ProtocolResultMap {
     ping: PingResult;
 }
 
-/** 反向通道名联合（恰好 9 个；REVERSE_CHANNELS 常量数组与之同源互证）。 */
-type ReverseChannel = "host/log" | "host/askUser" | "host/permission" | "host/streamDelta" | "host/poolResolved" | "host/handleReady" | "host/childSpawned" | "host/childStateChanged" | "host/roundLifecycle";
-declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+/**
+ * 反向通道名联合（恰好 6 个；REVERSE_CHANNELS 常量数组与之同源互证）。
+ */
+type ReverseChannel = "host/log" | "host/askUser" | "host/streamDelta" | "host/handleReady" | "host/childSpawned" | "host/childStateChanged";
+/**
+ * 通道名全集（运行时顺序化枚举；与 ReverseChannel 的同源关系由测试断言）。
+ */
+declare const REVERSE_CHANNELS: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
 /**
  * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
- * host/roundLifecycle 属数据面（终态回执语义：宿主必须确认收到，10s 未答 = 引擎故障）。
  */
 declare const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass>;
 /** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
@@ -219,61 +233,24 @@ interface HostAskUserParams {
 }
 /** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
 type HostAskUserResult = UiResponse;
-/**
- * host/permission：权限询问（引擎请求宿主裁决工具执行）。
- * v1 骨架字段（设计未钉死载荷细节，细化归各引擎提取设计；W2 实装 core 应答端时
- * 若需扩展走 additive 演进）。
- */
-interface HostPermissionParams {
-    runId: string;
-    toolName: string;
-    args?: unknown;
-    /** 请求方向引擎给出的原因/说明（展示用）。 */
-    reason?: string;
-}
-/** host/permission 两阶段结果。 */
-type HostPermissionResult = {
-    approved: boolean;
-} | {
-    unsupported: true;
-};
 /**
  * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
  *
- * [v1.x 关联键扩展——D1-A 裁定，W1 落地不再临场选择]：
- *   - run 域轮（含 run 会话形态首轮）：runId 关联（v1 现状不变，runId 由 core 在
- *     run 帧分配）；
- *   - interact 发起的续聊轮：**recordId** 关联（续聊轮无独立 runId——InteractParams/
- *     InteractResult 均不含，recordId 经 handle.sessionRef 送达引擎）。
- * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
+ * 关联键恒为 runId（runId 由 core 在 run 帧分配）；[H1] chat 续聊轮经 resume run
+ * 复用 runId 关联（原 recordId 关联键随 interact 面退役删除）。
  */
-type HostStreamDeltaParams = {
+interface HostStreamDeltaParams {
     runId: string;
-    recordId?: undefined;
     delta: string;
-} | {
-    recordId: string;
-    runId?: undefined;
-    delta: string;
-};
-/** streamDelta 载荷结构判定（关联键互斥 + delta 形状；消费侧共用，防双侧各写一份）。 */
-declare function isHostStreamDeltaParams(value: unknown): value is HostStreamDeltaParams;
-/**
- * host/poolResolved：journal 落盘路径单一权威（契约：必须在首个事件 emit 前调用——
- * 否则 journal 归属错）。载荷 = core onPoolResolved(poolKey) 的 runId 关联形态。
- */
-interface HostPoolResolvedParams {
-    runId: string;
-    poolKey: string;
 }
 /**
  * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
  * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
+ * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议面 poolKey 退役删除。
  */
 interface HostHandleReadyParams {
     runId: string;
     sessionRef: Record<string, string>;
-    poolKey: string;
 }
 /**
  * host/childSpawned：引擎内一次性子进程 pid 上报。
@@ -298,95 +275,6 @@ interface HostChildStateChangedParams {
     exitCode?: number;
     signal?: string;
 }
-/**
- * 轮次关联键（D1-A 裁定的类型面）：run 域轮 = runId（v1 现状）；interact 续聊轮 =
- * recordId（经 handle.sessionRef）。undefined 孪生位保证两键互斥。
- */
-interface RoundKeyedByRun {
-    runId: string;
-    recordId?: undefined;
-}
-interface RoundKeyedByRecord {
-    recordId: string;
-    runId?: undefined;
-}
-/**
- * 轮次终态相位（事件即 record 回写载体——chat 域 record 处置由相位一一映射，
- * 设计 D2 裁决表 conversation 行：settled/idle 轮收口不终态、failed 标 failed）：
- *   - settled：轮收敛（输出完整）。消费点 = settled-watchdog disarm + D3 abort
- *     收敛判据（cancel 受理后等本事件，超 CANCEL_SETTLE_GRACE_MS 走杀链）；
- *   - idle：轮收口 + 会话进 idle 稳态（core 侧 doFinalizeRoundToIdle + idle 定时器
- *     锚点）。settled 与 idle 是两个锚点：watchdog 在 settled 即解除，idle 管置闲；
- *   - failed：轮异常终止（引擎自知失败，如 EPIPE 兜底耗尽）——error 如实上报，
- *     record 标 failed（与 run 域 AgentOutcome.error 的「失败收口」语义对齐）。
- * usage 为本轮 message_end 增量（interact 续聊轮无 event 通知通道，用量经本帧回填）。
- * 不设 seq：stdio NDJSON 单连接有序 + 数据面应答确认，无重排/重放面（与 event
- * 通知的 seq 对照——后者镜像进程内事件流基线，本帧无基线可镜像）。
- */
-interface RoundSettledPhase {
-    phase: "settled";
-    usage?: AgentUsage;
-}
-interface RoundIdlePhase {
-    phase: "idle";
-    usage?: AgentUsage;
-    /** 冷续锚点回填（session 滚动/compaction 后锚点可能变化，宿主按帧刷新）。 */
-    anchor?: ResumeAnchor;
-}
-interface RoundFailedPhase {
-    phase: "failed";
-    /** 失败原因（结构对齐协议 error 帧——code/message/recovery 可操作闭环）。 */
-    error: ProtocolError;
-    anchor?: ResumeAnchor;
-}
-/** 相位联合（消费侧 switch(phase) 判别用）。 */
-type RoundLifecyclePhase = RoundSettledPhase | RoundIdlePhase | RoundFailedPhase;
-/** host/roundLifecycle 载荷：关联键（run|record）× 相位（settled|idle|failed）。 */
-type HostRoundLifecycleParams = (RoundKeyedByRun & RoundSettledPhase) | (RoundKeyedByRun & RoundIdlePhase) | (RoundKeyedByRun & RoundFailedPhase) | (RoundKeyedByRecord & RoundSettledPhase) | (RoundKeyedByRecord & RoundIdlePhase) | (RoundKeyedByRecord & RoundFailedPhase);
-/**
- * roundLifecycle 载荷结构判定：关联键互斥 + phase 词表 + 各相位专属形状
- * （failed 必含 error.code/message）。引擎侧发帧前自检与 core 侧消费共用，
- * 防两侧各写一份判别（与 isHostStreamDeltaParams 同理）。
- */
-declare function isHostRoundLifecycleParams(value: unknown): value is HostRoundLifecycleParams;
-/** 通道 → 载荷类型映射。 */
-interface ReverseChannelParamsMap {
-    "host/log": HostLogParams;
-    "host/askUser": HostAskUserParams;
-    "host/permission": HostPermissionParams;
-    "host/streamDelta": HostStreamDeltaParams;
-    "host/poolResolved": HostPoolResolvedParams;
-    "host/handleReady": HostHandleReadyParams;
-    "host/childSpawned": HostChildSpawnedParams;
-    "host/childStateChanged": HostChildStateChangedParams;
-    "host/roundLifecycle": HostRoundLifecycleParams;
-}
-/** 通道 → 异步/同步结果类型映射（ack 两阶段通道的第二阶段 result）。 */
-interface ReverseChannelResultMap {
-    "host/log": {
-        ok: true;
-    };
-    "host/askUser": HostAskUserResult;
-    "host/permission": HostPermissionResult;
-    "host/streamDelta": {
-        ok: true;
-    };
-    "host/poolResolved": {
-        ok: true;
-    };
-    "host/handleReady": {
-        ok: true;
-    };
-    "host/childSpawned": {
-        ok: true;
-    };
-    "host/childStateChanged": {
-        ok: true;
-    };
-    "host/roundLifecycle": {
-        ok: true;
-    };
-}
 
 /** 协议错误对象 schema。 */
 declare const protocolErrorSchema: {
@@ -424,7 +312,7 @@ declare const requestFrameSchema: {
         };
         readonly method: {
             readonly type: "string";
-            readonly enum: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+            readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
         };
         readonly params: {};
     };
@@ -506,7 +394,7 @@ declare const notificationFrameSchema: {
                     readonly properties: {
                         readonly type: {
                             readonly type: "string";
-                            readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "error"];
+                            readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error"];
                         };
                     };
                 };
@@ -527,7 +415,7 @@ declare const reverseRequestFrameSchema: {
         };
         readonly method: {
             readonly type: "string";
-            readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+            readonly enum: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
         };
         readonly params: {};
     };
@@ -546,7 +434,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
             };
             readonly method: {
                 readonly type: "string";
-                readonly enum: readonly ["initialize", "probe", "run", "cancel", "interact", "read", "listModels", "validateModel", "dispose", "ping"];
+                readonly enum: readonly ["initialize", "probe", "run", "cancel", "read", "listModels", "validateModel", "dispose", "ping"];
             };
             readonly params: {};
         };
@@ -626,7 +514,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
                         readonly properties: {
                             readonly type: {
                                 readonly type: "string";
-                                readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "error"];
+                                readonly enum: readonly ["tool_start", "tool_end", "text_delta", "thinking_delta", "turn_end", "message_end", "compaction", "activity", "error"];
                             };
                         };
                     };
@@ -646,7 +534,7 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
             };
             readonly method: {
                 readonly type: "string";
-                readonly enum: readonly ["host/log", "host/askUser", "host/permission", "host/streamDelta", "host/poolResolved", "host/handleReady", "host/childSpawned", "host/childStateChanged", "host/roundLifecycle"];
+                readonly enum: readonly ["host/log", "host/askUser", "host/streamDelta", "host/handleReady", "host/childSpawned", "host/childStateChanged"];
             };
             readonly params: {};
         };
@@ -679,7 +567,42 @@ declare const ENGINE_PROTOCOL_SCHEMAS: {
  * 不得出现。词表覆盖常见拼写（子串匹配，非精确枚举）。
  */
 declare const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: readonly ["apikey", "api_key", "token", "credential", "password", "secret"];
-/** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
-declare const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[];
+/**
+ * run.params 的会话形态参数载荷 schema（draft-07 深载荷片段）。设计权威源：
+ * docs/architecture/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
+ *
+ * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
+ * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
+ * 刻意不做深校验（见本文件头注释），本片段供消费方（引擎读端结构化报错 / 测试正负
+ * 样本）按需深校验。
+ */
+declare const runSessionParamsSchema: {
+    readonly $schema: "http://json-schema.org/draft-07/schema#";
+    readonly title: "EngineRunSessionParams";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["recordId"];
+    readonly properties: {
+        readonly recordId: {
+            readonly type: "string";
+        };
+        readonly resume: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly required: readonly ["sessionRef"];
+            readonly properties: {
+                readonly sessionRef: {
+                    readonly type: "object";
+                    readonly additionalProperties: {
+                        readonly type: "string";
+                    };
+                };
+                readonly journalPath: {
+                    readonly type: "string";
+                };
+            };
+        };
+    };
+};
 
-export { AgentCallOpts, AgentOutcome, AgentUsage, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostPermissionParams, type HostPermissionResult, type HostPoolResolvedParams, type HostRoundLifecycleParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, InteractAction, type InteractParams, InteractResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, ProtocolError, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_NAMES, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseChannelParamsMap, type ReverseChannelResultMap, type ReverseRequestTimeoutClass, type RoundFailedPhase, type RoundIdlePhase, type RoundKeyedByRecord, type RoundKeyedByRun, type RoundLifecyclePhase, type RoundSettledPhase, type RunChatParams, type RunContextParams, type RunParams, type RunResult, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isHostRoundLifecycleParams, isHostStreamDeltaParams, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, successResponseFrameSchema };
+export { AgentCallOpts, AgentOutcome, CANCEL_SETTLE_GRACE_MS, CRASH_REBUILD_BACKOFF_MS, CRASH_REBUILD_MAX_ATTEMPTS, type CancelParams, type CancelResult, type DisposeParams, type DisposeResult, ENGINE_EVENT_COALESCE_DEFAULT, ENGINE_EVENT_COALESCE_ENV, ENGINE_PROTOCOL_SCHEMAS, ENGINE_PROTOCOL_VERSION, EngineCapabilities, EngineHandleData, FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS, HANDSHAKE_TIMEOUT_MS, type HostAskUserParams, type HostAskUserResult, type HostChildSpawnedParams, type HostChildStateChangedParams, type HostHandleReadyParams, type HostLogParams, type HostStreamDeltaParams, type InitializeParams, type InitializeResult, type ListModelsParams, type ListModelsResult, ModelCatalogEntry, PROTOCOL_METHODS, type PingParams, type PingResult, type ProbeParams, ProbeReport, type ProtocolMethod, type ProtocolParamsMap, type ProtocolResultMap, REVERSE_CHANNELS, REVERSE_CHANNEL_TIMEOUT_CLASS, REVERSE_REQUEST_TIMEOUT_MS, type ReadParams, ResumeAnchor, type ReverseChannel, type ReverseRequestTimeoutClass, type RunContextParams, type RunParams, type RunResult, type RunResumeParams, STDERR_TAIL_CHARS, SUPPORTED_PROTOCOL_RANGE, SessionView, type ValidateModelParams, type ValidateModelResult, errorResponseFrameSchema, isProtocolVersionCompatible, notificationFrameSchema, protocolErrorSchema, requestFrameSchema, reverseRequestFrameSchema, runSessionParamsSchema, successResponseFrameSchema };

package/dist/protocol/index.js

@@ -3,11 +3,8 @@ import {
   FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   errorResponseFrameSchema,
-  isHostRoundLifecycleParams,
-  isHostStreamDeltaParams,
   isNotificationFrame,
   isRequestFrame,
   isResponseFrame,
@@ -16,8 +13,9 @@ import {
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
+  runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-YFSN3D5N.js";
+} from "../chunk-TW2FAMAJ.js";
 import {
   CANCEL_SETTLE_GRACE_MS,
   CRASH_REBUILD_BACKOFF_MS,
@@ -42,7 +40,7 @@ import {
   isEngineProtocolErrorCode,
   isProtocolVersionCompatible,
   schemaEmulationFailedDetail
-} from "../chunk-PPEPBVCC.js";
+} from "../chunk-WS4WAZVR.js";
 import "../chunk-JSBRDJBE.js";
 export {
   CANCEL_SETTLE_GRACE_MS,
@@ -60,7 +58,6 @@ export {
   HANDSHAKE_TIMEOUT_MS,
   PROTOCOL_METHODS,
   REVERSE_CHANNELS,
-  REVERSE_CHANNEL_NAMES,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   REVERSE_REQUEST_TIMEOUT_MS,
   STDERR_TAIL_CHARS,
@@ -73,8 +70,6 @@ export {
   errorResponseFrameSchema,
   isEngineErrorPassthroughCode,
   isEngineProtocolErrorCode,
-  isHostRoundLifecycleParams,
-  isHostStreamDeltaParams,
   isNotificationFrame,
   isProtocolVersionCompatible,
   isRequestFrame,
@@ -84,6 +79,7 @@ export {
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
+  runSessionParamsSchema,
   schemaEmulationFailedDetail,
   successResponseFrameSchema
 };

package/dist/ui-types.cjs

@@ -3,6 +3,10 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
 var __copyProps = (to, from, except, desc) => {
   if (from && typeof from === "object" || typeof from === "function") {
     for (let key of __getOwnPropNames(from))
@@ -15,4 +19,16 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 
 // src/ui-types.ts
 var ui_types_exports = {};
+__export(ui_types_exports, {
+  isUiResponse: () => isUiResponse
+});
 module.exports = __toCommonJS(ui_types_exports);
+function isUiResponse(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  return typeof v.value === "string" || typeof v.confirmed === "boolean" || v.cancelled === true || v.ack === true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isUiResponse
+});

package/dist/ui-types.d.cts

@@ -3,11 +3,12 @@
  *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
  *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
 type UiMethod = "select" | "confirm" | "input" | "editor" | "notify" | "setStatus" | "setWidget" | "setTitle" | "set_editor_text" | (string & {});
-/** UI 请求（session-runner 构造后传给 handler）。
+/** UI 请求（引擎侧构造后经 host/askUser 送达宿主 handler）。
  *
  *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
- *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
- *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由引擎侧
+ *  ui-request-queue 从 ExtensionUiRequest 平铺构造）。channel/channelPayload 由
+ *  parseChannel 填充。
  *
  *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
 interface UiRequest {
@@ -35,8 +36,10 @@ interface UiRequest {
     /** channel 解析后的结构化 payload（已 JSON.parse）。
      *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
     channelPayload?: unknown;
-    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
-     *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由引擎侧 ui-request-queue 从
+     *  child.pid 填入——session-runner 已随协议化重构删除，填充点现住 pi 引擎包）。
+     *  L2 队列据此关联 rejectChildDialogs（子进程退出时批量取消，见
+     *  notifyChildProcessExited 的接线链）。
      *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
     _childPid?: number;
 }
@@ -54,9 +57,13 @@ type UiResponse = {
 } | {
     ack: true;
 };
+/** UiResponse 载荷结构判定（四成员判别；形态对齐 reverse-channels 的
+ *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前守卫，防宿主畸形帧
+ *  静默流入 UI 队列（S7：askUser 应答跨界无守卫）。 */
+declare function isUiResponse(value: unknown): value is UiResponse;
 /** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
  *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
  *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
 type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
 
-export type { UiMethod, UiRequest, UiRequestHandler, UiResponse };
+export { type UiMethod, type UiRequest, type UiRequestHandler, type UiResponse, isUiResponse };

package/dist/ui-types.d.ts

@@ -3,11 +3,12 @@
  *  fire-and-forget 类：notify/setStatus/setWidget/setTitle/set_editor_text（纯展示/写入）。
  *  (string & {}) 兜底：Pi 未来新增 method 或未知 method 走字符串字面量类型。 */
 type UiMethod = "select" | "confirm" | "input" | "editor" | "notify" | "setStatus" | "setWidget" | "setTitle" | "set_editor_text" | (string & {});
-/** UI 请求（session-runner 构造后传给 handler）。
+/** UI 请求（引擎侧构造后经 host/askUser 送达宿主 handler）。
  *
  *  method 是判别字段，决定排队策略（dialog 排队）和业务路由（channel 分发）。
- *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由 session-runner 从
- *  ExtensionUiRequest 平铺构造）。channel/channelPayload 由 parseChannel 填充。
+ *  method 特定字段按 method 可选出现（与 ExtensionUiRequest 1:1，由引擎侧
+ *  ui-request-queue 从 ExtensionUiRequest 平铺构造）。channel/channelPayload 由
+ *  parseChannel 填充。
  *
  *  契约来源：.fix-plans/00-master-summary.md §二 2.2。 */
 interface UiRequest {
@@ -35,8 +36,10 @@ interface UiRequest {
     /** channel 解析后的结构化 payload（已 JSON.parse）。
      *  ask_user: {questions, allowCancel}；gui_widget: {component}；无 channel: undefined。 */
     channelPayload?: unknown;
-    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由 session-runner.handleUiRequest 从
-     *  child.pid 填入）。L2 队列据此关联 rejectChildDialogs（child close 时批量 reject）。
+    /** 内部元数据字段：发起该 UI 请求的子进程 pid（由引擎侧 ui-request-queue 从
+     *  child.pid 填入——session-runner 已随协议化重构删除，填充点现住 pi 引擎包）。
+     *  L2 队列据此关联 rejectChildDialogs（子进程退出时批量取消，见
+     *  notifyChildProcessExited 的接线链）。
      *  下划线前缀表示内部字段，非 Pi 协议字段，不参与 stdin 回写。 */
     _childPid?: number;
 }
@@ -54,9 +57,13 @@ type UiResponse = {
 } | {
     ack: true;
 };
+/** UiResponse 载荷结构判定（四成员判别；形态对齐 reverse-channels 的
+ *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前守卫，防宿主畸形帧
+ *  静默流入 UI 队列（S7：askUser 应答跨界无守卫）。 */
+declare function isUiResponse(value: unknown): value is UiResponse;
 /** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
  *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
  *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */
 type UiRequestHandler = (req: UiRequest) => Promise<UiResponse>;
 
-export type { UiMethod, UiRequest, UiRequestHandler, UiResponse };
+export { type UiMethod, type UiRequest, type UiRequestHandler, type UiResponse, isUiResponse };

package/dist/ui-types.js

@@ -1 +1,7 @@
-import "./chunk-2DIMPZCQ.js";
+import {
+  isUiResponse
+} from "./chunk-EUSM6ZX4.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  isUiResponse
+};

package/package.json

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

package/src/cli-entry.ts

@@ -51,7 +51,12 @@ export function runEngineCliEntry(opts: RunEngineCliEntryOptions): void {
     log(level, component, message, data) {
       // stderr 兜底先落（反向通道未就绪/失败时日志不丢）；host/log 为数据面反向请求
       // （10s 应答分类），失败吞掉——日志面不能拖垮主链路。
-      process.stderr.write(`[${level}] [${component}] ${message}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}\n`);
+      // debug 不写 stderr：对齐 logger.ts CONSOLE_SINK 的「debug no-op」语义——
+      // 引擎 stderr 落宿主 [rpc:stderr] 全量 ERROR 级链路，debug 刷屏会淹没真异常
+      // （常态路径的分级降噪依赖此跳过）；host/log 反向请求仍全级别透传。
+      if (level !== "debug") {
+        process.stderr.write(`[${level}] [${component}] ${message}${data !== undefined ? ` ${JSON.stringify(data)}` : ""}\n`);
+      }
       void server.reverseRequest("host/log", { level, component, message }).catch(() => undefined);
     },
   });

package/src/data-dir.ts

@@ -12,8 +12,9 @@
 // warn-once 语义（回退非权威通道必须可观测），与 core 版行为逐字对齐。
 //
 // 通道调查结论（2026-08-25，P2 实测证据链，自 core 版头部保留）：
-//   - runtime spawn pi 主会话时 RpcClient.buildSafeEnv 从 runtime process.env 继承
-//     XYZ_ 前缀白名单变量（rpc-client.ts:14-30），且显式设置 PI_CODING_AGENT_DIR；
+//   - runtime spawn pi 主会话时 RpcClient 出站 env 从 runtime process.env 继承
+//     XYZ_ 前缀白名单变量（调查当时经私有 buildSafeEnv，现已被 buildPiOutboundEnv
+//     → buildOutboundChildEnv 共享构建器取代），且显式设置 PI_CODING_AGENT_DIR；
 //   - dev 模式 Electron main 设置 XYZ_AGENT_DATA_DIR（apps/electron/main/main.ts:122），
 //     经 process-control.ts:262 透传给 runtime → 透传链成立；
 //   - prod 默认路径（~/.xyz-agent 缺省）下 runtime 进程 env 中**没有**该变量