@zhushanwen/subagent-engine-sdk 0.7.0 → 0.8.0

package/dist/protocol/index.js

@@ -6,17 +6,19 @@ import {
   REVERSE_CHANNELS,
   REVERSE_CHANNEL_TIMEOUT_CLASS,
   errorResponseFrameSchema,
-  isNotificationFrame,
-  isRequestFrame,
-  isResponseFrame,
-  isReverseRequestFrame,
   notificationFrameSchema,
   protocolErrorSchema,
   requestFrameSchema,
   reverseRequestFrameSchema,
   runSessionParamsSchema,
   successResponseFrameSchema
-} from "../chunk-W23PAAGX.js";
+} from "../chunk-DIIYVO4O.js";
+import {
+  isNotificationFrame,
+  isRequestFrame,
+  isResponseFrame,
+  isReverseRequestFrame
+} from "../chunk-D36ZIQQK.js";
 import {
   CANCEL_SETTLE_GRACE_MS,
   CRASH_REBUILD_BACKOFF_MS,

package/dist/server/index.cjs

@@ -0,0 +1,217 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/server/index.ts
+var server_exports = {};
+__export(server_exports, {
+  REVERSE_TIMEOUT_DEFAULT_MS: () => REVERSE_TIMEOUT_DEFAULT_MS,
+  assembleFullTask: () => assembleFullTask,
+  classifyInboundFrame: () => classifyInboundFrame,
+  handleInboundFrame: () => handleInboundFrame,
+  initializeEngine: () => initializeEngine,
+  notInitializedError: () => notInitializedError,
+  reverseRequestRejection: () => reverseRequestRejection,
+  sendReverseRequest: () => sendReverseRequest,
+  toProtocolError: () => toProtocolError,
+  unknownMethodError: () => unknownMethodError,
+  writeRunEvent: () => writeRunEvent
+});
+module.exports = __toCommonJS(server_exports);
+
+// src/error-message.ts
+function toErrorMessage(e) {
+  if (e instanceof Error) return e.message;
+  if (typeof e === "object" && e !== null) {
+    try {
+      return JSON.stringify(e);
+    } catch {
+      return String(e);
+    }
+  }
+  return String(e);
+}
+
+// src/protocol/engine-protocol.ts
+var ENGINE_PROTOCOL_VERSION = 1;
+
+// src/protocol/error-codes.ts
+var EngineSdkError = class extends Error {
+  code;
+  recovery;
+  data;
+  constructor(code, detail, recovery, data) {
+    super(`${code}: ${detail}`);
+    this.name = "EngineSdkError";
+    this.code = code;
+    this.recovery = recovery;
+    this.data = data;
+  }
+  /** 协议 error 帧载荷投影。 */
+  toStructured() {
+    return { code: this.code, message: this.message, recovery: this.recovery, data: this.data };
+  }
+};
+
+// src/protocol/frames.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function isResponseFrame(frame) {
+  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;
+}
+function isReverseRequestFrame(frame) {
+  return isRecord(frame) && typeof frame.id === "string" && typeof frame.method === "string" && frame.method.startsWith("host/") && "params" in frame;
+}
+
+// src/server/index.ts
+var REVERSE_TIMEOUT_DEFAULT_MS = 6e4;
+function toProtocolError(err, recovery) {
+  if (err instanceof EngineSdkError) return err.toStructured();
+  return { code: "engine_run_failed", message: toErrorMessage(err), recovery };
+}
+function classifyInboundFrame(frame) {
+  if (isResponseFrame(frame)) return { kind: "reverse-response", id: frame.id };
+  if (isReverseRequestFrame(frame)) return { kind: "rejected-reverse-request", method: String(frame.method) };
+  if (typeof frame === "object" && frame !== null && "id" in frame && "method" in frame && typeof frame.method === "string") {
+    const { id, method, params } = frame;
+    if (typeof id === "number") return { kind: "request", id, method, params };
+  }
+  return { kind: "ignore" };
+}
+function reverseRequestRejection(method) {
+  return {
+    id: 0,
+    error: {
+      code: "engine_protocol_bad_frame",
+      message: `unexpected reverse request frame from host: ${method}`,
+      recovery: "The engine protocol v1 only carries host/* requests engine\u2192host."
+    }
+  };
+}
+function unknownMethodError(id, method) {
+  return new EngineSdkError(
+    "engine_protocol_unknown_method",
+    `unknown protocol method: ${method} (request id ${id})`,
+    "The engine speaks protocol v1; check the installed engine package version vs the host."
+  );
+}
+function handleInboundFrame(frame, ctx) {
+  const action = classifyInboundFrame(frame);
+  switch (action.kind) {
+    case "reverse-response":
+      ctx.settleReverse(action.id, frame);
+      return action;
+    case "rejected-reverse-request":
+      ctx.write(reverseRequestRejection(action.method));
+      return action;
+    case "request": {
+      let result;
+      try {
+        result = ctx.dispatch(action.id, action.method, action.params);
+      } catch (err) {
+        ctx.write({ id: action.id, error: ctx.toError(err) });
+        return action;
+      }
+      void Promise.resolve(result).then(
+        (value) => ctx.write({ id: action.id, result: value }),
+        (err) => ctx.write({ id: action.id, error: ctx.toError(err) })
+      );
+      return action;
+    }
+    case "ignore":
+      return action;
+  }
+}
+function sendReverseRequest(ctx, method, params) {
+  const id = ctx.nextId();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      ctx.pending.delete(id);
+      ctx.clock?.settled(id);
+      reject(new Error(`reverse request ${method} (${id}) timed out after ${ctx.timeoutMs}ms`));
+    }, ctx.timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+    ctx.pending.set(id, { resolve, reject, timer, ...ctx.pendingExtras?.(method) ?? {} });
+    ctx.clock?.started(id);
+    try {
+      ctx.write({ id, method, params });
+    } catch (err) {
+      ctx.pending.delete(id);
+      clearTimeout(timer);
+      ctx.clock?.settled(id);
+      reject(new Error(`reverse request ${method} (${id}) could not be written: ${toErrorMessage(err)}`));
+    }
+  });
+}
+function writeRunEvent(write, activeRuns, runId, event) {
+  const active = activeRuns.get(runId);
+  const seq = active !== void 0 ? ++active.seq : 0;
+  write({ method: "event", params: { runId, seq, event } });
+}
+function initializeEngine(params, ctx) {
+  if (params?.protocolVersion !== ENGINE_PROTOCOL_VERSION) {
+    throw new EngineSdkError(
+      "engine_protocol_mismatch",
+      `host protocol version ${String(params?.protocolVersion)} is not compatible with engine protocol v${ENGINE_PROTOCOL_VERSION}`,
+      `Upgrade the engine package or the host so both speak protocol v${ENGINE_PROTOCOL_VERSION}.`
+    );
+  }
+  const models = ctx.listModels();
+  return {
+    protocolVersion: ENGINE_PROTOCOL_VERSION,
+    engineId: ctx.engineId,
+    engineVersion: ctx.adapterVersion,
+    adapterVersion: ctx.adapterVersion,
+    capabilities: ctx.capabilities,
+    ...models !== null ? { models: models.map((m) => ({ id: m.id })) } : {}
+  };
+}
+function notInitializedError() {
+  return new EngineSdkError(
+    "engine_protocol_not_initialized",
+    "run before initialize is a protocol violation",
+    "The host must complete the initialize handshake before dispatching runs."
+  );
+}
+function assembleFullTask(task, ctx) {
+  return {
+    ...task,
+    ...ctx.model !== void 0 ? { model: ctx.model } : {},
+    ...ctx.cwd !== void 0 ? { cwd: ctx.cwd } : {}
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  REVERSE_TIMEOUT_DEFAULT_MS,
+  assembleFullTask,
+  classifyInboundFrame,
+  handleInboundFrame,
+  initializeEngine,
+  notInitializedError,
+  reverseRequestRejection,
+  sendReverseRequest,
+  toProtocolError,
+  unknownMethodError,
+  writeRunEvent
+});

package/dist/server/index.d.cts

@@ -0,0 +1,146 @@
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-DqOD58r-.cjs';
+import { I as InitializeResult, R as RunContextParams, a as InitializeParams, E as EngineSdkError } from '../error-codes-C3oVToMr.cjs';
+import { ReverseRequestClock } from '../spawn.cjs';
+import 'node:child_process';
+import '../env.cjs';
+
+/** 出站帧写入面（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
+type FrameWriter = (frame: unknown) => void;
+/**
+ * 反向请求应答等待缺省上限（ms）——数据面分类 core 侧 10s，两阶段等待放宽一档兜底。
+ *
+ * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议面常数，分叉会让同一宿主
+ * 在不同引擎下得到不同的超时语义。
+ */
+declare const REVERSE_TIMEOUT_DEFAULT_MS = 60000;
+/** 单个 run 的在途登记（cancel 帧路由 + 事件 seq 计数）。 */
+interface ActiveRun {
+    controller: AbortController;
+    seq: number;
+}
+/**
+ * 反向请求在途登记（引擎 → 宿主请求的应答等待项）。
+ *
+ * `method` 是 pi 引擎的扩展位（settle 时按通道守卫应答形态，如 askUser 的 UI 应答面
+ * 检查）；zcode 无该通道守卫，可缺省。
+ */
+interface ReversePending {
+    resolve: (result: unknown) => void;
+    reject: (err: Error) => void;
+    timer: NodeJS.Timeout;
+    method?: string;
+}
+/** 协议错误帧载荷（`{code,message,recovery}` 三件套——宿主据此渲染恢复指引）。 */
+interface ProtocolErrorPayload {
+    code: string;
+    message: string;
+    recovery: string;
+}
+/**
+ * 异常 → 协议错误帧载荷。
+ *
+ * `EngineSdkError` 自带结构化（`toStructured()`，含引擎侧恢复指引）；其余异常落
+ * `engine_run_failed` + 调用方给的恢复指引文案（各引擎的日志位置不同，故 recovery
+ * 由调用方注入而不是在这里写死）。
+ */
+declare function toProtocolError(err: unknown, recovery: string): ProtocolErrorPayload;
+/** 入站帧分类结果（纯判定、零副作用，便于单测逐分支断言）。 */
+type InboundFrameAction = {
+    kind: "reverse-response";
+    id: number | string;
+} | {
+    kind: "rejected-reverse-request";
+    method: string;
+} | {
+    kind: "request";
+    id: number;
+    method: string;
+    params: unknown;
+} | {
+    kind: "ignore";
+};
+/**
+ * 入站帧 → 动作。
+ *
+ * 判序即协议纪律：①反向应答（对端在等的 host/* 应答）②反向请求（引擎不发 host/*，
+ * 属非法入站 → 坏帧应答）③正向请求（`id` 为 number 且 `method` 为 string）④其余静默
+ * 忽略（stdout 是独占协议通道，不回显坏帧防对端解析器混乱）。
+ */
+declare function classifyInboundFrame(frame: unknown): InboundFrameAction;
+/** 引擎侧收到反向请求帧时的坏帧应答（`id: 0` = 非请求应答，对端只记坏帧）。 */
+declare function reverseRequestRejection(method: string): {
+    id: number;
+    error: ProtocolErrorPayload;
+};
+/** 未知协议方法错误（两引擎逐字一致；表查找失败时抛，经 `toError` 转错误帧）。 */
+declare function unknownMethodError(id: number, method: string): EngineSdkError;
+/** 帧循环所需的最小上下文（引擎侧实现注入；每引擎构造一次，不在每帧重建）。 */
+interface FrameLoopContext {
+    /** 出站帧写入面。 */
+    write: FrameWriter;
+    /** 反向应答帧落地（各引擎的两阶段 ack 语义在此，**刻意不统一**）。 */
+    settleReverse(id: number | string, frame: {
+        result?: unknown;
+        error?: unknown;
+    }): void;
+    /** 正向请求分发（9 方法表；抛出的错误经 `toError` 转错误帧）。 */
+    dispatch(id: number, method: string, params: unknown): unknown;
+    /** 错误 → 错误帧载荷（各引擎的恢复指引文案不同，故由引擎注入）。 */
+    toError(err: unknown): ProtocolErrorPayload;
+}
+/** 跑一帧（分类 → 落地）。返回值仅用于测试可读性，生产调用方忽略。 */
+declare function handleInboundFrame(frame: unknown, ctx: FrameLoopContext): InboundFrameAction;
+/**
+ * 反向请求发送（引擎 → 宿主请求的发出与等待登记）。
+ *
+ * 语义（两条都是踩过坑的）：
+ *   - 计时兜底在**发出侧**武装——应答侧不重复武装，两阶段 ack 只延长等待而不重置计时。
+ *   - `write` 同步抛错（stdout 关闭等）就地收尾：清 pending + 停 timer + 记 clock 后转
+ *     reject；不让异常同步逃出 Promise executor（逃出 = pending 条目与 timer 残留，
+ *     且 reject 无人消费时仍是 unhandled rejection 面）。
+ */
+interface ReverseRequestSendContext {
+    write: FrameWriter;
+    pending: Map<string, ReversePending>;
+    timeoutMs: number;
+    clock?: ReverseRequestClock;
+    /** 请求 id 分配（各引擎可带自己的前缀与计数器）。 */
+    nextId(): string;
+    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答面检查用；zcode 不记）。 */
+    pendingExtras?(method: string): Partial<ReversePending>;
+}
+declare function sendReverseRequest(ctx: ReverseRequestSendContext, method: string, params: unknown): Promise<unknown>;
+/** 运行事件通知帧（`seq` 单调：无在途登记时取 0，仅作占位而非序号源）。 */
+declare function writeRunEvent(write: FrameWriter, activeRuns: Map<string, ActiveRun>, runId: string, event: AgentEvent): void;
+/** 初始化握手所需的最小上下文（版本协商共用；引擎实例面与适配器版本由引擎注入）。 */
+interface InitializeHandshakeContext {
+    /** 引擎实例 id（`EnginePort.id`）。 */
+    engineId: string;
+    /** 引擎包自己的适配器版本常量（各包独立版本号）。 */
+    adapterVersion: string;
+    /** 能力位（`EnginePort.capabilities()` 的返回值）。 */
+    capabilities: InitializeResult["capabilities"];
+    /** 可用模型列表；`null` = 本引擎不提供（应答里不带 models 字段）。 */
+    listModels(): Array<{
+        id: string;
+    }> | null;
+}
+/**
+ * 初始化握手：协议版本协商（越界 → `engine_protocol_mismatch`）+ 能力与模型应答。
+ *
+ * 版本比对用严格相等：v1 系列内仍以 `ENGINE_PROTOCOL_VERSION` 为准（宿主与引擎同批发布），
+ * 放宽比对会让「装了旧引擎」静默通过，后续方法缺失才炸在更远处。
+ */
+declare function initializeEngine(params: InitializeParams, ctx: InitializeHandshakeContext): InitializeResult;
+/** run 前门未初始化拒绝（两引擎逐字一致的协议错误）。 */
+declare function notInitializedError(): EngineSdkError;
+/**
+ * 协议 `task` 子集 + `ctx` 还原 = 本地全量 `AgentCallOpts`（与宿主侧
+ * `RemoteEngine.toSdkTaskSubset` 镜像）。
+ *
+ * 还原纪律：`model` / `cwd` **有值才写**（wire additive 语义）——写 `undefined` 会覆盖
+ * 引擎侧缺省值，worktree 隔离与模型选择都会静默走错。
+ */
+declare function assembleFullTask(task: AgentCallOpts, ctx: RunContextParams): AgentCallOpts;
+
+export { type ActiveRun, type FrameLoopContext, type FrameWriter, type InboundFrameAction, type InitializeHandshakeContext, type ProtocolErrorPayload, REVERSE_TIMEOUT_DEFAULT_MS, type ReversePending, type ReverseRequestSendContext, assembleFullTask, classifyInboundFrame, handleInboundFrame, initializeEngine, notInitializedError, reverseRequestRejection, sendReverseRequest, toProtocolError, unknownMethodError, writeRunEvent };

package/dist/server/index.d.ts

@@ -0,0 +1,146 @@
+import { b as AgentCallOpts, A as AgentEvent } from '../contract-types-DqOD58r-.js';
+import { I as InitializeResult, R as RunContextParams, a as InitializeParams, E as EngineSdkError } from '../error-codes-CiDwaODz.js';
+import { ReverseRequestClock } from '../spawn.js';
+import 'node:child_process';
+import '../env.js';
+
+/** 出站帧写入面（各引擎 main.ts 注入 process.stdout；测试注入内存缓冲）。 */
+type FrameWriter = (frame: unknown) => void;
+/**
+ * 反向请求应答等待缺省上限（ms）——数据面分类 core 侧 10s，两阶段等待放宽一档兜底。
+ *
+ * 两个引擎此值必须相同：它是「宿主应答迟到多久算超时」的协议面常数，分叉会让同一宿主
+ * 在不同引擎下得到不同的超时语义。
+ */
+declare const REVERSE_TIMEOUT_DEFAULT_MS = 60000;
+/** 单个 run 的在途登记（cancel 帧路由 + 事件 seq 计数）。 */
+interface ActiveRun {
+    controller: AbortController;
+    seq: number;
+}
+/**
+ * 反向请求在途登记（引擎 → 宿主请求的应答等待项）。
+ *
+ * `method` 是 pi 引擎的扩展位（settle 时按通道守卫应答形态，如 askUser 的 UI 应答面
+ * 检查）；zcode 无该通道守卫，可缺省。
+ */
+interface ReversePending {
+    resolve: (result: unknown) => void;
+    reject: (err: Error) => void;
+    timer: NodeJS.Timeout;
+    method?: string;
+}
+/** 协议错误帧载荷（`{code,message,recovery}` 三件套——宿主据此渲染恢复指引）。 */
+interface ProtocolErrorPayload {
+    code: string;
+    message: string;
+    recovery: string;
+}
+/**
+ * 异常 → 协议错误帧载荷。
+ *
+ * `EngineSdkError` 自带结构化（`toStructured()`，含引擎侧恢复指引）；其余异常落
+ * `engine_run_failed` + 调用方给的恢复指引文案（各引擎的日志位置不同，故 recovery
+ * 由调用方注入而不是在这里写死）。
+ */
+declare function toProtocolError(err: unknown, recovery: string): ProtocolErrorPayload;
+/** 入站帧分类结果（纯判定、零副作用，便于单测逐分支断言）。 */
+type InboundFrameAction = {
+    kind: "reverse-response";
+    id: number | string;
+} | {
+    kind: "rejected-reverse-request";
+    method: string;
+} | {
+    kind: "request";
+    id: number;
+    method: string;
+    params: unknown;
+} | {
+    kind: "ignore";
+};
+/**
+ * 入站帧 → 动作。
+ *
+ * 判序即协议纪律：①反向应答（对端在等的 host/* 应答）②反向请求（引擎不发 host/*，
+ * 属非法入站 → 坏帧应答）③正向请求（`id` 为 number 且 `method` 为 string）④其余静默
+ * 忽略（stdout 是独占协议通道，不回显坏帧防对端解析器混乱）。
+ */
+declare function classifyInboundFrame(frame: unknown): InboundFrameAction;
+/** 引擎侧收到反向请求帧时的坏帧应答（`id: 0` = 非请求应答，对端只记坏帧）。 */
+declare function reverseRequestRejection(method: string): {
+    id: number;
+    error: ProtocolErrorPayload;
+};
+/** 未知协议方法错误（两引擎逐字一致；表查找失败时抛，经 `toError` 转错误帧）。 */
+declare function unknownMethodError(id: number, method: string): EngineSdkError;
+/** 帧循环所需的最小上下文（引擎侧实现注入；每引擎构造一次，不在每帧重建）。 */
+interface FrameLoopContext {
+    /** 出站帧写入面。 */
+    write: FrameWriter;
+    /** 反向应答帧落地（各引擎的两阶段 ack 语义在此，**刻意不统一**）。 */
+    settleReverse(id: number | string, frame: {
+        result?: unknown;
+        error?: unknown;
+    }): void;
+    /** 正向请求分发（9 方法表；抛出的错误经 `toError` 转错误帧）。 */
+    dispatch(id: number, method: string, params: unknown): unknown;
+    /** 错误 → 错误帧载荷（各引擎的恢复指引文案不同，故由引擎注入）。 */
+    toError(err: unknown): ProtocolErrorPayload;
+}
+/** 跑一帧（分类 → 落地）。返回值仅用于测试可读性，生产调用方忽略。 */
+declare function handleInboundFrame(frame: unknown, ctx: FrameLoopContext): InboundFrameAction;
+/**
+ * 反向请求发送（引擎 → 宿主请求的发出与等待登记）。
+ *
+ * 语义（两条都是踩过坑的）：
+ *   - 计时兜底在**发出侧**武装——应答侧不重复武装，两阶段 ack 只延长等待而不重置计时。
+ *   - `write` 同步抛错（stdout 关闭等）就地收尾：清 pending + 停 timer + 记 clock 后转
+ *     reject；不让异常同步逃出 Promise executor（逃出 = pending 条目与 timer 残留，
+ *     且 reject 无人消费时仍是 unhandled rejection 面）。
+ */
+interface ReverseRequestSendContext {
+    write: FrameWriter;
+    pending: Map<string, ReversePending>;
+    timeoutMs: number;
+    clock?: ReverseRequestClock;
+    /** 请求 id 分配（各引擎可带自己的前缀与计数器）。 */
+    nextId(): string;
+    /** 实现特有的 pending 附加字段（pi 记 `method` 供应答面检查用；zcode 不记）。 */
+    pendingExtras?(method: string): Partial<ReversePending>;
+}
+declare function sendReverseRequest(ctx: ReverseRequestSendContext, method: string, params: unknown): Promise<unknown>;
+/** 运行事件通知帧（`seq` 单调：无在途登记时取 0，仅作占位而非序号源）。 */
+declare function writeRunEvent(write: FrameWriter, activeRuns: Map<string, ActiveRun>, runId: string, event: AgentEvent): void;
+/** 初始化握手所需的最小上下文（版本协商共用；引擎实例面与适配器版本由引擎注入）。 */
+interface InitializeHandshakeContext {
+    /** 引擎实例 id（`EnginePort.id`）。 */
+    engineId: string;
+    /** 引擎包自己的适配器版本常量（各包独立版本号）。 */
+    adapterVersion: string;
+    /** 能力位（`EnginePort.capabilities()` 的返回值）。 */
+    capabilities: InitializeResult["capabilities"];
+    /** 可用模型列表；`null` = 本引擎不提供（应答里不带 models 字段）。 */
+    listModels(): Array<{
+        id: string;
+    }> | null;
+}
+/**
+ * 初始化握手：协议版本协商（越界 → `engine_protocol_mismatch`）+ 能力与模型应答。
+ *
+ * 版本比对用严格相等：v1 系列内仍以 `ENGINE_PROTOCOL_VERSION` 为准（宿主与引擎同批发布），
+ * 放宽比对会让「装了旧引擎」静默通过，后续方法缺失才炸在更远处。
+ */
+declare function initializeEngine(params: InitializeParams, ctx: InitializeHandshakeContext): InitializeResult;
+/** run 前门未初始化拒绝（两引擎逐字一致的协议错误）。 */
+declare function notInitializedError(): EngineSdkError;
+/**
+ * 协议 `task` 子集 + `ctx` 还原 = 本地全量 `AgentCallOpts`（与宿主侧
+ * `RemoteEngine.toSdkTaskSubset` 镜像）。
+ *
+ * 还原纪律：`model` / `cwd` **有值才写**（wire additive 语义）——写 `undefined` 会覆盖
+ * 引擎侧缺省值，worktree 隔离与模型选择都会静默走错。
+ */
+declare function assembleFullTask(task: AgentCallOpts, ctx: RunContextParams): AgentCallOpts;
+
+export { type ActiveRun, type FrameLoopContext, type FrameWriter, type InboundFrameAction, type InitializeHandshakeContext, type ProtocolErrorPayload, REVERSE_TIMEOUT_DEFAULT_MS, type ReversePending, type ReverseRequestSendContext, assembleFullTask, classifyInboundFrame, handleInboundFrame, initializeEngine, notInitializedError, reverseRequestRejection, sendReverseRequest, toProtocolError, unknownMethodError, writeRunEvent };

package/dist/server/index.js

@@ -0,0 +1,143 @@
+import {
+  isResponseFrame,
+  isReverseRequestFrame
+} from "../chunk-D36ZIQQK.js";
+import {
+  toErrorMessage
+} from "../chunk-PYO3YR7W.js";
+import {
+  ENGINE_PROTOCOL_VERSION,
+  EngineSdkError
+} from "../chunk-SFNTX7Q3.js";
+import "../chunk-JSBRDJBE.js";
+
+// src/server/index.ts
+var REVERSE_TIMEOUT_DEFAULT_MS = 6e4;
+function toProtocolError(err, recovery) {
+  if (err instanceof EngineSdkError) return err.toStructured();
+  return { code: "engine_run_failed", message: toErrorMessage(err), recovery };
+}
+function classifyInboundFrame(frame) {
+  if (isResponseFrame(frame)) return { kind: "reverse-response", id: frame.id };
+  if (isReverseRequestFrame(frame)) return { kind: "rejected-reverse-request", method: String(frame.method) };
+  if (typeof frame === "object" && frame !== null && "id" in frame && "method" in frame && typeof frame.method === "string") {
+    const { id, method, params } = frame;
+    if (typeof id === "number") return { kind: "request", id, method, params };
+  }
+  return { kind: "ignore" };
+}
+function reverseRequestRejection(method) {
+  return {
+    id: 0,
+    error: {
+      code: "engine_protocol_bad_frame",
+      message: `unexpected reverse request frame from host: ${method}`,
+      recovery: "The engine protocol v1 only carries host/* requests engine\u2192host."
+    }
+  };
+}
+function unknownMethodError(id, method) {
+  return new EngineSdkError(
+    "engine_protocol_unknown_method",
+    `unknown protocol method: ${method} (request id ${id})`,
+    "The engine speaks protocol v1; check the installed engine package version vs the host."
+  );
+}
+function handleInboundFrame(frame, ctx) {
+  const action = classifyInboundFrame(frame);
+  switch (action.kind) {
+    case "reverse-response":
+      ctx.settleReverse(action.id, frame);
+      return action;
+    case "rejected-reverse-request":
+      ctx.write(reverseRequestRejection(action.method));
+      return action;
+    case "request": {
+      let result;
+      try {
+        result = ctx.dispatch(action.id, action.method, action.params);
+      } catch (err) {
+        ctx.write({ id: action.id, error: ctx.toError(err) });
+        return action;
+      }
+      void Promise.resolve(result).then(
+        (value) => ctx.write({ id: action.id, result: value }),
+        (err) => ctx.write({ id: action.id, error: ctx.toError(err) })
+      );
+      return action;
+    }
+    case "ignore":
+      return action;
+  }
+}
+function sendReverseRequest(ctx, method, params) {
+  const id = ctx.nextId();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      ctx.pending.delete(id);
+      ctx.clock?.settled(id);
+      reject(new Error(`reverse request ${method} (${id}) timed out after ${ctx.timeoutMs}ms`));
+    }, ctx.timeoutMs);
+    if (typeof timer.unref === "function") timer.unref();
+    ctx.pending.set(id, { resolve, reject, timer, ...ctx.pendingExtras?.(method) ?? {} });
+    ctx.clock?.started(id);
+    try {
+      ctx.write({ id, method, params });
+    } catch (err) {
+      ctx.pending.delete(id);
+      clearTimeout(timer);
+      ctx.clock?.settled(id);
+      reject(new Error(`reverse request ${method} (${id}) could not be written: ${toErrorMessage(err)}`));
+    }
+  });
+}
+function writeRunEvent(write, activeRuns, runId, event) {
+  const active = activeRuns.get(runId);
+  const seq = active !== void 0 ? ++active.seq : 0;
+  write({ method: "event", params: { runId, seq, event } });
+}
+function initializeEngine(params, ctx) {
+  if (params?.protocolVersion !== ENGINE_PROTOCOL_VERSION) {
+    throw new EngineSdkError(
+      "engine_protocol_mismatch",
+      `host protocol version ${String(params?.protocolVersion)} is not compatible with engine protocol v${ENGINE_PROTOCOL_VERSION}`,
+      `Upgrade the engine package or the host so both speak protocol v${ENGINE_PROTOCOL_VERSION}.`
+    );
+  }
+  const models = ctx.listModels();
+  return {
+    protocolVersion: ENGINE_PROTOCOL_VERSION,
+    engineId: ctx.engineId,
+    engineVersion: ctx.adapterVersion,
+    adapterVersion: ctx.adapterVersion,
+    capabilities: ctx.capabilities,
+    ...models !== null ? { models: models.map((m) => ({ id: m.id })) } : {}
+  };
+}
+function notInitializedError() {
+  return new EngineSdkError(
+    "engine_protocol_not_initialized",
+    "run before initialize is a protocol violation",
+    "The host must complete the initialize handshake before dispatching runs."
+  );
+}
+function assembleFullTask(task, ctx) {
+  return {
+    ...task,
+    ...ctx.model !== void 0 ? { model: ctx.model } : {},
+    ...ctx.cwd !== void 0 ? { cwd: ctx.cwd } : {}
+  };
+}
+export {
+  REVERSE_TIMEOUT_DEFAULT_MS,
+  assembleFullTask,
+  classifyInboundFrame,
+  handleInboundFrame,
+  initializeEngine,
+  notInitializedError,
+  reverseRequestRejection,
+  sendReverseRequest,
+  toProtocolError,
+  unknownMethodError,
+  writeRunEvent
+};