@xyagent/cli 0.0.1

package/src-ext/runtime/codex/preflight.mjs

@@ -0,0 +1,67 @@
+// Codex 预检：
+//   - 二进制存在
+//   - 版本号能解析（决定用 `mcp-server` 还是老版 `mcp`）
+//
+// 用户若未登录（`codex login`）在 spawn 时才会显式报错 —— 我们透传。
+
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+
+const PREFLIGHT_TIMEOUT_MS = 5000;
+
+/**
+ * @returns {{ ok: boolean, version?: string, mcpSubcommand?: "mcp-server"|"mcp", error?: string, hint?: string }}
+ */
+export function codexPreflight({ log } = {}) {
+  const isWin = process.platform === "win32";
+  const pfLog = log ? log.child({ comp: "child", stage: "preflight" }) : null;
+
+  let res;
+  try {
+    res = spawnSync("codex", ["--version"], {
+      encoding: "utf8",
+      timeout: PREFLIGHT_TIMEOUT_MS,
+      shell: isWin ? true : false,
+    });
+  } catch (err) {
+    pfLog?.error("bridge.preflight.fail", "spawn threw", { err: err?.message || String(err) });
+    return { ok: false, error: err?.message || String(err), hint: "请先安装 codex CLI 并登录" };
+  }
+  if (res.error) {
+    const isENOENT = res.error.code === "ENOENT";
+    pfLog?.error("bridge.preflight.fail", "spawn errored", {
+      code: res.error.code, err: res.error.message,
+    });
+    return {
+      ok: false, error: res.error.message,
+      hint: isENOENT
+        ? "未找到 `codex` 命令。请先安装 OpenAI Codex CLI 并登录（`codex login`）。"
+        : "spawn codex 失败",
+    };
+  }
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      error: `codex --version exit ${res.status}`,
+      hint: "codex 启动报错",
+    };
+  }
+
+  // "codex-cli 0.116.0" → "0.116.0"
+  const line = (res.stdout || "").trim().split(/\r?\n/)[0] || "";
+  const m = line.match(/(\d+)\.(\d+)\.(\d+)/);
+  const version = line;
+  let mcpSubcommand = "mcp-server";
+  if (m) {
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const patch = Number(m[3]);
+    // 0.43.0-alpha.5 之前老接口叫 `mcp`。近似：major=0 && minor < 43 → `mcp`。
+    if (major === 0 && (minor < 43 || (minor === 43 && patch < 0))) {
+      mcpSubcommand = "mcp";
+    }
+  }
+
+  pfLog?.info("bridge.preflight.pass", "codex binary ok", { version, mcpSubcommand });
+  return { ok: true, version, mcpSubcommand };
+}

package/src-ext/runtime/hermes/commandBackend.mjs

@@ -0,0 +1,117 @@
+// Hermes subprocess command backend.
+//
+// Spawn an external binary and pipe a single JSON request to its stdin; expect
+// a stream of newline-delimited JSON events on stdout, each shaped like:
+//
+//   {"type":"delta","text":"hello"}
+//   {"type":"delta","text":" world"}
+//   {"type":"usage","prompt_tokens":12,"completion_tokens":3}
+//   {"type":"done"}
+//
+// The external program is responsible for talking to whatever LLM lives behind
+// it. Bridge is just a transport. Lets users plug in a Python script,
+// llama.cpp, or anything else without forking the bridge.
+
+import { spawn } from "node:child_process";
+
+/**
+ * @param {Array<{role:string,content:string}>} messages
+ * @param {{ command: string[], model?: string, signal?: AbortSignal }} opts
+ * @returns {AsyncGenerator<{kind:"delta"|"done"|"usage"|"error", text?:string, fullText?:string, usage?:any, error?:string}>}
+ */
+export async function* streamChat(messages, opts) {
+  const argv = opts.command.slice();
+  const cmd = argv.shift();
+  if (!cmd) {
+    yield { kind: "error", error: "command backend: empty argv" };
+    return;
+  }
+  const child = spawn(cmd, argv, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: { ...process.env, HERMES_BRIDGE_MODEL: opts.model || "", HERMES_HOME: opts.hermesHome || "" },
+  });
+  if (opts.signal) {
+    opts.signal.addEventListener("abort", () => {
+      try { child.kill("SIGTERM"); } catch {}
+    });
+  }
+
+  // Send request.
+  child.stdin.write(JSON.stringify({ messages, model: opts.model }) + "\n");
+  child.stdin.end();
+
+  let pending = "";
+  let accum = "";
+  let usage = null;
+  let stderrTail = "";
+
+  child.stderr.on("data", (chunk) => {
+    stderrTail += chunk.toString("utf8");
+    if (stderrTail.length > 4000) stderrTail = stderrTail.slice(-4000);
+  });
+
+  // Yield from stdout line-by-line.
+  for await (const chunk of child.stdout) {
+    pending += chunk.toString("utf8");
+    let nlIdx;
+    while ((nlIdx = pending.indexOf("\n")) !== -1) {
+      const line = pending.slice(0, nlIdx).trim();
+      pending = pending.slice(nlIdx + 1);
+      if (!line) continue;
+      let evt;
+      try {
+        evt = JSON.parse(line);
+      } catch {
+        // Non-JSON line; treat as delta.
+        accum += line;
+        yield { kind: "delta", text: line };
+        continue;
+      }
+      switch (evt.type) {
+        case "delta": {
+          const t = String(evt.text ?? "");
+          if (!t) break;
+          accum += t;
+          yield { kind: "delta", text: t };
+          break;
+        }
+        case "usage":
+          usage = {
+            prompt_tokens: evt.prompt_tokens ?? evt.input_tokens ?? 0,
+            completion_tokens: evt.completion_tokens ?? evt.output_tokens ?? 0,
+            total_tokens: evt.total_tokens ?? 0,
+          };
+          break;
+        case "done":
+          yield { kind: "done", fullText: accum };
+          if (usage) yield { kind: "usage", usage };
+          break;
+        case "error":
+          yield { kind: "error", error: String(evt.error ?? "command backend error") };
+          break;
+        default:
+          break;
+      }
+    }
+  }
+  // Wait for child exit.
+  const exitCode = await new Promise((resolve) => {
+    child.once("exit", (code) => resolve(code ?? -1));
+  });
+  if (exitCode !== 0 && !accum) {
+    yield {
+      kind: "error",
+      error: `command backend exit ${exitCode}: ${stderrTail.slice(-400)}`,
+    };
+    return;
+  }
+  if (accum && !pendingHasDone(pending)) {
+    // Backend didn't emit explicit done; flush.
+    yield { kind: "done", fullText: accum };
+    if (usage) yield { kind: "usage", usage };
+  }
+}
+
+function pendingHasDone(s) {
+  return /\"type\"\s*:\s*\"done\"/.test(s);
+}

package/src-ext/runtime/hermes/envSetup.mjs

@@ -0,0 +1,229 @@
+// hermes runtime — `~/.hermes/.env` 自检 + 自动补齐 API_SERVER_* 配置。
+//
+// 背景：hermes-agent v0.13+ 的 OpenAI-compatible HTTP API（gateway 上的
+// `/v1/chat/completions` `/v1/responses` `/health` 等）**默认关闭**。开启
+// 条件（`hermes-agent/gateway/config.py:1472-1480`）：
+//   - env `API_SERVER_ENABLED=true / 1 / yes`，或
+//   - env `API_SERVER_KEY=<非空>`
+//
+// 没开就 :8642 没人监听，bridge preflight 通过（只读取了 base_url 字面值），
+// 但实际发请求秒 Connection refused，用户感知是「pair 成功了但 App 上消息
+// 一直转圈不通」——很难自查到 env 这一行没写。
+//
+// 这个模块在 `agentlink pair -r hermes` 流程里**主动**确保 `.env` 至少有
+//   API_SERVER_ENABLED=true
+//   API_SERVER_HOST=127.0.0.1   (仅当未设)
+//   API_SERVER_PORT=8642        (仅当未设)
+// 三行。用户已有自定义 HOST/PORT 不动；只补缺的。
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const REQUIRED_KEYS = ["API_SERVER_ENABLED", "API_SERVER_HOST", "API_SERVER_PORT"];
+
+const DEFAULTS = {
+  API_SERVER_ENABLED: "true",
+  API_SERVER_HOST: "127.0.0.1",
+  API_SERVER_PORT: "8642",
+};
+
+// 与 hermes-agent 自身判断逻辑等价（gateway/config.py:1472）。
+const TRUTHY = new Set(["true", "1", "yes"]);
+
+function resolveHermesHome() {
+  const fromEnv = String(process.env.HERMES_HOME || "").trim();
+  if (fromEnv) {
+    return fromEnv.startsWith("~")
+      ? path.join(os.homedir(), fromEnv.slice(1))
+      : fromEnv;
+  }
+  return path.join(os.homedir(), ".hermes");
+}
+
+/**
+ * 解析 .env 文件成 { key: value } 字典（保留首次出现的值）。
+ * 不读注释 / 空行 / 没等号的行。
+ */
+function parseEnvFile(content) {
+  const out = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#") || !line.includes("=")) continue;
+    if (line.startsWith("export ")) line = line.slice(7).trim();
+    const eq = line.indexOf("=");
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if (
+      val.length >= 2 &&
+      val[0] === val[val.length - 1] &&
+      (val[0] === '"' || val[0] === "'")
+    ) {
+      val = val.slice(1, -1);
+    }
+    if (!(key in out)) out[key] = val;
+  }
+  return out;
+}
+
+/**
+ * 决定哪些 key 需要 patch：
+ *   - API_SERVER_ENABLED：**强制 true**。pair 流程不允许这条关闭——关了 bridge
+ *     秒 Connection refused，用户感知是消息一直转圈不通。已有非 truthy 值
+ *     （如显式 false / 空 / 注释）都改成 true。已有 API_SERVER_KEY 等价开启，
+ *     但同时显式写 ENABLED=true 不冗余，schema 友好。
+ *   - API_SERVER_HOST / API_SERVER_PORT：缺失才补默认值，**已设不动**（尊重
+ *     用户自定义的端口 / 监听地址）。
+ *
+ * 返回 { toAppend, toOverride } —— toAppend 是缺失要追加的 key 列表，
+ * toOverride 是已存在但值不对要重写的 key 列表（仅 API_SERVER_ENABLED）。
+ */
+function decideEnvPatch(envMap) {
+  const toAppend = [];
+  const toOverride = [];
+  const enabledVal = String(envMap.API_SERVER_ENABLED ?? "").toLowerCase();
+  const enabledOk = TRUTHY.has(enabledVal);
+  if (!("API_SERVER_ENABLED" in envMap)) {
+    toAppend.push("API_SERVER_ENABLED");
+  } else if (!enabledOk) {
+    toOverride.push("API_SERVER_ENABLED");
+  }
+  for (const k of ["API_SERVER_HOST", "API_SERVER_PORT"]) {
+    if (!(k in envMap)) toAppend.push(k);
+    // 已设的 host/port 不动，尊重用户自定义（preflight 会自动读取最新值）
+  }
+  return { toAppend, toOverride };
+}
+
+/**
+ * 用 line-by-line 改写把 toOverride 中的 key 替换成默认值。保留原文件
+ * 的注释/空行/格式；只动单行。
+ */
+function rewriteEnvOverrides(content, toOverride) {
+  if (toOverride.length === 0) return { content, replaced: [] };
+  const overrideSet = new Set(toOverride);
+  const replaced = [];
+  const lines = content.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const trimmed = raw.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    let bare = trimmed;
+    if (bare.startsWith("export ")) bare = bare.slice(7).trim();
+    const eq = bare.indexOf("=");
+    if (eq < 0) continue;
+    const key = bare.slice(0, eq).trim();
+    if (!overrideSet.has(key)) continue;
+    // 替换整行；不保留 export / 引号 —— 简单一致
+    lines[i] = `${key}=${DEFAULTS[key]}`;
+    replaced.push(key);
+    overrideSet.delete(key);
+  }
+  return { content: lines.join("\n"), replaced };
+}
+
+/**
+ * 主入口。
+ * @param {{ log?: any }} [opts]
+ * @returns {{
+ *   status: "ok" | "patched" | "no_home" | "io_error",
+ *   envPath: string,
+ *   appended: string[],   // 缺失被追加的 key
+ *   overridden: string[], // 已存在但值不对被覆盖的 key (仅 API_SERVER_ENABLED)
+ *   kept: { key: string, value: string }[], // 保留用户已设的 key/value（HOST/PORT）
+ *   error?: string,
+ *   warning?: string,
+ * }}
+ */
+export function ensureHermesApiServer({ log, home: homeOverride } = {}) {
+  const eLog = log?.child ? log.child({ comp: "hermes.env" }) : log;
+  const home = homeOverride || resolveHermesHome();
+  if (!fs.existsSync(home)) {
+    eLog?.warn?.("hermes.env.no_home", "~/.hermes 不存在 — hermes-agent 没装?", { home });
+    return {
+      status: "no_home", envPath: path.join(home, ".env"),
+      appended: [], overridden: [], kept: [],
+      warning: `${home} 不存在，hermes-agent 可能没装。装好之后这条 pair 再跑一次即可。`,
+    };
+  }
+  const envPath = path.join(home, ".env");
+
+  let content = "";
+  if (fs.existsSync(envPath)) {
+    try { content = fs.readFileSync(envPath, "utf8"); }
+    catch (err) {
+      eLog?.error?.("hermes.env.read_failed", "读 ~/.hermes/.env 失败", {
+        err: err?.message || String(err),
+      });
+      return {
+        status: "io_error", envPath, appended: [], overridden: [], kept: [],
+        error: `读 ${envPath} 失败：${err?.message || err}`,
+      };
+    }
+  }
+
+  const envMap = parseEnvFile(content);
+  const { toAppend, toOverride } = decideEnvPatch(envMap);
+  // 用户已设的 HOST/PORT 列出来，给调用方打印"沿用现有"提示。
+  const kept = [];
+  for (const k of ["API_SERVER_HOST", "API_SERVER_PORT"]) {
+    if (k in envMap && !toAppend.includes(k) && !toOverride.includes(k)) {
+      kept.push({ key: k, value: envMap[k] });
+    }
+  }
+
+  if (toAppend.length === 0 && toOverride.length === 0) {
+    return {
+      status: "ok", envPath, appended: [], overridden: [], kept,
+    };
+  }
+
+  // 1. 先 in-place 替换 API_SERVER_ENABLED=false → true（如果需要）
+  let newContent = content;
+  let replaced = [];
+  if (toOverride.length > 0) {
+    const r = rewriteEnvOverrides(content, toOverride);
+    newContent = r.content;
+    replaced = r.replaced;
+  }
+
+  // 2. 追加 toAppend 缺失的 key
+  if (toAppend.length > 0) {
+    const tail = [];
+    if (newContent.length > 0 && !newContent.endsWith("\n")) tail.push("");
+    tail.push("");
+    tail.push(
+      "# Added by `agentlink pair -r hermes` — hermes-agent OpenAI-compatible HTTP API",
+    );
+    tail.push(
+      "# API_SERVER_ENABLED 默认关闭 (gateway/config.py:1472)；不开 :8642 上没监听",
+    );
+    tail.push(
+      "# → bridge 连不上 → App 消息不通。pair 流程强制写齐。",
+    );
+    for (const k of toAppend) {
+      tail.push(`${k}=${DEFAULTS[k]}`);
+    }
+    tail.push("");
+    newContent += tail.join("\n");
+  }
+
+  try {
+    fs.writeFileSync(envPath, newContent, "utf8");
+  } catch (err) {
+    eLog?.error?.("hermes.env.write_failed", "写 ~/.hermes/.env 失败", {
+      err: err?.message || String(err),
+    });
+    return {
+      status: "io_error", envPath, appended: [], overridden: [], kept,
+      error: `写 ${envPath} 失败：${err?.message || err}`,
+    };
+  }
+  eLog?.info?.("hermes.env.patched", "补齐 / 强制开启 hermes API_SERVER_* env", {
+    env_path: envPath, appended: toAppend, overridden: replaced, kept,
+  });
+  return {
+    status: "patched", envPath,
+    appended: toAppend, overridden: replaced, kept,
+  };
+}