@zhushanwen/subagent-engine-sdk 0.3.0 → 0.5.0

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" },
       },
     },