@zhushanwen/subagent-engine-sdk 0.2.1 → 0.4.0

package/src/env.ts

@@ -23,16 +23,16 @@ export const ENGINE_ENV_PREFIXES: readonly string[] = [
   'XYZ_', 'XYZ_AGENT_', 'XYZ_SUBAGENT_',
 ];
 
-/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。 */
+/** L1 deny + 显式剥除键集（镜像 shared SSOT，勿单独改动）。
+ *  互引（场景域分化，勿互混）：dev 装配器（apps/electron/scripts/dev-instance-lib.mjs
+ *  `LEAK_ENV_KEYS`）仍剥 RELAY_STD* 三键——dev 宿主进程环境防泄漏口径独立于引擎
+ *  spawn 面；本清单（引擎侧）已退役同名三键，写入方已清零。 */
 export const ENGINE_ENV_DENY_LIST: readonly string[] = [
   'XYZ_AGENT_PACKAGED',
   'XYZ_RUNTIME_TOKEN',
   'XYZ_AGENT_API_KEY',
   'XYZ_SUBAGENT_RELAY_SESSION_ID',
   'XYZ_SUBAGENT_RELAY_RECORD_ID',
-  'XYZ_SUBAGENT_RELAY_STDIN',
-  'XYZ_SUBAGENT_RELAY_STDOUT',
-  'XYZ_SUBAGENT_RELAY_STDERR',
 ];
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/journal-replay.ts

@@ -349,6 +349,10 @@ export function updateFromEvent(record: ReplayRecordView, event: AgentEvent): vo
     case "compaction":
       return;
 
+    // ── activity：纯活性信号，reducer no-op（协议语义见 contract-types）──
+    case "activity":
+      return;
+
     default: {
       // 穷尽性检查：新增 AgentEvent variant 时编译期报错
       const _exhaustive: never = event;

package/src/nesting-guard.ts

@@ -17,7 +17,7 @@
 //
 // [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
 // 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
-// 单点于公共层。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-⑤
+// 单点于公共层。设计权威源：docs/design/dual-track（已删 git 可追溯）§3.3 D3-⑤
 // + 双轨清单 #10。
 
 import { AsyncLocalStorage } from "node:async_hooks";

package/src/paths.ts

@@ -7,7 +7,7 @@ import { join } from 'node:path';
  * 自算池/journal 路径）；core 侧引用切换已完成（core execution/engine/paths.ts 为
  * re-export shim，子入口 ./engine/paths 解析路径不变）。
  *
- * 设计权威源：subagent-engine-abstraction.md D5/D6。
+ * 设计权威源：constraints.json C-ext-15（原 subagent-engine-abstraction.md D5/D6，已删，git 可追溯）。
  *
  * 为什么独立成模块：extension 写侧（journal 落盘 / preparer 池目录）与
  * runtime 校验侧（subagent-extractor 前缀白名单）必须同源推导——

package/src/port-contract.ts

@@ -28,8 +28,6 @@ import type {
   AgentOutcome,
   EngineCapabilities,
   EngineHandleData,
-  InteractAction,
-  InteractResult,
   ProbeReport,
   ResumeAnchor,
   SessionView,
@@ -64,26 +62,62 @@ export interface EngineStream {
   onDelta(delta: string): void;
 }
 
-/** run 的运行期上下文（core RunContext 结构等价镜像；chat? = 会话形态参数，缺省一次性任务）。 */
+/**
+ * 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/
+ * host/poolResolved 通道/EngineHandleData）已整体退役，本常量不再跨进程透传，仅
+ * 三类消费：① journal 落盘路径构造（core journal-wiring）；② 存量 record 兼容
+ * （zcode read 旧相对 dbPath 的锚定分支 + 持久化 engineHandle.poolKey 字段——
+ * record-store 读侧守卫要求非空，值恒本常量）；③ 引擎数据目录布局 SSOT paths.ts
+ * 的签名参数。**值逐字不变**（存量 journal 落盘路径与记录含该值分段，改名不改值）。
+ */
+export const SHARED_POOL_KEY = "shared";
+
+/** run 的运行期上下文（core RunContext 结构等价镜像；resume? = 会话形态参数，缺省一次性任务）。 */
 export interface RunContext {
   taskId: string;
-  poolKey: string;
   signal?: AbortSignal;
   onEvent?: (event: AgentEvent) => void;
   ctxModel?: EngineCtxModel;
   stream?: EngineStream;
   schemaEnv?: string;
   engineFallback?: { from: string; reason: string };
-  onPoolResolved?: (poolKey: string) => void;
-  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef" | "poolKey">) => void;
+  /**
+   * [F6] 根 session id（协议 run.params.ctx.sessionRootId 的进程内还原）——pi 引擎
+   * relay 归属键 SESSION_ID 的权威来源。additive 可选：宿主缺省不传。
+   */
+  sessionRootId?: string;
+  /**
+   * [Option C 协议化] 权威 subagent session 目录（协议 run.params.ctx.sessionDir 的
+   * 进程内还原）——pi 引擎组装 `--session-dir` 的唯一权威值（宿主
+   * getSubagentSessionDir 推导，引擎不自推导）。additive 可选：缺省走引擎内
+   * [LEGACY] fallback（独立运行/测试形态）。
+   */
+  sessionDir?: string;
+  onHandleReady?: (partial: Pick<EngineHandleData, "sessionRef">) => void;
   /** 一次性子进程 pid 上报（host/childSpawned 载荷形态；ChildProcess 句柄不跨协议面）。 */
   onChildSpawned?: (child: { pid: number | undefined; killed: boolean }) => void;
   /**
-   * [v1.x] chat 会话形态参数（协议 run.params.chat 的进程内还原；缺省 = 一次性任务
-   * 形态）。recordId = chat 轮次关联键与 interact 定位键；resume 锚点存在 = 冷续
-   * （--session 续写原文件），不存在 = 首轮新建。
+   * 子进程退出态上报（host/childStateChanged 载荷形态；SR-4 接线：宿主镜像据此取消
+   * 该 pid 的挂起 dialog）。引擎侧只在 exited 相位上报——running 由 onChildSpawned 覆盖。
+   */
+  onChildStateChanged?: (p: {
+    pid: number;
+    recordId: string;
+    state: "running" | "exited";
+    killed: boolean;
+    exitCode?: number;
+    signal?: string;
+  }) => void;
+  /**
+   * [H1 U6 终态] resume 续聊参数（协议 run.params.resume 的进程内还原；唯一会话形态
+   * 键——原 v1.x `chat` 字段已随键切换退役）。recordId = 轮次关联键与镜像帧锚定键；
+   * resume 锚点存在 = 冷续（--session 续写原文件），不存在 = 首轮新建。缺省 =
+   * 一次性任务形态。
    */
-  chat?: { recordId: string; resume?: ResumeAnchor };
+  resume?: { recordId: string; resume?: ResumeAnchor };
 }
 
 export interface EngineHandle {
@@ -101,7 +135,6 @@ export interface EnginePort {
   capabilities(): EngineCapabilities;
   probe(opts?: { force?: boolean }): Promise<ProbeReport>;
   run(task: EngineAgentCallOpts, ctx: RunContext): Promise<EngineRunResult>;
-  interact(handle: EngineHandle, action: InteractAction): Promise<InteractResult>;
   read(handle: EngineHandle): Promise<SessionView>;
   listModels?(): Array<{ id: string; name?: string }> | null;
   validateModel?(modelRef: string | undefined): { canonicalRef: string };

package/src/protocol/contract-types.ts

@@ -1,19 +1,22 @@
 // src/protocol/contract-types.ts
 //
 // 引擎面契约类型 SSOT（协议两侧不许各写一份；core 反向 re-export 保上层消费面）。
-// 设计权威源：docs/design/subagent-engine-protocolization.md §3.5.1 D7 类型闭包表 +
+// 设计权威源：docs/architecture/subagent-engine-protocolization.md §3.5.1 D7 类型闭包表 +
 // impl-plan §2.1「类型闭包处置」。
 //
 // 搬运口径（逐字对照，结构等价、零 core import）：
 //   - AgentEvent / AgentUsage / AgentUsageTotal / ToolCallResult / ToolCall /
-//     InternalToolCall / Turn ← core execution/types.ts（2026-09-09 实测 :164-:313）
+//     InternalToolCall / Turn ← core execution/assembly/types.ts（2026-09-09 实测 :164-:313）
 //   - ReplayedTurn / SessionView / EngineHandleData / EngineCapabilities / ProbeReport /
-//     InteractAction / InteractResult / AgentOutcome ← core execution/engine/types.ts
+//     AgentOutcome ← core execution/engine/types.ts
 //   - AgentFailureKind / AgentOutcomeUsage（core 名 AgentUsage，orchestration 版）/
 //     ToolCallEntry / AgentCallOpts 子集 ← core orchestration/models/types.ts
-//   - WorktreeHandle ← core execution/types.ts:349（SDK 结构等价副本——设计 §3.5.1
+//   - WorktreeHandle ← core execution/assembly/types.ts:349（SDK 结构等价副本——设计 §3.5.1
 //     点名「AgentCallOpts.worktree 的 WorktreeHandle 即这类副本」）
 //
+// [H1] InteractAction / InteractResult 已随 chat-run 统一退役（U5 删除；
+// docs/architecture/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
+//
 // core 域类型（ExecutionRecord / Turn 的宿主内部态消费）留 core；SDK 侧一切类型为
 // 结构等价形态，漂移由双向可赋值断言（AssertMutuallyAssignable）在 typecheck 期抓出
 // ——core 侧断言挂靠归 W2（本文件导出该类型助手供其复用），SDK 侧样板见
@@ -41,7 +44,7 @@ export type AssertMutuallyAssignable<A, B> = [A] extends [B]
 // 事件面（AgentEvent 及其字段型）
 // ============================================================
 
-/** token 用量（message_end 单条消息增量）。← core execution/types.ts AgentUsage。 */
+/** token 用量（message_end 单条消息增量）。← core execution/assembly/types.ts AgentUsage。 */
 export interface AgentUsage {
   input: number;
   output: number;
@@ -96,8 +99,12 @@ export interface Turn {
 }
 
 /**
- * 引擎事件（8 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ * 引擎事件（9 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
+ * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
+ *
+ * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
+ * （core journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
+ * 无进展守护刷新判活（长工具执行期）。节流属生产者实现细节，不进协议承诺。
  */
 export type AgentEvent =
   | { type: "tool_start"; toolName: string; args?: unknown }
@@ -107,6 +114,7 @@ export type AgentEvent =
   | { type: "turn_end"; summary?: string }
   | { type: "message_end"; usage?: AgentUsage; error?: string }
   | { type: "compaction" }
+  | { type: "activity" }
   | { type: "error"; message: string };
 
 // ============================================================
@@ -114,7 +122,7 @@ export type AgentEvent =
 // ============================================================
 
 /**
- * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / interact / read 的
+ * EngineHandle 的持久化形态（JSON v1）。协议 run 终态应答 / read 的
  * handle 载荷（引擎不持有宿主运行时引用，data 即全部）。
  */
 export interface EngineHandleData {
@@ -123,9 +131,11 @@ export interface EngineHandleData {
   engineId: string;
   /** 引擎自定义定位键值。pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }。 */
   sessionRef: Record<string, string>;
-  /** 隔离池定位。pi 无池化恒 'shared'。 */
-  poolKey: string;
-  /** journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。 */
+  /**
+   * journal 绝对路径（read 第②级数据源；宿主读前校验前缀白名单）。缺省 = 无 journal。
+   * [池抽象降级 2026-09-13] 原 poolKey 字段已删除——两引擎 poolKey 恒 'shared'
+   * （SDK SHARED_POOL_KEY），journal 固定落 engines/<engineId>/shared/，字段零信息量。
+   */
   journalPath?: string;
   /** probe 实测版本（漂移排查锚点）。 */
   engineVersion?: string;
@@ -135,18 +145,15 @@ export interface EngineHandleData {
 
 /**
  * [v1.x] 冷续 resume 锚点——EngineHandleData 定位键的投影子集（诊断字段
- * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。两处消费：
- *   - run.params.chat.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
- *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）；
- *   - host/roundLifecycle 载荷 anchor（引擎 → 宿主：轮次终态时回填当前锚点，
- *     宿主据此刷新冷续依据——pi 定位键形态同 EngineHandleData.sessionRef 注释）。
+ * v/engineVersion/adapterVersion 不属锚点语义，不随锚点走）。消费点：
+ *   - run.params.resume（宿主 → 引擎：冷续重开已 idle 的 session，pi 消费
+ *     sessionRef.sessionFile —— 对照 core SpawnResumeOpts.sessionFile 的锚点面）。
+ * [H1 U6 已切换] 键切换单批完成（读写端同批），锚点仅经 resume 键携带。
  * 类型层与 EngineHandleData 定位形态的对照由测试断言（Pick 可赋值闭包）锁定。
  */
 export interface ResumeAnchor {
   /** 引擎定位键（pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }）。 */
   sessionRef: Record<string, string>;
-  /** 隔离池定位（锚点补全 handle 重建所需；pi 无池化恒 'shared'）。 */
-  poolKey: string;
   /** journal 绝对路径（read 降级链第②级数据源；无 journal 缺省）。 */
   journalPath?: string;
 }
@@ -188,8 +195,16 @@ export interface EngineCapabilities {
   schemaEnforcement: "native" | "emulated";
   /** 注意区分「引擎 RPC 层有此能力」与「subagent 链路已接通」。 */
   steer: "native" | "emulated" | "unsupported";
-  /** interact 控制面（message/close/cancel + idle）。 */
-  conversation: "native" | "unsupported";
+  /**
+   * [H1 D5 语义收窄] resume 能力位（chat 续聊 = 新 run + resume 锚点的承载前提；
+   * 原名字沿用——conversation 位保留、语义从「interact 长驻控制面」收窄为
+   * 「resume 续聊能力」，gate 判据与消费方不变）。
+   * [U6 / 永久会话模型 §3.2.6 要点 4] 新值 "cold" = 冷恢复会话：resume 读通道取
+   * 结构化历史 + 新 session 注入（无热 steering）。gate 判据仍是 `=== "unsupported"`
+   * 拒绝——"cold" 在 gate 面与 "native" 等价放行，差异只在续聊形态（新 session
+   * 注入 vs 原地续写）。
+   */
+  conversation: "native" | "cold" | "unsupported";
   /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
   personaInjection: "file" | "flag" | "prompt";
   /** 粗粒度引擎：GUI 显示降级为阶段态。 */
@@ -218,20 +233,6 @@ export interface ProbeReport {
   error?: { code: string; recovery: string };
 }
 
-/**
- * interact 的 action（交互控制面）。interrupt: true = steer（抢占）/ false|缺省 =
- * followUp（排队）；不支持抢占的引擎忽略。
- */
-export type InteractAction =
-  | { kind: "message"; payload: string; interrupt?: boolean }
-  | { kind: "close"; payload?: { force: boolean } }
-  | { kind: "cancel" };
-
-/** interact 的结果（失败码 = engine_session_not_resumable / engine_capability_unsupported 等）。 */
-export type InteractResult =
-  | { ok: true; delivered: true }
-  | { ok: false; code: string; message: string };
-
 // ============================================================
 // 终态 / 任务声明
 // ============================================================
@@ -261,7 +262,7 @@ export interface ToolCallEntry {
   input: string;
 }
 
-/** worktree 句柄（结构等价副本；core 权威定义在 execution/types.ts:349）。 */
+/** worktree 句柄（结构等价副本；core 权威定义在 execution/assembly/types.ts:349）。 */
 export interface WorktreeHandle {
   /** checkout 目录（子 agent 工作目录）。 */
   readonly path: string;

package/src/protocol/engine-protocol.ts

@@ -1,7 +1,7 @@
 // src/protocol/engine-protocol.ts
 //
 // 引擎协议 v1 版本常量与协商（W1 契约根）。设计权威源：
-// docs/design/subagent-engine-protocolization.md §3.3 + impl-plan §2.1。
+// docs/architecture/subagent-engine-protocolization.md §3.3 + impl-plan §2.1。
 //
 // 传输 = stdio NDJSON（每行一个 JSON 对象）。stdout 独占协议帧；stderr 常驻排空
 // （内存环形缓冲尾 400 字符，崩溃现场由 engine_crashed 携带，宿主侧不落盘）。
@@ -10,14 +10,25 @@
 // engine_protocol_mismatch（含双方版本 + 升级指引），该引擎标记不可用，
 // 不影响其他引擎与宿主。
 //
-// [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）]：chat 域增量（run.params.chat
-// 可选参数、host/roundLifecycle 通道、host/streamDelta 的 recordId 关联形态）以
-// **可选载荷/可选参数**形态向后兼容，major 不 bump、不引入 minor 协商位：
-//   - 新 core × 旧引擎：chat 请求被 conversation gate 同步拒（manifest 无 gate 位，
+// [v1.x 增量语义（chat-domain 设计 §3.2 D1-A/§3.3）][H1 后历史叙述——run.params.chat
+// 已随 U6 删除，现唯一会话形态键 = run.params.resume]：chat 域增量（原 run.params.chat
+// 可选参数、host/streamDelta 的 recordId 关联形态）曾以**可选载荷/可选参数**形态向后
+// 兼容，major 不 bump、不引入 minor 协商位：
+//   - 新 core × 旧引擎：conversation 请求（resume 续聊形态）被 conversation gate
+//     同步拒（manifest 无 gate 位，
 //     A6 方向——engine_capability_unsupported + 升级引擎包指引）；run 域零影响；
-//   - 旧 core × 新引擎：新引擎可能发出旧 core 词表外的 host/roundLifecycle——
-//     既有反向路由对未知 host/* 通道回 {unsupported:true} 引擎自行降级，无需
-//     独立负向场景（设计已裁决）。
+//   事件变体增量同政策（例：activity 活性信号变体）：新变体以可选载荷形态进
+//   union，旧宿主 runtime 对其 no-op（reducer default 分支安全落空 / journal
+//   豁免面不感知），协议版本维持 1、不 bump。
+//
+// [H1 双键过渡（chat-run 统一，docs/architecture/subagent-chat-run-unification.md §3.3
+// D3 + §5 U1 行）][H1 U6 已切换]：run.params.resume 曾与原 run.params.chat 载荷
+// 同形并存（additive 可选，协议版本维持 1）；U1 只加键——U2-U5 过渡期 core 恒
+// 构造旧 `chat` 键、pi 引擎恒读 `ctx.chat`。U6 已单批同时切换写端（core 构造
+// resume）与读端（pi 改读）并删 `chat` 键，resume 现为唯一会话形态键——全程不存在
+// 「写新读旧」窗口（错配 = resume 静默失效、每轮新文件、sessionFile 被覆盖）。
+// 同批退役已落地：轮次相位反向通道与 interact 方法已随 U5 删除（D5——续聊轮统一
+// 为新 run + resume 锚点，轮次终态由 run 应答承载）。
 
 /** 协议版本（引擎包 manifest `xyz-agent.subagentEngine.protocol` 与 initialize 应答同值）。 */
 export const ENGINE_PROTOCOL_VERSION = 1;
@@ -72,10 +83,9 @@ export 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「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */
 export type ReverseRequestTimeoutClass = "data-plane" | "interaction";

package/src/protocol/error-codes.ts

@@ -101,12 +101,13 @@ export function engineProtocolMismatchError(engineVersion: number): EngineSdkErr
 }
 
 // ============================================================
-// [v1.x] conversation gate 位负向：chat 请求（run 会话形态）同步拒
+// [v1.x] conversation gate 位负向：conversation 请求（resume 续聊会话形态）同步拒
 // ============================================================
 
 /**
- * [v1.x] chat 会话形态的 gate 拒绝具名错误（chat-domain 设计 §3.2 D1-A +
- * 验收 A6：manifest 无 conversation gate 位的引擎收到 chat 请求 → 同步拒）。
+ * [v1.x] resume 会话形态（run.params.resume）的 gate 拒绝具名错误（chat-domain
+ * 设计 §3.2 D1-A + 验收 A6：manifest 无 conversation gate 位的引擎收到
+ * conversation 请求 → 同步拒；[H1] 文案随 D5 语义收窄——续聊 = resume 续聊）。
  * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
  * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
  * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
@@ -114,15 +115,15 @@ export function engineProtocolMismatchError(engineVersion: number): EngineSdkErr
 export function engineConversationUnsupportedError(engineId: string): EngineSdkError {
   return new EngineSdkError(
     "engine_capability_unsupported",
-    `engine '${engineId}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
-      `manifest 无 conversation gate 位——无同进程 idle 复用，message/close 交互控制面不可用）`,
+    `engine '${engineId}' 不支持 resume 续聊（capabilities.conversation = 'unsupported'，` +
+      `manifest 无 conversation gate 位）`,
     `去掉 conversation 参数（一次性任务默认形态），或修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）`,
     { engineId, capability: "conversation", declared: "unsupported" },
   );
 }
 
 /**
- * [v1.x] chat 会话形态（run.params.chat / task.conversation=true）派发前的同步 gate：
+ * [v1.x] resume 会话形态（run.params.resume / task.conversation=true）派发前的同步 gate：
  * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
  * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
  * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支

package/src/protocol/frames.ts

@@ -82,13 +82,11 @@ export interface ReverseRequestFrame {
 export type ReverseResponseResult =
   /** 数据面类：处理确认。 */
   | { ok: true }
-  /** 人机交互类（askUser/permission）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+  /** 人机交互类（askUser）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
   | { ack: true }
   /** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
   | { unsupported: true };
 
-export type AnyFrame = RequestFrame | ResponseFrame | NotificationFrame | ReverseRequestFrame;
-
 // ============================================================
 // 判别守卫（W2 行解析器消费；结构判定，不抛错）
 // ============================================================

package/src/protocol/methods.ts

@@ -1,11 +1,12 @@
 // src/protocol/methods.ts
 //
-// 10 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
-// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」。
+// 9 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
+// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」（[H1] 收敛为 9）。
 //
-// [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：方法集不变（chat 轮次 = run 会话形态
-// + 既有 interact，不新造 chatRound 方法——D1-B 被否）；增量以可选参数形态落在
-// run.params.chat（会话形态参数 + 冷续 resume 锚点），major 不 bump。
+// [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：增量以可选参数形态落在 run.params.chat
+// （会话形态参数 + 冷续 resume 锚点），major 不 bump。[H1] chat-run 统一后续聊 =
+// 新 run + resume 锚点（docs/architecture/subagent-chat-run-unification.md §3.3 D5/D7），
+// 既有 interact 方法已随 U5 删除，方法集收敛为 9 个。
 //
 // 应答面补充约定（设计 §3.3）：initialize 应答仅诊断（与 manifest 不一致 → warn 留痕，
 // 不参与同步成员判据；唯一阻断面 = 被 gate 能力位多声明 → engine_capability_mismatch）；
@@ -17,21 +18,22 @@ import type {
   EngineCapabilities,
   EngineHandleData,
   AgentOutcome,
-  InteractAction,
-  InteractResult,
   ModelCatalogEntry,
   ProbeReport,
   ResumeAnchor,
   SessionView,
 } from "./contract-types.ts";
 
-/** 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。 */
+/**
+ * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
+ * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
+ */
 export type ProtocolMethod =
   | "initialize"
   | "probe"
   | "run"
   | "cancel"
-  | "interact"
   | "read"
   | "listModels"
   | "validateModel"
@@ -44,7 +46,6 @@ export const PROTOCOL_METHODS = [
   "probe",
   "run",
   "cancel",
-  "interact",
   "read",
   "listModels",
   "validateModel",
@@ -60,8 +61,6 @@ export const PROTOCOL_METHODS = [
  * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
  */
 export interface RunContextParams {
-  /** 隔离池归属（journal 归属错 = 缺失后果）。 */
-  poolKey: string;
   /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
   cwd: string;
   /** 请求模型 ref（未传 = 引擎缺省模型）。 */
@@ -74,24 +73,40 @@ export interface RunContextParams {
   engineFallback?: { from: string; reason: string };
   /** 事件粒度请求（引擎按 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] run 的 chat 会话形态参数（chat-domain 设计 §3.2 D1-A）
+// [H1] run 的 resume 会话形态参数（chat-run 统一终态；原 v1.x chat 键已退役）
 // ============================================================
 
 /**
- * [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）。
  */
-export interface RunChatParams {
+export interface RunResumeParams {
   recordId: string;
   resume?: ResumeAnchor;
 }
@@ -127,11 +142,11 @@ export 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 通知；长运行方法，应答到达即终态）。 */
@@ -153,11 +168,6 @@ export interface CancelResult {
   ok: true;
 }
 
-export interface InteractParams {
-  handle: EngineHandleData;
-  action: InteractAction;
-}
-
 export interface ReadParams {
   handle: EngineHandleData;
   /** 数据根必填：存量池时代引擎自算池/journal 相对 dbPath 的定位需要它（设计钉死）。 */
@@ -206,7 +216,6 @@ export interface ProtocolParamsMap {
   probe: ProbeParams;
   run: RunParams;
   cancel: CancelParams;
-  interact: InteractParams;
   read: ReadParams;
   listModels: ListModelsParams;
   validateModel: ValidateModelParams;
@@ -220,7 +229,6 @@ export interface ProtocolResultMap {
   probe: ProbeReport;
   run: RunResult;
   cancel: CancelResult;
-  interact: InteractResult;
   read: SessionView;
   listModels: ListModelsResult;
   validateModel: ValidateModelResult;