@zhushanwen/subagent-engine-sdk 0.2.0

package/src/protocol/error-codes.ts

@@ -0,0 +1,179 @@
+// src/protocol/error-codes.ts
+//
+// 协议错误码表（impl-plan §2.1「错误码表」逐项）+ 结构化错误载体 + kill-chain 消费的
+// 具名错误文案构造器（自 core execution/engine/common/errors.ts 迁入 SDK 的引擎面
+// 子集；core 侧错误 SSOT 留守，双侧错误码词表由测试互证）。
+//
+// 错误码语义与 core 侧处置（设计 §3.3 错误码表）：
+//   engine_not_found            配置/清单里的 id 无对应包 → 列出已发现引擎 + 配置路径
+//   engine_protocol_mismatch    握手版本越界 → 该引擎不可用；升级 core 或引擎包
+//   engine_capability_unsupported  core 的 gate 同步拦（manifest 少声明被 gate 四类之一）
+//                               ——core 生成，不属「引擎 error 帧透传」
+//   engine_capability_mismatch  manifest 声明 ≠ 握手能力位（被 gate 位多声明 → run 失败
+//                               + 清理前置副作用；非 gate 位不一致 → 仅 warn）
+//   engine_model_unknown        validateModel 未命中且 dynamic=false → 同步拒（record 不创建）
+//   engine_model_mismatch       dynamic=true 运行期引擎拒绝 → run 失败 + record 标 failed
+//   engine_handshake_timeout    initialize 超时（HANDSHAKE_TIMEOUT_MS=10s）→ 引擎不可用
+//   engine_crashed              进程意外退出 → 在途 run 失败（附 stderr 尾
+//                               STDERR_TAIL_CHARS=400 字符）；重建最多 3 次退避 1s/2s/4s
+//   engine_probe_failed         probe 失败 → 既有 fallback 三守卫不变
+//   其余 engine_*               引擎在 error 帧原样给出 → core 透传，文案契约不变
+
+/** 协议核心错误码（引擎 error 帧 + core 同步拦截共用的固定词表）。 */
+export const ENGINE_PROTOCOL_ERROR_CODES = [
+  "engine_not_found",
+  "engine_protocol_mismatch",
+  "engine_capability_unsupported",
+  "engine_capability_mismatch",
+  "engine_model_unknown",
+  "engine_model_mismatch",
+  "engine_handshake_timeout",
+  "engine_crashed",
+  "engine_probe_failed",
+] as const;
+
+export type EngineProtocolErrorCode = (typeof ENGINE_PROTOCOL_ERROR_CODES)[number];
+
+/** unknown → 协议错误码收窄（外部输入携带错误码时的运行时 guard；其余 engine_* 走透传）。 */
+export function isEngineProtocolErrorCode(value: unknown): value is EngineProtocolErrorCode {
+  return (
+    typeof value === "string" &&
+    (ENGINE_PROTOCOL_ERROR_CODES as readonly string[]).includes(value)
+  );
+}
+
+/** 其余引擎自报错误码的前缀契约（透传面；core 不解释文案）。 */
+export const ENGINE_ERROR_CODE_PREFIX = "engine_";
+
+export function isEngineErrorPassthroughCode(value: string): boolean {
+  return (
+    !isEngineProtocolErrorCode(value) && value.startsWith(ENGINE_ERROR_CODE_PREFIX)
+  );
+}
+
+// ============================================================
+// 结构化错误载体（协议 ProtocolError 的 TS 异常形态）
+// ============================================================
+
+import type { ProtocolError } from "./frames.ts";
+import { SUPPORTED_PROTOCOL_RANGE } from "./engine-protocol.ts";
+import type { EngineCapabilities } from "./contract-types.ts";
+
+/**
+ * 结构化引擎错误（message 恒为 `<code>: <detail>` 前缀格式——AgentOutcome.error 与
+ * 协议 error 帧共用的错误码前缀约定）；recovery 指向恢复动作。
+ * toStructured() 产出即协议 ProtocolError 形态（error 帧载荷直用）。
+ */
+export class EngineSdkError extends Error {
+  readonly code: string;
+  readonly recovery: string;
+  readonly data?: Record<string, unknown>;
+
+  constructor(code: string, detail: string, recovery: string, data?: Record<string, unknown>) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineSdkError";
+    this.code = code;
+    this.recovery = recovery;
+    this.data = data;
+  }
+
+  /** 协议 error 帧载荷投影。 */
+  toStructured(): ProtocolError {
+    return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
+  }
+}
+
+// ============================================================
+// engine_protocol_mismatch 具名构造器（版本协商失败：含双方版本 + 升级指引）
+// ============================================================
+
+export function engineProtocolMismatchError(engineVersion: number): EngineSdkError {
+  return new EngineSdkError(
+    "engine_protocol_mismatch",
+    `engine speaks protocol v${engineVersion}, host supports [${SUPPORTED_PROTOCOL_RANGE.min}, ${SUPPORTED_PROTOCOL_RANGE.max})`,
+    "Upgrade the engine package (or the host) so both sides speak a protocol version in the supported range, then re-run the task. The engine is marked unavailable until then.",
+    {
+      engineProtocolVersion: engineVersion,
+      supportedMin: SUPPORTED_PROTOCOL_RANGE.min,
+      supportedMaxExclusive: SUPPORTED_PROTOCOL_RANGE.max,
+    },
+  );
+}
+
+// ============================================================
+// [v1.x] conversation gate 位负向：chat 请求（run 会话形态）同步拒
+// ============================================================
+
+/**
+ * [v1.x] chat 会话形态的 gate 拒绝具名错误（chat-domain 设计 §3.2 D1-A +
+ * 验收 A6：manifest 无 conversation gate 位的引擎收到 chat 请求 → 同步拒）。
+ * 文案契约对齐 core capability-gate.ts conversation 分支（错误码
+ * engine_capability_unsupported + 「去掉参数 / 修 manifest / 升级引擎包」恢复指引）
+ * ——W3 chat 路由切协议客户端时以本构造器替换 core 内联文案，保持两侧一致。
+ */
+export function engineConversationUnsupportedError(engineId: string): EngineSdkError {
+  return new EngineSdkError(
+    "engine_capability_unsupported",
+    `engine '${engineId}' 不支持 conversation（capabilities.conversation = 'unsupported'，` +
+      `manifest 无 conversation gate 位——无同进程 idle 复用，message/close 交互控制面不可用）`,
+    `去掉 conversation 参数（一次性任务默认形态），或修 manifest capabilities / 升级引擎包（若引擎实际支持该能力）`,
+    { engineId, capability: "conversation", declared: "unsupported" },
+  );
+}
+
+/**
+ * [v1.x] chat 会话形态（run.params.chat / task.conversation=true）派发前的同步 gate：
+ * manifest conversation 位 unsupported 即抛 engineConversationUnsupportedError——
+ * 进程/record 创建前同步拒（A6：run 域不受影响，仅 chat 面被拦）。
+ * 判据单源：core 侧 capability-gate.assertTaskShapeSupported 的 conversation 分支
+ * 覆盖同一能力位，协议客户端路径（W3 接线）消费本函数，防两处判据漂移。
+ */
+export function assertChatConversationSupported(
+  engineId: string,
+  capabilities: Pick<EngineCapabilities, "conversation">,
+): void {
+  if (capabilities.conversation === "unsupported") {
+    throw engineConversationUnsupportedError(engineId);
+  }
+}
+
+// ============================================================
+// kill-chain 消费的引擎面错误文案（自 core errors.ts 迁入，逐字等价）
+// ============================================================
+
+/** 错误回显长度上限（截断长输出，避免错误消息爆炸）。 */
+const DETAIL_ECHO_MAX_CHARS = 200;
+
+/** stdout 尾部回显上限（engine_timeout / engine_run_failed 的错误规格载体系数）。 */
+export const STDOUT_TAIL_ECHO_CHARS = 2000;
+
+function truncate(text: string, max: number): string {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+
+/** engine_timeout 的恢复指引（kill-chain 超时杀链收尾文案）。 */
+export const ENGINE_TIMEOUT_RECOVERY =
+  "The engine was killed by the host timeout chain. Inspect the captured stdout tail, then re-run with a larger " +
+  "timeout, a narrower task, or `engine: pi`.";
+
+/**
+ * engine_timeout 的 outcome.error 文案：含 stdout 尾部 2000 字 + 恢复指引
+ * （kill-chain synthesizeTimeoutOutcome 消费；与 core errors.ts engineTimeoutDetail 逐字等价）。
+ */
+export function engineTimeoutDetail(stdoutTail: string): string {
+  return (
+    `host timeout chain exhausted (SIGTERM -> grace -> SIGKILL). ` +
+    `Stdout tail (last ${STDOUT_TAIL_ECHO_CHARS} chars): ${truncate(stdoutTail, STDOUT_TAIL_ECHO_CHARS)}. ` +
+    `Recovery: ${ENGINE_TIMEOUT_RECOVERY}`
+  );
+}
+
+/** schema_emulation_failed 的终报文案（宿主编排层「重试一次仍失败」后消费）。 */
+export function schemaEmulationFailedDetail(error: string, tail: string): string {
+  return (
+    `structured output emulation failed after tolerant extraction and one host-side retry: ${error}. ` +
+    `Raw output tail: ${truncate(tail, DETAIL_ECHO_MAX_CHARS)}. ` +
+    `Recovery: retry with a strengthened prompt or relax the schema; if it still fails switch to a ` +
+    `schema-native engine (engine: pi).`
+  );
+}

package/src/protocol/frames.ts

@@ -0,0 +1,145 @@
+// 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/permission）两阶段第一阶段：已受理，结果异步到达（R9-2）。 */
+  | { ack: true }
+  /** 未实现的交互能力（设计：未实现回 unsupported，引擎自行降级）。 */
+  | { unsupported: true };
+
+export type AnyFrame = RequestFrame | ResponseFrame | NotificationFrame | ReverseRequestFrame;
+
+// ============================================================
+// 判别守卫（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

@@ -0,0 +1,12 @@
+// 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

@@ -0,0 +1,229 @@
+// src/protocol/methods.ts
+//
+// 10 正向方法（core → 引擎）params/result 逐方法写死（v1）。设计权威源：
+// 设计 §3.3 方法集表 + impl-plan §2.1「10 正向方法」。
+//
+// [v1.x 增量（chat-domain 设计 §3.2 D1-A）]：方法集不变（chat 轮次 = run 会话形态
+// + 既有 interact，不新造 chatRound 方法——D1-B 被否）；增量以可选参数形态落在
+// run.params.chat（会话形态参数 + 冷续 resume 锚点），major 不 bump。
+//
+// 应答面补充约定（设计 §3.3）：initialize 应答仅诊断（与 manifest 不一致 → warn 留痕，
+// 不参与同步成员判据；唯一阻断面 = 被 gate 能力位多声明 → engine_capability_mismatch）；
+// listModels / validateModel 为诊断面（宿主侧同步成员读 manifest，不经本方法）；
+// dispose 幂等；ping 为健康检查（ADR-0047：静默 ≠ 卡死，不据此杀任务）。
+
+import type {
+  AgentCallOpts,
+  EngineCapabilities,
+  EngineHandleData,
+  AgentOutcome,
+  InteractAction,
+  InteractResult,
+  ModelCatalogEntry,
+  ProbeReport,
+  ResumeAnchor,
+  SessionView,
+} from "./contract-types.ts";
+
+/** 正向方法名联合（恰好 10 个；PROTOCOL_METHODS 常量数组与之同源互证）。 */
+export type ProtocolMethod =
+  | "initialize"
+  | "probe"
+  | "run"
+  | "cancel"
+  | "interact"
+  | "read"
+  | "listModels"
+  | "validateModel"
+  | "dispose"
+  | "ping";
+
+/** 方法名全集（运行时顺序化枚举；与 ProtocolMethod 的同源关系由测试断言）。 */
+export const PROTOCOL_METHODS = [
+  "initialize",
+  "probe",
+  "run",
+  "cancel",
+  "interact",
+  "read",
+  "listModels",
+  "validateModel",
+  "dispose",
+  "ping",
+] as const satisfies readonly ProtocolMethod[];
+
+// ============================================================
+// run 专用载荷
+// ============================================================
+
+/**
+ * run 上下文（RunContext 字段映射的协议承载，设计 §3.3 RunContext 映射表）。
+ */
+export interface RunContextParams {
+  /** 隔离池归属（journal 归属错 = 缺失后果）。 */
+  poolKey: string;
+  /** 任务工作目录（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";
+}
+
+// ============================================================
+// [v1.x] run 的 chat 会话形态参数（chat-domain 设计 §3.2 D1-A）
+// ============================================================
+
+/**
+ * [v1.x] chat 会话形态参数——HostChatRoundTicket 五字段过协议映射中「record」的
+ * 承载位（docs/design/chat-domain-v1x-liveness-governance.md §3.2 D1 五字段映射）：
+ *   - recordId：core 预建 record 的关联键（引擎据此回填 handle.sessionRef、上报
+ *     host/childSpawned|childStateChanged 与 host/roundLifecycle 的 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）。
+ */
+export interface RunChatParams {
+  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;
+  /**
+   * [v1.x 可选增量] chat 会话形态参数（task.conversation=true 的 chat 路由承载）。
+   * 缺省 = 一次性任务形态，v1 引擎/宿主语义不变（向后兼容：旧引擎忽略未知字段，
+   * 帧级 schema params 不做深校验）。续聊/关断不经此参数——走既有 interact。
+   */
+  chat?: RunChatParams;
+}
+
+/** 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 InteractParams {
+  handle: EngineHandleData;
+  action: InteractAction;
+}
+
+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;
+  interact: InteractParams;
+  read: ReadParams;
+  listModels: ListModelsParams;
+  validateModel: ValidateModelParams;
+  dispose: DisposeParams;
+  ping: PingParams;
+}
+
+/** 方法 → result 类型映射。 */
+export interface ProtocolResultMap {
+  initialize: InitializeResult;
+  probe: ProbeReport;
+  run: RunResult;
+  cancel: CancelResult;
+  interact: InteractResult;
+  read: SessionView;
+  listModels: ListModelsResult;
+  validateModel: ValidateModelResult;
+  dispose: DisposeResult;
+  ping: PingResult;
+}