@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/protocol/index.cjs

@@ -0,0 +1,400 @@
+"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/protocol/index.ts
+var protocol_exports = {};
+__export(protocol_exports, {
+  CANCEL_SETTLE_GRACE_MS: () => CANCEL_SETTLE_GRACE_MS,
+  CRASH_REBUILD_BACKOFF_MS: () => CRASH_REBUILD_BACKOFF_MS,
+  CRASH_REBUILD_MAX_ATTEMPTS: () => CRASH_REBUILD_MAX_ATTEMPTS,
+  ENGINE_ERROR_CODE_PREFIX: () => ENGINE_ERROR_CODE_PREFIX,
+  ENGINE_EVENT_COALESCE_DEFAULT: () => ENGINE_EVENT_COALESCE_DEFAULT,
+  ENGINE_EVENT_COALESCE_ENV: () => ENGINE_EVENT_COALESCE_ENV,
+  ENGINE_PROTOCOL_ERROR_CODES: () => ENGINE_PROTOCOL_ERROR_CODES,
+  ENGINE_PROTOCOL_SCHEMAS: () => ENGINE_PROTOCOL_SCHEMAS,
+  ENGINE_PROTOCOL_VERSION: () => ENGINE_PROTOCOL_VERSION,
+  ENGINE_TIMEOUT_RECOVERY: () => ENGINE_TIMEOUT_RECOVERY,
+  EngineSdkError: () => EngineSdkError,
+  FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS: () => FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
+  HANDSHAKE_TIMEOUT_MS: () => HANDSHAKE_TIMEOUT_MS,
+  PROTOCOL_METHODS: () => PROTOCOL_METHODS,
+  REVERSE_CHANNELS: () => REVERSE_CHANNELS,
+  REVERSE_CHANNEL_NAMES: () => REVERSE_CHANNEL_NAMES,
+  REVERSE_CHANNEL_TIMEOUT_CLASS: () => REVERSE_CHANNEL_TIMEOUT_CLASS,
+  REVERSE_REQUEST_TIMEOUT_MS: () => REVERSE_REQUEST_TIMEOUT_MS,
+  STDERR_TAIL_CHARS: () => STDERR_TAIL_CHARS,
+  STDOUT_TAIL_ECHO_CHARS: () => STDOUT_TAIL_ECHO_CHARS,
+  SUPPORTED_PROTOCOL_RANGE: () => SUPPORTED_PROTOCOL_RANGE,
+  assertChatConversationSupported: () => assertChatConversationSupported,
+  engineConversationUnsupportedError: () => engineConversationUnsupportedError,
+  engineProtocolMismatchError: () => engineProtocolMismatchError,
+  engineTimeoutDetail: () => engineTimeoutDetail,
+  errorResponseFrameSchema: () => errorResponseFrameSchema,
+  isEngineErrorPassthroughCode: () => isEngineErrorPassthroughCode,
+  isEngineProtocolErrorCode: () => isEngineProtocolErrorCode,
+  isHostRoundLifecycleParams: () => isHostRoundLifecycleParams,
+  isHostStreamDeltaParams: () => isHostStreamDeltaParams,
+  isNotificationFrame: () => isNotificationFrame,
+  isProtocolVersionCompatible: () => isProtocolVersionCompatible,
+  isRequestFrame: () => isRequestFrame,
+  isResponseFrame: () => isResponseFrame,
+  isReverseRequestFrame: () => isReverseRequestFrame,
+  notificationFrameSchema: () => notificationFrameSchema,
+  protocolErrorSchema: () => protocolErrorSchema,
+  requestFrameSchema: () => requestFrameSchema,
+  reverseRequestFrameSchema: () => reverseRequestFrameSchema,
+  schemaEmulationFailedDetail: () => schemaEmulationFailedDetail,
+  successResponseFrameSchema: () => successResponseFrameSchema
+});
+module.exports = __toCommonJS(protocol_exports);
+
+// src/protocol/engine-protocol.ts
+var ENGINE_PROTOCOL_VERSION = 1;
+var SUPPORTED_PROTOCOL_RANGE = { min: 1, max: 2 };
+function isProtocolVersionCompatible(version) {
+  return Number.isInteger(version) && version >= SUPPORTED_PROTOCOL_RANGE.min && version < SUPPORTED_PROTOCOL_RANGE.max;
+}
+var REVERSE_REQUEST_TIMEOUT_MS = 1e4;
+var HANDSHAKE_TIMEOUT_MS = 1e4;
+var CANCEL_SETTLE_GRACE_MS = 3e3;
+var CRASH_REBUILD_MAX_ATTEMPTS = 3;
+var CRASH_REBUILD_BACKOFF_STEP_1_MS = 1e3;
+var CRASH_REBUILD_BACKOFF_STEP_2_MS = 2e3;
+var CRASH_REBUILD_BACKOFF_STEP_3_MS = 4e3;
+var CRASH_REBUILD_BACKOFF_MS = [
+  CRASH_REBUILD_BACKOFF_STEP_1_MS,
+  CRASH_REBUILD_BACKOFF_STEP_2_MS,
+  CRASH_REBUILD_BACKOFF_STEP_3_MS
+];
+var STDERR_TAIL_CHARS = 400;
+var ENGINE_EVENT_COALESCE_ENV = "XYZ_ENGINE_EVENT_COALESCE";
+var ENGINE_EVENT_COALESCE_DEFAULT = "0";
+
+// src/protocol/frames.ts
+function isRecord(v) {
+  return typeof v === "object" && v !== null;
+}
+function isRequestFrame(frame) {
+  return isRecord(frame) && typeof frame.id === "number" && typeof frame.method === "string" && "params" in frame && !("result" in frame) && !("error" in frame);
+}
+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 isNotificationFrame(frame) {
+  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";
+}
+function isReverseRequestFrame(frame) {
+  return isRecord(frame) && typeof frame.id === "string" && typeof frame.method === "string" && frame.method.startsWith("host/") && "params" in frame;
+}
+
+// src/protocol/methods.ts
+var PROTOCOL_METHODS = [
+  "initialize",
+  "probe",
+  "run",
+  "cancel",
+  "interact",
+  "read",
+  "listModels",
+  "validateModel",
+  "dispose",
+  "ping"
+];
+
+// src/protocol/reverse-channels.ts
+var REVERSE_CHANNELS = [
+  "host/log",
+  "host/askUser",
+  "host/permission",
+  "host/streamDelta",
+  "host/poolResolved",
+  "host/handleReady",
+  "host/childSpawned",
+  "host/childStateChanged",
+  "host/roundLifecycle"
+];
+var REVERSE_CHANNEL_TIMEOUT_CLASS = {
+  "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"
+};
+function isHostStreamDeltaParams(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  const hasRunId = typeof v.runId === "string";
+  const hasRecordId = typeof v.recordId === "string";
+  if (hasRunId === hasRecordId) return false;
+  return typeof v.delta === "string";
+}
+function isHostRoundLifecycleParams(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value;
+  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.code === "string" && typeof err.message === "string";
+}
+
+// src/protocol/error-codes.ts
+var 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"
+];
+function isEngineProtocolErrorCode(value) {
+  return typeof value === "string" && ENGINE_PROTOCOL_ERROR_CODES.includes(value);
+}
+var ENGINE_ERROR_CODE_PREFIX = "engine_";
+function isEngineErrorPassthroughCode(value) {
+  return !isEngineProtocolErrorCode(value) && value.startsWith(ENGINE_ERROR_CODE_PREFIX);
+}
+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 };
+  }
+};
+function engineProtocolMismatchError(engineVersion) {
+  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
+    }
+  );
+}
+function engineConversationUnsupportedError(engineId) {
+  return new EngineSdkError(
+    "engine_capability_unsupported",
+    `engine '${engineId}' \u4E0D\u652F\u6301 conversation\uFF08capabilities.conversation = 'unsupported'\uFF0Cmanifest \u65E0 conversation gate \u4F4D\u2014\u2014\u65E0\u540C\u8FDB\u7A0B idle \u590D\u7528\uFF0Cmessage/close \u4EA4\u4E92\u63A7\u5236\u9762\u4E0D\u53EF\u7528\uFF09`,
+    `\u53BB\u6389 conversation \u53C2\u6570\uFF08\u4E00\u6B21\u6027\u4EFB\u52A1\u9ED8\u8BA4\u5F62\u6001\uFF09\uFF0C\u6216\u4FEE manifest capabilities / \u5347\u7EA7\u5F15\u64CE\u5305\uFF08\u82E5\u5F15\u64CE\u5B9E\u9645\u652F\u6301\u8BE5\u80FD\u529B\uFF09`,
+    { engineId, capability: "conversation", declared: "unsupported" }
+  );
+}
+function assertChatConversationSupported(engineId, capabilities) {
+  if (capabilities.conversation === "unsupported") {
+    throw engineConversationUnsupportedError(engineId);
+  }
+}
+var DETAIL_ECHO_MAX_CHARS = 200;
+var STDOUT_TAIL_ECHO_CHARS = 2e3;
+function truncate(text, max) {
+  return text.length <= max ? text : `${text.slice(0, max)}...`;
+}
+var 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`.";
+function engineTimeoutDetail(stdoutTail) {
+  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}`;
+}
+function schemaEmulationFailedDetail(error, tail) {
+  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).`;
+}
+
+// src/protocol/schema.ts
+var ANY_JSON = {};
+var protocolErrorSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolError",
+  type: "object",
+  additionalProperties: false,
+  required: ["code", "message", "recovery"],
+  properties: {
+    code: { type: "string", pattern: "^engine_" },
+    message: { type: "string" },
+    recovery: { type: "string" },
+    data: { type: "object" }
+  }
+};
+var requestFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolRequestFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "method", "params"],
+  properties: {
+    id: { type: "number" },
+    method: { type: "string", enum: [...PROTOCOL_METHODS] },
+    params: ANY_JSON
+  }
+};
+var successResponseFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolSuccessResponseFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "result"],
+  properties: {
+    id: { type: ["number", "string"] },
+    result: ANY_JSON
+  }
+};
+var errorResponseFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolErrorResponseFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "error"],
+  properties: {
+    id: { type: ["number", "string"] },
+    error: protocolErrorSchema
+  }
+};
+var notificationFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolNotificationFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["method", "params"],
+  properties: {
+    method: { type: "string", const: "event" },
+    params: {
+      type: "object",
+      additionalProperties: false,
+      required: ["runId", "seq", "event"],
+      properties: {
+        runId: { type: "string" },
+        seq: { type: "number" },
+        event: {
+          type: "object",
+          required: ["type"],
+          properties: {
+            type: {
+              type: "string",
+              enum: [
+                "tool_start",
+                "tool_end",
+                "text_delta",
+                "thinking_delta",
+                "turn_end",
+                "message_end",
+                "compaction",
+                "error"
+              ]
+            }
+          }
+        }
+      }
+    }
+  }
+};
+var reverseRequestFrameSchema = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "EngineProtocolReverseRequestFrame",
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "method", "params"],
+  properties: {
+    id: { type: "string" },
+    method: { type: "string", enum: [...REVERSE_CHANNELS] },
+    params: ANY_JSON
+  }
+};
+var ENGINE_PROTOCOL_SCHEMAS = {
+  request: requestFrameSchema,
+  successResponse: successResponseFrameSchema,
+  errorResponse: errorResponseFrameSchema,
+  notification: notificationFrameSchema,
+  reverseRequest: reverseRequestFrameSchema,
+  protocolError: protocolErrorSchema
+};
+var FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS = [
+  "apikey",
+  "api_key",
+  "token",
+  "credential",
+  "password",
+  "secret"
+];
+var REVERSE_CHANNEL_NAMES = REVERSE_CHANNELS;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CANCEL_SETTLE_GRACE_MS,
+  CRASH_REBUILD_BACKOFF_MS,
+  CRASH_REBUILD_MAX_ATTEMPTS,
+  ENGINE_ERROR_CODE_PREFIX,
+  ENGINE_EVENT_COALESCE_DEFAULT,
+  ENGINE_EVENT_COALESCE_ENV,
+  ENGINE_PROTOCOL_ERROR_CODES,
+  ENGINE_PROTOCOL_SCHEMAS,
+  ENGINE_PROTOCOL_VERSION,
+  ENGINE_TIMEOUT_RECOVERY,
+  EngineSdkError,
+  FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
+  HANDSHAKE_TIMEOUT_MS,
+  PROTOCOL_METHODS,
+  REVERSE_CHANNELS,
+  REVERSE_CHANNEL_NAMES,
+  REVERSE_CHANNEL_TIMEOUT_CLASS,
+  REVERSE_REQUEST_TIMEOUT_MS,
+  STDERR_TAIL_CHARS,
+  STDOUT_TAIL_ECHO_CHARS,
+  SUPPORTED_PROTOCOL_RANGE,
+  assertChatConversationSupported,
+  engineConversationUnsupportedError,
+  engineProtocolMismatchError,
+  engineTimeoutDetail,
+  errorResponseFrameSchema,
+  isEngineErrorPassthroughCode,
+  isEngineProtocolErrorCode,
+  isHostRoundLifecycleParams,
+  isHostStreamDeltaParams,
+  isNotificationFrame,
+  isProtocolVersionCompatible,
+  isRequestFrame,
+  isResponseFrame,
+  isReverseRequestFrame,
+  notificationFrameSchema,
+  protocolErrorSchema,
+  requestFrameSchema,
+  reverseRequestFrameSchema,
+  schemaEmulationFailedDetail,
+  successResponseFrameSchema
+});