@xyagent/cli 0.0.1

package/bin/agentlink-agent

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// Independent bin for external-agents (claude / codex) bridging.
+// 设计意图见 agentlink-cli/src-ext/README.md。
+//
+// 本文件**禁止** import `../src/**`。只允许 `../src-ext/**` 和 `../src-shared/**`。
+
+import "../src-ext/bin.mjs";

package/bin/agentlink-mcp-stdio

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+// 独立 stdio → localhost HTTP 的 MCP 桥。
+//
+// 调用方：Claude / Codex / Hermes / OpenClaw 的 MCP 客户端把本脚本作为
+// stdio MCP server spawn。两种调用形式:
+//
+//   1) 旧式(直接传 url + auth, 不推荐, 端口变化时配置会过期):
+//      { command: "node", args: ["/path/to/agentlink-mcp-stdio",
+//                                "--url", "http://127.0.0.1:54321",
+//                                "--auth", "abc..."] }
+//
+//   2) 新式(推荐, 通过 discovery 文件解耦, bridge 重启换端口对 MCP 配置透明):
+//      { command: "node", args: ["/path/to/agentlink-mcp-stdio",
+//                                "--discovery", "/Users/<user>/.agentlink/tools-server.json"] }
+//      discovery 文件 shape: { url, auth, pid, version, startedAt }
+//      由 bridge 进程在启动时写, 退出时清理。
+//
+// 本脚本:
+//   1. 读 discovery 或 --url/--auth 拿到 url + auth
+//   2. 监听 stdin 的 JSON-RPC 行, initialize 握手本地回, tools/list /
+//      tools/call 转发到 url (POST, Authorization: Bearer <auth>)
+//   3. 其它方法返回 method not found
+
+import process from "node:process";
+import fs from "node:fs";
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--") && argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) {
+      out[a.slice(2)] = argv[++i];
+    } else if (a.startsWith("--")) {
+      out[a.slice(2)] = true;
+    }
+  }
+  return out;
+}
+
+const args = parseArgs(process.argv);
+
+// 优先级:--discovery (推荐) > --url / --auth (legacy) > 环境变量。
+// --agentlink-version 是 marker, 让 fanout 升级时识别旧条目;脚本本身不消费它。
+let url = args.url || process.env.AGENTLINK_MCP_URL || "";
+let auth = args.auth || process.env.AGENTLINK_MCP_AUTH || "";
+
+if (args.discovery && (!url || !auth)) {
+  try {
+    const raw = fs.readFileSync(args.discovery, "utf8");
+    const doc = JSON.parse(raw);
+    if (typeof doc?.url === "string" && typeof doc?.auth === "string") {
+      url = url || doc.url;
+      auth = auth || doc.auth;
+    }
+  } catch (err) {
+    // discovery 缺失 = bridge 没在跑;干净退出, MCP 客户端把我们当 server unavailable
+    process.stderr.write(`agentlink tools server not running (discovery=${args.discovery}: ${err?.message || err})\n`);
+    process.exit(2);
+  }
+}
+
+// stderr 用于错误观察(stdout 是 JSON-RPC 通道,不能污染)
+function logStderr(level, event, extra) {
+  const row = { ts: new Date().toISOString(), level, comp: "mcp_bridge", event, pid: process.pid, ...extra };
+  try { process.stderr.write(JSON.stringify(row) + "\n"); } catch {}
+}
+
+if (!url) {
+  logStderr("error", "bridge.start.fail", { err: "missing --url or --discovery with usable file" });
+  process.exit(2);
+}
+
+logStderr("info", "bridge.start", {
+  url, has_auth: !!auth,
+  source: args.discovery ? "discovery" : "args",
+  agentlink_version: args["agentlink-version"] || null,
+});
+
+function sendRpc(obj) {
+  try { process.stdout.write(JSON.stringify(obj) + "\n"); }
+  catch (err) { logStderr("error", "bridge.stdout.write", { err: err?.message }); }
+}
+
+async function postJson(path, body) {
+  const res = await fetch(url.replace(/\/+$/, "") + path, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      // 优先 Authorization: Bearer(标准 MCP / 与 spec 对齐);保留 X-Agentlink-Auth
+      // 兼容更老的 bridge(也能识别两种)。
+      ...(auth ? { "Authorization": `Bearer ${auth}`, "X-Agentlink-Auth": auth } : {}),
+    },
+    body: JSON.stringify(body || {}),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`agentlink tools server ${res.status}: ${text.slice(0, 200)}`);
+  }
+  return text ? JSON.parse(text) : {};
+}
+
+async function handleMessage(msg) {
+  const { id, method, params } = msg;
+  if (method === "initialize") {
+    sendRpc({
+      jsonrpc: "2.0", id,
+      result: {
+        protocolVersion: "2024-11-05",
+        serverInfo: { name: "agentlink", version: "p5" },
+        capabilities: { tools: {} },
+      },
+    });
+    return;
+  }
+  if (method === "notifications/initialized") {
+    // no-op
+    return;
+  }
+  if (method === "tools/list") {
+    try {
+      const r = await postJson("/tools/list", {});
+      sendRpc({ jsonrpc: "2.0", id, result: { tools: r.tools || [] } });
+    } catch (err) {
+      sendRpc({ jsonrpc: "2.0", id, error: { code: -32603, message: err?.message || String(err) } });
+    }
+    return;
+  }
+  if (method === "tools/call") {
+    try {
+      const r = await postJson("/tools/call", {
+        name: params?.name || "",
+        arguments: params?.arguments || {},
+      });
+      sendRpc({ jsonrpc: "2.0", id, result: r });
+    } catch (err) {
+      sendRpc({ jsonrpc: "2.0", id, error: { code: -32603, message: err?.message || String(err) } });
+    }
+    return;
+  }
+  // 未实现的方法
+  if (id !== undefined) {
+    sendRpc({ jsonrpc: "2.0", id, error: { code: -32601, message: "method not implemented" } });
+  }
+}
+
+let buf = "";
+process.stdin.on("data", (chunk) => {
+  buf += chunk.toString("utf8");
+  if (buf.length > 8 << 20) buf = buf.slice(-(4 << 20));
+  let idx;
+  while ((idx = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, idx).replace(/\r$/, "").trim();
+    buf = buf.slice(idx + 1);
+    if (!line) continue;
+    let msg;
+    try { msg = JSON.parse(line); }
+    catch (err) {
+      logStderr("warn", "bridge.parse.fail", { err: err?.message, sample: line.slice(0, 200) });
+      continue;
+    }
+    Promise.resolve(handleMessage(msg)).catch((err) => {
+      logStderr("error", "bridge.handle.threw", { err: err?.message || String(err) });
+    });
+  }
+});
+
+process.stdin.on("end", () => {
+  logStderr("info", "bridge.stdin.end", {});
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));

package/docs/LOGGING.md

@@ -0,0 +1,159 @@
+# Agentlink Agent Logging Spec (P1 — P6 契约)
+
+本文档是 `agentlink-agent` 及其所有运行时桥接（Claude / Codex 等）必须遵守
+的**日志契约**。任何新代码落库前，对照本文件 review。
+
+## 1. 为什么有这份规范
+
+在多进程、多语言、带 relay 中继的架构里，bug 基本只能靠日志复盘。
+"想起来打 log" 的代码长期一定乱 —— 必须**约定**。
+
+## 2. 格式
+
+所有 `agentlink-agent` 输出**一律 JSON 行**（每行一个完整 JSON 对象）。
+
+```json
+{"ts":"2026-04-17T10:23:45.123Z","level":"info","comp":"bridge","event":"bridge.start","cid":"c_ab12","session":"agent:u1:relay-gw:gw-A::claude-1","rt":"claude","msg":"bridge starting","pid":12345}
+```
+
+必选字段：
+
+| 字段  | 含义 |
+|-------|------|
+| `ts`    | ISO8601 毫秒 UTC |
+| `level` | `debug` / `info` / `warn` / `error` |
+| `comp`  | 组件名（见 §4） |
+| `event` | 事件名（见 §5，见名知意，`scope.verb` 形式） |
+| `msg`   | 人类可读短描述 |
+
+可选：
+- `cid` — correlation id，一次完整 app→server→cli→agent 交互贯穿
+- `session` — agentlink 会话 key（带前缀）
+- `rt` — `claude` / `codex`
+- `pid` — 当前进程 pid
+- 其它任意 `snake_case` 附加字段
+
+## 3. level 使用标准
+
+| level | 何时用 |
+|-------|--------|
+| `debug` | 事件流细节（每条 stdout 行、每次 cursor advance） |
+| `info`  | 业务里程碑（bridge 启停、session 切换、审批完成） |
+| `warn`  | 异常但可恢复（schema mismatch、重连、审批超时） |
+| `error` | 意外异常（spawn 失败、panic、无法 recover） |
+
+**默认级别 info**。通过 `AGENTLINK_AGENT_LOG_LEVEL=debug` 打开 debug。
+
+## 4. 组件命名 (`comp` 字段)
+
+| comp | 归属 |
+|------|------|
+| `bridge` | `agentlink-agent` 顶层（启动、退出、参数解析） |
+| `relay`  | 与 Go server 的 SSE / HTTP 交互 |
+| `child`  | 外部 agent 子进程（claude / codex） |
+| `stdout` | claude stdout 解析器 |
+| `mcp`    | codex MCP 客户端 |
+| `hook`   | claude hook server |
+| `approval` | 审批闸门 |
+| `session`  | 会话槽位状态机 |
+| `shared`   | 共享基础设施（logger 自己、schema 校验） |
+
+## 5. 事件清单（硬约束，必打）
+
+每个阶段必打的事件。新增事件时在 PR 里更新本清单。
+
+### P1
+
+| event | level | 何时触发 |
+|-------|-------|----------|
+| `bridge.start`                 | info  | agent 启动入口第一行 |
+| `bridge.preflight.pass`        | info  | 检查通过 |
+| `bridge.preflight.fail`        | error | 检查失败（会立刻退出） |
+| `bridge.exit`                  | info  | 正常退出 |
+| `bridge.signal.recv`           | info  | 收到 SIGTERM/SIGINT |
+
+### P2 (Claude)
+
+| event | level |
+|-------|-------|
+| `child.spawn`                  | info  |
+| `child.exit`                   | info  |
+| `child.stderr_tail`            | warn  |
+| `stdout.line.parsed`           | debug |
+| `stdout.schema.mismatch`       | warn  |
+| `stdout.buffer.overflow`       | warn  |
+| `session.state`                | info  |
+| `relay.event.send`             | debug |
+| `relay.event.recv`             | debug |
+
+### P3 (审批)
+
+| event | level |
+|-------|-------|
+| `approval.request.sent`        | info  |
+| `approval.pending`             | info  | 每 60s 打一条，显示等待时长 |
+| `approval.response.recv`       | info  |
+
+### P4 (Codex)
+
+| event | level |
+|-------|-------|
+| `codex.connect`                | info  |
+| `codex.notif`                  | debug |
+| `codex.schema.mismatch`        | warn  |
+
+### P5 (MCP 反向桥)
+
+| event | level |
+|-------|-------|
+| `elicit.request`               | info  |
+| `elicit.response`              | info  |
+| `mcp_bridge.forward`           | debug |
+| `mcp_bridge.socket.connect`    | info  |
+
+### P6 (resume / 重连)
+
+| event | level |
+|-------|-------|
+| `resume.attempt`               | info  |
+| `resume.result`                | info  |
+| `relay.reconnect.backoff`      | warn  |
+| `relay.cursor.advance`         | debug |
+
+## 6. Correlation ID 流转
+
+- App 创建：`cid = "c_" + random(8)`，随消息/RPC 请求透传
+- Server 透传：`relay_events.payload.meta.cid`，`relay_events` 行本身不单独存列
+- CLI 读到 event → 后续由此触发的所有日志挂 `cid`
+- 子进程 → parent 走 stdout / fd3 / MCP 时也透传 cid（每行都带）
+
+出问题时 `grep cid=c_ab12cd34` 整条链可复盘。
+
+## 7. 落盘规则
+
+- **默认**：`~/.agentlink/logs/agent-<runtime>-YYYYMMDD.log`
+- 滚动：按天、保留 7 天、单文件 > 50MB 时滚动
+- 格式：和 stderr 一致（JSON 行），便于 `jq` 分析
+- **敏感内容脱敏**：
+  - 用户消息 body 截断 500 字符（更长则 `text_truncated: true`）
+  - token / credential / cookie 整字段替换成 `<redacted>`
+  - 文件路径保留
+- **所有级别日志走 stderr**（不走 stdout）—— stdout 是业务产出通道（help、version、未来的 JSON 响应）
+  所以 `agentlink-agent --help 2>/dev/null` 只出帮助，`... 1>/dev/null` 只出日志
+
+## 8. 工具命令
+
+```bash
+agentlink-agent logs tail              # 实时跟当天日志
+agentlink-agent logs grep <cid>        # 按 cid 查
+agentlink-agent logs path              # 输出日志文件路径
+```
+
+（P6 阶段实现，P1 先保证格式对。）
+
+## 9. 铁律
+
+1. **未知事件 / 未知字段** → `warn` 级别 `*.schema.mismatch` → **继续运行**，禁止 crash
+2. **任何 catch 块** → 必须打 `error.caught where=...`，然后决定吞/抛
+3. **循环 / 定时器** → 绝不打 `debug` 级别的"心跳"，审批等待类用 60s 节流
+4. **禁止 `console.log`** —— 一律走 logger，未走的视为 bug

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@xyagent/cli",
+  "version": "0.0.1",
+  "private": false,
+  "description": "Relay-first CLI for pairing and bridging OpenClaw gateway traffic",
+  "type": "module",
+  "files": [
+    "bin/agentlink",
+    "bin/agentlink-agent",
+    "bin/agentlink-mcp-stdio",
+    "src/",
+    "src-shared/",
+    "src-ext/",
+    "docs/LOGGING.md",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build:plugin": "node scripts/build-openclaw-plugin.mjs",
+    "prepublishOnly": "node scripts/build-openclaw-plugin.mjs",
+    "postinstall": "node -e 'import(process.cwd()+\"/src-ext/core/daemonRestart.mjs\").then(m=>m.kickstartDaemons()).catch(()=>{})'",
+    "test": "node --test --test-concurrency=1 'test/**/*.test.mjs'",
+    "test:coverage": "node --test --experimental-test-coverage test/tunnel/core.test.mjs"
+  },
+  "bin": {
+    "agentlink": "bin/agentlink",
+    "agentlink-agent": "bin/agentlink-agent",
+    "agentlink-mcp-stdio": "bin/agentlink-mcp-stdio"
+  },
+  "dependencies": {
+    "pdfjs-dist": "^4.10.38"
+  }
+}

package/src/core.mjs

@@ -0,0 +1,320 @@
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+
+export const NUMERIC_CODE_LENGTH = 4;
+export const GROUP_SIZE = 4;
+export const DEFAULT_BIND_PATH = "/testnextim/bind";
+export const FIXED_MEMORY_FILES = Object.freeze([
+  "AGENTS.md",
+  "HEARTBEAT.md",
+  "IDENTITY.md",
+  "MEMORY.md",
+  "SOUL.md",
+  "TOOLS.md",
+  "USER.md",
+]);
+
+function throwError(message) {
+  throw new Error(message);
+}
+
+export function buildPathString(values, delimiter = path.delimiter) {
+  const entries = [];
+  const seen = new Set();
+  for (const value of values) {
+    const raw = String(value ?? "").trim();
+    if (!raw) continue;
+    for (const part of raw.split(delimiter)) {
+      const normalized = part.trim();
+      if (!normalized || seen.has(normalized)) continue;
+      seen.add(normalized);
+      entries.push(normalized);
+    }
+  }
+  return entries.join(delimiter);
+}
+
+export function resolveSiblingBinDirs(executablePath, pathModule = path) {
+  const normalized = String(executablePath ?? "").trim();
+  if (!normalized) return [];
+  return [pathModule.dirname(normalized)];
+}
+
+export function normalizeFixedMemoryFileName(rawName, supportedFiles = FIXED_MEMORY_FILES) {
+  const normalized = String(rawName ?? "").trim().toUpperCase();
+  for (const fileName of supportedFiles) {
+    if (fileName.toUpperCase() === normalized) {
+      return fileName;
+    }
+  }
+  throw new Error(`unsupported memory file: ${String(rawName ?? "").trim()}`);
+}
+
+export function commandToString(command, args) {
+  return [command, ...args]
+    .map((part) => {
+      const value = String(part);
+      return /[\s"]/u.test(value) ? `"${value.replaceAll("\"", "\\\"")}"` : value;
+    })
+    .join(" ");
+}
+
+export function quoteWindowsCommandArg(value) {
+  const text = String(value ?? "");
+  if (!/[\s"]/u.test(text)) {
+    return text;
+  }
+  return `"${text.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+
+export function formatCode(raw, groupSize = GROUP_SIZE) {
+  return `${raw.slice(0, groupSize)}-${raw.slice(groupSize)}`;
+}
+
+export function normalizeProvidedCode(raw, onInvalid = throwError) {
+  const compact = String(raw ?? "")
+    .trim()
+    .toUpperCase()
+    .replace(/\s+/g, "")
+    .replace(/-/g, "");
+  if (/^\d{4}$/.test(compact)) return compact;
+  if (/^\d{6}$/.test(compact)) return compact;
+  if (/^[A-Z0-9]{8}$/.test(compact)) return formatCode(compact);
+  return onInvalid(
+    "invalid --code format. expected 4 digits (e.g. 1234), 6 digits (e.g. 123456), " +
+      "or 8 alphanumeric characters (e.g. ABCD-1234; case-insensitive, dash optional)",
+  );
+}
+
+export function generatePairCode(random = Math.random, numericCodeLength = NUMERIC_CODE_LENGTH) {
+  const min = 10 ** (numericCodeLength - 1);
+  const max = 10 ** numericCodeLength;
+  return String(min + Math.floor(random() * (max - min)));
+}
+
+export function parseNonNegativeInt(value, fallback = 0) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value >= 0 ? Math.trunc(value) : fallback;
+  }
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number.parseInt(value.trim(), 10);
+    if (Number.isFinite(parsed) && parsed >= 0) {
+      return parsed;
+    }
+  }
+  return fallback;
+}
+
+export function normalizePath(input, fallback) {
+  const value = typeof input === "string" ? input.trim() : "";
+  if (!value) return fallback;
+  return value.startsWith("/") ? value : `/${value}`;
+}
+
+export function normalizeChatTransportMode(raw, fallback = "relay") {
+  const value = String(raw ?? "")
+    .trim()
+    .toLowerCase();
+  if (value === "relay") return "relay";
+  return fallback;
+}
+
+export function normalizeRuntimeKind(raw, fallback = "openclaw") {
+  const value = String(raw ?? "")
+    .trim()
+    .toLowerCase();
+  if (value === "hermes") return "hermes";
+  if (value === "openclaw") return "openclaw";
+  return fallback;
+}
+
+export function trimSlash(input) {
+  return String(input ?? "").replace(/\/+$/, "");
+}
+
+export function normalizeBaseUrl(input) {
+  const value = typeof input === "string" ? input.trim() : "";
+  if (!value) return null;
+  return trimSlash(value);
+}
+
+export function buildBindUrl(
+  { base, bindPath, accountId, code },
+  defaultBindPath = DEFAULT_BIND_PATH,
+) {
+  if (!base || typeof base !== "string" || !base.trim()) return null;
+  const normalizedBase = trimSlash(base.trim());
+  const normalizedPath = normalizePath(bindPath, defaultBindPath);
+  const qp = new URLSearchParams({ accountId, code });
+  return `${normalizedBase}${normalizedPath}?${qp.toString()}`;
+}
+
+export function buildGatewayResponsesUrl(base, onInvalid = throwError) {
+  const normalized = normalizeBaseUrl(base);
+  if (!normalized) return onInvalid("gateway base URL is required");
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    return onInvalid(`invalid gateway base URL: ${base}`);
+  }
+  parsed.pathname = "/v1/responses";
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+export function buildGatewayWsUrl(base, onInvalid = throwError) {
+  const normalized = normalizeBaseUrl(base);
+  if (!normalized) return onInvalid("gateway base URL is required");
+  let parsed;
+  try {
+    parsed = new URL(normalized);
+  } catch {
+    return onInvalid(`invalid gateway base URL: ${base}`);
+  }
+  parsed.protocol = parsed.protocol === "https:" ? "wss:" : "ws:";
+  parsed.pathname = "/v1/ws";
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString();
+}
+
+export function parseGatewayPortEnvValue(raw) {
+  const trimmed = String(raw ?? "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  if (/^\d+$/.test(trimmed)) {
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  }
+  const bracketedIpv6Match = trimmed.match(/^\[[^\]]+\]:(\d+)$/);
+  if (bracketedIpv6Match?.[1]) {
+    const parsed = Number.parseInt(bracketedIpv6Match[1], 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+  }
+  const firstColon = trimmed.indexOf(":");
+  const lastColon = trimmed.lastIndexOf(":");
+  if (firstColon <= 0 || firstColon !== lastColon) {
+    return null;
+  }
+  const suffix = trimmed.slice(firstColon + 1);
+  if (!/^\d+$/.test(suffix)) {
+    return null;
+  }
+  const parsed = Number.parseInt(suffix, 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+export function extractPortFromText(raw) {
+  const text = String(raw ?? "").trim();
+  if (!text) return null;
+  const direct = parseGatewayPortEnvValue(text);
+  if (direct != null) return direct;
+  const matches = text.match(/\b\d{2,5}\b/g) ?? [];
+  for (let i = matches.length - 1; i >= 0; i -= 1) {
+    const parsed = parseGatewayPortEnvValue(matches[i]);
+    if (parsed != null) return parsed;
+  }
+  return null;
+}
+
+export function formatHostForUrl(host) {
+  const value = String(host ?? "").trim();
+  if (!value) return "";
+  if (value.startsWith("[") && value.endsWith("]")) {
+    return value;
+  }
+  if (value.includes(":")) {
+    return `[${value}]`;
+  }
+  return value;
+}
+
+export function safeJsonParse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function extractErrorMessage(decoded, fallback) {
+  if (decoded && typeof decoded === "object") {
+    if (typeof decoded.error === "string" && decoded.error.trim()) return decoded.error.trim();
+    if (typeof decoded.message === "string" && decoded.message.trim()) {
+      return decoded.message.trim();
+    }
+  }
+  return fallback;
+}
+
+export function formatErrorDetails(error) {
+  if (!(error instanceof Error)) {
+    return String(error ?? "");
+  }
+  const details = [];
+  if (error.name && error.name !== "Error") {
+    details.push(`name=${error.name}`);
+  }
+  if (error.code) {
+    details.push(`code=${String(error.code)}`);
+  }
+  if (error.errno) {
+    details.push(`errno=${String(error.errno)}`);
+  }
+  if (error.type) {
+    details.push(`type=${String(error.type)}`);
+  }
+  if (error.cause && typeof error.cause === "object") {
+    const cause = error.cause;
+    if (cause?.code) {
+      details.push(`cause.code=${String(cause.code)}`);
+    }
+    if (cause?.errno) {
+      details.push(`cause.errno=${String(cause.errno)}`);
+    }
+    if (cause?.message) {
+      details.push(`cause=${String(cause.message)}`);
+    }
+  }
+  return details.length > 0
+    ? `${error.message} [${details.join(", ")}]`
+    : error.message;
+}
+
+export function isTransientNetworkError(error) {
+  const message = String(error instanceof Error ? error.message : error).toLowerCase();
+  return (
+    message.includes("timeout") ||
+    message.includes("fetch failed") ||
+    message.includes("terminated") ||
+    message.includes("socket") ||
+    message.includes("econnreset") ||
+    message.includes("econnrefused") ||
+    message.includes("ehostunreach") ||
+    message.includes("enotfound") ||
+    message.includes("etimedout") ||
+    message.includes("epipe") ||
+    message.includes("network")
+  );
+}
+
+export function normalizeGatewayIdRaw(value) {
+  return String(value ?? "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function generateRelayGatewayId(accountId, randomHexFn = defaultRandomHex) {
+  const normalizedAccount = normalizeGatewayIdRaw(accountId) || "default";
+  return `gw-${normalizedAccount}-${randomHexFn(4)}`;
+}
+
+function defaultRandomHex(bytesLength = 16) {
+  return randomBytes(bytesLength).toString("hex");
+}