@xyagent/cli 0.0.1

package/src-ext/core/mcpRuntimeFanout.mjs

@@ -0,0 +1,236 @@
+// mcpRuntimeFanout.mjs — 把 `agentlink` MCP server 注册到各 runtime 的 MCP
+// 配置里的统一入口。
+//
+// 设计要点(见 spec cli-tools-mcp-fanout/spec.md 和 design.md D9–D14):
+//   1. idempotent: 同样输入跑 N 次产物一致
+//   2. non-destructive: 用户其它 MCP server entry 一字不动
+//   3. versioned: 写入的 args 含 `--agentlink-version <X>`,升级时识别旧条目
+//      自动替换
+//   4. traceable: 写入前的 config 内容备份到 ~/.agentlink/fanout-history/
+//      <runtime>-<ISO>.<ext>,保留最近 10 份
+//   5. 4 个 runtime 走 4 条不同适配:
+//      - claude: JSON (stdlib)
+//      - codex: TOML (vendored smol-toml)
+//      - hermes: YAML (vendored yaml)
+//      - openclaw: 走 plugin 路径(本模块仅 stub 返回 "plugin_managed",真正
+//                  的 tool injection 在 openclaw-plugin/index.cjs)
+//
+// 入口:
+//   await register("claude", { projectCwd })   → { ok, mode?, reason? }
+//   await deregister("claude", { projectCwd }) → { ok, reason? }
+//   await status()                              → 4-runtime 状态汇总,给 `agentlink mcp list` 用
+//
+// 每个 adapter 必须实现 register / deregister / read,签名一致。
+
+import path from "node:path";
+import fs from "node:fs/promises";
+import { getAgentlinkDir } from "./attachAuditLog.mjs";
+import { getDiscoveryPath } from "./toolsServerLifecycle.mjs";
+
+import * as claudeAdapter from "../runtime/claude/mcpConfigAdapter.mjs";
+import * as codexAdapter from "../runtime/codex/mcpConfigAdapter.mjs";
+import * as hermesAdapter from "../runtime/hermes/mcpConfigAdapter.mjs";
+import * as openclawAdapter from "../runtime/openclaw/mcpConfigAdapter.mjs";
+
+const ADAPTERS = {
+  claude: claudeAdapter,
+  codex: codexAdapter,
+  hermes: hermesAdapter,
+  openclaw: openclawAdapter,
+};
+
+const HISTORY_DIR = () => path.join(getAgentlinkDir(), "fanout-history");
+const HISTORY_KEEP = 10;
+
+/**
+ * 拼出所有 adapter 共用的 args 数组(写到 MCP server entry 里)。
+ *
+ * @param {object} opts
+ * @param {string} opts.binPath        agentlink-mcp-stdio 的绝对路径
+ * @param {string} opts.discoveryPath  ~/.agentlink/tools-server.json 路径
+ * @param {string} opts.version        npm_cli 包版本(用于 fanout 版本漂移检测)
+ * @returns {string[]}
+ */
+export function buildArgs({ binPath, discoveryPath, version }) {
+  return [
+    binPath,
+    "--discovery", discoveryPath,
+    "--agentlink-version", String(version || "unknown"),
+  ];
+}
+
+/**
+ * 给某个 runtime 注册 agentlink MCP server。idempotent + 可逆。
+ *
+ * @param {"claude"|"codex"|"hermes"|"openclaw"} runtime
+ * @param {object} [opts]
+ * @param {string} [opts.projectCwd]   Claude 适用,选用项目级配置写哪里
+ * @param {string} [opts.binPath]      agentlink-mcp-stdio 绝对路径,默认从 process.argv 推断
+ * @param {string} [opts.version]      npm_cli 版本
+ * @param {object} [opts.log]
+ * @returns {Promise<{ ok: boolean, reason?: string, mode?: string, changed?: boolean }>}
+ */
+export async function register(runtime, opts = {}) {
+  const adapter = ADAPTERS[runtime];
+  if (!adapter) {
+    return { ok: false, reason: "unknown_runtime" };
+  }
+  const log = opts.log || console;
+  const binPath = opts.binPath || defaultBinPath();
+  const discoveryPath = getDiscoveryPath();
+  const version = opts.version || "unknown";
+  const args = buildArgs({ binPath, discoveryPath, version });
+
+  // openclaw adapter 是 plugin-managed, no-op stub.
+  if (runtime === "openclaw") {
+    return await adapter.register({ args, log });
+  }
+
+  // 1) 读现有配置(可能 ENOENT,adapter 自己 handle)
+  let beforeRaw;
+  try {
+    beforeRaw = await adapter.read({ projectCwd: opts.projectCwd });
+  } catch (err) {
+    // not_installed (来自 hermes adapter 显式标记) → 视为致命,该 runtime 没装
+    if (err?.kind === "not_installed") {
+      return { ok: false, reason: err.reason || "not_installed" };
+    }
+    // ENOENT 仅代表"配置文件不存在",对 claude/codex 是合法初次注册场景,
+    // 不阻塞 register —— 留给 adapter 的 register() 自己 create。
+    if (err?.code !== "ENOENT") {
+      log.warn?.("mcp.fanout.read_failed", `read existing config failed: ${err?.message}`);
+    }
+  }
+
+  // 2) 备份(只在内容非空时备份,避免无意义 0 字节)
+  if (beforeRaw && typeof beforeRaw === "string" && beforeRaw.length > 0) {
+    try {
+      await backupConfig(runtime, beforeRaw, adapter.fileExtension);
+    } catch (err) {
+      log.warn?.("mcp.fanout.backup_failed",
+        `backup before write failed (non-fatal): ${err?.message}`);
+    }
+  }
+
+  // 3) 让 adapter 处理 idempotent merge + write
+  try {
+    const result = await adapter.register({
+      projectCwd: opts.projectCwd,
+      args,
+      log,
+    });
+    log.info?.("mcp.fanout.register",
+      `registered agentlink MCP server in ${runtime}`, { runtime, ...result });
+    return { ok: true, ...result };
+  } catch (err) {
+    log.error?.("mcp.fanout.register_failed",
+      `register ${runtime} failed: ${err?.message}`);
+    return { ok: false, reason: "write_failed", error: err?.message };
+  }
+}
+
+/**
+ * 给某个 runtime 取消注册 agentlink MCP server。
+ *
+ * @param {"claude"|"codex"|"hermes"|"openclaw"} runtime
+ * @param {object} [opts]
+ */
+export async function deregister(runtime, opts = {}) {
+  const adapter = ADAPTERS[runtime];
+  if (!adapter) {
+    return { ok: false, reason: "unknown_runtime" };
+  }
+  const log = opts.log || console;
+
+  if (runtime === "openclaw") {
+    return await adapter.deregister({ log });
+  }
+
+  let beforeRaw;
+  try {
+    beforeRaw = await adapter.read({ projectCwd: opts.projectCwd });
+  } catch (err) {
+    if (err?.code === "ENOENT" || err?.kind === "not_installed") {
+      // 配置不存在 → 自然「未注册」状态,no-op success
+      return { ok: true, mode: "noop_no_config" };
+    }
+  }
+
+  if (beforeRaw && typeof beforeRaw === "string" && beforeRaw.length > 0) {
+    try {
+      await backupConfig(runtime, beforeRaw, adapter.fileExtension);
+    } catch { /* swallow */ }
+  }
+
+  try {
+    const result = await adapter.deregister({
+      projectCwd: opts.projectCwd,
+      log,
+    });
+    log.info?.("mcp.fanout.deregister",
+      `deregistered agentlink MCP server from ${runtime}`, { runtime, ...result });
+    return { ok: true, ...result };
+  } catch (err) {
+    return { ok: false, reason: "write_failed", error: err?.message };
+  }
+}
+
+/**
+ * 汇总 4 个 runtime 的当前状态(给 `agentlink mcp list` 用)。
+ *
+ * @returns {Promise<Array<{ runtime, installed, registered, version?, error? }>>}
+ */
+export async function status(opts = {}) {
+  const out = [];
+  for (const runtime of Object.keys(ADAPTERS)) {
+    const adapter = ADAPTERS[runtime];
+    try {
+      const s = await adapter.status({ projectCwd: opts.projectCwd });
+      out.push({ runtime, ...s });
+    } catch (err) {
+      out.push({ runtime, installed: false, registered: false, error: err?.message });
+    }
+  }
+  return out;
+}
+
+/**
+ * 调试用:列出所有 4 个 adapter 模块。
+ */
+export function listAdapters() {
+  return Object.keys(ADAPTERS);
+}
+
+/**
+ * 推断 agentlink-mcp-stdio 二进制位置。如果不在 process.argv[1] 同目录,
+ * 退到 node_modules/.bin/agentlink-mcp-stdio。fanout 写入前用绝对路径,
+ * 否则 MCP 客户端 spawn 时找不到。
+ */
+function defaultBinPath() {
+  const argv1 = process.argv[1] || "";
+  const argv1Dir = path.dirname(argv1);
+  // npm_cli/bin/agentlink-mcp-stdio 跟 agentlink-agent / agentlink 同目录
+  const candidate = path.join(argv1Dir, "agentlink-mcp-stdio");
+  return candidate;
+}
+
+/**
+ * 写备份。文件名 <runtime>-<ISO8601>.<ext>;ext 从 adapter 拿(json/toml/yaml)。
+ * 保留最近 10 份,旧的删。
+ */
+async function backupConfig(runtime, content, ext) {
+  const dir = HISTORY_DIR();
+  await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const dst = path.join(dir, `${runtime}-${stamp}.${ext || "txt"}`);
+  await fs.writeFile(dst, content, { mode: 0o600 });
+  // 删旧
+  const entries = await fs.readdir(dir);
+  const mine = entries
+    .filter((n) => n.startsWith(`${runtime}-`) && n.endsWith(`.${ext || "txt"}`))
+    .sort()
+    .reverse();
+  for (const old of mine.slice(HISTORY_KEEP)) {
+    try { await fs.unlink(path.join(dir, old)); } catch { /* swallow */ }
+  }
+}

package/src-ext/core/mcpStdioClient.mjs

@@ -0,0 +1,316 @@
+// 极简 MCP over stdio 客户端。
+//
+// 为什么手写：
+//   - 只用到 initialize / tools/call / notifications 三类报文
+//   - @modelcontextprotocol/sdk 对我们来说是黑盒，多一层版本风险
+//   - 手写 + 类型松校验 = 未来 codex 升级协议时只需改这里
+//
+// 设计：
+//   - 给定 command + args 启动子进程
+//   - 所有出站报文 → `{ "jsonrpc":"2.0", ... }\n`
+//   - 入站按 `\n` 分片 → JSON.parse → 路由到请求回调 / 通知监听器
+//   - call(method, params, { timeoutMs }) → Promise，超时 reject
+//   - onNotification(method, cb)
+//   - onRequest(method, cb)  —— 用于服务端反向调用（P5 elicitation 用）
+
+import { spawn } from "node:child_process";
+
+const DEFAULT_CALL_TIMEOUT_MS = 600_000; // codex 工具调用可能长达数分钟
+
+export function createMcpStdioClient({
+  command,
+  args = [],
+  env,
+  cwd,
+  log,
+  clientInfo = { name: "agentlink-agent", version: "p4" },
+  signal,
+}) {
+  if (!command) throw new Error("mcp: command required");
+  if (!log) throw new Error("mcp: log required");
+
+  const cLog = log.child({ comp: "mcp" });
+
+  const mergedEnv = { ...process.env, ...(env || {}) };
+  const proc = spawn(command, args, {
+    env: mergedEnv,
+    cwd,
+    stdio: ["pipe", "pipe", "pipe"],
+    windowsHide: true,
+    shell: process.platform === "win32",
+  });
+
+  cLog.info("mcp.spawn", "mcp server spawned", {
+    command, args: args.join(" "), pid: proc.pid,
+  });
+
+  // 外部 signal → kill child
+  if (signal) {
+    if (signal.aborted) safeKill(proc, cLog, "aborted-before-spawn");
+    else signal.addEventListener("abort", () => safeKill(proc, cLog, "signal-abort"), { once: true });
+  }
+
+  const stderrRing = createRing(4096);
+  proc.stderr.on("data", (buf) => stderrRing.push(buf.toString("utf8")));
+
+  let exitHandler = null;
+  proc.once("exit", (code, sig) => {
+    cLog.info("mcp.exit", "mcp server exited", {
+      code, signal: sig, stderr_tail: stderrRing.tail(1000),
+    });
+    if (exitHandler) exitHandler({ code, signal: sig });
+  });
+  proc.once("error", (err) => {
+    cLog.error("mcp.error", "mcp server emit error", { err: err?.message || String(err) });
+  });
+
+  let idCounter = 0;
+  const pending = new Map(); // id → { resolve, reject, method, timer }
+  const notifHandlers = new Map(); // method → [cb]
+  const reqHandlers = new Map();   // method → cb (returns result or Promise)
+
+  let initialized = false;
+
+  // ---- stdin (outgoing) ----
+  function sendRaw(obj) {
+    const line = JSON.stringify(obj) + "\n";
+    return new Promise((resolve, reject) => {
+      if (proc.stdin.destroyed) return reject(new Error("stdin destroyed"));
+      proc.stdin.write(line, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  // ---- stdout (incoming) ----
+  const decoder = new TextDecoder("utf-8");
+  let buf = "";
+  proc.stdout.on("data", (chunk) => {
+    buf += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    if (buf.length > 8 << 20) {
+      cLog.warn("mcp.stdout.overflow", "buffer exceeded 8MB; truncating", { size: buf.length });
+      buf = buf.slice(-(4 << 20));
+    }
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx);
+      buf = buf.slice(idx + 1);
+      handleLine(line);
+    }
+  });
+
+  function handleLine(rawLine) {
+    const line = rawLine.replace(/\r$/, "").trim();
+    if (!line) return;
+    let msg;
+    try { msg = JSON.parse(line); }
+    catch (err) {
+      cLog.warn("mcp.stdout.parse.failed", "non-json line", {
+        err: err?.message, sample: line.slice(0, 200),
+      });
+      return;
+    }
+    if (!msg || typeof msg !== "object") return;
+
+    // Response（有 id + result/error）
+    if (Object.prototype.hasOwnProperty.call(msg, "id") && (msg.result !== undefined || msg.error !== undefined)) {
+      const entry = pending.get(msg.id);
+      if (!entry) {
+        cLog.warn("mcp.response.orphan", "no pending request for id", { id: msg.id });
+        return;
+      }
+      pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.error) {
+        const err = new Error(`mcp call ${entry.method} failed: ${msg.error.message || "unknown"}`);
+        err.code = msg.error.code;
+        err.data = msg.error.data;
+        entry.reject(err);
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    // Request from server (has id + method) —— P5 会用（elicitation）
+    if (msg.method && Object.prototype.hasOwnProperty.call(msg, "id")) {
+      const handler = reqHandlers.get(msg.method);
+      const id = msg.id;
+      if (!handler) {
+        cLog.warn("mcp.request.unhandled", "no handler for server request", { method: msg.method });
+        void sendRaw({ jsonrpc: "2.0", id, error: { code: -32601, message: "method not supported" } });
+        return;
+      }
+      Promise.resolve().then(() => handler(msg.params)).then(
+        (result) => sendRaw({ jsonrpc: "2.0", id, result: result ?? {} }),
+        (err) => sendRaw({
+          jsonrpc: "2.0", id,
+          error: { code: -32603, message: err?.message || String(err) },
+        }),
+      );
+      return;
+    }
+    // Notification（有 method 无 id）
+    if (msg.method && !Object.prototype.hasOwnProperty.call(msg, "id")) {
+      const cbs = notifHandlers.get(msg.method);
+      if (!cbs || cbs.length === 0) {
+        cLog.debug("mcp.notif.unhandled", "no handler for notification", { method: msg.method });
+        return;
+      }
+      for (const cb of cbs) {
+        try { cb(msg.params); }
+        catch (err) {
+          cLog.error("error.caught", "notification handler threw", {
+            where: "mcpStdioClient.notif", method: msg.method,
+            err: err?.message || String(err),
+          });
+        }
+      }
+      return;
+    }
+    cLog.warn("mcp.stdout.unknown_shape", "message dropped", { sample: line.slice(0, 200) });
+  }
+
+  // ---- public API ----
+
+  /**
+   * callWithId(method, params, opts) → { promise, requestId }
+   *
+   * 与 call() 行为完全相同，但同时返回本次分配的 JSON-RPC requestId，
+   * 供调用方后续 cancel(requestId) 取消 in-flight 请求。
+   * call() 改为 callWithId().promise，保持向后兼容。
+   */
+  function callWithId(method, params, { timeoutMs } = {}) {
+    const id = ++idCounter;
+    const promise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (pending.delete(id)) {
+          reject(new Error(`mcp call ${method} timed out after ${timeoutMs || DEFAULT_CALL_TIMEOUT_MS}ms`));
+        }
+      }, timeoutMs || DEFAULT_CALL_TIMEOUT_MS);
+      pending.set(id, { resolve, reject, method, timer });
+      cLog.debug("mcp.call", "outgoing request", { id, method });
+      sendRaw({ jsonrpc: "2.0", id, method, params: params ?? {} }).catch((err) => {
+        if (pending.delete(id)) {
+          clearTimeout(timer);
+          reject(err);
+        }
+      });
+    });
+    return { promise, requestId: id };
+  }
+
+  function call(method, params, opts) {
+    return callWithId(method, params, opts).promise;
+  }
+
+  /**
+   * cancel(requestId) — 取消 in-flight 请求。
+   *
+   * 1. 向 server 发 notifications/cancelled { requestId }（MCP 协议取消通知）。
+   * 2. 主动清理该 requestId 的 pending entry（clearTimeout + reject + delete），
+   *    避免 codex 不回复时 orphaned 响应挂到 600s 超时。
+   *    清除后若 server 仍发回 response，会走 mcp.response.orphan warn 路径，不触发 reject。
+   *
+   * 对不存在的 requestId 调用是 no-op（不抛异常）。
+   */
+  async function cancel(requestId) {
+    // 主动清理 pending entry（先清后发 notify，避免 notify 回传 response 时 pending 还在）
+    const entry = pending.get(requestId);
+    if (entry) {
+      pending.delete(requestId);
+      clearTimeout(entry.timer);
+      entry.reject(new Error(`mcp call ${entry.method} cancelled (requestId=${requestId})`));
+      cLog.debug("mcp.cancel", "pending entry cleared", { requestId, method: entry.method });
+    }
+    // 发 MCP notifications/cancelled 通知 server 停止处理
+    await notify("notifications/cancelled", { requestId });
+  }
+
+  function notify(method, params) {
+    return sendRaw({ jsonrpc: "2.0", method, params: params ?? {} });
+  }
+
+  function onNotification(method, cb) {
+    const arr = notifHandlers.get(method) || [];
+    arr.push(cb);
+    notifHandlers.set(method, arr);
+    return () => {
+      const a = notifHandlers.get(method) || [];
+      const i = a.indexOf(cb);
+      if (i >= 0) a.splice(i, 1);
+    };
+  }
+
+  function onRequest(method, cb) {
+    reqHandlers.set(method, cb);
+    return () => reqHandlers.delete(method);
+  }
+
+  async function initialize({ capabilities = {}, protocolVersion = "2024-11-05" } = {}) {
+    if (initialized) return;
+    const result = await call("initialize", {
+      protocolVersion,
+      capabilities,
+      clientInfo,
+    }, { timeoutMs: 30_000 });
+    await notify("notifications/initialized", {});
+    initialized = true;
+    cLog.info("mcp.initialized", "handshake complete", {
+      server: result?.serverInfo, version: result?.protocolVersion,
+    });
+    return result;
+  }
+
+  function setExitHandler(cb) {
+    exitHandler = cb;
+  }
+
+  async function close(reason = "manual") {
+    cLog.info("mcp.close", "closing mcp client", { reason });
+    safeKill(proc, cLog, reason);
+    // 让所有 pending 失败
+    for (const [id, entry] of pending.entries()) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(`mcp closing: ${reason}`));
+      pending.delete(id);
+    }
+  }
+
+  return {
+    proc,
+    call,
+    callWithId,
+    cancel,
+    notify,
+    onNotification,
+    onRequest,
+    initialize,
+    setExitHandler,
+    close,
+    get pendingCount() { return pending.size; },
+    getStderrTail: (n = 1000) => stderrRing.tail(n),
+  };
+}
+
+function safeKill(child, log, reason) {
+  if (!child || child.killed) return;
+  try {
+    log.info("mcp.kill.term", "sending SIGTERM", { reason });
+    child.kill("SIGTERM");
+  } catch (err) {
+    log.warn("mcp.kill.term.failed", "SIGTERM failed", { err: err?.message });
+  }
+  const deadline = setTimeout(() => {
+    if (child.exitCode === null && !child.killed) {
+      log.warn("mcp.kill.force", "SIGKILL after timeout", { reason });
+      try { child.kill("SIGKILL"); } catch {}
+    }
+  }, 2000);
+  deadline.unref?.();
+}
+
+function createRing(capacity) {
+  let buf = "";
+  return {
+    push(s) { buf += s; if (buf.length > capacity) buf = buf.slice(-capacity); },
+    tail(n) { return buf.slice(-n); },
+  };
+}