@zhushanwen/subagent-engine-sdk 0.5.0 → 0.5.1

package/src/protocol/frames.ts

@@ -1,143 +0,0 @@
-// src/protocol/frames.ts
-//
-// 帧型四类（传输 = stdio NDJSON，每行一个 JSON 对象）。设计权威源：
-// 设计 §3.3 帧型 + impl-plan §2.1「帧型四类」。
-//
-//   ① 请求（core → 引擎）        { id, method, params }
-//   ② 应答（引擎 → core）        { id, result } | { id, error }
-//   ③ 通知（引擎 → core，无 id） { method: "event", params }
-//   ④ 反向请求（引擎 → core）    { id, method: "host/*", params }（必须应答）
-//
-// id 形态：正向请求 id = number（core 单调计数）；反向请求 id = string（引擎侧命名，
-// 如 "rev-1"）；应答 id = 请求或反向请求 id 原样回传（number | string）。
-// 实现面（行解析、请求关联、反向路由）归 W2 EngineClient；本文件只定帧型与判别。
-
-import type { AgentEvent } from "./contract-types.ts";
-
-/** 协议错误对象（error 帧载荷与反向请求错误应答共用形态）。 */
-export interface ProtocolError {
-  /** 错误码（error-codes.ts 词表 + 其余 engine_* 引擎自报透传）。 */
-  code: string;
-  /** 人类可读详情。 */
-  message: string;
-  /** 恢复指引：指向具体下一步（命令 / 配置路径 / 升级动作），非安慰性文案。 */
-  recovery: string;
-  /** 结构化附参（如 engine_protocol_mismatch 的双方版本）。 */
-  data?: Record<string, unknown>;
-}
-
-// ============================================================
-// ① 请求（core → 引擎）
-// ============================================================
-
-export interface RequestFrame {
-  id: number;
-  method: string;
-  params: unknown;
-}
-
-// ============================================================
-// ② 应答（引擎 → core）
-// ============================================================
-
-export interface SuccessResponseFrame {
-  id: number | string;
-  result: unknown;
-}
-
-export interface ErrorResponseFrame {
-  id: number | string;
-  error: ProtocolError;
-}
-
-export type ResponseFrame = SuccessResponseFrame | ErrorResponseFrame;
-
-// ============================================================
-// ③ 通知（引擎 → core，无 id）
-// ============================================================
-
-/** event 通知载荷：runId 关联在途 run；seq 单调递增（基线①结构等价断言对象）。 */
-export interface EventNotificationParams {
-  runId: string;
-  seq: number;
-  event: AgentEvent;
-}
-
-export interface NotificationFrame {
-  method: "event";
-  params: EventNotificationParams;
-}
-
-// ============================================================
-// ④ 反向请求（引擎 → core，必须应答）
-// ============================================================
-
-export interface ReverseRequestFrame {
-  id: string;
-  method: string;
-  params: unknown;
-}
-
-/** 反向请求的应答（core → 引擎，沿 ResponseFrame 通道回传；id = 反向请求 id 原样）。 */
-export type ReverseResponseResult =
-  /** 数据面类：处理确认。 */
-  | { ok: true }
-  /** 人机交互类（askUser）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
-  | { ack: true }
-  /** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
-  | { unsupported: true };
-
-// ============================================================
-// 判别守卫（W2 行解析器消费；结构判定，不抛错）
-// ============================================================
-
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === "object" && v !== null;
-}
-
-/** ① 请求：有数字 id + method + params，且无 result/error（与②应答区分）。 */
-export function isRequestFrame(frame: unknown): frame is RequestFrame {
-  return (
-    isRecord(frame) &&
-    typeof frame.id === "number" &&
-    typeof frame.method === "string" &&
-    "params" in frame &&
-    !("result" in frame) &&
-    !("error" in frame)
-  );
-}
-
-/** ② 应答：有 id（number|string）且 result/error 二选一。 */
-export function isResponseFrame(frame: unknown): frame is ResponseFrame {
-  if (!isRecord(frame) || !("id" in frame)) return false;
-  const idOk = typeof frame.id === "number" || typeof frame.id === "string";
-  if (!idOk) return false;
-  const hasResult = "result" in frame;
-  const hasError = "error" in frame;
-  return hasResult !== hasError;
-}
-
-/** ③ 通知：无 id，method === "event"，params 含 runId/seq/event。 */
-export function isNotificationFrame(frame: unknown): frame is NotificationFrame {
-  return (
-    isRecord(frame) &&
-    !("id" in frame) &&
-    frame.method === "event" &&
-    isRecord(frame.params) &&
-    typeof frame.params.runId === "string" &&
-    typeof frame.params.seq === "number" &&
-    isRecord(frame.params.event) &&
-    typeof frame.params.event.type === "string"
-  );
-}
-
-/** ④ 反向请求：有字符串 id + host/* method + params（与①的区别 = id 形态与 method 前缀）。 */
-export function isReverseRequestFrame(frame: unknown): frame is ReverseRequestFrame {
-  return (
-    isRecord(frame) &&
-    typeof frame.id === "string" &&
-    typeof frame.method === "string" &&
-    frame.method.startsWith("host/") &&
-    "params" in frame
-  );
-}

package/src/protocol/index.ts

@@ -1,12 +0,0 @@
-// src/protocol/index.ts
-//
-// 协议面 barrel（契约根公共出口）。W2 协议客户端（EngineClient/RemoteEngine）与
-// 各引擎 CLI 包（W5/W7）从本入口消费帧型/方法/通道/错误码/契约类型/JSON Schema。
-
-export * from "./engine-protocol.ts";
-export * from "./frames.ts";
-export * from "./methods.ts";
-export * from "./reverse-channels.ts";
-export * from "./error-codes.ts";
-export * from "./contract-types.ts";
-export * from "./schema.ts";

package/src/protocol/methods.ts

@@ -1,237 +0,0 @@
-// src/protocol/methods.ts
-//
-// 9 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
-// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」（[H1] 收敛为 9）。
-//
-// [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）；
-// listModels / validateModel 为诊断面（宿主侧同步成员读 manifest，不经本方法）；
-// dispose 幂等；ping 为健康检查（ADR-0047：静默 ≠ 卡死，不据此杀任务）。
-
-import type {
-  AgentCallOpts,
-  EngineCapabilities,
-  EngineHandleData,
-  AgentOutcome,
-  ModelCatalogEntry,
-  ProbeReport,
-  ResumeAnchor,
-  SessionView,
-} from "./contract-types.ts";
-
-/**
- * 正向方法名联合（恰好 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"
-  | "read"
-  | "listModels"
-  | "validateModel"
-  | "dispose"
-  | "ping";
-
-/** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
-export const PROTOCOL_METHODS = [
-  "initialize",
-  "probe",
-  "run",
-  "cancel",
-  "read",
-  "listModels",
-  "validateModel",
-  "dispose",
-  "ping",
-] as const satisfies readonly ProtocolMethod[];
-
-// ============================================================
-// run 专用载荷
-// ============================================================
-
-/**
- * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
- */
-export interface RunContextParams {
-  /** 任务工作目录（worktree 隔离时 = worktree 路径）。 */
-  cwd: string;
-  /** 请求模型 ref（未传 = 引擎缺省模型）。 */
-  model?: string;
-  /** 结构化输出 schema 的 env 注入形态（schemaEnv 降级通道）。 */
-  schemaEnv?: string;
-  /** 上下文模型 ref（与 run 模型分离的 ctx 模型）。 */
-  ctxModel?: string;
-  /** fallback 留痕（引擎回填 outcome.engineFallback 的种子）。 */
-  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;
-}
-
-// ============================================================
-// [H1] run 的 resume 会话形态参数（chat-run 统一终态；原 v1.x chat 键已退役）
-// ============================================================
-
-/**
- * [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 的 record 键形态）；
- *   - resume：冷续锚点（重开已 idle 的 session 续聊；缺省 = 新 session）。对照
- *     core SpawnResumeOpts——sessionFile 经 anchor.sessionRef 携带，model/
- *     thinkingLevel 防漂移覆盖走既有 task/ctx 字段，不双写。
- * [H1 U6 已切换] `chat` 键整体退役（读写端同批切换，无「写新读旧」窗口），本键为
- * 唯一会话形态参数。载荷 schema 权威 = runSessionParamsSchema（schema.ts）。
- */
-export interface RunResumeParams {
-  recordId: string;
-  resume?: ResumeAnchor;
-}
-
-// ============================================================
-// params / result 逐方法映射（方法名 → 载荷）
-// ============================================================
-
-/** initialize 参数（engineConfig = L3 显式配置 engines.<id>.config 透传，不放凭据）。 */
-export interface InitializeParams {
-  protocolVersion: number;
-  hostInfo: { name: string; version: string; dataRoot: string };
-  engineConfig: Record<string, string>;
-}
-
-/** initialize 应答（仅诊断面：capabilities/models 与 manifest 不一致 → warn，不参与判据）。 */
-export interface InitializeResult {
-  protocolVersion: number;
-  engineId: string;
-  engineVersion: string;
-  adapterVersion: string;
-  capabilities: EngineCapabilities;
-  /** 模型目录（诊断面；省略/null = 无枚举面语义）。 */
-  models?: ModelCatalogEntry[] | null;
-}
-
-export interface ProbeParams {
-  force?: boolean;
-}
-
-export interface RunParams {
-  runId: string;
-  task: AgentCallOpts;
-  ctx: RunContextParams;
-  /**
-   * [H1 U6 终态] resume 续聊参数（唯一会话形态键；原 v1.x `chat` 键已随键切换退役，
-   * 见 RunResumeParams）。缺省 = 一次性任务形态（向后兼容：旧引擎忽略未知字段，
-   * 帧级 schema params 不做深校验）。additive 可选：undefined 不上 wire。
-   */
-  resume?: RunResumeParams;
-}
-
-/** run 终态应答（期间事件经 event 通知；长运行方法，应答到达即终态）。 */
-export interface RunResult {
-  handle: EngineHandleData;
-  outcome: AgentOutcome;
-}
-
-export interface CancelParams {
-  runId: string;
-  reason: string;
-}
-
-/**
- * cancel 应答（受理确认）。终态本体由该 run 的 run 终态应答承载（abort 合成终态经
- * event/终态应答到达）；引擎须 CANCEL_SETTLE_GRACE_MS（3s）内收敛，超时 core 走杀链。
- */
-export interface CancelResult {
-  ok: true;
-}
-
-export interface ReadParams {
-  handle: EngineHandleData;
-  /** 数据根必填：存量池时代引擎自算池/journal 相对 dbPath 的定位需要它（设计钉死）。 */
-  dataDir: string;
-}
-
-export interface ListModelsParams {
-  /** 占位空参（帧形状一致性；未来诊断参数在此扩展）。 */
-  _placeholder?: never;
-}
-
-export interface ListModelsResult {
-  /** 数组 = 有枚举面；null = 无枚举面（buildCoreAlignedHint 语义，与 manifest 省略对齐）。 */
-  models: ModelCatalogEntry[] | null;
-}
-
-export interface ValidateModelParams {
-  modelRef?: string;
-}
-
-export interface ValidateModelResult {
-  canonicalRef: string;
-}
-
-export interface DisposeParams {
-  /** 占位空参（帧形状一致性；幂等语义）。 */
-  _placeholder?: never;
-}
-
-export interface DisposeResult {
-  ok: true;
-}
-
-export interface PingParams {
-  /** 占位空参（帧形状一致性）。 */
-  _placeholder?: never;
-}
-
-export interface PingResult {
-  pong: true;
-}
-
-/** 方法 → params 类型映射。 */
-export interface ProtocolParamsMap {
-  initialize: InitializeParams;
-  probe: ProbeParams;
-  run: RunParams;
-  cancel: CancelParams;
-  read: ReadParams;
-  listModels: ListModelsParams;
-  validateModel: ValidateModelParams;
-  dispose: DisposeParams;
-  ping: PingParams;
-}
-
-/** 方法 → result 类型映射。 */
-export interface ProtocolResultMap {
-  initialize: InitializeResult;
-  probe: ProbeReport;
-  run: RunResult;
-  cancel: CancelResult;
-  read: SessionView;
-  listModels: ListModelsResult;
-  validateModel: ValidateModelResult;
-  dispose: DisposeResult;
-  ping: PingResult;
-}

package/src/protocol/reverse-channels.ts

@@ -1,123 +0,0 @@
-// src/protocol/reverse-channels.ts
-//
-// 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}，结果异步到达
-// （R9-2：已 ack 的等待不计入任何 in-flight 超时；ADR-0047 静默 ≠ 卡死）；
-// 未实现的交互能力回 {unsupported:true}（引擎自行降级，不重试）。
-
-import type { ReverseRequestTimeoutClass } from "./engine-protocol.ts";
-import type { UiRequest, UiResponse } from "../ui-types.ts";
-
-/**
- * 反向通道名联合（恰好 6 个；REVERSE_CHANNELS 常量数组与之同源互证）。
- */
-export type ReverseChannel =
-  | "host/log"
-  | "host/askUser"
-  | "host/streamDelta"
-  | "host/handleReady"
-  | "host/childSpawned"
-  | "host/childStateChanged";
-
-/**
- * 通道名全集（运行时顺序化枚举；与 ReverseChannel 的同源关系由测试断言）。
- */
-export const REVERSE_CHANNELS = [
-  "host/log",
-  "host/askUser",
-  "host/streamDelta",
-  "host/handleReady",
-  "host/childSpawned",
-  "host/childStateChanged",
-] as const satisfies readonly ReverseChannel[];
-
-/**
- * 超时二分归属（10s 数据面 / 不设统一超时的人机交互面）。实现归 W2 EngineClient；
- * 引擎侧自灭计时（W12）复用同表——已 ack 的 askUser 等待不计入 in-flight（R9-2）。
- */
-export const REVERSE_CHANNEL_TIMEOUT_CLASS: Record<ReverseChannel, ReverseRequestTimeoutClass> = {
-  "host/log": "data-plane",
-  "host/streamDelta": "data-plane",
-  "host/handleReady": "data-plane",
-  "host/childSpawned": "data-plane",
-  "host/childStateChanged": "data-plane",
-  "host/askUser": "interaction",
-};
-
-// ============================================================
-// 通道载荷（params）
-// ============================================================
-
-/** host/log：引擎日志落宿主日志（对齐 core HostServices.log 调用面）。 */
-export interface HostLogParams {
-  level: "debug" | "warn" | "error";
-  component: string;
-  message: string;
-  data?: unknown;
-}
-
-/** host/askUser：UI 请求经反向通道送达宿主（core 壳侧 uiRequestHandler 应答）。 */
-export interface HostAskUserParams {
-  runId: string;
-  /** Pi extension_ui_request 平铺形态（类型 SSOT = SDK ui-types.ts，core 反向 re-export）。 */
-  request: UiRequest;
-}
-
-/** host/askUser 的最终结果（ack 两阶段第二阶段，异步应答帧②的 result）。 */
-export type HostAskUserResult = UiResponse;
-
-/**
- * host/streamDelta：UI 实时通道（双通道之一；与 event 通知并行的渲染加速面）。
- *
- * 关联键恒为 runId（runId 由 core 在 run 帧分配）；[H1] chat 续聊轮经 resume run
- * 复用 runId 关联（原 recordId 关联键随 interact 面退役删除）。
- */
-export interface HostStreamDeltaParams {
-  runId: 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>;
-}
-
-/**
- * host/childSpawned：引擎内一次性子进程 pid 上报。
- * 用途 = isResumable 镜像谓词 + 诊断留痕；**不供杀链/收割**（v6 已删按 pid 补杀，
- * 收割只靠进程组）；常驻进程不报（归 dispose）。
- */
-export interface HostChildSpawnedParams {
-  pid: number;
-  recordId: string;
-}
-
-/**
- * host/childStateChanged：childSpawned 的状态面（core 侧镜像数据源，
- * hasLiveProcessHandle/isResumable 同步读镜像，不跨进程查询）。
- * **killed 必含**（判据 `child !== undefined && !child.killed`）——类型层 required。
- */
-export interface HostChildStateChangedParams {
-  pid: number;
-  recordId: string;
-  state: "running" | "exited";
-  /** 必含：true = 已被杀/已终止（镜像置死判据）。 */
-  killed: boolean;
-  exitCode?: number;
-  signal?: string;
-}