@xyagent/cli 0.0.1

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

@@ -0,0 +1,219 @@
+// Hermes HTTP backend.
+//
+// OpenAI-compatible streaming SSE 协议。任何兼容 /v1/chat/completions（含
+// `stream: true`）的服务都能跑：OpenAI、Azure OpenAI、DeepSeek、自建 vLLM、
+// LiteLLM、Cloudflare Workers AI 兼容层、本地 ollama 兼容层。
+//
+// 只用 stdlib（global fetch + ReadableStream）。Node 18+ 自带。
+
+/**
+ * @typedef {Object} ChatMessage
+ * @property {"system"|"user"|"assistant"|"tool"} role
+ * @property {string} content
+ */
+
+/**
+ * @typedef {Object} BackendOptions
+ * @property {string} apiBaseUrl     base URL ending without /chat/completions
+ * @property {string} [apiKey]       Bearer token; some servers don't need one
+ * @property {string} model          model name passed verbatim
+ * @property {AbortSignal} [signal]
+ */
+
+/**
+ * @typedef {Object} StreamChunk
+ * @property {"delta"|"done"|"usage"|"error"} kind
+ * @property {string} [text]         delta only
+ * @property {string} [fullText]     done only — accumulated final text
+ * @property {Object} [usage]        usage only — {prompt_tokens, completion_tokens, total_tokens}
+ * @property {string} [error]        error only — message
+ */
+
+/**
+ * Stream a chat completion. Yields {kind, ...} chunks as the response arrives.
+ *
+ * @param {ChatMessage[]} messages
+ * @param {BackendOptions} opts
+ * @returns {AsyncGenerator<StreamChunk, void, void>}
+ */
+export async function* streamChat(messages, opts) {
+  const url = `${opts.apiBaseUrl.replace(/\/+$/, "")}/chat/completions`;
+  const headers = {
+    "Content-Type": "application/json",
+    "Accept": "text/event-stream",
+  };
+  if (opts.apiKey) headers["Authorization"] = `Bearer ${opts.apiKey}`;
+
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        model: opts.model,
+        messages,
+        stream: true,
+      }),
+      signal: opts.signal,
+    });
+  } catch (err) {
+    yield { kind: "error", error: `fetch failed: ${err?.message || String(err)}` };
+    return;
+  }
+  if (!res.ok) {
+    const body = await safeReadText(res);
+    yield {
+      kind: "error",
+      error: `http ${res.status}: ${body.slice(0, 400)}`,
+    };
+    return;
+  }
+  if (!res.body) {
+    yield { kind: "error", error: "empty response body" };
+    return;
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let pending = "";
+  let accum = "";
+  let usage = null;
+
+  try {
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      pending += decoder.decode(value, { stream: true });
+
+      // Process complete events delimited by blank line ("\n\n").
+      let dblIdx;
+      while ((dblIdx = pending.indexOf("\n\n")) !== -1) {
+        const frame = pending.slice(0, dblIdx);
+        pending = pending.slice(dblIdx + 2);
+
+        // SSE per-frame state:
+        //   - frameEvent : value of "event:" header (defaults to "message")
+        //   - frameData  : concatenation of all "data:" lines in the frame
+        // hermes-agent api_server 在子 agent / 工具触发时会单独发一帧
+        //   event: hermes.tool.progress
+        //   data:  {"tool":"<name>","emoji":"...","label":"..."}
+        // 这帧不带 OpenAI chat.completion.chunk 结构，必须按 frameEvent 分流。
+        let frameEvent = "";
+        const frameDataLines = [];
+        for (const rawLine of frame.split("\n")) {
+          const line = rawLine.replace(/\r$/, "");
+          if (line.startsWith(":")) continue; // comment / heartbeat
+          if (line.startsWith("event:")) {
+            frameEvent = line.slice(6).trim();
+            continue;
+          }
+          if (line.startsWith("data:")) {
+            frameDataLines.push(line.slice(5).trim());
+          }
+        }
+        const payload = frameDataLines.join("\n");
+        if (!payload) continue;
+
+        // Hermes 自定义事件：tool / subagent 进度通知。整帧 yield 一条
+        // hermes_tool_progress chunk，handleRequest 负责映射到 unified protocol。
+        if (frameEvent === "hermes.tool.progress") {
+          try {
+            const parsed = JSON.parse(payload);
+            yield {
+              kind: "hermes_tool_progress",
+              tool: String(parsed?.tool || ""),
+              label: String(parsed?.label || ""),
+              emoji: String(parsed?.emoji || ""),
+            };
+          } catch {
+            // 解析失败静默忽略 — 不阻塞正文流
+          }
+          continue;
+        }
+
+        // OpenAI chat.completion.chunk 路径：兼容多 data 行合并 (SSE spec) +
+        // [DONE] sentinel。
+        if (payload === "[DONE]") {
+          // Server signals end — flush + return.
+          yield { kind: "done", fullText: accum };
+          if (usage) yield { kind: "usage", usage };
+          return;
+        }
+        // 简化：旧实现把每行 data: 单独尝试 parse；新实现先合并整帧再 parse。
+        // OpenAI 流通常每帧只有一条 data 行，行为等价；多行合并是 SSE spec 兼容。
+        const parsed = (() => {
+          try { return JSON.parse(payload); } catch { return null; }
+        })();
+        if (parsed) {
+          // OpenAI streaming shape: choices[].delta.content + optional usage on
+          // last chunk (with stream_options.include_usage=true).
+          //
+          // Reasoning models (deepseek-r1, qwen-qwq, some OpenAI-compatible
+          // proxies) additionally emit `delta.reasoning_content` (string) when
+          // the model is in chain-of-thought mode. We yield those as a separate
+          // `kind: "thinking"` chunk so the unified envelope chain can route
+          // them to content_block{type:"thinking"}. Most providers that inline
+          // thinking inside delta.content (e.g. Gemini via OpenAI-compat
+          // gateway) won't trigger this branch — that's expected, since the
+          // upstream has not split reasoning out.
+          const choice = parsed?.choices?.[0];
+          const reasoningDelta = choice?.delta?.reasoning_content;
+          if (typeof reasoningDelta === "string" && reasoningDelta.length > 0) {
+            yield { kind: "thinking", text: reasoningDelta };
+          }
+          // OpenAI tool-calling streaming shape:
+          //   delta.tool_calls = [{ index, id?, function: { name?, arguments? } }]
+          // arguments arrives incrementally as a JSON string; id/name typically
+          // only on the first chunk for each call.
+          const toolCalls = choice?.delta?.tool_calls;
+          if (Array.isArray(toolCalls)) {
+            for (const tc of toolCalls) {
+              if (!tc || typeof tc !== "object") continue;
+              const callId = String(tc.id || "");
+              const name = String(tc.function?.name || "");
+              const args = String(tc.function?.arguments || "");
+              if (callId && name) {
+                yield { kind: "tool_use_start", call_id: callId, name };
+              }
+              if (args.length > 0 && callId) {
+                yield { kind: "tool_use_args_delta", call_id: callId, arguments: args };
+              }
+            }
+          }
+          const delta = choice?.delta?.content;
+          if (typeof delta === "string" && delta.length > 0) {
+            accum += delta;
+            yield { kind: "delta", text: delta };
+          }
+          if (parsed?.usage) {
+            usage = parsed.usage;
+          }
+          // Stop when finish_reason is present.
+          if (choice?.finish_reason) {
+            // OpenAI signals tool-call turn end via finish_reason === "tool_calls".
+            // We don't synthesize tool_use.completed here — the dispatch handler
+            // does that based on argument accumulation. Just signal done.
+            yield { kind: "done", fullText: accum };
+            if (usage) yield { kind: "usage", usage };
+            return;
+          }
+        }
+      }
+    }
+    // Stream closed without [DONE] — best-effort flush.
+    if (accum) yield { kind: "done", fullText: accum };
+    if (usage) yield { kind: "usage", usage };
+  } catch (err) {
+    yield { kind: "error", error: `stream read failed: ${err?.message || String(err)}` };
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+async function safeReadText(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}

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

@@ -0,0 +1,196 @@
+// Hermes 桥接入口 — long-poll worker 模式。
+//
+// 与旧 SSE 订阅模式的本质差异:
+//   - 不再 subscribe relay 流;改用 GET /v1/gateways/<gw>/requests/next 长轮询拉用户消息
+//   - 拉到 request 后串行调本地 LLM(http 或 command 后端)
+//   - 流式 native event 通过 POST /v1/gateways/<gw>/requests/<rid>/events 推回
+//   - 心跳走 POST /v1/gateways/<gw>/meta(无 bridge.status envelope)
+//
+// 服务端 hermes/openclaw adapter 期望 OpenAI Responses API 形态的 native event:
+//   { event: "start" }                                  ← turn 开始
+//   { event: "chunk", data: "<openai-style json line>" }← 流式 delta
+//   { event: "end" }                                    ← turn 完成
+//   { event: "error", error: "msg" }                    ← 失败
+//
+// 我们这里把 hermes backend 的 {kind:"delta",text:"..."} 转成 OpenAI Responses API
+// 风格的 chunk:
+//   {"type":"response.output_text.delta","delta":"..."}
+// 然后用 {event:"chunk", data:JSON.stringify(...)} 包一层送上去。
+// 最终 finalize 用 {event:"end"} 发,服务端翻译为 unified run.completed。
+
+import process from "node:process";
+
+import { createSessionSlot, SESSION_STATES } from "../../core/sessionSlot.mjs";
+import { createRelayWorker } from "../../core/relayWorker.mjs";
+import { bootstrapAgentlinkTools } from "../../core/agentlinkToolsBootstrap.mjs";
+import { installAutoTunnel } from "../../core/autoTunnelWiring.mjs";
+import { resolveSession } from "../../core/pairCodeClient.mjs";
+import { createUsageReporter } from "../../core/usageReporter.mjs";
+import { runWorkerWithRevokeHandling } from "../../core/bridgeSelfUninstall.mjs";
+
+import { hermesPreflightWithHeal, resolveProfileHome } from "./preflight.mjs";
+import { manageProfileGateway } from "./gatewayManager.mjs";
+import { createHermesHandleRequest } from "./handleRequest.mjs";
+
+
+export async function runHermesBridge({ options, positional, log }) {
+  // 1. preflight
+  const pre = await hermesPreflightWithHeal({ options, log });
+  if (!pre.ok) {
+    process.stderr.write(`hermes preflight failed: ${pre.error}\n`);
+    if (pre.hint) process.stderr.write(`${pre.hint}\n`);
+    process.exit(65);
+  }
+  log.info("bridge.preflight.pass", "hermes preflight ok", {
+    backend: pre.backend, model: pre.model,
+  });
+
+  // 2. resolve session(consume pair code 或读本地状态)
+  let gwId, relayBase, bridgeToken, profileName;
+  try {
+    const r = await resolveSession({ runtime: "hermes", options, log });
+    gwId = r.gwId;
+    relayBase = r.relayUrl;
+    bridgeToken = r.bridgeToken;
+    // T2.1: 从 pair state 读取 profileName（N2.3 写入的字段）；旧 pair state 无此字段时为空字符串
+    profileName = r.profileName ?? "";
+    log.info("bridge.preflight.pass", "hermes runtime entry reached", {
+      relay: relayBase, gw_id: gwId, source: r.source, has_bridge_token: !!bridgeToken,
+      profile_name: profileName || "(none)",
+    });
+  } catch (err) {
+    process.stderr.write(`${err?.message || err}\n`);
+    process.exit(65);
+  }
+  if (!bridgeToken) {
+    process.stderr.write("缺少 bridge_token,请重新运行 agentlink pair <code> -r hermes\n");
+    process.exit(65);
+  }
+
+  const sessLog = log.child({ gw: gwId });
+
+  // 3.1: 计算默认 profileHome（模型 b：此值作为无 workspace_path 时的 fallback）
+  // T2.1: 用 profileName（来自 pair state）而非 gwId 派生 profileHome；旧 pair state 无此字段则 fallback ~/.hermes
+  const profileHome = resolveProfileHome(profileName);
+  // T2.2: slug 用于 manageProfileGateway key，优先用 profileName；旧 pair state 无 profileName 则 fallback gwId 截断
+  const slug = profileName || String(gwId).toLowerCase().slice(0, 32);
+
+  // 模型 b: 默认 profile gateway 在 bridge 启动时 ensure 一次（保持向后兼容）。
+  // per-conversation 路由（带 workspace_path 的 dispatch）会在 defaultOpenclawInvoke
+  // 里 per-request 调 manageProfileGateway，不依赖此处的 gatewayBaseUrl。
+  let gatewayBaseUrl = null;
+  try {
+    const gwResult = await manageProfileGateway(slug, profileHome, {
+      mode: "ensure", log: sessLog,
+    });
+    if (gwResult.ok) {
+      gatewayBaseUrl = gwResult.baseUrl + "/v1";
+    } else {
+      sessLog.warn("bridge.profile.gateway.ensure.failed",
+        "default profile gateway ensure failed, falling back to preflight apiBaseUrl", {
+          error: gwResult.error, slug, profileHome,
+        });
+    }
+  } catch (err) {
+    sessLog.warn("bridge.profile.gateway.ensure.error",
+      "default profile gateway ensure threw, falling back to preflight apiBaseUrl", {
+        error: err?.message, slug, profileHome,
+      });
+  }
+
+  // 默认 pre：bridge 启动时绑定到默认 profile（无 workspace_path 时使用）
+  const effectivePre = gatewayBaseUrl
+    ? { ...pre, apiBaseUrl: gatewayBaseUrl }
+    : pre;
+
+  sessLog.info("bridge.preflight.pass", "hermes profile resolved", {
+    profileHome, slug, gatewayBaseUrl, effective_api_base: effectivePre.apiBaseUrl,
+    model_b_routing: "per-conversation dispatch will route by workspace_path",
+  });
+
+  const worker = createRelayWorker({
+    relayUrl: relayBase, gwId, bridgeToken, runtime: "hermes", log: sessLog,
+  });
+  installAutoTunnel({ relayUrl: relayBase, log: sessLog });
+
+  // usage reporter — flush 时把 native event 推到"最近一个" in-flight request。
+  // hermes 是单 in-flight 模型(turn 串行),所以维护 lastRequestId 就够了。
+  let lastRequestId = null;
+  const usage = createUsageReporter({
+    runtime: "hermes",
+    log: sessLog,
+    publishEvent: (event) => {
+      if (!lastRequestId) return Promise.resolve(false);
+      return worker.publishEvent(lastRequestId, event);
+    },
+  });
+  usage.setContextWindow(Number(options.contextWindow) || 32_000);
+
+  const slot = createSessionSlot({ log: sessLog, name: "hermes" });
+  slot.transition(SESSION_STATES.READY, "hermes-no-spawn");
+
+  // agentlinkToolsServer + discovery 文件(见 claude/index.mjs 同段注释)
+  let toolsLifecycle = null;
+  try {
+    toolsLifecycle = await bootstrapAgentlinkTools({
+      runtime: "hermes", gwId, relayUrl: relayBase, bridgeToken,
+      worker, log: sessLog, version: pre?.version || "",
+      getLastRequestId: () => lastRequestId,
+    });
+  } catch (err) {
+    sessLog.warn("agentlink_tools.bootstrap.failed",
+      "agentlink tools server failed to start; continuing without tools", { err: err?.message });
+  }
+
+  let shuttingDown = false;
+  async function shutdown(reason) {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    sessLog.info("bridge.shutdown", "shutting down", { reason });
+    worker.stop(reason);
+    try { usage.dispose(); } catch {}
+    if (toolsLifecycle?.stop) {
+      try { await toolsLifecycle.stop(); } catch {}
+    }
+  }
+  process.once("SIGINT", () => { void shutdown("SIGINT").then(() => process.exit(0)); });
+  process.once("SIGTERM", () => { void shutdown("SIGTERM").then(() => process.exit(0)); });
+
+  // ---- handler:每条 in-flight 请求一次完整 turn ----
+  // D-C2.1.3: 替换内联 handleRequest，改为 createHermesHandleRequest 工厂函数
+  // 模型 b: 传入 manageProfileGateway 供 per-conversation dispatch 路由（workspace_path → profile gateway）
+  // profileHome 作为无 workspace_path 时的 fallback 默认值
+  const _handleRequestImpl = createHermesHandleRequest({
+    pre: effectivePre,  // 默认 profile 的 pre（无 workspace_path 时 fallback）
+    log: sessLog,
+    gwId,
+    usage,
+    profileHome,  // 默认 profileHome（fallback，来自 resolveProfileHome(profileName)）
+    dispatchHandlerOptions: {
+      relayUrl: relayBase,
+      bridgeToken,
+    },
+    // workspaceRpc 由 handleRequest 内部用 profileHome 实例化（不再显式传入）
+    scanner: toolsLifecycle?.scanner ?? null,
+    // 模型 b: 注入真实 manageProfileGateway，供 per-conv 路由使用
+    _manageProfileGateway: manageProfileGateway,
+  });
+
+  async function handleRequest(request, ctx) {
+    lastRequestId = ctx.requestId;
+    return _handleRequestImpl(request, ctx);
+  }
+
+  // ---- 启动 worker 主循环 ----
+  // 用 runWorkerWithRevokeHandling 而不是裸 worker.run() —— 让 bridge 在收到
+  // App 端解绑信号（HTTP 404 on /requests/next）时自动 spawn `agentlink
+  // uninstall` 卸 launchd plist + 清本地 pair state，配对双向闭环。
+  sessLog.info("bridge.loop.entered", "hermes worker entering long-poll loop", {
+    gw_id: gwId, backend: pre.backend, model: pre.model,
+  });
+  await runWorkerWithRevokeHandling({
+    worker, handler: handleRequest, runtime: "hermes", log: sessLog,
+  });
+}
+
+// helpers 已移入 handleRequest.mjs

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

@@ -0,0 +1,189 @@
+// mcpConfigAdapter.mjs — Hermes 的 MCP server 配置注入器。
+//
+// hermes-agent 读 ~/.hermes/config.yaml 的 `mcp_servers:` top-level key:
+//
+//   mcp_servers:
+//     agentlink:
+//       command: node
+//       args: [...]
+//
+// 见 ~/.hermes/hermes-agent/tools/mcp_tool.py 第 2121 行: config.get("mcp_servers")
+//
+// 跟 Codex 不同:Hermes YAML 用 vendored `yaml` 包的 `parseDocument`,可以保留
+// 用户的注释与 key 顺序(yaml 2.x 文档级 API)。
+//
+// 操作要求(spec.md Hermes MCP server registration):
+//   - vendored yaml 2.x parseDocument API
+//   - 用户其它 keys / 注释 保留
+//   - 若 ~/.hermes/ 不存在 → hermes 未装 → 返回 { ok: false, reason: "hermes_not_installed" }
+//     而非创建空目录(避免把 ~/.hermes/ 误当成 hermes 装好了)
+
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs/promises";
+
+import { fileURLToPath } from "node:url";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const YAML = await import(
+  path.join(__dirname, "../../../src-shared/vendor/yaml/dist/index.js")
+);
+
+export const fileExtension = "yaml";
+
+const SERVER_NAME = "agentlink";
+
+function hermesHome() {
+  return path.join(os.homedir(), ".hermes");
+}
+
+function configPath() {
+  return path.join(hermesHome(), "config.yaml");
+}
+
+/**
+ * 检查 Hermes 是否安装。判定:`~/.hermes/` 目录存在(hermes-agent 启动会自创)。
+ */
+async function isHermesInstalled() {
+  try {
+    const st = await fs.stat(hermesHome());
+    return st.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export async function read() {
+  if (!(await isHermesInstalled())) {
+    const e = new Error("hermes not installed (~/.hermes/ missing)");
+    e.kind = "not_installed";
+    e.reason = "hermes_not_installed";
+    throw e;
+  }
+  return await fs.readFile(configPath(), "utf8");
+}
+
+export async function register({ args, log } = {}) {
+  if (!(await isHermesInstalled())) {
+    return { ok: false, reason: "hermes_not_installed", mode: "noop_hermes_missing" };
+  }
+  const cfgPath = configPath();
+  const desired = {
+    command: "node",
+    args: args.slice(),
+  };
+
+  let raw = "";
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  let doc;
+  if (raw.trim().length > 0) {
+    try {
+      doc = YAML.parseDocument(raw);
+    } catch (err) {
+      const e = new Error(`hermes config.yaml parse failed: ${err.message}`);
+      e.kind = "parse_failed";
+      throw e;
+    }
+  } else {
+    doc = YAML.parseDocument("mcp_servers:\n");
+  }
+
+  // idempotent check: 取出 current,跟 desired 比对
+  const currentNode = doc.getIn(["mcp_servers", SERVER_NAME], true);
+  const current = currentNode ? currentNode.toJSON() : null;
+  if (yamlEqual(current, desired)) {
+    return { changed: false, configPath: cfgPath, mode: "noop_idempotent" };
+  }
+
+  // 确保 mcp_servers 是个 Map(parseDocument 对 null/missing 都给一个空块)
+  if (!doc.has("mcp_servers") || doc.get("mcp_servers") === null) {
+    doc.set("mcp_servers", { [SERVER_NAME]: desired });
+  } else {
+    doc.setIn(["mcp_servers", SERVER_NAME], desired);
+  }
+
+  await fs.writeFile(cfgPath, doc.toString(), { mode: 0o600 });
+  log?.info?.("mcp.fanout.hermes.write", "wrote agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function deregister({ log } = {}) {
+  const cfgPath = configPath();
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { changed: false, configPath: cfgPath, mode: "noop_no_config" };
+    }
+    throw err;
+  }
+  let doc;
+  try { doc = YAML.parseDocument(raw); }
+  catch { return { changed: false, configPath: cfgPath, mode: "noop_parse_failed" }; }
+
+  if (!doc.hasIn(["mcp_servers", SERVER_NAME])) {
+    return { changed: false, configPath: cfgPath, mode: "noop_not_registered" };
+  }
+  doc.deleteIn(["mcp_servers", SERVER_NAME]);
+  await fs.writeFile(cfgPath, doc.toString(), { mode: 0o600 });
+  log?.info?.("mcp.fanout.hermes.delete", "removed agentlink mcp entry", {
+    configPath: cfgPath,
+  });
+  return { changed: true, configPath: cfgPath };
+}
+
+export async function status() {
+  if (!(await isHermesInstalled())) {
+    return { installed: false, registered: false, reason: "hermes_not_installed" };
+  }
+  const cfgPath = configPath();
+  let raw;
+  try {
+    raw = await fs.readFile(cfgPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return { installed: true, registered: false, configPath: cfgPath, reason: "no_config_file" };
+    }
+    return { installed: true, registered: false, error: err.message };
+  }
+  let doc;
+  try { doc = YAML.parseDocument(raw); }
+  catch { return { installed: true, registered: false, configPath: cfgPath, reason: "parse_failed" }; }
+  const entryNode = doc.getIn(["mcp_servers", SERVER_NAME], true);
+  if (!entryNode) {
+    return { installed: true, registered: false, configPath: cfgPath };
+  }
+  const entry = entryNode.toJSON();
+  return {
+    installed: true,
+    registered: true,
+    configPath: cfgPath,
+    version: extractAgentlinkVersion(entry.args),
+  };
+}
+
+function yamlEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  if (a.command !== b.command) return false;
+  if (!Array.isArray(a.args) || !Array.isArray(b.args)) return false;
+  if (a.args.length !== b.args.length) return false;
+  for (let i = 0; i < a.args.length; i++) {
+    if (a.args[i] !== b.args[i]) return false;
+  }
+  return true;
+}
+
+function extractAgentlinkVersion(args) {
+  if (!Array.isArray(args)) return null;
+  const idx = args.indexOf("--agentlink-version");
+  if (idx >= 0 && idx + 1 < args.length) return args[idx + 1];
+  return null;
+}