@zhushanwen/subagent-engine-sdk 0.2.0

package/dist/chunk-YFSN3D5N.js

@@ -0,0 +1,216 @@
+// 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/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;
+
+export {
+  isRequestFrame,
+  isResponseFrame,
+  isNotificationFrame,
+  isReverseRequestFrame,
+  PROTOCOL_METHODS,
+  REVERSE_CHANNELS,
+  REVERSE_CHANNEL_TIMEOUT_CLASS,
+  isHostStreamDeltaParams,
+  isHostRoundLifecycleParams,
+  protocolErrorSchema,
+  requestFrameSchema,
+  successResponseFrameSchema,
+  errorResponseFrameSchema,
+  notificationFrameSchema,
+  reverseRequestFrameSchema,
+  ENGINE_PROTOCOL_SCHEMAS,
+  FORBIDDEN_CREDENTIAL_KEY_FRAGMENTS,
+  REVERSE_CHANNEL_NAMES
+};

package/dist/chunk-ZOFFJNJD.js

@@ -0,0 +1,136 @@
+import {
+  EngineSdkError
+} from "./chunk-PPEPBVCC.js";
+
+// src/node-executor.ts
+import { spawn } from "child_process";
+var ENGINE_NODE_ENV = "XYZ_AGENT_ENGINE_NODE";
+var PROBE_TIMEOUT_MS = 5e3;
+function probeNodeExecutor(execPath, isElectron) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let child = null;
+    const finish = (ok) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try {
+        child?.kill("SIGKILL");
+      } catch {
+      }
+      resolve(ok);
+    };
+    const env = {};
+    if (process.env.PATH !== void 0) env.PATH = process.env.PATH;
+    if (process.env.HOME !== void 0) env.HOME = process.env.HOME;
+    if (isElectron) env.ELECTRON_RUN_AS_NODE = "1";
+    try {
+      child = spawn(execPath, ["--eval", "process.exit(0)"], {
+        env,
+        stdio: "ignore",
+        windowsHide: true
+      });
+    } catch {
+      resolve(false);
+      return;
+    }
+    const timer = setTimeout(() => finish(false), PROBE_TIMEOUT_MS);
+    timer.unref();
+    child.on("error", () => finish(false));
+    child.on("exit", (code) => finish(code === 0));
+  });
+}
+var probeCache = /* @__PURE__ */ new Map();
+function probeCached(execPath, isElectron) {
+  const key = `${execPath}:${isElectron}`;
+  let p = probeCache.get(key);
+  if (!p) {
+    p = probeNodeExecutor(execPath, isElectron);
+    probeCache.set(key, p);
+  }
+  return p;
+}
+function resetEngineNodeProbeCache() {
+  probeCache.clear();
+}
+function engineNotFound(detail, recovery) {
+  return new EngineSdkError("engine_not_found", detail, recovery);
+}
+function launchEnvOf(opts) {
+  return opts.env ?? process.env;
+}
+async function resolvePiExtensionLaunch(entryPath, entryArgs, env) {
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode === void 0 || engineNode === "") {
+    throw engineNotFound(
+      `pi extension host must spawn engines via injected executor ${ENGINE_NODE_ENV}, but it is not set (host process.execPath is the pi binary, not a node executor)`,
+      `The xyz-agent runtime injects ${ENGINE_NODE_ENV} when spawning the pi host. If you are running the extension inside a packaged app, report this as a packaging regression; standalone pi installs do not use the pi-extension host kind.`
+    );
+  }
+  const isElectron = env.ELECTRON_RUN_AS_NODE === "1";
+  if (!await probeCached(engineNode, isElectron)) {
+    throw engineNotFound(
+      `injected node executor failed the probe: ${engineNode} (isElectron=${isElectron})`,
+      `Verify the executor exists and can run plain node semantics (Electron binaries need ELECTRON_RUN_AS_NODE=1). The host re-probes after restart.`
+    );
+  }
+  return { command: engineNode, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+async function resolveRuntimeSidecarLaunch(entryPath, entryArgs, opts) {
+  const execPath = opts.execPath ?? process.execPath;
+  const isElectron = opts.isElectronHost ?? process.versions.electron !== void 0;
+  if (!await probeCached(execPath, isElectron)) {
+    throw engineNotFound(
+      `runtime sidecar executor failed the probe: ${execPath} (isElectron=${isElectron})`,
+      `The sidecar process.execPath must run plain node semantics (ELECTRON_RUN_AS_NODE=1 for Electron binaries). Check how the runtime sidecar was spawned.`
+    );
+  }
+  return { command: execPath, args: [entryPath, ...entryArgs], electronRunAsNode: isElectron };
+}
+async function resolveStandaloneLaunch(entryPath, entryArgs) {
+  if (!await probeCached("node", false)) {
+    throw engineNotFound(
+      `no usable 'node' on PATH for standalone engine launch (entry: ${entryPath})`,
+      `Install Node.js >= 22 and ensure 'node' is on PATH (https://nodejs.org/), or configure the engine explicitly via subagents/config.json.`
+    );
+  }
+  return { command: "node", args: [entryPath, ...entryArgs], electronRunAsNode: false };
+}
+async function resolveEngineNodeLaunch(opts) {
+  const platform = opts.platform ?? process.platform;
+  const entryArgs = [...opts.args ?? []];
+  if (platform === "win32" && opts.entryPath.toLowerCase().endsWith(".cmd")) {
+    return {
+      command: "cmd.exe",
+      args: ["/c", opts.entryPath, ...entryArgs],
+      electronRunAsNode: false
+    };
+  }
+  if (!/\.(?:js|mjs|cjs|ts)$/i.test(opts.entryPath)) {
+    return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+  }
+  if (opts.hostKind === "pi-extension") {
+    return resolvePiExtensionLaunch(opts.entryPath, entryArgs, launchEnvOf(opts));
+  }
+  if (opts.hostKind === "runtime-sidecar") {
+    return resolveRuntimeSidecarLaunch(opts.entryPath, entryArgs, opts);
+  }
+  if (opts.hostKind === "standalone") {
+    return resolveStandaloneLaunch(opts.entryPath, entryArgs);
+  }
+  return { command: opts.entryPath, args: entryArgs, electronRunAsNode: false };
+}
+function hostKindOf(hostKind, env = process.env) {
+  if (hostKind.startsWith("runtime")) return "runtime-sidecar";
+  const engineNode = env[ENGINE_NODE_ENV]?.trim();
+  if (engineNode !== void 0 && engineNode !== "") return "pi-extension";
+  return "standalone";
+}
+
+export {
+  ENGINE_NODE_ENV,
+  probeNodeExecutor,
+  resetEngineNodeProbeCache,
+  resolveEngineNodeLaunch,
+  hostKindOf
+};

package/dist/chunk-ZXEAW25V.js

@@ -0,0 +1,132 @@
+import {
+  getLogger
+} from "./chunk-75QEMUGV.js";
+
+// src/env.ts
+var logger = getLogger("engine-sdk/env");
+var ENGINE_ENV_PREFIXES = [
+  "XYZ_",
+  "XYZ_AGENT_",
+  "XYZ_SUBAGENT_"
+];
+var ENGINE_ENV_DENY_LIST = [
+  "XYZ_AGENT_PACKAGED",
+  "XYZ_RUNTIME_TOKEN",
+  "XYZ_AGENT_API_KEY",
+  "XYZ_SUBAGENT_RELAY_SESSION_ID",
+  "XYZ_SUBAGENT_RELAY_RECORD_ID",
+  "XYZ_SUBAGENT_RELAY_STDIN",
+  "XYZ_SUBAGENT_RELAY_STDOUT",
+  "XYZ_SUBAGENT_RELAY_STDERR"
+];
+var ENGINE_ENV_L0_INFRA_KEYS = [
+  "XYZ_AGENT_DATA_DIR",
+  "XYZ_AGENT_ENGINE_NODE",
+  "ELECTRON_RUN_AS_NODE",
+  "XYZ_AGENT_SUBAGENT",
+  "XYZ_SUBAGENT_RELAY_SOCKET",
+  "XYZ_SUBAGENT_RELAY_NODE",
+  "XYZ_SUBAGENT_RELAY_SCRIPT"
+];
+var ENV_PREFIX_SHAPE_RE = /^[A-Za-z0-9_]+$/;
+function deleteEnvKeysCaseInsensitive(env, names) {
+  const lowered = new Set(names.map((n) => n.toLowerCase()));
+  for (const key of Object.keys(env)) {
+    if (lowered.has(key.toLowerCase())) delete env[key];
+  }
+}
+function compileManifestPrefixes(prefixes) {
+  const compiled = [];
+  for (const raw of prefixes) {
+    if (!ENV_PREFIX_SHAPE_RE.test(raw)) {
+      logger.warn(
+        `envPrefixes entry dropped (invalid shape, expected ^[A-Za-z0-9_]+$): ${JSON.stringify(raw)}`
+      );
+      continue;
+    }
+    const lowered = raw.toLowerCase();
+    if (ENGINE_ENV_PREFIXES.some((reserved) => lowered.startsWith(reserved.toLowerCase()))) {
+      logger.warn(
+        `envPrefixes entry dropped (reserved prefix, infra keys are L0-only): ${JSON.stringify(raw)}`
+      );
+      continue;
+    }
+    compiled.push(lowered);
+  }
+  return compiled.length > 0 ? compiled : null;
+}
+function applyManifestAllowlist(env, opts) {
+  if (opts.processEnv !== void 0 && opts.envPrefixes !== void 0) {
+    const compiled = compileManifestPrefixes(opts.envPrefixes);
+    if (compiled !== null) {
+      for (const [key, value] of Object.entries(opts.processEnv)) {
+        if (value === void 0) continue;
+        const loweredKey = key.toLowerCase();
+        if (compiled.some((prefix) => loweredKey.startsWith(prefix))) {
+          env[key] = value;
+        } else {
+          logger.warn(`processEnv key not allowed (no declared envPrefix matches): ${key}`);
+        }
+      }
+    }
+  } else if (opts.processEnv !== void 0) {
+    for (const key of Object.keys(opts.processEnv)) {
+      logger.warn(`processEnv key not allowed (manifest declares no envPrefixes): ${key}`);
+    }
+  }
+}
+function injectL0InfraKeys(env, opts) {
+  env.XYZ_AGENT_DATA_DIR = opts.dataDir;
+  if (opts.engineNode !== void 0) env.XYZ_AGENT_ENGINE_NODE = opts.engineNode;
+  if (opts.electronRunAsNode === true) env.ELECTRON_RUN_AS_NODE = "1";
+  env.XYZ_AGENT_SUBAGENT = "1";
+  if (opts.relay !== void 0) {
+    env.XYZ_SUBAGENT_RELAY_SOCKET = opts.relay.socket;
+    env.XYZ_SUBAGENT_RELAY_NODE = opts.relay.node;
+    env.XYZ_SUBAGENT_RELAY_SCRIPT = opts.relay.script;
+  }
+  if (opts.identityEnv !== void 0) {
+    for (const [key, value] of Object.entries(opts.identityEnv)) {
+      if (value !== void 0) env[key] = value;
+    }
+  }
+}
+function buildEngineChildEnv(baseEnv, opts) {
+  const env = {};
+  for (const [key, value] of Object.entries(baseEnv)) {
+    if (value !== void 0) env[key] = value;
+  }
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+  applyManifestAllowlist(env, opts);
+  deleteEnvKeysCaseInsensitive(env, ENGINE_ENV_DENY_LIST);
+  injectL0InfraKeys(env, opts);
+  return env;
+}
+function buildOutboundChildEnv(opts) {
+  const out = {};
+  const loweredPrefixes = opts.prefixes !== void 0 ? opts.prefixes.map((p) => p.toLowerCase()) : null;
+  for (const [key, value] of Object.entries(opts.parentEnv)) {
+    if (value === void 0) continue;
+    if (loweredPrefixes !== null) {
+      const loweredKey = key.toLowerCase();
+      if (!loweredPrefixes.some((prefix) => loweredKey.startsWith(prefix))) continue;
+    }
+    out[key] = value;
+  }
+  if (opts.extras !== void 0) {
+    for (const [key, value] of Object.entries(opts.extras)) {
+      if (value !== void 0) out[key] = value;
+      else delete out[key];
+    }
+  }
+  deleteEnvKeysCaseInsensitive(out, ENGINE_ENV_DENY_LIST);
+  return out;
+}
+
+export {
+  ENGINE_ENV_PREFIXES,
+  ENGINE_ENV_DENY_LIST,
+  ENGINE_ENV_L0_INFRA_KEYS,
+  buildEngineChildEnv,
+  buildOutboundChildEnv
+};

package/dist/cli-entry.cjs

@@ -0,0 +1,119 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli-entry.ts
+var cli_entry_exports = {};
+__export(cli_entry_exports, {
+  runEngineCliEntry: () => runEngineCliEntry
+});
+module.exports = __toCommonJS(cli_entry_exports);
+var readline = __toESM(require("readline"), 1);
+
+// src/logger.ts
+var SINK_SLOT_KEY = /* @__PURE__ */ Symbol.for("@zhushanwen/subagent-engine-sdk.logger-sink");
+function getSinkSlot() {
+  let slot = Reflect.get(globalThis, SINK_SLOT_KEY);
+  if (!slot) {
+    slot = { current: void 0 };
+    Reflect.set(globalThis, SINK_SLOT_KEY, slot);
+  }
+  return slot;
+}
+var CONSOLE_SINK = {
+  log(level, component, message, data) {
+    const line = `[${component}] ${message}`;
+    if (level === "error") {
+      if (data === void 0) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === void 0) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+  }
+};
+function currentSink() {
+  return getSinkSlot().current ?? CONSOLE_SINK;
+}
+function configureLoggerSink(sink) {
+  getSinkSlot().current = sink;
+}
+var facadeCache = /* @__PURE__ */ new Map();
+function getLogger(component) {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade = {
+    debug(msg, data) {
+      currentSink().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      currentSink().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      currentSink().log("error", component, msg, data);
+    }
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}
+
+// src/cli-entry.ts
+var INBOUND_LOG_CHARS = 200;
+function runEngineCliEntry(opts) {
+  const logger = getLogger(opts.component);
+  const server = opts.server;
+  configureLoggerSink({
+    log(level, component, message, data) {
+      process.stderr.write(`[${level}] [${component}] ${message}${data !== void 0 ? ` ${JSON.stringify(data)}` : ""}
+`);
+      void server.reverseRequest("host/log", { level, component, message }).catch(() => void 0);
+    }
+  });
+  const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+  rl.on("line", (line) => {
+    const text = line.trim();
+    if (text === "") return;
+    try {
+      server.handleFrame(JSON.parse(text));
+    } catch (err) {
+      logger.warn(`unparseable inbound protocol line (ignored): ${text.slice(0, INBOUND_LOG_CHARS)}`, {
+        reason: err instanceof Error ? err.message : String(err)
+      });
+    }
+  });
+  rl.on("close", () => {
+    logger.debug("stdin closed (host exit path)");
+  });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runEngineCliEntry
+});

package/dist/cli-entry.d.cts

@@ -0,0 +1,24 @@
+/**
+ * 引擎协议服务器的结构化最小接口（调用方薄层注入本包 EngineProtocolServer 实例；
+ * 结构子集避免 SDK 反向依赖各包 server 类型）。
+ */
+interface CliProtocolServerSink {
+    /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
+    handleFrame(frame: unknown): void;
+    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    reverseRequest(method: string, params: unknown): Promise<unknown>;
+}
+/** runEngineCliEntry 参数。 */
+interface RunEngineCliEntryOptions {
+    /** logger component 标签（如 "pi-engine-cli" / "zcode-engine-cli"）。 */
+    component: string;
+    /** 调用方构造的协议服务器实例（构造参数含 armEngineSelfDestruct 产出的 reverseClock）。 */
+    server: CliProtocolServerSink;
+}
+/**
+ * 引擎 CLI 进程入口样板（行为与收编前两包 main.ts 逐字节等价）：
+ * configureLoggerSink → stdin 行解析（NDJSON）→ server.handleFrame → close 留痕。
+ */
+declare function runEngineCliEntry(opts: RunEngineCliEntryOptions): void;
+
+export { type CliProtocolServerSink, type RunEngineCliEntryOptions, runEngineCliEntry };

package/dist/cli-entry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 引擎协议服务器的结构化最小接口（调用方薄层注入本包 EngineProtocolServer 实例；
+ * 结构子集避免 SDK 反向依赖各包 server 类型）。
+ */
+interface CliProtocolServerSink {
+    /** 入站协议帧处理（readline 已拆行 + JSON.parse 后的帧）。 */
+    handleFrame(frame: unknown): void;
+    /** 数据面反向请求（host/log 等；应答分类由各包 server 实现承载）。 */
+    reverseRequest(method: string, params: unknown): Promise<unknown>;
+}
+/** runEngineCliEntry 参数。 */
+interface RunEngineCliEntryOptions {
+    /** logger component 标签（如 "pi-engine-cli" / "zcode-engine-cli"）。 */
+    component: string;
+    /** 调用方构造的协议服务器实例（构造参数含 armEngineSelfDestruct 产出的 reverseClock）。 */
+    server: CliProtocolServerSink;
+}
+/**
+ * 引擎 CLI 进程入口样板（行为与收编前两包 main.ts 逐字节等价）：
+ * configureLoggerSink → stdin 行解析（NDJSON）→ server.handleFrame → close 留痕。
+ */
+declare function runEngineCliEntry(opts: RunEngineCliEntryOptions): void;
+
+export { type CliProtocolServerSink, type RunEngineCliEntryOptions, runEngineCliEntry };

package/dist/cli-entry.js

@@ -0,0 +1,8 @@
+import {
+  runEngineCliEntry
+} from "./chunk-N3RL6OVM.js";
+import "./chunk-75QEMUGV.js";
+import "./chunk-JSBRDJBE.js";
+export {
+  runEngineCliEntry
+};