@zhushanwen/subagent-engine-sdk 0.2.1 → 0.4.0

package/src/protocol/reverse-channels.ts

@@ -1,9 +1,14 @@
 // src/protocol/reverse-channels.ts
 //
-// 9 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
-// 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」
-// + chat 域 v1.x 增量（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1-A：
-// 第 9 通道 host/roundLifecycle 承载轮次终态事件与 record 回写）。
+// 6 反向通道（引擎 → core，帧④，必须应答）载荷与超时二分。设计权威源：
+// 设计 §3.3 方法集表 host/* 行 + impl-plan §2.1「8 反向通道」与「反向请求超时二分」。
+// [H1] chat 域 v1.x 增量曾新增的第 9 通道（轮次相位帧）已随 chat-run 统一退役
+// （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}，结果异步到达
@@ -12,48 +17,41 @@
 
 import type { ReverseRequestTimeoutClass } from "./engine-protocol.ts";
 import type { UiRequest, UiResponse } from "../ui-types.ts";
-import type { AgentUsage, ResumeAnchor } from "./contract-types.ts";
-import type { ProtocolError } from "./frames.ts";
 
-/** 反向通道名联合（恰好 9 个；REVERSE_CHANNELS 常量数组与之同源互证）。 */
+/**
+ * 反向通道名联合（恰好 6 个；REVERSE_CHANNELS 常量数组与之同源互证）。
+ */
 export type ReverseChannel =
   | "host/log"
   | "host/askUser"
-  | "host/permission"
   | "host/streamDelta"
-  | "host/poolResolved"
   | "host/handleReady"
   | "host/childSpawned"
-  | "host/childStateChanged"
-  | "host/roundLifecycle";
+  | "host/childStateChanged";
 
+/**
+ * 通道名全集（运行时顺序化枚举；与 ReverseChannel 的同源关系由测试断言）。
+ */
 export const REVERSE_CHANNELS = [
   "host/log",
   "host/askUser",
-  "host/permission",
   "host/streamDelta",
-  "host/poolResolved",
   "host/handleReady",
   "host/childSpawned",
   "host/childStateChanged",
-  "host/roundLifecycle",
 ] as const satisfies readonly ReverseChannel[];
 
 /**
  * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
  * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
- * host/roundLifecycle 属数据面（终态回执语义：宿主必须确认收到，10s 未答 = 引擎故障）。
  */
 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/roundLifecycle": "data-plane",
   "host/askUser": "interaction",
-  "host/permission": "interaction",
 };
 
 // ============================================================
@@ -78,64 +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 通知并行的渲染加速面）。
  *
- * [v1.x 关联键扩展——D1-A 裁定，W1 落地不再临场选择]：
- *   - run 域轮（含 run 会话形态首轮）：runId 关联（v1 现状不变，runId 由 core 在
- *     run 帧分配）；
- *   - interact 发起的续聊轮：**recordId** 关联（续聊轮无独立 runId——InteractParams/
- *     InteractResult 均不含，recordId 经 handle.sessionRef 送达引擎）。
- * 两键互斥（undefined 孪生位防双填），消费侧经 isHostStreamDeltaParams 收窄。
- */
-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 关联形态。
+ * 关联键恒为 runId（runId 由 core 在 run 帧分配）；[H1] chat 续聊轮经 resume run
+ * 复用 runId 关联（原 recordId 关联键随 interact 面退役删除）。
  */
-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;
 }
 
 /**
@@ -162,113 +121,3 @@ export interface HostChildStateChangedParams {
   exitCode?: number;
   signal?: string;
 }
-
-// ============================================================
-// [v1.x] host/roundLifecycle：轮次生命周期载荷（chat 域 v1.x 唯一新通道）
-// ============================================================
-
-/**
- * 轮次关联键（D1-A 裁定的类型面）：run 域轮 = runId（v1 现状）；interact 续聊轮 =
- * recordId（经 handle.sessionRef）。undefined 孪生位保证两键互斥。
- */
-export interface RoundKeyedByRun {
-  runId: string;
-  recordId?: undefined;
-}
-
-export 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 对照——后者镜像进程内事件流基线，本帧无基线可镜像）。
- */
-export interface RoundSettledPhase {
-  phase: "settled";
-  usage?: AgentUsage;
-}
-
-export interface RoundIdlePhase {
-  phase: "idle";
-  usage?: AgentUsage;
-  /** 冷续锚点回填（session 滚动/compaction 后锚点可能变化，宿主按帧刷新）。 */
-  anchor?: ResumeAnchor;
-}
-
-export interface RoundFailedPhase {
-  phase: "failed";
-  /** 失败原因（结构对齐协议 error 帧——code/message/recovery 可操作闭环）。 */
-  error: ProtocolError;
-  anchor?: ResumeAnchor;
-}
-
-/** 相位联合（消费侧 switch(phase) 判别用）。 */
-export type RoundLifecyclePhase = RoundSettledPhase | RoundIdlePhase | RoundFailedPhase;
-
-/** host/roundLifecycle 载荷：关联键（run|record）× 相位（settled|idle|failed）。 */
-export type HostRoundLifecycleParams =
-  | (RoundKeyedByRun & RoundSettledPhase)
-  | (RoundKeyedByRun & RoundIdlePhase)
-  | (RoundKeyedByRun & RoundFailedPhase)
-  | (RoundKeyedByRecord & RoundSettledPhase)
-  | (RoundKeyedByRecord & RoundIdlePhase)
-  | (RoundKeyedByRecord & RoundFailedPhase);
-
-/**
- * roundLifecycle 载荷结构判定：关联键互斥 + phase 词表 + 各相位专属形状
- * （failed 必含 error.code/message）。引擎侧发帧前自检与 core 侧消费共用，
- * 防两侧各写一份判别（与 isHostStreamDeltaParams 同理）。
- */
-export function isHostRoundLifecycleParams(value: unknown): value is HostRoundLifecycleParams {
-  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";
-  if (hasRunId === hasRecordId) return false;
-  if (v.phase === "settled" || v.phase === "idle") return true;
-  if (v.phase !== "failed") return false;
-  const err = v.error;
-  return (
-    typeof err === "object" &&
-    err !== null &&
-    typeof (err as Record<string, unknown>).code === "string" &&
-    typeof (err as Record<string, unknown>).message === "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;
-  "host/roundLifecycle": HostRoundLifecycleParams;
-}
-
-/** 通道 → 异步/同步结果类型映射（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 };
-  "host/roundLifecycle": { 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";
 
@@ -103,6 +102,7 @@ export const notificationFrameSchema = {
                 "turn_end",
                 "message_end",
                 "compaction",
+                "activity",
                 "error",
               ],
             },
@@ -150,5 +150,36 @@ 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/architecture/subagent-chat-run-unification.md §3.3 D3 + §5 U1/U6 行。
+ *
+ * [H1 U6 已切换] 键切换单批完成后本 schema 面向唯一键 `resume`（RunResumeParams：
+ * recordId + 可选 ResumeAnchor），形状不变。帧级 schema（requestFrameSchema.params）
+ * 刻意不做深校验（见本文件头注释），本片段供消费方（引擎读端结构化报错 / 测试正负
+ * 样本）按需深校验。
+ */
+export const runSessionParamsSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineRunSessionParams",
+  type: "object",
+  additionalProperties: false,
+  required: ["recordId"],
+  properties: {
+    recordId: { type: "string" },
+    resume: {
+      type: "object",
+      additionalProperties: false,
+      required: ["sessionRef"],
+      properties: {
+        // ResumeAnchor.sessionRef = Record<string, string>（引擎定位键值对）
+        sessionRef: { type: "object", additionalProperties: { type: "string" } },
+        journalPath: { type: "string" },
+      },
+    },
+  },
+} as const;

package/src/ui-types.ts

@@ -28,11 +28,12 @@ export type UiMethod =
   | "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。 */
 export interface UiRequest {
@@ -61,8 +62,10 @@ export 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;
 }
@@ -78,6 +81,20 @@ export type UiResponse =
   | { cancelled: true }
   | { ack: true };
 
+/** UiResponse 载荷结构判定（四成员判别；形态对齐 reverse-channels 的
+ *  isHostStreamDeltaParams 先例）。消费方：引擎侧应答落位前守卫，防宿主畸形帧
+ *  静默流入 UI 队列（S7：askUser 应答跨界无守卫）。 */
+export function isUiResponse(value: unknown): value is UiResponse {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.value === "string" ||
+    typeof v.confirmed === "boolean" ||
+    v.cancelled === true ||
+    v.ack === true
+  );
+}
+
 /** UI 请求 handler 签名（单函数，按 req.method 内部路由）。
  *  实现方负责：channel 业务路由（ask_user → AskUserComponent）+ 默认转发（ctx.ui.*）。
  *  抛错由调用方（DialogGlobalQueue / session-runner）兜底为 {cancelled:true}。 */