@xyagent/cli 0.0.1

package/src-ext/bin.mjs

@@ -0,0 +1,128 @@
+// agentlink-agent 入口。
+//
+// 本文件**禁止** import `../src/**`。只允许 `../src-shared/**` 以及
+// 同目录子模块。违反即破坏"平行世界"原则。
+
+import process from "node:process";
+import { createLogger } from "../src-shared/logger.mjs";
+import { newCid } from "../src-shared/correlation.mjs";
+import { runAgentCommand } from "./commands/agent.mjs";
+import { runServiceCommand } from "./commands/service.mjs";
+import { printHelp } from "./commands/help.mjs";
+
+const PKG_NAME = "agentlink-agent";
+
+// short flag 到长名的映射。只加必要的：-r → runtime。
+const SHORT_FLAGS = Object.freeze({ r: "runtime" });
+
+function parseArgs(argv) {
+  // 支持：
+  //   --key=value / --key value / --bool / -r value
+  // 第一个 non-flag token 是 subcommand，其余 positional。
+  let subcommand = "";
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i];
+    if (raw.startsWith("--")) {
+      const eq = raw.indexOf("=");
+      if (eq > 0) {
+        options[raw.slice(2, eq)] = raw.slice(eq + 1);
+      } else {
+        const key = raw.slice(2);
+        const nxt = argv[i + 1];
+        if (nxt === undefined || nxt.startsWith("-")) {
+          options[key] = true;
+        } else {
+          options[key] = nxt;
+          i += 1;
+        }
+      }
+    } else if (raw.startsWith("-") && raw.length >= 2 && !/^\-\d/.test(raw)) {
+      // single-dash short flag: `-r claude`
+      const short = raw.slice(1);
+      const mapped = SHORT_FLAGS[short] || short;
+      const nxt = argv[i + 1];
+      if (nxt === undefined || nxt.startsWith("-")) {
+        options[mapped] = true;
+      } else {
+        options[mapped] = nxt;
+        i += 1;
+      }
+    } else if (!subcommand) {
+      subcommand = raw;
+    } else {
+      positional.push(raw);
+    }
+  }
+  return { subcommand, positional, options };
+}
+
+async function main() {
+  // 只在启动期用一次 cid，用于冒烟日志；后续每个 session / request 自己生成。
+  const startCid = newCid();
+  const log = createLogger({ comp: "bridge", cid: startCid });
+
+  const { subcommand, positional, options } = parseArgs(process.argv.slice(2));
+
+  if (options.help || subcommand === "help" || subcommand === "") {
+    printHelp();
+    log.info("bridge.exit", "help rendered");
+    return;
+  }
+
+  if (options.version) {
+    // 版本信息走简单 stdout（非 JSON 行）避免脚本侧解析困难；logger 独立记一条。
+    process.stdout.write(`${PKG_NAME} p1-skeleton\n`);
+    log.info("bridge.exit", "version rendered");
+    return;
+  }
+
+  log.info("bridge.start", "agent bin start", {
+    subcommand,
+    node: process.version,
+  });
+
+  process.on("SIGINT", () => {
+    log.info("bridge.signal.recv", "SIGINT", { signal: "SIGINT" });
+  });
+  process.on("SIGTERM", () => {
+    log.info("bridge.signal.recv", "SIGTERM", { signal: "SIGTERM" });
+  });
+
+  switch (subcommand) {
+    case "claude":
+    case "codex":
+    case "hermes":
+    case "picoclaw":
+      await runAgentCommand({ runtime: subcommand, options, positional, log });
+      return;
+    case "service":
+      await runServiceCommand({ options, positional, log });
+      return;
+    case "logs":
+      // P6 实现；P1 先占位
+      log.warn("bridge.not_implemented", "logs subcommand not implemented yet");
+      process.stderr.write("logs subcommand will land in P6\n");
+      process.exit(2);
+    default:
+      log.error("bridge.unknown_subcommand", "unknown subcommand", { subcommand });
+      process.stderr.write(`unknown subcommand: ${subcommand}\n`);
+      process.stderr.write("run 'agentlink-agent --help' for usage\n");
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  // main 保护性 catch：logger 可能还没初始化完整，直接写 stderr + 尝试 log。
+  const msg = err && err.message ? err.message : String(err);
+  try {
+    const log = createLogger({ comp: "bridge" });
+    log.error("bridge.fatal", "unhandled error in main", {
+      err: msg,
+      stack: err && err.stack ? String(err.stack).split("\n").slice(0, 6).join("\n") : undefined,
+    });
+  } catch {}
+  process.stderr.write(`fatal: ${msg}\n`);
+  process.exit(1);
+});

package/src-ext/commands/agent.mjs

@@ -0,0 +1,66 @@
+import { runClaudeBridge } from "../runtime/claude/index.mjs";
+import { runCodexBridge } from "../runtime/codex/index.mjs";
+import { runHermesBridge } from "../runtime/hermes/index.mjs";
+import { runPicoclawBridge } from "../runtime/picoclaw/index.mjs";
+import { runPairInstall, runUninstall } from "./pair.mjs";
+
+/**
+ * `agentlink-agent <runtime> [action] [args]` 分发。
+ *
+ * 子动作：
+ *   pair <code>  —— 消费配对码 + 保存状态 + 自动装 service（后台保活）
+ *   uninstall    —— 卸载 service + 清理本地状态
+ *   （无）       —— 前台 bridge（从本地状态读 session，适合调试）
+ */
+export async function runAgentCommand({ runtime, options, positional, log }) {
+  const rtLog = log.child({ rt: runtime });
+  const action = (positional[0] || "").toLowerCase();
+
+  if (action === "pair") {
+    // picoclaw 不走传统 `pair <code>`,daemon 启动后自动配对(QR 流)。
+    if (runtime === "picoclaw") {
+      process.stderr.write(
+        "picoclaw 不需要 pair 子命令,直接启动 daemon: agentlink-agent picoclaw\n",
+      );
+      process.exit(2);
+    }
+    const code = String(positional[1] || options.pair || "").trim();
+    if (!code) {
+      process.stderr.write(`usage: agentlink pair <code> -r ${runtime}\n`);
+      process.exit(2);
+    }
+    rtLog.info("bridge.preflight.pass", "pair subcommand", { code_len: code.length });
+    await runPairInstall({ runtime, code, options, log: rtLog });
+    return;
+  }
+
+  if (action === "uninstall") {
+    rtLog.info("bridge.preflight.pass", "uninstall subcommand", {});
+    await runUninstall({ runtime, options, log: rtLog });
+    return;
+  }
+
+  rtLog.info("bridge.preflight.pass", "runtime dispatcher entered", {
+    runtime,
+    args_count: positional.length,
+  });
+
+  switch (runtime) {
+    case "claude":
+      await runClaudeBridge({ options, positional, log: rtLog });
+      return;
+    case "codex":
+      await runCodexBridge({ options, positional, log: rtLog });
+      return;
+    case "hermes":
+      await runHermesBridge({ options, positional, log: rtLog });
+      return;
+    case "picoclaw":
+      await runPicoclawBridge({ options, positional, log: rtLog });
+      return;
+    default:
+      rtLog.error("bridge.unknown_runtime", "unsupported runtime", { runtime });
+      process.stderr.write(`unsupported runtime: ${runtime}\n`);
+      process.exit(2);
+  }
+}

package/src-ext/commands/help.mjs

@@ -0,0 +1,31 @@
+// 纯 stdout 帮助文本。不走 logger —— 这是给人看的，不是日志。
+
+export function printHelp() {
+  const lines = [
+    "agentlink-agent —— 连接手机 App 与本地 Claude Code / Codex 的中继桥",
+    "",
+    "用法:",
+    "  agentlink-agent <runtime> [--pair-code=<code>] [--cwd=<path>] [...]",
+    "",
+    "运行时:",
+    "  claude        桥接官方 claude CLI（P2 起实现）",
+    "  codex         桥接官方 codex CLI（P4 起实现）",
+    "",
+    "工具:",
+    "  logs tail     实时跟踪日志（P6 实现）",
+    "  logs grep     按 correlation id 查日志（P6 实现）",
+    "",
+    "环境变量:",
+    "  AGENTLINK_AGENT_LOG_LEVEL   debug / info (默认) / warn / error",
+    "  AGENTLINK_AGENT_LOG_DIR     日志目录，默认 ~/.agentlink/logs",
+    "  AGENTLINK_RELAY_URL         relay 地址（P2 起使用）",
+    "",
+    "选项:",
+    "  --help         本帮助",
+    "  --version      版本",
+    "",
+    "本命令独立于 `agentlink bridge`，两者可并存互不干扰。",
+    "",
+  ];
+  process.stdout.write(lines.join("\n"));
+}

package/src-ext/commands/pair.mjs

@@ -0,0 +1,455 @@
+// `agentlink-agent <runtime> pair <code>`：一次性完成 consume + 装 service + 退出。
+//
+// 设计：与老 `agentlink pair` 语义对齐 —— pair 完就行，不需要用户再跑第二条命令。
+// 用户明确不要后台时可加 `--no-service`，此时仅 consume + save state。
+//
+// 流程：
+//   1. 调 /api/ext/pair-codes/<code>/consume
+//   2. 写本地状态 ~/.agentlink/ext-<runtime>-last.json
+//   3. 装 service（launchd / systemd-user / schtasks）
+//   4. 打印回执
+//
+// 失败路径：service install 失败不回滚 pair state —— 配对凭证仍有效，
+// 用户可以手动 `agentlink bridge -r <runtime>` 前台跑，或稍后 `agentlink service install`。
+
+import process from "node:process";
+
+import {
+  consumePairCode,
+  writePairState,
+  resolveRelayUrl,
+} from "../core/pairCodeClient.mjs";
+import {
+  serviceInstall,
+  serviceUninstall,
+  serviceStatus,
+} from "../service/serviceManager.mjs";
+import { ensureHermesApiServer } from "../runtime/hermes/envSetup.mjs";
+import { manageHermesGateway } from "../runtime/hermes/gatewayManager.mjs";
+import { ensureDefaultWorkspace } from "../core/defaultWorkspace.mjs";
+import os from "node:os";
+import path from "node:path";
+
+export async function runPairInstall({ runtime, code, options, log }) {
+  const relay = resolveRelayUrl(options.relay);
+  const pLog = log.child({ comp: "pair" });
+  pLog.info("pair.consume.start", "consuming pair code", { code, relay });
+
+  // 1. consume
+  let result;
+  try {
+    result = await consumePairCode({ relayUrl: relay, code, runtime });
+  } catch (err) {
+    pLog.error("pair.consume.failed", "consume failed", {
+      err: err?.message || String(err), code: err?.code || "",
+    });
+    process.stderr.write(`配对失败：${err?.message || err}\n`);
+    process.exit(65);
+  }
+  if (result.runtime !== runtime) {
+    process.stderr.write(
+      `配对码是 ${result.runtime} 的，但你用了 -r ${runtime}\n`,
+    );
+    process.exit(65);
+  }
+
+  // 2. 保存本地状态(含 server 颁发的 bridge_token + gw_id 供 bridge SSE 鉴权)
+  // N2.1/N2.2: hermes runtime 支持 --profile <name> 指定 profile，写入 hermesProfileName
+  const pairStateData = {
+    session_id: result.session_id,
+    relay_url: relay,
+    bridge_token: result.bridge_token || "",
+    gw_id: result.gw_id || "",
+  };
+  if (runtime === "hermes" && options.profile) {
+    pairStateData.hermesProfileName = String(options.profile).trim();
+  }
+  writePairState(runtime, pairStateData);
+  pLog.info("pair.consumed", "pair code accepted", {
+    session_id: result.session_id, runtime,
+    has_bridge_token: !!result.bridge_token,
+  });
+  // result 字段是 gw_id（pairCodeClient 把老 session_id 也归一到 gw_id）。
+  // 用 session_id 会显示 undefined，对用户没意义；显示 runtime + 短 gw 后缀更清楚。
+  process.stdout.write(`✅ 配对成功（${runtime}）\n`);
+
+  // 2.5 runtime-specific 本机配置体检 —— hermes 必须 API_SERVER_ENABLED=true，
+  // 默认关闭会让 :8642 没监听 → bridge 连不上 → App 消息不通。
+  if (runtime === "hermes") {
+    await ensureHermesEnvAndProbe(pLog);
+  }
+
+  // 2.6 align-runtime-default-workspace: 对 claude/codex 配对时 eager 创建默认工作区。
+  // 这样新装用户配对完、打开 App 导入列表时，默认工作区已物理存在。
+  // openclaw/hermes 有原生默认工作区（openclaw.json / profileHome），跳过。
+  if (runtime === "claude" || runtime === "codex") {
+    try {
+      const wsPath = await ensureDefaultWorkspace(runtime);
+      pLog.info("pair.default_workspace.created", "default workspace ensured", {
+        runtime, path: wsPath,
+      });
+    } catch (err) {
+      // best-effort：不让默认工作区创建失败影响配对流程
+      pLog.warn("pair.default_workspace.failed", "failed to ensure default workspace (non-fatal)", {
+        runtime, err: err?.message || String(err),
+      });
+    }
+  }
+
+  // 3. 装 service（可被 --no-service / --manual 跳过）
+  if (options["no-service"] || options.manual) {
+    process.stdout.write("⚠️  已跳过后台服务安装（--no-service）\n");
+    process.stdout.write(
+      `   如需后台运行：agentlink service install -r ${runtime}\n` +
+      `   或前台调试：agentlink bridge -r ${runtime}\n`,
+    );
+    return;
+  }
+
+  // 先尝试 uninstall 旧的（幂等保险 —— 反复配对不会冲突）
+  try { serviceUninstall(runtime, pLog); } catch {}
+
+  try {
+    const r = await serviceInstall(runtime, pLog);
+    process.stdout.write(`✅ 已装为后台服务（${r.backend}）\n`);
+    // 装完等 3s 再查状态 —— launchd / systemd 都需要短暂时间拉起子进程
+    await sleep(3000);
+    const status = serviceStatus(runtime);
+    pLog.info("pair.install.status_after_3s", "post-install status", status);
+    if (status.running) {
+      process.stdout.write(
+        `✅ 后台进程已运行${status.pid ? ` (pid=${status.pid})` : ""}\n` +
+        `   查看状态：agentlink service status -r ${runtime}\n` +
+        `   卸载：agentlink uninstall -r ${runtime}\n`,
+      );
+    } else {
+      const logDir = `${process.env.HOME || "~"}/.agentlink/logs`;
+      process.stderr.write(
+        `⚠️  service 已装，但进程 3 秒内未运行起来。\n` +
+        `   最可能原因：后台 PATH 里找不到 claude/codex，或 agent 启动崩溃。\n` +
+        `   请看日志：${logDir}/service-${runtime}.err.log\n` +
+        `   也可以直接前台跑看报错：agentlink bridge -r ${runtime}\n`,
+      );
+    }
+  } catch (err) {
+    pLog.warn("pair.install.failed", "service install failed after pair", {
+      err: err?.message || String(err),
+    });
+    process.stderr.write(
+      `⚠️  自动装服务失败：${err?.message || err}\n` +
+      `   配对本身已完成。可以手动跑：agentlink bridge -r ${runtime}\n`,
+    );
+  }
+
+  // 4. MCP fanout —— 把 agentlink MCP server 注入到当前 runtime 的 MCP 配置,
+  // 让 agent 启动时就能 spawn agentlink-mcp-stdio 看到 agentlink_*_* 工具。
+  // 失败不致命:pair 已经成功;用户可手动 `agentlink mcp register <runtime>` 重试。
+  try {
+    const { register } = await import("../core/mcpRuntimeFanout.mjs");
+    const pkgVersion = await readPkgVersion();
+    const r = await register(runtime, {
+      projectCwd: process.cwd(),
+      version: pkgVersion,
+      log: pLog,
+    });
+    if (r.ok && r.changed) {
+      process.stdout.write(`✅ 已注册 agentlink MCP server 到 ${runtime}\n`);
+    } else if (r.ok && r.mode === "plugin_managed") {
+      process.stdout.write(`ℹ️  openclaw 用 plugin 管理 agentlink 工具(无需 MCP 配置)\n`);
+    } else if (r.ok && !r.changed) {
+      // idempotent no-op,什么都不打印,免噪音
+    } else if (!r.ok && r.reason === "hermes_not_installed") {
+      process.stderr.write(`⚠️  Hermes 未安装,跳过 MCP 配置注册\n`);
+    } else if (!r.ok) {
+      process.stderr.write(`⚠️  MCP 配置注册失败 (${r.reason || "unknown"}): agentlink 工具不会出现在 ${runtime} 的工具列表里。\n` +
+        `   可手动重试:agentlink mcp register ${runtime}\n`);
+    }
+  } catch (err) {
+    pLog.warn("pair.fanout.failed", "mcp fanout failed after pair", {
+      err: err?.message || String(err),
+    });
+    process.stderr.write(`⚠️  MCP 配置注册抛错(${err?.message || err}),pair 本身已成功;agentlink 工具暂不可用。\n`);
+  }
+}
+
+/** 读 npm_cli/package.json 的 version 字段,失败兜底 "unknown"。 */
+async function readPkgVersion() {
+  try {
+    const { readFile } = await import("node:fs/promises");
+    const path = await import("node:path");
+    const { fileURLToPath } = await import("node:url");
+    const __dirname = path.dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(await readFile(path.join(__dirname, "../../package.json"), "utf8"));
+    return pkg.version || "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/**
+ * hermes 专用：确保 `~/.hermes/.env` 里 `API_SERVER_ENABLED=true`，
+ * 必要时也写齐 HOST/PORT。已设的不动。
+ *
+ * 写完之后 probe `http://<host>:<port>/health`，如果不通就提示用户启动 /
+ * 重启 gateway（new env 只对**之后启动的** gateway 生效）。
+ */
+// 配对场景下等 hermes gateway 健康的上限。收短到 5s（默认 30s 是给 bridge
+// preflight 用的）：配对**不该**为了确认 gateway 健康而阻塞后续 runtime ——
+// hermes 没配模型时 gateway 永远不健康，等满 30s 会把 claude/codex 的配对 +
+// host-inventory 上报顶到 App 等待窗口之外，导致「CLI 成功但 App 不显示」。
+// gateway 是 detached spawn，5s 没就绪也会在后台继续起来。
+const PAIR_GATEWAY_HEALTH_TIMEOUT_MS = 5000;
+
+export async function ensureHermesEnvAndProbe(log, opts = {}) {
+  const healthTimeoutMs = opts.healthTimeoutMs || PAIR_GATEWAY_HEALTH_TIMEOUT_MS;
+  const r = ensureHermesApiServer({ log });
+  if (r.status === "no_home") {
+    process.stdout.write(`⚠️  ${r.warning || "~/.hermes 不存在"}\n`);
+    return;
+  }
+  if (r.status === "io_error") {
+    process.stderr.write(`⚠️  hermes 配置自检失败：${r.error}\n`);
+    return;
+  }
+  let restartMatters = false;
+  if (r.status === "patched") {
+    const parts = [];
+    if (r.appended.length > 0) parts.push(`追加 [${r.appended.join(", ")}]`);
+    if (r.overridden.length > 0) parts.push(`改写 [${r.overridden.join(", ")}=true]`);
+    if (r.kept.length > 0) {
+      const keepStr = r.kept.map(({ key, value }) => `${key}=${value}`).join(", ");
+      parts.push(`沿用 [${keepStr}]`);
+    }
+    process.stdout.write(`🔧 已更新 ${r.envPath}：${parts.join("；")}\n`);
+    // overridden（强制把 false → true）一定需要重启；appended 中只有
+    // API_SERVER_ENABLED 真正改变行为（HOST/PORT 缺失情况下 gateway 也是用同
+    // 一套默认值 127.0.0.1:8642 在 listen，append 默认值不改行为）。
+    restartMatters =
+      r.overridden.length > 0 ||
+      r.appended.includes("API_SERVER_ENABLED");
+  } else if (r.kept.length > 0) {
+    // status === "ok"，但仍然把用户已设的 host/port 列出来给用户确认
+    const keepStr = r.kept.map(({ key, value }) => `${key}=${value}`).join(", ");
+    log.info("hermes.env.ok", "hermes API_SERVER_* env already configured", {
+      env_path: r.envPath, kept: r.kept,
+    });
+    process.stdout.write(`ℹ️  hermes 配置 OK，沿用 [${keepStr}]\n`);
+  }
+
+  // 自动起 / 重启 hermes gateway —— 用户不用再手敲 nohup。
+  //   - 配置有 behavior-affecting 变化 (restartMatters)：mode=restart 强制
+  //     kill listening process 再 spawn（老内存里是 stale env，不重启没用）。
+  //   - 配置不变 / 只是补默认值：mode=ensure 只有探活失败才 spawn。
+  const baseUrl = _resolveHermesBaseUrl(r);
+  const logPath = path.join(os.homedir(), ".hermes", "gateway.log");
+  const mgr = await manageHermesGateway({
+    baseUrl,
+    mode: restartMatters ? "restart" : "ensure",
+    logPath,
+    log,
+    healthTimeoutMs,
+  });
+  if (mgr.ok) {
+    if (mgr.alreadyOk) {
+      process.stdout.write(`✅ hermes gateway 已在跑，健康检查通过 (${baseUrl}/health)\n`);
+    } else if (mgr.restarted) {
+      process.stdout.write(
+        `✅ hermes gateway 已重启 (新 pid=${mgr.pid}, 旧 pid=${mgr.stoppedOldPid})，` +
+        `新配置生效，健康检查通过 (${baseUrl}/health)\n` +
+        `   日志：${mgr.logPath}\n`,
+      );
+    } else {
+      process.stdout.write(
+        `✅ hermes gateway 已自动启动 (pid=${mgr.pid})，健康检查通过 (${baseUrl}/health)\n` +
+        `   日志：${mgr.logPath}\n`,
+      );
+    }
+  } else if (mgr.healthTimedOut) {
+    // gateway 进程已 spawn（detached），只是没在收短的健康窗口内通过 /health
+    // —— 典型是没配模型 / 启动慢。这**不阻塞配对**：进程在后台继续起，配模型
+    // 后即可用。打 info 级软提示，不报错、不刷一屏 troubleshooting。
+    log.info("hermes.gateway.health.pending", "gateway spawned but not healthy within pair window (non-blocking)", {
+      baseUrl, timeoutMs: healthTimeoutMs, logPath: mgr.logPath,
+    });
+    process.stdout.write(
+      `ℹ️  hermes gateway 已在后台启动 (pid=${mgr.pid})，但 ${healthTimeoutMs / 1000}s 内未通过健康检查` +
+      `（多半是未配置模型）。不阻塞配对，配好模型后即生效。\n` +
+      `   验证：curl -sf ${baseUrl}/health   日志：${mgr.logPath}\n`,
+    );
+  } else {
+    process.stderr.write(
+      `⚠️  hermes gateway 自动启动失败：${mgr.error}\n`,
+    );
+    if (mgr.logPath) {
+      process.stderr.write(`   看日志定位：tail -50 ${mgr.logPath}\n`);
+    }
+    process.stderr.write(
+      `   手动启动：nohup hermes gateway run > ${mgr.logPath || "/tmp/hermes-gateway.log"} 2>&1 &\n` +
+      `   验证：curl -sf ${baseUrl}/health\n`,
+    );
+  }
+}
+
+/**
+ * 从 envSetup 返回值 + 默认值反推 hermes gateway 的 base URL。
+ * 已设的 HOST/PORT 用用户值；缺失的用默认 127.0.0.1:8642。
+ */
+function _resolveHermesBaseUrl(setupResult) {
+  const kept = new Map((setupResult.kept || []).map(({ key, value }) => [key, value]));
+  const host = kept.get("API_SERVER_HOST") || "127.0.0.1";
+  const port = kept.get("API_SERVER_PORT") || "8642";
+  return `http://${host}:${port}`;
+}
+
+/**
+ * 把"解绑"通知到 relay server。这步是双向解绑的关键 ——
+ *
+ *   - 不通知：CLI 这边状态清了、launchd plist 卸了，但 server 还以为
+ *     binding 在跑；App 端 GET /v1/app-users/me/binding 仍能看到这条
+ *     gateway，发消息会被 dispatch 到一个永远没人 poll 的 gateway。
+ *   - 通知：server 把 pair_sessions 这一行 deleted_at=now，App 下次
+ *     刷新 / SSE 推 thread.archived 时这条会议自动消失。
+ *
+ * 用 POST /v1/gateways/<gw>/reset，鉴权用本机存的 bridge_token（=
+ * relayGatewayToken）。404 = server 端已经被人 reset（典型情况：用户
+ * 在 App 上先删了 → relayWorker 收到 404 自调 uninstall）→ 视为成功，
+ * 不阻塞后续 service uninstall + 本地状态清理。
+ *
+ * @param {string} runtime
+ * @param {{ info, warn, error }} log
+ * @returns {Promise<{ ok: boolean, alreadyRevoked?: boolean, error?: string }>}
+ */
+async function notifyServerOfRevoke(runtime, log) {
+  const { readPairState } = await import("../core/pairCodeClient.mjs");
+  const state = readPairState(runtime);
+  if (!state) return { ok: true, alreadyRevoked: true };
+  const relayUrl = String(state.relay_url || "").replace(/\/+$/, "");
+  const gwId = String(state.gw_id || "").trim();
+  const bridgeToken = String(state.bridge_token || "").trim();
+  if (!relayUrl || !gwId || !bridgeToken) {
+    log?.info?.("uninstall.revoke.skip", "缺少 gw/token，跳过 server 通知", {
+      has_relay: !!relayUrl, has_gw: !!gwId, has_token: !!bridgeToken,
+    });
+    return { ok: true, alreadyRevoked: true };
+  }
+  try {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), 5000);
+    const res = await fetch(`${relayUrl}/v1/gateways/${encodeURIComponent(gwId)}/reset`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${bridgeToken}`,
+        "Content-Type": "application/json",
+      },
+      signal: controller.signal,
+    });
+    clearTimeout(t);
+    if (res.ok) {
+      log?.info?.("uninstall.revoke.ok", "server-side binding revoked", {
+        gw_id: gwId, status: res.status,
+      });
+      return { ok: true };
+    }
+    // 404 / 401 都视为 already revoked —— server 这边没这个 binding 了。
+    if (res.status === 404 || res.status === 401 || res.status === 410) {
+      log?.info?.("uninstall.revoke.gone", "server-side binding already gone", {
+        gw_id: gwId, status: res.status,
+      });
+      return { ok: true, alreadyRevoked: true };
+    }
+    log?.warn?.("uninstall.revoke.fail", "server reset failed (continuing)", {
+      gw_id: gwId, status: res.status,
+    });
+    return { ok: false, error: `HTTP ${res.status}` };
+  } catch (err) {
+    log?.warn?.("uninstall.revoke.err", "server reset errored (continuing)", {
+      err: err?.message || String(err),
+    });
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+/**
+ * `agentlink-agent <runtime> uninstall`：通知 server 解绑 + 卸 service +
+ * 清本地状态。三件事**容错执行**，任一步失败不阻断后面，最终态保证：
+ *   - server: pair_sessions deleted_at 标记
+ *   - 本机:   launchd plist 移除 + ~/.agentlink/ext-<runtime>-last.json 删除
+ *
+ * **bridge 进程自调用场景**：relayWorker 检测到 binding 被 App 端解绑
+ * (HTTP 404 on /requests/next) → spawn 自己 \`agentlink uninstall -r
+ * <runtime> --keep-state\` 把 service plist 也卸掉，pair state 已被
+ * bridge 自行清掉。--keep-state 让 uninstall 跳过 clearPairState。
+ */
+export async function runUninstall({ runtime, options, log }) {
+  const pLog = log.child({ comp: "uninstall" });
+  pLog.info("uninstall.start", "uninstalling runtime", { runtime });
+
+  // 1. **先**通知 server —— 本地状态还在才能拿到 gw_id/bridge_token
+  if (options["skip-server-revoke"]) {
+    process.stdout.write("ℹ️  跳过 server 端解绑通知（--skip-server-revoke）\n");
+  } else {
+    const r = await notifyServerOfRevoke(runtime, pLog);
+    if (r.ok && r.alreadyRevoked) {
+      process.stdout.write(`✅ server 端绑定已不存在\n`);
+    } else if (r.ok) {
+      process.stdout.write(`✅ 已通知 server 解绑 (POST /v1/gateways/<gw>/reset)\n`);
+    } else {
+      process.stderr.write(
+        `⚠️  通知 server 解绑失败：${r.error}\n` +
+        `   本地清理仍继续。server 端 binding 残留请手动 App 端删除。\n`,
+      );
+    }
+  }
+
+  // 1.5 撤 MCP fanout —— 把 ~/.claude.json / ~/.codex/config.toml /
+  // ~/.hermes/config.yaml 里 agentlink server entry 删掉(用户其它 MCP server
+  // 一字不动)。失败不致命,后面 service / state 清理继续。
+  try {
+    const { deregister } = await import("../core/mcpRuntimeFanout.mjs");
+    const r = await deregister(runtime, {
+      projectCwd: process.cwd(),
+      log: pLog,
+    });
+    if (r.ok && r.changed) {
+      process.stdout.write(`✅ 已从 ${runtime} 移除 agentlink MCP server\n`);
+    } else if (!r.ok) {
+      process.stderr.write(`⚠️  MCP 配置清理失败 (${r.reason || "unknown"});其它清理继续。\n`);
+    }
+  } catch (err) {
+    pLog.warn("uninstall.fanout.failed", "mcp deregister failed", {
+      err: err?.message || String(err),
+    });
+  }
+
+  // 2. 卸 service (launchd plist / systemd-user / schtasks)
+  let serviceResult = null;
+  try {
+    serviceResult = serviceUninstall(runtime, pLog);
+    pLog.info("uninstall.service.done", "service uninstalled", serviceResult);
+  } catch (err) {
+    pLog.warn("uninstall.service.failed", "service uninstall failed", {
+      err: err?.message || String(err),
+    });
+    process.stderr.write(`⚠️  service uninstall: ${err?.message || err}\n`);
+  }
+
+  // 3. 清本地状态文件（除非用户显式保留）
+  if (options["keep-state"]) {
+    process.stdout.write("ℹ️  保留本地配对状态（--keep-state）\n");
+  } else {
+    const { clearPairState, clearCursor } = await import("../core/pairCodeClient.mjs");
+    const cleared = clearPairState(runtime);
+    // cursor 必须一起清：留着会让下次 pair 到新 session 时做 session_id 不
+    // 匹配判断——虽然能兜住，但多一次文件 IO。主要目的是状态一致。
+    const cursorCleared = clearCursor(runtime);
+    pLog.info("uninstall.state.cleared", "pair state cleared", {
+      cleared, cursor_cleared: cursorCleared,
+    });
+  }
+
+  process.stdout.write(`✅ 已卸载 ${runtime}\n`);
+}