@xyagent/cli 0.0.1

package/src/tunnel_state.mjs

@@ -0,0 +1,301 @@
+// tunnel.mjs 拆分:配置/状态/路径/日志/HTTP 工具。
+// 不包含任何业务逻辑(代理 / 长轮询 / 心跳),只是基础设施。
+//
+// 这层做三件事:
+//   1. ~/.agentlink/tunnels/{port}.json 状态文件读写
+//   2. tunnel-agent 的统一日志格式 (key=value)
+//   3. fetchJson / fetchWithTimeout / withServerToken / extractJsonError 等 HTTP helper
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import { normalizeBaseUrl, trimSlash } from "./core.mjs";
+
+export const DEFAULT_POLL_WAIT_SECONDS = 20;
+export const DEFAULT_REQUEST_TIMEOUT_MS = 60000;
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 10000;
+export const DEFAULT_HEARTBEAT_TIMEOUT_MS = 10000;
+export const DEFAULT_STREAM_WAIT_TIMEOUT_MS = 30000;
+export const LOCAL_TARGET_HOST = "127.0.0.1";
+export const TUNNEL_IDLE_LOG_EVERY = 6;
+export const TUNNEL_HEARTBEAT_ERROR_LOG_EVERY = 3;
+export const TUNNEL_STREAM_IDLE_LOG_EVERY = 4;
+export const TUNNEL_PROTOCOL_HTTP = "http";
+export const TUNNEL_PROTOCOL_WS = "ws";
+export const TUNNEL_PROTOCOL_TCP = "tcp";
+
+// ---- relay url / protocol / port 解析 ----
+
+export function resolveRelayUrl(override, fallback, fail) {
+  const resolved = resolveRelayOverride(override, fallback);
+  if (!resolved) {
+    fail("relay URL is required");
+  }
+  return resolved;
+}
+
+export function normalizeTunnelProtocol(raw, fail, allowEmpty = false) {
+  const value = String(raw ?? "").trim().toLowerCase();
+  if (!value) {
+    return allowEmpty ? "" : TUNNEL_PROTOCOL_HTTP;
+  }
+  if (value === TUNNEL_PROTOCOL_HTTP || value === TUNNEL_PROTOCOL_WS || value === TUNNEL_PROTOCOL_TCP) {
+    return value;
+  }
+  fail(`invalid tunnel protocol: ${value}`);
+}
+
+export function buildTunnelTargetBaseUrl(protocol, port) {
+  switch (protocol) {
+    case TUNNEL_PROTOCOL_WS:
+      return `ws://${LOCAL_TARGET_HOST}:${port}`;
+    case TUNNEL_PROTOCOL_TCP:
+      return `${LOCAL_TARGET_HOST}:${port}`;
+    default:
+      return `http://${LOCAL_TARGET_HOST}:${port}`;
+  }
+}
+
+export function resolveRelayOverride(override, fallback) {
+  return (
+    normalizeBaseUrl(override) ||
+    normalizeBaseUrl(process.env.AGENTLINK_RELAY_URL) ||
+    normalizeBaseUrl(process.env.TESTNEXTIM_RELAY_URL) ||
+    normalizeBaseUrl(fallback)
+  );
+}
+
+export function parsePort(raw, fail) {
+  const text = String(raw ?? "").trim();
+  const parsed = Number.parseInt(text, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 65535) {
+    fail(`invalid port: ${text || "(empty)"}`);
+  }
+  return parsed;
+}
+
+// ---- HTTP helpers ----
+
+export function fetchJson(url, options = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const headers = new Headers(options.headers ?? {});
+  if (options.body != null && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  return fetchWithTimeout(url, { ...options, headers }, timeoutMs).then(async (response) => {
+    const text = await response.text();
+    let body = null;
+    if (text) {
+      try { body = JSON.parse(text); }
+      catch { body = { error: text }; }
+    }
+    return { ok: response.ok, status: response.status, body };
+  });
+}
+
+export function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timeout));
+}
+
+export function extractJsonError(body, fallback) {
+  if (body && typeof body === "object") {
+    if (typeof body.error === "string" && body.error.trim()) return body.error.trim();
+    if (typeof body.message === "string" && body.message.trim()) return body.message.trim();
+  }
+  return fallback;
+}
+
+export function withServerToken(token) {
+  if (!token) return { "content-type": "application/json" };
+  return {
+    "content-type": "application/json",
+    Authorization: `Bearer ${token}`,
+  };
+}
+
+// ---- ~/.agentlink/tunnels 状态文件 ----
+
+export function ensureTunnelStateDir() {
+  fs.mkdirSync(tunnelStateDir(), { recursive: true });
+}
+
+export function tunnelStateDir() {
+  return path.join(resolveAgentlinkHome(), "tunnels");
+}
+
+export function ensureTunnelLogsDir() {
+  fs.mkdirSync(resolveTunnelLogsDir(), { recursive: true });
+}
+
+export function resolveTunnelLogsDir() {
+  return path.join(resolveAgentlinkHome(), "logs");
+}
+
+export function resolveTunnelLogPath(port) {
+  return path.join(resolveTunnelLogsDir(), `tunnel-${port}.log`);
+}
+
+export function tunnelStatePath(port) {
+  return path.join(tunnelStateDir(), `${port}.json`);
+}
+
+export function resolveAgentlinkHome() {
+  const fromEnv = String(process.env.AGENTLINK_HOME ?? "").trim();
+  if (fromEnv) return fromEnv;
+  const home = String(process.env.HOME ?? process.env.USERPROFILE ?? "").trim() || os.homedir();
+  if (!home || home === "/") {
+    if (process.platform === "win32") {
+      const appData = String(process.env.APPDATA ?? "").trim();
+      if (appData) return path.join(appData, ".agentlink");
+      const userProfile = String(process.env.USERPROFILE ?? "").trim();
+      if (userProfile) return path.join(userProfile, ".agentlink");
+    }
+    let username = "";
+    try { username = os.userInfo().username || ""; } catch { username = ""; }
+    if (username) {
+      const bases = username === "root" ? ["/root"] : ["/home", "/Users"];
+      for (const base of bases) {
+        const candidate = username === "root"
+          ? path.join(base, ".agentlink")
+          : path.join(base, username, ".agentlink");
+        if (fs.existsSync(candidate)) return candidate;
+      }
+      if (username === "root") return "/root/.agentlink";
+      if (process.platform === "darwin") return path.join("/Users", username, ".agentlink");
+      return path.join("/home", username, ".agentlink");
+    }
+  }
+  return path.join(home, ".agentlink");
+}
+
+export function readTunnelState(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch { return null; }
+}
+
+export function writeTunnelState(filePath, state) {
+  fs.writeFileSync(filePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+export function safeUnlink(filePath) {
+  try { fs.unlinkSync(filePath); } catch { /* noop */ }
+}
+
+export function safeReaddir(dirPath) {
+  try { return fs.readdirSync(dirPath); }
+  catch { return []; }
+}
+
+export function isPidAlive(pid) {
+  if (!pid || !Number.isInteger(pid)) return false;
+  try { process.kill(pid, 0); return true; }
+  catch { return false; }
+}
+
+export function safeKill(pid) {
+  try { process.kill(pid, "SIGTERM"); } catch { /* noop */ }
+}
+
+// ---- HTTP / proxy 通用 ----
+
+export function isHopByHopHeader(name) {
+  switch (String(name ?? "").trim().toLowerCase()) {
+    case "connection":
+    case "keep-alive":
+    case "proxy-authenticate":
+    case "proxy-authorization":
+    case "te":
+    case "trailer":
+    case "transfer-encoding":
+    case "upgrade":
+    case "content-length":
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function joinTunnelTargetUrl(baseUrl, requestPath, rawQuery) {
+  const pathName = typeof requestPath === "string" && requestPath.trim() ? requestPath : "/";
+  const url = new URL(trimSlash(baseUrl) + pathName);
+  if (typeof rawQuery === "string" && rawQuery) url.search = rawQuery;
+  return url.toString();
+}
+
+export function parseTunnelTCPAddress(value) {
+  const raw = String(value ?? "").trim();
+  const match = raw.match(/^(.+):(\d{1,5})$/u);
+  if (!match) throw new Error(`invalid tcp target address: ${raw}`);
+  return { host: match[1], port: Number.parseInt(match[2], 10) };
+}
+
+export async function normalizeWebSocketPayload(data) {
+  if (typeof data === "string") return Buffer.from(data, "utf8");
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  if (ArrayBuffer.isView(data)) return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  if (typeof Blob !== "undefined" && data instanceof Blob) return Buffer.from(await data.arrayBuffer());
+  return Buffer.from([]);
+}
+
+// ---- 渲染 / 摘要 / 日志格式 ----
+
+export function renderOutput(json, payload, lines) {
+  if (json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(lines.join("\n"));
+}
+
+export function summarizeTunnelRequest(request) {
+  const pathName = typeof request?.path === "string" && request.path.trim() ? request.path.trim() : "/";
+  const rawQuery = typeof request?.rawQuery === "string" ? request.rawQuery : "";
+  return {
+    requestId: String(request?.requestId ?? "").trim() || "-",
+    method: String(request?.method ?? "GET").trim().toUpperCase(),
+    path: rawQuery ? `${pathName}?${rawQuery}` : pathName,
+  };
+}
+
+export function decodeBase64Length(value) {
+  if (typeof value !== "string" || value.length === 0) return 0;
+  return Buffer.from(value, "base64").byteLength;
+}
+
+export function createTunnelLogger({ localPort, tunnelID, targetBaseUrl, relayUrl }) {
+  const base = { port: localPort, tunnel: tunnelID, target: targetBaseUrl, relay: relayUrl };
+  return {
+    info(message, fields = {}) {
+      console.log(formatTunnelLogLine("info", message, { ...base, ...fields }));
+    },
+    error(message, fields = {}) {
+      console.error(formatTunnelLogLine("error", message, { ...base, ...fields }));
+    },
+  };
+}
+
+function formatTunnelLogLine(level, message, fields = {}) {
+  const parts = [
+    new Date().toISOString(),
+    `[tunnel-agent]`,
+    `level=${level}`,
+    `message=${quoteTunnelLogValue(message)}`,
+  ];
+  for (const [key, value] of Object.entries(fields)) {
+    if (value == null || value === "") continue;
+    parts.push(`${key}=${quoteTunnelLogValue(value)}`);
+  }
+  return parts.join(" ");
+}
+
+function quoteTunnelLogValue(value) {
+  const text = String(value);
+  return /[\s"]/u.test(text) ? JSON.stringify(text) : text;
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/unified_producer.mjs

@@ -0,0 +1,259 @@
+/**
+ * unified_producer.mjs — C1.1.1 + C1.2.1
+ *
+ * createUnifiedProducer({ relayUrl, bridgeToken, threadId })
+ *   → { postEvents(envelopes), close() }
+ *
+ * ensureUnifiedThread({ relayUrl, bridgeToken, runtime, config })
+ *   → threadId (string)
+ */
+
+// ---------------------------------------------------------------------------
+// AgentBridgeError
+// ---------------------------------------------------------------------------
+
+export class AgentBridgeError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = "AgentBridgeError";
+    this.status = status;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// C1.1.1 — createUnifiedProducer
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{ relayUrl: string, bridgeToken: string, threadId: string }} opts
+ * @returns {{ postEvents(envelopes: any[]): Promise<{accepted:number, rejected:number}>, close(): void }}
+ */
+export function createUnifiedProducer({ relayUrl, bridgeToken, threadId }) {
+  if (!relayUrl) throw new Error("createUnifiedProducer: relayUrl required");
+  if (!bridgeToken) throw new Error("createUnifiedProducer: bridgeToken required");
+  if (!threadId) throw new Error("createUnifiedProducer: threadId required");
+
+  const base = relayUrl.replace(/\/$/, "");
+  const url = `${base}/v1/agents/threads/${encodeURIComponent(threadId)}/events`;
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Agent-Bridge-Token": bridgeToken,
+  };
+
+  /**
+   * envelope 补全：server 端 schema 要求每个 envelope 都带 `thread_id` / `role` /
+   * `source` 三个 top-level 字段，但 `src-shared/envelope_builder.mjs` 的 build*
+   * 系列只构造 `{type, run_id, payload}`。openclaw 走 openclaw-plugin/index.cjs
+   * 的 enrichEnvelope() 补全后再发；hermes/claude/codex 走的就是当前模块，
+   * 不补就会被 server 退 400 schema.invalid（实测过 codex run 全 batch 拒绝、
+   * App 端永远转圈）。规则与 openclaw-plugin 对齐：
+   *   - heartbeat / error → role=system, source=relay
+   *   - 其他（run.* / content_block.* / 大多数）→ role=assistant, source=runtime
+   * 若 envelope 已经带了这些字段（来自 hook / 测试 stub），保留不覆盖。
+   */
+  function enrichEnvelope(env) {
+    const type = String(env?.type || "");
+    const isSystem = type === "heartbeat" || type === "error";
+    return {
+      thread_id: env?.thread_id || threadId,
+      role: env?.role || (isSystem ? "system" : "assistant"),
+      source: env?.source || (isSystem ? "relay" : "runtime"),
+      ...env,
+    };
+  }
+
+  /**
+   * POST a batch of envelopes to the relay.
+   * @param {any[]} envelopes
+   */
+  async function postEvents(envelopes) {
+    const enriched = Array.isArray(envelopes)
+      ? envelopes.map((env) => enrichEnvelope(env))
+      : envelopes;
+    const body = JSON.stringify({ events: enriched });
+    let resp;
+    try {
+      resp = await fetch(url, { method: "POST", headers, body });
+    } catch (networkErr) {
+      throw new AgentBridgeError(`network error: ${networkErr.message}`, 0);
+    }
+    if (!resp.ok) {
+      const text = await resp.text().catch(() => "");
+      const err = new AgentBridgeError(
+        `POST /events failed HTTP ${resp.status}: ${text}`,
+        resp.status,
+      );
+      if (resp.status === 413) {
+        err.code = "stream.payload_too_large";
+      }
+      throw err;
+    }
+    const json = await resp.json().catch(() => ({ accepted: 0, rejected: 0 }));
+    return json;
+  }
+
+  function close() {
+    // no persistent connection to close in Phase 1
+  }
+
+  return { postEvents, close };
+}
+
+// ---------------------------------------------------------------------------
+// createHookedUnifiedProducer — wraps createUnifiedProducer with outgoing hooks
+//
+// 为 bridge-auto-tunnel（src-ext/core/bridgeHooks.mjs）等场景把 envelopes 上行
+// 前的 hook chain 应用到 postEvents 调用。失败 / 超时一律不阻塞主链路。
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   relayUrl: string,
+ *   bridgeToken: string,
+ *   threadId: string,
+ *   applyHooks?: (envelopes: any[], opts?: any) => Promise<any[]>,
+ *   logger?: any,
+ *   hookTimeoutMs?: number,
+ * }} opts
+ *   applyHooks 默认懒加载 src-ext/core/bridgeHooks.mjs#applyOutgoingHooks，
+ *   方便单测时注入桩函数。
+ * @returns {{ postEvents(envelopes: any[]): Promise<{accepted:number, rejected:number}>, close(): void }}
+ */
+export function createHookedUnifiedProducer(opts) {
+  const inner = createUnifiedProducer({
+    relayUrl: opts.relayUrl,
+    bridgeToken: opts.bridgeToken,
+    threadId: opts.threadId,
+  });
+  const hookTimeoutMs = opts.hookTimeoutMs;
+  const logger = opts.logger;
+  let applyHooks = opts.applyHooks;
+
+  async function ensureApplyHooks() {
+    if (applyHooks) return applyHooks;
+    const mod = await import("../src-ext/core/bridgeHooks.mjs");
+    applyHooks = mod.applyOutgoingHooks;
+    return applyHooks;
+  }
+
+  return {
+    async postEvents(envelopes) {
+      const apply = await ensureApplyHooks();
+      let transformed;
+      try {
+        transformed = await apply(envelopes, {
+          logger,
+          timeoutMs: hookTimeoutMs,
+          thread_id: opts.threadId,
+        });
+      } catch (err) {
+        // applyOutgoingHooks 已自己吞错；走到这说明 import 链路本身炸了。
+        logger?.warn?.("producer.hooks.bootstrap_err",
+          "failed to apply outgoing hooks, posting raw envelopes",
+          { err: err?.message || String(err) });
+        transformed = envelopes;
+      }
+      return inner.postEvents(Array.isArray(transformed) ? transformed : envelopes);
+    },
+    close() {
+      inner.close();
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// C1.2.2 — processOpenClawStreamWithUnified (bridge integration helper)
+// ---------------------------------------------------------------------------
+
+/**
+ * Process a sequence of openclaw stream chunks, translate each to unified
+ * envelopes, and POST them to the relay via the micro-batched flusher.
+ *
+ * Each chunk's envelopes are enqueued immediately after translation (真流式),
+ * rather than accumulated for a single batch POST at the end. This eliminates
+ * the fake-streaming behavior that caused relay 413 errors on long turns.
+ *
+ * @param {{
+ *   chunks: Array<{ event: string, delta?: string }>,
+ *   relayUrl: string,
+ *   bridgeToken: string,
+ *   threadId: string,
+ *   runId: string,
+ *   flushPolicy?: { size?: number, timeMs?: number },
+ * }} opts
+ */
+export async function processOpenClawStreamWithUnified({
+  chunks,
+  relayUrl,
+  bridgeToken,
+  threadId,
+  runId,
+  flushPolicy,
+}) {
+  const { translateOpenClawChunkToEnvelope, newBlockState } = await import("../src-shared/envelope_builder.mjs");
+  const { createEnvelopeFlusher } = await import("../src-ext/core/unifiedDispatchHandler.mjs");
+
+  const producer = createUnifiedProducer({ relayUrl, bridgeToken, threadId });
+  const flusher = createEnvelopeFlusher({
+    postEvents: (envs) => producer.postEvents(envs),
+    flushPolicy,
+  });
+
+  let blockState = newBlockState();
+
+  for (const chunk of chunks) {
+    const { envelopes, blockState: next } = translateOpenClawChunkToEnvelope(chunk, runId, blockState);
+    blockState = next;
+    if (envelopes.length > 0) {
+      flusher.enqueue(envelopes);
+    }
+  }
+
+  await flusher.waitAll();
+}
+
+// ---------------------------------------------------------------------------
+// C1.2.1 — ensureUnifiedThread
+// ---------------------------------------------------------------------------
+
+/**
+ * If config.unifiedThreadId is set, return it immediately.
+ * Otherwise POST /v1/agents/threads (with bridge_token), store in config, return.
+ *
+ * @param {{ relayUrl: string, bridgeToken: string, runtime: string, config: object }} opts
+ * @returns {Promise<string>} threadId
+ */
+export async function ensureUnifiedThread({ relayUrl, bridgeToken, runtime, config }) {
+  if (config.unifiedThreadId) {
+    return config.unifiedThreadId;
+  }
+
+  const base = relayUrl.replace(/\/$/, "");
+  const url = `${base}/v1/agents/threads`;
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Agent-Bridge-Token": bridgeToken,
+      },
+      body: JSON.stringify({ runtime: runtime || "openclaw" }),
+    });
+  } catch (networkErr) {
+    throw new AgentBridgeError(`ensureUnifiedThread network error: ${networkErr.message}`, 0);
+  }
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new AgentBridgeError(
+      `POST /threads failed HTTP ${resp.status}: ${text}`,
+      resp.status,
+    );
+  }
+  const json = await resp.json();
+  const threadId = json.thread_id;
+  if (!threadId) throw new AgentBridgeError("POST /threads returned no thread_id", 0);
+
+  config.unifiedThreadId = threadId;
+  return threadId;
+}

package/src-ext/README.md

@@ -0,0 +1,75 @@
+# `src-ext/` — External Agents (Hermes / Claude / Codex) 桥接
+
+**平行世界**：整个目录对老 `src/` 零依赖。即使这里全删，老 `agentlink bridge`
+（OpenClaw）完全不受影响。
+
+## 隔离契约
+
+| 允许                            | 禁止                                  |
+| ------------------------------- | ------------------------------------- |
+| `import '../src-shared/*'`      | `import '../src/**'`                  |
+| `import '../../node_modules/*'` | 反向依赖、跨目录 relative             |
+| 独立 bin `agentlink-agent`      | 在老 `agentlink` 里注册命令           |
+| 独立持久化目录 / 日志 / 配置    | 混用老的 OpenClaw gateway 凭证        |
+
+## 目录
+
+```
+src-ext/
+├── bin.mjs                       # agentlink-agent 入口分发
+├── commands/
+│   ├── agent.mjs                 # agentlink-agent <runtime> 子命令
+│   ├── pair.mjs                  # agentlink-agent pair（pair-code consume）
+│   ├── service.mjs               # agentlink-agent service install/...
+│   ├── reload.mjs                # 配置 / 凭证热重载
+│   └── help.mjs
+├── core/
+│   ├── pairCodeClient.mjs        # POST /v1/pair-codes/<code>/consume + 状态持久化
+│   ├── relayWorker.mjs           # 4 个 bridge 共用的 long-poll 主循环
+│   ├── relayWorkerHttp.mjs       # bridge_token Bearer header / fetchJson 工具
+│   ├── sessionSlot.mjs           # 单 session 槽状态机
+│   ├── stateMachine.mjs          # 通用 FSM
+│   ├── approvalGateway.mjs       # HITL 工具审批
+│   ├── mcpStdioClient.mjs        # MCP stdio 客户端（Codex 用）
+│   ├── agentlinkToolsRegistry.mjs # 反向工具注册表
+│   ├── agentlinkToolsServer.mjs  # 反向 MCP 工具服务器
+│   ├── accountResolver.mjs       # accountId / clientUserId 解析
+│   └── usageReporter.mjs         # token 用量上报
+├── runtime/
+│   ├── hermes/
+│   │   └── index.mjs             # Hermes bridge（OpenAI-compatible HTTP / 子进程，256 行）
+│   ├── claude/
+│   │   └── index.mjs             # Claude bridge（spawn `claude` CLI + stream-json，223 行）
+│   └── codex/
+│       └── index.mjs             # Codex bridge（spawn `codex` MCP stdio，240 行）
+├── service/
+│   └── serviceManager.mjs        # launchd / systemd / Task Scheduler 跨平台保活
+└── openclaw-plugin/              # agentlink-hooks OpenClaw 插件源码（pair openclaw 时 link 进 OpenClaw）
+```
+
+## 重构后的关键事实
+
+- **不再有 `src-ext/core/unified_relay_shim.mjs`** —— 整个文件已删除。CLI 端不再做
+  legacy native event → unified envelope 的协议翻译。bridge 把 native 事件
+  （Claude stream-json / Codex `codex/event` / Hermes OpenAI SSE chunk）**直接**
+  POST 给服务端，由 `agentlink-server/internal/adapter/<runtime>/` 翻译为
+  unified envelope 写入 `agent_events` 表。
+- **不再有 `usageReporter` 的 envelope 翻译辅助** —— 现在只是把 native usage
+  事件作为一种 chunk 透传。
+- **4 个 runtime bridge 走完全统一的主循环**（`core/relayWorker.mjs`）：
+  1. 调 `pairCodeClient.consume()` 拿 `{gw_id, bridge_token}`
+  2. `GET /v1/gateways/<gw>/requests/next?waitSeconds=25` 长轮询
+  3. 调本地 runtime（HTTP / spawn CLI / MCP stdio）
+  4. `POST /v1/gateways/<gw>/requests/<rid>/events` 推 native 事件
+  5. `POST /v1/gateways/<gw>/meta` 每 10s 心跳
+
+## 运行
+
+```bash
+node ./bin/agentlink-agent --help
+
+# 各 runtime 的前台调试入口
+AGENTLINK_AGENT_LOG_LEVEL=debug node ./bin/agentlink-agent hermes
+AGENTLINK_AGENT_LOG_LEVEL=debug node ./bin/agentlink-agent claude
+AGENTLINK_AGENT_LOG_LEVEL=debug node ./bin/agentlink-agent codex
+```