@chenacc/agentbridge 0.0.0-stage → 0.1.0

package/src/attachments.js

@@ -0,0 +1,187 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+
+/**
+ * Attachments for phone-sent messages.
+ *
+ * A phone is the device most likely to hold the thing the agent needs — a
+ * screenshot of the error, a photo of the whiteboard, a log file — and before this
+ * there was no way to get one across. Files are written under the bridge data
+ * directory, described in a small catalog so a preview URL survives a restart, and
+ * bounded hard: a phone on a tunnel must not be able to fill the disk.
+ */
+
+const MAX_BYTES = 8 * 1024 * 1024;
+const MAX_ENTRIES = 400;
+const MAX_FILES_PER_SESSION = 60;
+
+const EXTENSIONS = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/webp": ".webp",
+  "image/gif": ".gif",
+  "application/pdf": ".pdf",
+  "text/plain": ".txt",
+  "text/markdown": ".md",
+  "application/json": ".json",
+  "application/zip": ".zip",
+};
+
+export function extensionFor(mimeType, name = "") {
+  const byMime = EXTENSIONS[String(mimeType ?? "").toLowerCase()];
+  if (byMime) return byMime;
+  const byName = path.extname(String(name)).toLowerCase();
+  return /^\.[a-z0-9]{1,8}$/.test(byName) ? byName : ".bin";
+}
+
+export function isImage(mimeType) {
+  return /^image\/(png|jpe?g|webp|gif)$/i.test(String(mimeType ?? ""));
+}
+
+function cleanName(value) {
+  const name = String(value ?? "").trim().replace(/[\u0000-\u001f\\/:*?"<>|]/g, "_");
+  return name.slice(-120) || "attachment";
+}
+
+export class AttachmentStore {
+  #byId = new Map();
+  #catalogPath;
+  #directory;
+  #writes = Promise.resolve();
+  #now;
+
+  constructor({ dataDir, now = () => Date.now() }) {
+    this.#directory = path.join(dataDir, "attachments");
+    this.#catalogPath = path.join(this.#directory, "attachments.json");
+    this.#now = now;
+  }
+
+  get maxBytes() {
+    return MAX_BYTES;
+  }
+
+  async init() {
+    await mkdir(this.#directory, { recursive: true });
+    try {
+      const parsed = JSON.parse(await readFile(this.#catalogPath, "utf8"));
+      for (const entry of Array.isArray(parsed?.items) ? parsed.items : []) {
+        if (typeof entry?.id === "string" && typeof entry?.file === "string") this.#byId.set(entry.id, entry);
+      }
+    } catch {
+      // No catalog yet: a fresh data directory is not an error.
+    }
+  }
+
+  list(sessionId) {
+    return [...this.#byId.values()]
+      .filter((entry) => !sessionId || entry.sessionId === sessionId)
+      .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0));
+  }
+
+  get(id) {
+    return this.#byId.get(id) ?? null;
+  }
+
+  /** Absolute path for an attachment, or null when it is unknown. */
+  pathOf(id) {
+    const entry = this.#byId.get(id);
+    return entry ? path.join(this.#directory, entry.file) : null;
+  }
+
+  /**
+   * Store one upload. `data` is a Buffer; anything larger than `maxBytes` is
+   * rejected before it is written, and the catalog is trimmed oldest-first so a
+   * phone cannot grow the directory without bound.
+   */
+  async save({ sessionId, name, mimeType, data }) {
+    if (!Buffer.isBuffer(data) || data.length === 0) {
+      throw Object.assign(new Error("The upload is empty"), { statusCode: 400 });
+    }
+    if (data.length > MAX_BYTES) {
+      throw Object.assign(new Error(`附件不能超过 ${Math.round(MAX_BYTES / 1024 / 1024)} MB`), { statusCode: 413 });
+    }
+    const sessionFiles = this.list(sessionId);
+    if (sessionFiles.length >= MAX_FILES_PER_SESSION) {
+      const oldest = sessionFiles.at(-1);
+      await this.#remove(oldest.id);
+    }
+    const id = `att_${randomUUID()}`;
+    const fileName = `${createHash("sha256").update(id).digest("hex").slice(0, 24)}${extensionFor(mimeType, name)}`;
+    const target = path.join(this.#directory, fileName);
+    const handle = await open(target, "w");
+    try {
+      await handle.writeFile(data);
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    const entry = {
+      id,
+      sessionId,
+      name: cleanName(name),
+      mimeType: String(mimeType ?? "application/octet-stream").toLowerCase().slice(0, 120),
+      bytes: data.length,
+      file: fileName,
+      createdAt: this.#now(),
+    };
+    this.#byId.set(id, entry);
+    await this.#persist();
+    return { ...entry };
+  }
+
+  async remove(id) {
+    return this.#remove(id);
+  }
+
+  async #remove(id) {
+    const entry = this.#byId.get(id);
+    if (!entry) return false;
+    this.#byId.delete(id);
+    await rm(path.join(this.#directory, entry.file), { force: true });
+    await this.#persist();
+    return true;
+  }
+
+  /** Read the bytes back for a provider that needs them inline (base64). */
+  async read(id) {
+    const entry = this.#byId.get(id);
+    if (!entry) return null;
+    const buffer = await readFile(path.join(this.#directory, entry.file));
+    return { ...entry, data: buffer };
+  }
+
+  async sizeOf(id) {
+    const entry = this.#byId.get(id);
+    if (!entry) return null;
+    try {
+      const info = await stat(path.join(this.#directory, entry.file));
+      return info.size;
+    } catch {
+      return null;
+    }
+  }
+
+  #persist() {
+    const payload = JSON.stringify({
+      version: 1,
+      items: [...this.#byId.values()]
+        .sort((a, b) => (b.createdAt ?? 0) - (a.createdAt ?? 0))
+        .slice(0, MAX_ENTRIES),
+    });
+    // Once over the cap, the entries that fell out are removed from disk too.
+    for (const entry of this.#byId.values()) {
+      if (!payload.includes(entry.id)) {
+        this.#byId.delete(entry.id);
+        void rm(path.join(this.#directory, entry.file), { force: true });
+      }
+    }
+    const operation = this.#writes.catch(() => undefined).then(async () => {
+      const temporary = `${this.#catalogPath}.tmp`;
+      await writeFile(temporary, payload, "utf8");
+      await rename(temporary, this.#catalogPath);
+    });
+    this.#writes = operation;
+    return operation;
+  }
+}

package/src/cc-switch-models.js

@@ -0,0 +1,86 @@
+import { readFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { DatabaseSync } from "node:sqlite";
+
+const KIMI_PROVIDER_ID = "cc-switch:kimi";
+const KIMI_MODELS = [
+  { id: "kimi-for-coding", name: "Kimi K2.7 Code", note: "256K 上下文" },
+  { id: "k3-256k", name: "Kimi K3 256K", note: "K3，256K 上下文" },
+  { id: "k3", name: "Kimi K3", note: "K3；可用上下文取决于会员权益" },
+];
+
+function parseJson(raw) {
+  try { return JSON.parse(raw); } catch { return null; }
+}
+
+function isKimiCodingEndpoint(value) {
+  try {
+    const url = new URL(String(value ?? ""));
+    return url.hostname === "api.kimi.com" && url.pathname.startsWith("/coding");
+  } catch {
+    return false;
+  }
+}
+
+function isLocalProxyEndpoint(value) {
+  try {
+    const url = new URL(String(value ?? ""));
+    return ["127.0.0.1", "localhost", "::1"].includes(url.hostname);
+  } catch {
+    return false;
+  }
+}
+
+export class CcSwitchModelCatalog {
+  constructor({ homeDir = os.homedir(), readFile: read = readFile, openDatabase = (filePath) => new DatabaseSync(filePath, { readOnly: true }) } = {}) {
+    this.homeDir = homeDir;
+    this.readFile = read;
+    this.openDatabase = openDatabase;
+  }
+
+  async current() {
+    const ccSwitchPath = path.join(this.homeDir, ".cc-switch", "settings.json");
+    const claudePath = path.join(this.homeDir, ".claude", "settings.json");
+    let ccSwitch;
+    let claude;
+    try {
+      [ccSwitch, claude] = await Promise.all([
+        this.readFile(ccSwitchPath, "utf8").then(parseJson),
+        this.readFile(claudePath, "utf8").then(parseJson),
+      ]);
+    } catch {
+      return null;
+    }
+    const providerId = String(ccSwitch?.currentProviderClaude ?? "");
+    const activeEndpoint = String(claude?.env?.ANTHROPIC_BASE_URL ?? "");
+    const selectedEndpoint = this.#providerEndpoint(providerId);
+    const usesCcSwitchProxy = ccSwitch?.enableLocalProxy === true && isLocalProxyEndpoint(activeEndpoint);
+    if (!providerId || !isKimiCodingEndpoint(selectedEndpoint) || (!isKimiCodingEndpoint(activeEndpoint) && !usesCcSwitchProxy)) return null;
+
+    const configuredModel = String(claude?.env?.ANTHROPIC_MODEL ?? "");
+    const knownModel = KIMI_MODELS.some((entry) => entry.id === configuredModel);
+    return {
+      source: "cc-switch",
+      label: "CC Switch · Kimi 模型",
+      description: "仅影响此手机会话后续的 Claude 回合；不会修改 CC Switch 厂商、密钥或代理。",
+      routable: true,
+      current: knownModel ? { provider: KIMI_PROVIDER_ID, model: configuredModel } : null,
+      groups: [{ id: KIMI_PROVIDER_ID, name: "Kimi（CC Switch 当前厂商）", models: KIMI_MODELS }],
+      failures: [],
+    };
+  }
+
+  #providerEndpoint(providerId) {
+    let database;
+    try {
+      database = this.openDatabase(path.join(this.homeDir, ".cc-switch", "cc-switch.db"));
+      const row = database.prepare("SELECT url FROM provider_endpoints WHERE provider_id = ? AND app_type = 'claude' LIMIT 1").get(providerId);
+      return row?.url ?? null;
+    } catch {
+      return null;
+    } finally {
+      database?.close();
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,199 @@
+import { randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import QRCode from "qrcode";
+
+const sourceDir = path.dirname(fileURLToPath(import.meta.url));
+const bridgeRoot = path.resolve(sourceDir, "..");
+const cliEntry = path.join(bridgeRoot, "bin", "agentbridge.js");
+
+export function parseCliArguments(argv) {
+  const command = argv[0]?.startsWith("-") ? "phone" : argv.shift() ?? "phone";
+  const options = {};
+  if (command === "setup" && argv[0] && !argv[0].startsWith("-")) {
+    options.target = argv.shift().toLowerCase();
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const item = argv[index];
+    if (!item.startsWith("--")) throw new Error(`Unexpected argument: ${item}`);
+    const key = item.slice(2);
+    if (["json", "no-start", "user", "project", "help"].includes(key)) {
+      options[key] = true;
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) throw new Error(`Missing value for --${key}`);
+    options[key] = value;
+    index += 1;
+  }
+  return { command, options };
+}
+
+export function renderClaudePhoneSkill(entryPath = cliEntry) {
+  const portableEntry = entryPath.replaceAll("\\", "/").replaceAll('"', '\\"');
+  return `---
+name: phone
+description: Generate a one-time WeChat QR code bound to this exact Claude Code conversation and project directory.
+disable-model-invocation: true
+allowed-tools: Bash(node "${portableEntry}" phone --agent claude --session * --cwd .)
+---
+
+# Send this Claude conversation to AgentBridge
+
+Generate a short-lived QR code for the current conversation. The command output is authoritative; reproduce it without changing the URL or QR layout.
+
+!\`node "${portableEntry}" phone --agent claude --session "\${CLAUDE_SESSION_ID}" --cwd .\`
+
+Tell the user to scan the QR with WeChat. While the phone controls this session, keep this terminal idle so messages do not interleave.
+`;
+}
+
+export function renderCodexPhoneSkill(entryPath = cliEntry) {
+  const portableEntry = entryPath.replaceAll("\\", "/").replaceAll('"', '\\"');
+  return `---
+name: phone
+description: Generate a one-time WeChat QR code for a Codex project conversation. Use only when the user explicitly invokes /phone.
+disable-model-invocation: true
+---
+
+# Send a Codex project to AgentBridge
+
+When the user invokes \`/phone\`, you must immediately execute the following command in the terminal from the current project directory. Do not merely describe the command or ask the user to run it:
+
+\`node "${portableEntry}" phone --agent codex --cwd .\`
+
+After a successful command, reply with the exact QR image Markdown emitted by the command (for example, \`![微信扫码二维码](<temporary QR image URL>)\`) so Codex Desktop renders a scannable image. The temporary QR image URL and pairing URL must be shown as clickable links; then tell the user to scan the 微信扫码二维码 with WeChat. Do not invent or alter either URL. If the command fails, show its exact safe error and do not claim that a QR code was generated.
+
+If the user supplies a known persisted Codex thread ID, append \`--session <thread-id>\` to resume that exact thread. Do not claim that the command attached the current desktop conversation when no thread ID was supplied: Codex does not expose a documented current-thread substitution to this local skill.
+`;
+}
+
+function help() {
+  return `AgentBridge phone launcher
+
+Usage:
+  agentbridge phone [--agent claude|codex|echo] [--session ID] [--cwd PATH] [--title TEXT]
+  agentbridge setup <codex|claude> [--user|--project] [--cwd PATH]
+  agentbridge install-claude-skill [--user|--project] [--cwd PATH]
+  agentbridge install-codex-skill [--user|--project] [--cwd PATH]
+
+Examples:
+  agentbridge phone --agent codex
+  agentbridge phone --agent claude --session <claude-session-id>
+  agentbridge setup codex
+  agentbridge install-claude-skill --user`;
+}
+
+async function bridgeIsReady(origin) {
+  try {
+    const response = await fetch(`${origin}/api/health`, { signal: AbortSignal.timeout(700) });
+    const body = response.ok ? await response.json() : null;
+    return body?.ok === true;
+  } catch {
+    return false;
+  }
+}
+
+async function ensureBridge(origin, autoStart) {
+  if (await bridgeIsReady(origin)) return;
+  if (!autoStart) throw new Error(`Bridge is not running at ${origin}`);
+  const child = spawn(process.execPath, [path.join(bridgeRoot, "src", "server.js")], {
+    cwd: bridgeRoot,
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+  });
+  child.unref();
+  for (let attempt = 0; attempt < 30; attempt += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 100));
+    if (await bridgeIsReady(origin)) return;
+  }
+  throw new Error(`Could not start Bridge at ${origin}`);
+}
+
+async function requestPhone(options) {
+  const port = process.env.AGENTBRIDGE_PORT ?? "8787";
+  const origin = (process.env.AGENTBRIDGE_LOCAL_ORIGIN ?? `http://127.0.0.1:${port}`).replace(/\/$/, "");
+  await ensureBridge(origin, !options["no-start"]);
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const adapterId = options.agent ?? "claude";
+  const response = await fetch(`${origin}/api/local/phone`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({
+      cwd,
+      adapterId,
+      providerSessionId: options.session || undefined,
+      title: options.title || `${path.basename(cwd)} · ${adapterId}`,
+      commandId: randomUUID(),
+    }),
+  });
+  const result = await response.json().catch(() => ({}));
+  if (!response.ok) throw new Error(result.error ?? `Phone pairing failed (${response.status})`);
+
+  if (options.json) {
+    console.log(JSON.stringify(result));
+    return result;
+  }
+  const qr = await QRCode.toString(result.pairing.url, { type: "terminal", small: true, errorCorrectionLevel: "M" });
+  console.log(`\nAgentBridge 已绑定当前对话`);
+  console.log(`Agent: ${adapterId}`);
+  console.log(`项目: ${cwd}`);
+  console.log(`会话: ${result.session.providerSessionId ?? result.session.id}`);
+  console.log(`有效期: ${new Date(result.pairing.expiresAt).toLocaleTimeString()}（一次性）\n`);
+  console.log(qr);
+  if (result.qrImageUrl) {
+    console.log(`临时二维码图片地址（仅本机；扫码、配对成功或到期后失效）: ${result.qrImageUrl}`);
+    console.log(`二维码图片 Markdown: ![微信扫码二维码](${result.qrImageUrl})`);
+  }
+  console.log(`微信扫码地址: ${result.pairing.url}`);
+  console.log(`电脑端会话: ${origin}/?session=${encodeURIComponent(result.session.id)}\n`);
+  return result;
+}
+
+async function installClaudeSkill(options) {
+  if (options.user && options.project) throw new Error("Choose only one of --user or --project");
+  const projectCwd = path.resolve(options.cwd ?? process.cwd());
+  const root = options.project
+    ? path.join(projectCwd, ".claude", "skills")
+    : path.join(os.homedir(), ".claude", "skills");
+  const target = path.join(root, "phone", "SKILL.md");
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, renderClaudePhoneSkill(), { encoding: "utf8", flag: "w" });
+  console.log(`Claude Code /phone 已安装到: ${target}`);
+  console.log("重新打开 Claude Code 后，输入 /phone 即可生成当前对话的微信二维码。");
+  return target;
+}
+
+async function installCodexSkill(options) {
+  if (options.user && options.project) throw new Error("Choose only one of --user or --project");
+  const projectCwd = path.resolve(options.cwd ?? process.cwd());
+  const root = options.project
+    ? path.join(projectCwd, ".agents", "skills")
+    : path.join(os.homedir(), ".agents", "skills");
+  const target = path.join(root, "phone", "SKILL.md");
+  await mkdir(path.dirname(target), { recursive: true });
+  await writeFile(target, renderCodexPhoneSkill(), { encoding: "utf8", flag: "w" });
+  console.log(`Codex /phone 已安装到: ${target}`);
+  console.log("重新打开 Codex 桌面项目后，在斜杠命令列表选择 /phone。未提供 thread ID 时，它会创建新的项目会话并清楚标注。");
+  return target;
+}
+
+async function setup(options) {
+  if (options.target === "codex") return installCodexSkill(options);
+  if (options.target === "claude") return installClaudeSkill(options);
+  throw new Error("Setup target must be one of: codex, claude");
+}
+
+export async function main(inputArgs) {
+  const { command, options } = parseCliArguments([...inputArgs]);
+  if (command === "help" || options.help) return console.log(help());
+  if (command === "phone" || command === "qr") return requestPhone(options);
+  if (command === "setup") return setup(options);
+  if (command === "install-claude-skill") return installClaudeSkill(options);
+  if (command === "install-codex-skill") return installCodexSkill(options);
+  throw new Error(`Unknown command: ${command}\n\n${help()}`);
+}

package/src/config.js

@@ -0,0 +1,127 @@
+import os from "node:os";
+import path from "node:path";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+
+function firstLanAddress() {
+  for (const entries of Object.values(os.networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (entry.family === "IPv4" && !entry.internal) return entry.address;
+    }
+  }
+  return "127.0.0.1";
+}
+
+function parseProjects(raw, workspace) {
+  if (!raw) return new Map([["workspace", path.resolve(workspace)]]);
+
+  const projects = new Map();
+  for (const part of raw.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 1) throw new Error(`Invalid AGENTBRIDGE_PROJECTS entry: ${part}`);
+    const alias = part.slice(0, separator).trim();
+    const projectPath = part.slice(separator + 1).trim();
+    if (!/^[a-zA-Z0-9_-]{1,40}$/.test(alias) || !projectPath) {
+      throw new Error(`Invalid project alias or path: ${part}`);
+    }
+    projects.set(alias, path.resolve(projectPath));
+  }
+  if (projects.size === 0) throw new Error("At least one allowed project is required");
+  return projects;
+}
+
+/**
+ * Notification settings can also live in `.agentbridge/notify.json`.
+ *
+ * Environment variables are awkward to keep on Windows (a double-clicked launcher
+ * inherits no shell environment), and a webhook token is a credential that must not
+ * end up in a tracked file. The bridge's own data directory is git-ignored, so a
+ * small JSON file there is the honest place for it; environment variables still win
+ * when both are present, which keeps `setx` and one-off experiments working.
+ */
+function readNotifyFile(dataDir) {
+  try {
+    const parsed = JSON.parse(readFileSync(path.join(dataDir, "notify.json"), "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+function pick(env, key, fallback) {
+  const value = String(env[key] ?? "").trim();
+  return value || fallback || null;
+}
+
+/** The persisted block, for callers that need to read it directly. */
+export function readNotifyConfig(dataDir) {
+  return readNotifyFile(dataDir);
+}
+
+/**
+ * Patch `.agentbridge/notify.json` without losing the rest of it.
+ *
+ * Written atomically (tmp + rename) because a half-written file after a power loss
+ * would silently disable notifications; the merge is what keeps the token intact when
+ * only `muted` changes.
+ */
+export function writeNotifyConfig(dataDir, patch) {
+  const next = { ...readNotifyFile(dataDir), ...patch };
+  mkdirSync(dataDir, { recursive: true });
+  const target = path.join(dataDir, "notify.json");
+  const temporary = `${target}.tmp`;
+  writeFileSync(temporary, JSON.stringify(next, null, 2), "utf8");
+  renameSync(temporary, target);
+  return next;
+}
+
+export function loadConfig(env = process.env, workspace = process.cwd()) {
+  const port = Number.parseInt(env.AGENTBRIDGE_PORT ?? "8787", 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error("AGENTBRIDGE_PORT must be a valid TCP port");
+  }
+
+  const host = env.AGENTBRIDGE_HOST ?? "0.0.0.0";
+  const publicOrigin = (env.AGENTBRIDGE_PUBLIC_ORIGIN ?? "").replace(/\/$/, "");
+  const advertisedOrigin = publicOrigin || `http://${firstLanAddress()}:${port}`;
+  const accessKey = (env.AGENTBRIDGE_ACCESS_KEY ?? "").trim() || null;
+  const dataDir = path.resolve(env.AGENTBRIDGE_DATA_DIR ?? path.join(workspace, ".agentbridge"));
+  const notifyFile = readNotifyFile(dataDir);
+
+  return {
+    host,
+    port,
+    advertisedOrigin,
+    accessKey,
+    secureCookies: advertisedOrigin.startsWith("https://"),
+    dataDir,
+    projects: parseProjects(env.AGENTBRIDGE_PROJECTS, workspace),
+    pairingTtlMs: Number.parseInt(env.AGENTBRIDGE_PAIRING_TTL_MS ?? "300000", 10),
+    sessionTtlMs: Number.parseInt(env.AGENTBRIDGE_SESSION_TTL_MS ?? "259200000", 10),
+    machineName: env.AGENTBRIDGE_MACHINE_NAME ?? os.hostname(),
+    // Outbound notifications: unset webhook means the feature is simply off.
+    notifyWebhook: pick(env, "AGENTBRIDGE_NOTIFY_WEBHOOK", notifyFile.webhook),
+    notifyFormat: pick(env, "AGENTBRIDGE_NOTIFY_FORMAT", notifyFile.format ?? "json").toLowerCase(),
+    notifyChatId: pick(env, "AGENTBRIDGE_NOTIFY_CHAT_ID", notifyFile.chatId),
+    // PushPlus-style services need the token inside the request body.
+    notifyToken: pick(env, "AGENTBRIDGE_NOTIFY_TOKEN", notifyFile.token),
+    // Some providers (PushPlus) also take a delivery channel, e.g. `clawbot`.
+    notifyChannel: pick(env, "AGENTBRIDGE_NOTIFY_CHANNEL", notifyFile.channel),
+    // Per-bridge mute, toggled from the phone; persisted so it survives a restart.
+    notifyMuted: notifyFile.muted === true,
+    // Opt-in: putting the access key into a third-party chat is a real disclosure,
+    // so the notification link stays keyless unless the operator asks for it.
+    notifyLink: notifyFile.link === true || pick(env, "AGENTBRIDGE_NOTIFY_LINK", null) === "1",
+  };
+}
+
+/** The URL a notification should offer; never includes the access key by default. */
+export function notificationLink(config) {
+  if (!config?.advertisedOrigin) return null;
+  const base = config.advertisedOrigin;
+  if (!config.notifyLink) return base;
+  return config.accessKey ? `${base}/?key=${encodeURIComponent(config.accessKey)}` : base;
+}
+
+export function isLoopback(address = "") {
+  return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}