@zhushanwen/subagent-engine-sdk 0.3.0 → 0.4.0

package/src/protocol/contract-types.ts

@@ -1,21 +1,21 @@
 // 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 /
 //     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/design/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
+// docs/architecture/subagent-chat-run-unification.md §3.3 D5——续聊统一为新 run + resume）。
 //
 // core 域类型（ExecutionRecord / Turn 的宿主内部态消费）留 core；SDK 侧一切类型为
 // 结构等价形态，漂移由双向可赋值断言（AssertMutuallyAssignable）在 typecheck 期抓出
@@ -44,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;
@@ -100,7 +100,7 @@ export interface Turn {
 
 /**
  * 引擎事件（9 种，协议 event.params.event 逐字序列化——「事件与 handle 序列化逐字
- * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/types.ts 注释）。
+ * 兼容」不变量 3 的类型面）。语义锚点 = pi（ACP 词汇对照见 core execution/assembly/types.ts 注释）。
  *
  * activity = 纯活性信号：双侧 reducer no-op、不开 turn、不写状态、不落 journal
  * （core journal-wiring 对其豁免 append），只承诺「引擎活跃时周期性出现」——供宿主
@@ -131,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;
@@ -152,8 +154,6 @@ export interface EngineHandleData {
 export interface ResumeAnchor {
   /** 引擎定位键（pi = { recordId?, sessionFile? }；zcode = { sessionId, dbPath }）。 */
   sessionRef: Record<string, string>;
-  /** 隔离池定位（锚点补全 handle 重建所需；pi 无池化恒 'shared'）。 */
-  poolKey: string;
   /** journal 绝对路径（read 降级链第②级数据源；无 journal 缺省）。 */
   journalPath?: string;
 }
@@ -199,8 +199,12 @@ export interface EngineCapabilities {
    * [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" | "unsupported";
+  conversation: "native" | "cold" | "unsupported";
   /** 决定 persona 路由策略（file/flag/prompt 通道）。 */
   personaInjection: "file" | "flag" | "prompt";
   /** 粗粒度引擎：GUI 显示降级为阶段态。 */
@@ -258,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 携带，宿主侧不落盘）。
@@ -21,7 +21,7 @@
 //   union，旧宿主 runtime 对其 no-op（reducer default 分支安全落空 / journal
 //   豁免面不感知），协议版本维持 1、不 bump。
 //
-// [H1 双键过渡（chat-run 统一，docs/design/subagent-chat-run-unification.md §3.3
+// [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 构造
@@ -83,9 +83,9 @@ export const ENGINE_EVENT_COALESCE_DEFAULT = "0";
 
 /**
  * 反向请求超时二分（帧④注释，R9-2）：
- * - 数据面类（host/log / host/streamDelta / host/poolResolved / host/handleReady /
+ * - 数据面类（host/log / host/streamDelta / host/handleReady /
  *   host/childSpawned / host/childStateChanged）：10s 未答 = 引擎故障；
- * - 人机交互类（host/askUser / host/permission）：不设统一超时——core 先回 {ack:true}，
+ * - 人机交互类（host/askUser）：不设统一超时——core 先回 {ack:true}，
  *   结果异步到达；按 ADR-0047「静默 ≠ 卡死」用无进展检测/用户取消，不据此判引擎故障。
  */
 export type ReverseRequestTimeoutClass = "data-plane" | "interaction";

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

@@ -5,7 +5,7 @@
 //
 // [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：增量以可选参数形态落在 run.params.chat
 // （会话形态参数 + 冷续 resume 锚点），major 不 bump。[H1] chat-run 统一后续聊 =
-// 新 run + resume 锚点（docs/design/subagent-chat-run-unification.md §3.3 D5/D7），
+// 新 run + resume 锚点（docs/architecture/subagent-chat-run-unification.md §3.3 D5/D7），
 // 既有 interact 方法已随 U5 删除，方法集收敛为 9 个。
 //
 // 应答面补充约定（设计 §3.3）：initialize 应答仅诊断（与 manifest 不一致 → warn 留痕，
@@ -26,7 +26,7 @@ import type {
 
 /**
  * 正向方法名联合（恰好 9 个；PROTOCOL_METHODS 常量数组与之同源互证）。
- * [H1] `interact` 成员已随 chat-run 统一退役（docs/design/subagent-chat-run-unification.md
+ * [H1] `interact` 成员已随 chat-run 统一退役（docs/architecture/subagent-chat-run-unification.md
  * §3.3 D5：续聊轮统一为「新 run + resume 锚点」，U5 删除）。
  */
 export type ProtocolMethod =
@@ -61,8 +61,6 @@ export const PROTOCOL_METHODS = [
  * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
  */
 export interface RunContextParams {
-  /** 隔离池归属（journal 归属错 = 缺失后果）。 */
-  poolKey: string;
   /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
   cwd: string;
   /** 请求模型 ref（未传 = 引擎缺省模型）。 */
@@ -96,7 +94,7 @@ export interface RunContextParams {
 // ============================================================
 
 /**
- * [H1] run 的 resume 会话形态参数（设计 docs/design/subagent-chat-run-unification.md
+ * [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 续聊」。

package/src/protocol/reverse-channels.ts

@@ -1,10 +1,14 @@
 // src/protocol/reverse-channels.ts
 //
-// 8 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
+// 6 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
 // 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」。
 // [H1] chat 域 v1.x 增量曾新增的第 9 通道（轮次相位帧）已随 chat-run 统一退役
-// （docs/design/subagent-chat-run-unification.md §3.3 D5，U5 删除）——轮次终态
-// 改由 run 应答（agent_settled resolve）承载，通道集收敛回 8 个。
+// （docs/architecture/subagent-chat-run-unification.md §3.3 D5，U5 删除）——轮次终态
+// 改由 run 应答（agent_settled resolve）承载。
+// [池抽象降级 2026-09-13] 原 host/poolResolved 通道（第 8 条）随 poolKey 协议面退役
+// 一并删除（两引擎 poolKey 恒 'shared'、journal 落盘路径固定，回调零信息量）。
+// [permission 通道退役 2026-09-13] host/permission 骨架删除（两引擎 permissionMode=
+// native 零 emit、core 零注入——未接线死通道），通道集收敛为 6 个。
 //
 // 应答约定：数据面类回 {ok:true}（REVERSE_REQUEST_TIMEOUT_MS=10s 未答 = 引擎故障 →
 // 杀进程 + 在途 run 失败）；人机交互类走 ack 两阶段——先回 {ack:true}，结果异步到达
@@ -15,14 +19,12 @@ import type { ReverseRequestTimeoutClass } from "./engine-protocol.ts";
 import type { UiRequest, UiResponse } from "../ui-types.ts";
 
 /**
- * 反向通道名联合（恰好 8 个；REVERSE_CHANNELS 常量数组与之同源互证）。
+ * 反向通道名联合（恰好 6 个；REVERSE_CHANNELS 常量数组与之同源互证）。
  */
 export type ReverseChannel =
   | "host/log"
   | "host/askUser"
-  | "host/permission"
   | "host/streamDelta"
-  | "host/poolResolved"
   | "host/handleReady"
   | "host/childSpawned"
   | "host/childStateChanged";
@@ -33,9 +35,7 @@ export type ReverseChannel =
 export const REVERSE_CHANNELS = [
   "host/log",
   "host/askUser",
-  "host/permission",
   "host/streamDelta",
-  "host/poolResolved",
   "host/handleReady",
   "host/childSpawned",
   "host/childStateChanged",
@@ -48,12 +48,10 @@ export const REVERSE_CHANNELS = [
 export const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass> = {
   "host/log": "data-plane",
   "host/streamDelta": "data-plane",
-  "host/poolResolved": "data-plane",
   "host/handleReady": "data-plane",
   "host/childSpawned": "data-plane",
   "host/childStateChanged": "data-plane",
   "host/askUser": "interaction",
-  "host/permission": "interaction",
 };
 
 // ============================================================
@@ -78,62 +76,25 @@ export interface HostAskUserParams {
 /** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
 export type HostAskUserResult = UiResponse;
 
-/**
- * host/permission：权限询问（引擎请求宿主裁决工具执行）。
- * v1 骨架字段（设计未钉死载荷细节，细化归各引擎提取设计；W2 实装 core 应答端时
- * 若需扩展走 additive 演进）。
- */
-export interface HostPermissionParams {
-  runId: string;
-  toolName: string;
-  args?: unknown;
-  /** 请求方向引擎给出的原因/说明（展示用）。 */
-  reason?: string;
-}
-
-/** host/permission 两阶段结果。 */
-export type HostPermissionResult = { approved: boolean } | { unsupported: true };
-
 /**
  * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
  *
- * [H1 U6 现行语义] 关联键恒 runId（run 域轮与 chat 续聊轮已统一为 run——续聊轮
- * 是携带 resume 锚点的新 run，runId 由 core 在 run 帧分配）。recordId 键分支是
- * v1.x 旧引擎的兼容载荷形态（存量兼容读，现行引擎不写）。
- * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
+ * 关联键恒为 runId（runId 由 core 在 run 帧分配）；[H1] chat 续聊轮经 resume run
+ * 复用 runId 关联（原 recordId 关联键随 interact 面退役删除）。
  */
-export type HostStreamDeltaParams =
-  | { runId: string; recordId?: undefined; delta: string }
-  | { recordId: string; runId?: undefined; delta: string };
-
-/** streamDelta 载荷结构判定（关联键互斥 + delta 形状；消费侧共用，防双侧各写一份）。 */
-export function isHostStreamDeltaParams(value: unknown): value is HostStreamDeltaParams {
-  if (typeof value !== "object" || value === null) return false;
-  const v = value as Record<string, unknown>;
-  const hasRunId = typeof v.runId === "string";
-  const hasRecordId = typeof v.recordId === "string";
-  // 恰一键：无键 / 双键 / 键非 string 都拒
-  if (hasRunId === hasRecordId) return false;
-  return typeof v.delta === "string";
-}
-
-/**
- * host/poolResolved：journal 落盘路径单一权威（契约：必须在首个事件 emit 前调用——
- * 否则 journal 归属错）。载荷 = core onPoolResolved(poolKey) 的 runId 关联形态。
- */
-export interface HostPoolResolvedParams {
+export interface HostStreamDeltaParams {
   runId: string;
-  poolKey: string;
+  delta: string;
 }
 
 /**
  * host/handleReady：运行中句柄回填（core onHandleReady 语义：session/create 应答后、
  * 早于 run resolve；AGENTS.md 关键规则 9「重开 session 仍可见」的前提）。
+ * [池抽象降级 2026-09-13] 原 poolKey 字段已随协议面 poolKey 退役删除。
  */
 export interface HostHandleReadyParams {
   runId: string;
   sessionRef: Record<string, string>;
-  poolKey: string;
 }
 
 /**
@@ -160,27 +121,3 @@ export interface HostChildStateChangedParams {
   exitCode?: number;
   signal?: string;
 }
-
-/** 通道 → 载荷类型映射。 */
-export 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;
-}
-
-/** 通道 → 异步/同步结果类型映射（ack 两阶段通道的第二阶段 result）。 */
-export 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 };
-}

package/src/protocol/schema.ts

@@ -12,7 +12,6 @@
 // 帧校验的目的是行解析器快速拒格式坏帧，不做深校验（深校验成本高于收益，坏载荷
 // 由消费方结构化报错）。
 
-import type { ReverseChannel } from "./reverse-channels.ts";
 import { REVERSE_CHANNELS } from "./reverse-channels.ts";
 import { PROTOCOL_METHODS } from "./methods.ts";
 
@@ -151,16 +150,13 @@ export const FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
   "secret",
 ] as const;
 
-/** 反向通道名词表导出（schema enum 与 W2 路由同源）。 */
-export const REVERSE_CHANNEL_NAMES: readonly ReverseChannel[] = REVERSE_CHANNELS;
-
 // ============================================================
 // [H1] run 会话形态参数载荷 schema（resume 单键校验权威）
 // ============================================================
 
 /**
  * run.params 的会话形态参数载荷 schema（draft-07 深载荷片段）。设计权威源：
- * docs/design/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
+ * docs/architecture/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
  *
  * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
  * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
@@ -178,11 +174,10 @@ export const runSessionParamsSchema = {
     resume: {
       type: "object",
       additionalProperties: false,
-      required: ["sessionRef", "poolKey"],
+      required: ["sessionRef"],
       properties: {
         // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
         sessionRef: { type: "object", additionalProperties: { type: "string" } },
-        poolKey: { type: "string" },
         journalPath: { type: "string" },
       },
     },