@chenacc/agentbridge 0.1.2 → 0.1.4

package/README.md

@@ -145,6 +145,8 @@ scripts\start-agentbridge.ps1 -CloudflareTunnel       # 3. 启动，窗口会打
 
 技能是纯文本文件，删掉对应的 `SKILL.md` 就等于卸载。
 
+二维码默认是**公网地址**（走 Cloudflare 隧道，手机用流量也能扫）。隧道要用的 `cloudflared` 缺了就自动下载到 `~/.agentbridge/bin`，和 DSH 插件共用同一套逻辑、同一个隧道和同一把访问密钥——DSH 那边已经开着隧道的话，CLI 直接复用，不会再起一条。只想在局域网用就设 `AGENTBRIDGE_NO_TUNNEL=1`；已经有自己的公网入口（命名隧道、Tailscale、ZeroTier）就设 `AGENTBRIDGE_PUBLIC_ORIGIN`。
+
 ### Claude Code
 
 ```powershell
@@ -178,13 +180,9 @@ node .\bin\agentbridge.js phone --agent codex --session <thread-id>
 
 **第 0 步：桥。** 插件是遥控器，桥是基站。从 0.2.0 起桥随插件一起安装，**DSH Desktop 启动时插件会自己在后台把它拉起来**，正常情况你什么都不用敲。
 
-从 0.3.0 起，插件默认再开一条 **Cloudflare 隧道**，把桥映射成公网 https 域名，于是手机不必和电脑在同一个 Wi-Fi——扫描、出差、用流量都能开。这一步需要一个 Cloudflare 官方小工具：
-
-```powershell
-winget install --id Cloudflare.cloudflared
-```
+从 0.3.0 起，插件默认再开一条 **Cloudflare 隧道**，把桥映射成公网 https 域名，于是手机不必和电脑在同一个 Wi-Fi——扫码、出差、用流量都能开。隧道要用的 `cloudflared`（Cloudflare 官方客户端）同样是自动的：先找本机已有的那份，找不到就自己从官方 GitHub Releases 下到 `~/.agentbridge/bin`（约 55 MB，只下一次，不要管理员权限，下载后跑一次 `cloudflared --version` 验证才留下）。
 
-没装也不影响使用，只是退回"手机与电脑同一 Wi-Fi"。想一直走局域网，设 `AGENTBRIDGE_NO_TUNNEL=1`；想用固定域名，去 Cloudflare 建命名隧道并把 `AGENTBRIDGE_PUBLIC_ORIGIN` 指向它。
+想自己装也行：`winget install --id Cloudflare.cloudflared`。下不动（断网、公司代理）照样能用，只是退回"手机与电脑同一 Wi-Fi"。想一直走局域网，设 `AGENTBRIDGE_NO_TUNNEL=1`；想用固定域名，去 Cloudflare 建命名隧道并把 `AGENTBRIDGE_PUBLIC_ORIGIN` 指向它。
 
 只有自动启动失败（沙箱限制、端口被占）才需要手动来一条：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chenacc/agentbridge",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Control local coding agents from a phone through a secure WeChat QR web console.",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,12 @@
   "bin": {
     "agentbridge": "bin/agentbridge.js"
   },
+  "exports": {
+    ".": "./src/server.js",
+    "./server": "./src/server.js",
+    "./tunnel": "./src/tunnel.js",
+    "./package.json": "./package.json"
+  },
   "engines": {
     "node": ">=22"
   },
@@ -58,7 +64,7 @@
     "verify:responsive": "node scripts/verify-responsive.mjs",
     "verify:guide": "node scripts/verify-product-guide.mjs",
     "verify:release": "node scripts/verify-plugin-release.mjs",
-    "check": "node --check src/server.js && node --check src/cli.js && node --check src/config.js && node --check src/cc-switch-models.js && node --check src/workspaces/workspace-catalog.js && node --check src/conversations/conversation-catalog.js && node --check src/adapters/capabilities.js && node --check src/adapters/claude.js && node --check src/adapters/codex.js && node --check src/adapters/deepseek-harness.js && node --check src/adapters/dsh-desktop.js && node --check src/dsh-desktop-channels.js && node --check src/event-store.js && node --check src/notifier.js && node --check src/attachments.js && node --check src/session-manager.js && node --check integrations/dsh-phone/lib/index.js && node --check integrations/dsh-phone/lib/tunnel.js && node --check src/adapters/zcode-native.js && node --check public/adapter-capabilities.js && node --check public/workspace-navigation.js && node --check public/markdown.js && node --check public/highlight.js && node --check public/transcript.js && node --check public/app.js && node --check scripts/verify-workspace-ui.mjs && node --check scripts/verify-message-blocks.mjs && node --check scripts/verify-background-scrim.mjs && node --check scripts/verify-model-control.mjs && node --check scripts/verify-notifications.mjs && node --check scripts/verify-attachments.mjs && node --check scripts/verify-features.mjs && node --check scripts/verify-quick-nav.mjs && node --check scripts/verify-questions.mjs && node --check scripts/verify-responsive.mjs && node --check scripts/verify-product-guide.mjs && node --check scripts/verify-plugin-release.mjs",
+    "check": "node --check src/server.js && node --check src/cli.js && node --check src/config.js && node --check src/cc-switch-models.js && node --check src/workspaces/workspace-catalog.js && node --check src/conversations/conversation-catalog.js && node --check src/adapters/capabilities.js && node --check src/adapters/claude.js && node --check src/adapters/codex.js && node --check src/adapters/deepseek-harness.js && node --check src/adapters/dsh-desktop.js && node --check src/dsh-desktop-channels.js && node --check src/event-store.js && node --check src/notifier.js && node --check src/attachments.js && node --check src/session-manager.js && node --check integrations/dsh-phone/lib/index.js && node --check src/tunnel.js && node --check src/adapters/zcode-native.js && node --check public/adapter-capabilities.js && node --check public/workspace-navigation.js && node --check public/markdown.js && node --check public/highlight.js && node --check public/transcript.js && node --check public/app.js && node --check scripts/verify-workspace-ui.mjs && node --check scripts/verify-message-blocks.mjs && node --check scripts/verify-background-scrim.mjs && node --check scripts/verify-model-control.mjs && node --check scripts/verify-notifications.mjs && node --check scripts/verify-attachments.mjs && node --check scripts/verify-features.mjs && node --check scripts/verify-quick-nav.mjs && node --check scripts/verify-questions.mjs && node --check scripts/verify-responsive.mjs && node --check scripts/verify-product-guide.mjs && node --check scripts/verify-plugin-release.mjs",
     "verify:remote": "node scripts/verify-remote-tunnel.mjs"
   },
   "dependencies": {

package/src/cli.js

@@ -5,6 +5,7 @@ import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import QRCode from "qrcode";
+import { ensureAccessKey, ensureCloudflared, findCloudflared, startQuickTunnel } from "./tunnel.js";
 
 const sourceDir = path.dirname(fileURLToPath(import.meta.url));
 const bridgeRoot = path.resolve(sourceDir, "..");
@@ -87,29 +88,143 @@ Examples:
   agentbridge install-claude-skill --user`;
 }
 
-async function bridgeIsReady(origin) {
+async function bridgeHealth(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;
+    return body?.ok === true ? body : null;
   } catch {
-    return false;
+    return null;
   }
 }
 
-async function ensureBridge(origin, autoStart) {
-  if (await bridgeIsReady(origin)) return;
-  if (!autoStart) throw new Error(`Bridge is not running at ${origin}`);
+async function bridgeIsReady(origin) {
+  return (await bridgeHealth(origin)) !== null;
+}
+
+/** Whether a host:port is only reachable from the same network. */
+export function isPrivateHost(hostname) {
+  const host = String(hostname ?? "").replace(/^\[|\]$/g, "").toLowerCase();
+  if (!host) return true;
+  if (host === "localhost" || host === "127.0.0.1" || host === "::1" || host.endsWith(".local")) return true;
+  if (/^10\./.test(host)) return true;
+  if (/^192\.168\./.test(host)) return true;
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return true;
+  // Tailscale and ZeroTier hand out addresses from these ranges, which are
+  // reachable from the phone only when it is on the same overlay.
+  if (/^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./.test(host)) return true;
+  return false;
+}
+
+export function describeOrigin(origin) {
+  try {
+    const url = new URL(origin);
+    return isPrivateHost(url.hostname) ? "private" : "public";
+  } catch {
+    return "private";
+  }
+}
+
+/**
+ * Where the tunnel state and the access key live.
+ *
+ * Deliberately the same directory the DSH plugin uses: if that plugin already
+ * brought a tunnel up to the same port, the CLI reuses it instead of opening a
+ * second one, and both sides read the same access key.
+ */
+function bridgeDataDir() {
+  return path.resolve(process.env.AGENTBRIDGE_DATA_DIR ?? path.join(os.homedir(), ".agentbridge"));
+}
+
+/**
+ * The public address the QR code should carry, if this run is going to have one.
+ *
+ * Returns null when the machine should stay on the LAN: the user opted out, the
+ * bridge is already running under someone else's address, or no tunnel could be
+ * brought up. Every one of those is a normal outcome — same-Wi-Fi pairing still
+ * works — so the reason is printed instead of thrown.
+ */
+export async function resolvePublicOrigin({ health, log = () => {}, env = process.env, dataDir = bridgeDataDir(), timeoutMs = 40_000 } = {}) {
+  const explicit = String(env.AGENTBRIDGE_PUBLIC_ORIGIN ?? "").trim().replace(/\/$/, "");
+  if (explicit) return { origin: explicit, accessKey: null, how: "AGENTBRIDGE_PUBLIC_ORIGIN" };
+
+  const supplied = String(env.AGENTBRIDGE_TUNNEL_URL ?? "").trim().replace(/\/$/, "");
+  if (supplied) return { origin: supplied, accessKey: ensureAccessKey(dataDir), how: "AGENTBRIDGE_TUNNEL_URL" };
+
+  if (env.AGENTBRIDGE_NO_TUNNEL === "1") {
+    log("AGENTBRIDGE_NO_TUNNEL=1: the QR code will only work on this Wi-Fi");
+    return null;
+  }
+  // An already-running bridge owns its address; asking it to move would mean
+  // restarting a service the user may be using right now.
+  if (health) {
+    const advertised = String(health.advertisedOrigin ?? "");
+    if (describeOrigin(advertised) === "public") return { origin: advertised, accessKey: null, how: "already running" };
+    log(`AgentBridge 已经在以局域网地址运行（${advertised || "unknown"}），本次二维码沿用这个地址。想换公网地址：先停掉它再重跑。`);
+    return null;
+  }
+
+  let command = findCloudflared({ env, home: os.homedir() });
+  if (!command) {
+    log("没有找到 cloudflared，正在从 Cloudflare 官方 Releases 下载（只下这一次）…");
+    command = await ensureCloudflared({ dataDir, env, log });
+  }
+  if (!command) {
+    log("仍然没有 cloudflared，二维码只能用在这台电脑所在 Wi-Fi 里。");
+    return null;
+  }
+
+  const port = new URL(`http://127.0.0.1:${env.AGENTBRIDGE_PORT ?? "8787"}`).port;
+  try {
+    const tunnel = await startQuickTunnel({
+      command,
+      origin: `http://127.0.0.1:${port}`,
+      dataDir,
+      log,
+      timeoutMs,
+    });
+    return { origin: tunnel.url, accessKey: ensureAccessKey(dataDir), how: tunnel.reused ? "cloudflare（复用已有隧道）" : "cloudflare" };
+  } catch (error) {
+    log(`Cloudflare 隧道没起来，二维码只能用在这台电脑所在 Wi-Fi 里：${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+async function startBridge(origin, env = {}) {
   const child = spawn(process.execPath, [path.join(bridgeRoot, "src", "server.js")], {
     cwd: bridgeRoot,
     detached: true,
     stdio: "ignore",
     windowsHide: true,
+    env: { ...process.env, ...env },
   });
   child.unref();
-  for (let attempt = 0; attempt < 30; attempt += 1) {
+  for (let attempt = 0; attempt < 60; attempt += 1) {
     await new Promise((resolve) => setTimeout(resolve, 100));
-    if (await bridgeIsReady(origin)) return;
+    if (await bridgeIsReady(origin)) return true;
+  }
+  return false;
+}
+
+async function ensureBridge(origin, autoStart, log = () => {}) {
+  const health = await bridgeHealth(origin);
+  if (health) return health;
+  if (!autoStart) throw new Error(`Bridge is not running at ${origin}`);
+
+  // The tunnel has to exist before the bridge starts, because the address is
+  // baked into the pairing URL at startup — the exact opposite of the DSH
+  // plugin, which keeps a local bridge up and restarts it once a tunnel exists.
+  const remote = await resolvePublicOrigin({ log });
+  const env = remote?.accessKey
+    ? { AGENTBRIDGE_PUBLIC_ORIGIN: remote.origin, AGENTBRIDGE_ACCESS_KEY: remote.accessKey }
+    : {};
+  if (await startBridge(origin, env)) {
+    if (remote) log(`公网地址就绪：${remote.origin}（${remote.how}）`);
+    return bridgeHealth(origin);
+  }
+  if (Object.keys(env).length) {
+    log("带公网地址的桥没起来，退回只用这台电脑所在 Wi-Fi。");
+    if (await startBridge(origin)) return bridgeHealth(origin);
   }
   throw new Error(`Could not start Bridge at ${origin}`);
 }
@@ -117,7 +232,8 @@ async function ensureBridge(origin, autoStart) {
 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 log = (message) => console.error(`[agentbridge] ${message}`);
+  const health = await ensureBridge(origin, !options["no-start"], log);
   const cwd = path.resolve(options.cwd ?? process.cwd());
   const adapterId = options.agent ?? "claude";
   const response = await fetch(`${origin}/api/local/phone`, {
@@ -139,10 +255,14 @@ async function requestPhone(options) {
     return result;
   }
   const qr = await QRCode.toString(result.pairing.url, { type: "terminal", small: true, errorCorrectionLevel: "M" });
+  const network = describeOrigin(result.pairing.url) === "public"
+    ? "公网地址，手机用流量也能打开"
+    : "局域网地址，手机需与电脑连同一个 Wi-Fi";
   console.log(`\nAgentBridge 已绑定当前对话`);
   console.log(`Agent: ${adapterId}`);
   console.log(`项目: ${cwd}`);
   console.log(`会话: ${result.session.providerSessionId ?? result.session.id}`);
+  console.log(`网络: ${network}`);
   console.log(`有效期: ${new Date(result.pairing.expiresAt).toLocaleTimeString()}（一次性）\n`);
   console.log(qr);
   if (result.qrImageUrl) {

package/src/config.js

@@ -170,6 +170,10 @@ export function loadConfig(env = process.env, workspace = process.cwd()) {
     // recognise its own child in /api/health and restart it to change the public
     // address, without ever touching a bridge the user started by hand.
     autostart: env.AGENTBRIDGE_AUTOSTART === "1",
+    // Shared secret between the plugin that spawned this bridge and the bridge
+    // itself, so the plugin may ask for a restart to change the advertised address
+    // without handing that power to anything else that can reach loopback.
+    autostartToken: (env.AGENTBRIDGE_AUTOSTART_TOKEN ?? "").trim() || null,
     // 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(),

package/src/server.js

@@ -386,6 +386,25 @@ export async function createBridge(options = {}) {
     return shutdownPromise;
   };
 
+  /**
+   * A restart requested by the plugin must not cut a running Agent turn in half.
+   *
+   * The plugin retries on the next desktop launch in that case; refusing is the
+   * safer answer than silently killing work the user is waiting on.
+   */
+  const refuseWhenBusy = () => {
+    const active = sessions.list().filter((session) => ["starting", "running", "stopping"].includes(session.status));
+    if (!active.length) return;
+    throw Object.assign(new Error("仍有 Agent 任务正在运行，请先停止任务再关闭 Bridge"), {
+      statusCode: 409,
+      code: "ACTIVE_SESSIONS",
+      diagnostics: {
+        count: active.length,
+        sessions: active.map(({ id, title, status, adapterId }) => ({ id, title, status, adapterId })),
+      },
+    });
+  };
+
   const server = http.createServer(async (req, res) => {
     const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
     try {
@@ -654,6 +673,31 @@ export async function createBridge(options = {}) {
       // point remain authenticated (and gated by the access key when enabled).
       if (req.method === "GET" && await serveStatic(res, url.pathname, url.search)) return;
 
+      // The DSH plugin starts this bridge itself and sometimes has to restart it,
+      // because the address it advertises (cloudflared hostname) only exists after
+      // the tunnel is up. Restarting needs a stop, and a stop needs an
+      // authorisation: loopback alone would let any local page POST here, so the
+      // caller must also present the token the plugin generated when it spawned
+      // this process. The token lives in the bridge's data directory, which keeps
+      // it out of the command line and out of the logs.
+      if (req.method === "POST" && url.pathname === "/api/local/autostart/shutdown") {
+        if (!isLoopback(req.socket.remoteAddress)) throw Object.assign(new Error("Local access only"), { statusCode: 403 });
+        if (!config.autostartToken || !keyMatches(req.headers["x-agentbridge-autostart"], config.autostartToken)) {
+          throw Object.assign(new Error("Autostart token required"), { statusCode: 401 });
+        }
+        refuseWhenBusy();
+        shuttingDown = true;
+        json(res, 202, { accepted: true, message: "AgentBridge is restarting to change its public address" });
+        setImmediate(() => {
+          void shutdown().catch((error) => {
+            console.error("AgentBridge safe shutdown failed", error);
+            shuttingDown = false;
+            shutdownPromise = null;
+          });
+        });
+        return;
+      }
+
       requireAccessKey(req, url, config);
       const device = pairing.authenticate(requestToken(req));
       if (!device) throw Object.assign(new Error("Authentication required"), { statusCode: 401 });
@@ -794,17 +838,7 @@ export async function createBridge(options = {}) {
       let match;
       if (req.method === "POST" && url.pathname === "/api/local/shutdown") {
         if (!isLoopback(req.socket.remoteAddress)) throw Object.assign(new Error("Local access only"), { statusCode: 403 });
-        const active = sessions.list().filter((session) => ["starting", "running", "stopping"].includes(session.status));
-        if (active.length) {
-          throw Object.assign(new Error("仍有 Agent 任务正在运行，请先停止任务再关闭 Bridge"), {
-            statusCode: 409,
-            code: "ACTIVE_SESSIONS",
-            diagnostics: {
-              count: active.length,
-              sessions: active.map(({ id, title, status, adapterId }) => ({ id, title, status, adapterId })),
-            },
-          });
-        }
+        refuseWhenBusy();
         shuttingDown = true;
         json(res, 202, { accepted: true, message: "AgentBridge 正在安全停止" });
         setImmediate(() => {

package/src/tunnel.js

@@ -0,0 +1,448 @@
+/**
+ * Cloudflare quick tunnel, so the phone does not have to share a Wi-Fi with the PC.
+ *
+ * A LAN-only QR code is a dead end the moment the user leaves the house, and it is
+ * also what WeChat likes least (an http URL with a bare IP address in it). A
+ * `cloudflared` quick tunnel hands back a real https hostname, which the phone can
+ * open from anywhere — at the cost of two honest caveats:
+ *
+ *  - the hostname is random and changes whenever the tunnel is recreated, so a
+ *    phone bookmark only lasts as long as the process keeps running;
+ *  - it is a public URL, so the bridge in front of it must keep its access key on.
+ *
+ * Everything here is deliberately side-effect free until called, and every
+ * environment-dependent lookup takes an injectable dependency, because this code
+ * decides whether a public URL exists at all and that is worth testing.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import https from "node:https";
+import os from "node:os";
+import path from "node:path";
+import tls from "node:tls";
+
+/**
+ * A quick tunnel hostname.
+ *
+ * The negative lookahead is load-bearing: cloudflared's own failure messages quote
+ * `https://api.trycloudflare.com/tunnel`, which matches a naive pattern and would
+ * be mistaken for the tunnel the phone should open.
+ */
+export const TUNNEL_URL_PATTERN = /https:\/\/(?!api\.)[-a-z0-9]+\.trycloudflare\.com/;
+
+// cloudflared writes the banner to stderr, but stdout is cheap to read too and
+// some builds differ.
+export function extractTunnelUrl(text) {
+  const match = TUNNEL_URL_PATTERN.exec(String(text ?? ""));
+  return match ? match[0] : null;
+}
+
+/**
+ * Where `cloudflared` usually lives on Windows, best first.
+ *
+ * PATH is included because `winget` installs a shim there, and the two Program
+ * Files directories cover the MSI, which does not touch PATH from a non-elevated
+ * shell. `AGENTBRIDGE_CLOUDFLARED` wins over all of it for unusual installs.
+ */
+export function cloudflaredCandidates(env = process.env, home = os.homedir()) {
+  const candidates = [];
+  if (env.AGENTBRIDGE_CLOUDFLARED) candidates.push(env.AGENTBRIDGE_CLOUDFLARED);
+  for (const dir of String(env.PATH ?? "").split(path.delimiter)) {
+    if (!dir) continue;
+    candidates.push(path.join(dir, "cloudflared.exe"), path.join(dir, "cloudflared"));
+  }
+  if (env.ProgramFiles) candidates.push(path.join(env.ProgramFiles, "cloudflared", "cloudflared.exe"));
+  if (env["ProgramFiles(x86)"]) candidates.push(path.join(env["ProgramFiles(x86)"], "cloudflared", "cloudflared.exe"));
+  if (env.LOCALAPPDATA) candidates.push(path.join(env.LOCALAPPDATA, "Microsoft", "WinGet", "Links", "cloudflared.exe"));
+  // The bridge's own data directory is a last resort for a portable copy the user
+  // downloaded by hand.
+  candidates.push(path.join(home, ".agentbridge", "bin", "cloudflared.exe"));
+  return candidates;
+}
+
+export function findCloudflared({ env = process.env, home = os.homedir(), exists = existsSync } = {}) {
+  for (const candidate of cloudflaredCandidates(env, home)) {
+    try {
+      if (exists(candidate)) return candidate;
+    } catch {
+      // An unreadable PATH entry is not worth failing the whole search.
+    }
+  }
+  return null;
+}
+
+/** The official release asset for this machine, or null when there is none. */
+export function cloudflaredAssetUrl({ platform = process.platform, arch = process.arch } = {}) {
+  if (platform === "win32" && arch === "x64") {
+    return "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-amd64.exe";
+  }
+  if (platform === "win32" && arch === "arm64") {
+    return "https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-windows-arm64.exe";
+  }
+  return null;
+}
+
+export function cloudflaredBinaryPath(dataDir, { platform = process.platform } = {}) {
+  return path.join(dataDir, "bin", platform === "win32" ? "cloudflared.exe" : "cloudflared");
+}
+
+function cloudflaredVersionPath(dataDir) {
+  return path.join(dataDir, "bin", "cloudflared.json");
+}
+
+/**
+ * Proves a downloaded file is the real cloudflared before anything runs through it.
+ *
+ * `--version` is the honest test: it exercises the binary the tunnel is about to
+ * use, and the banner ("cloudflared version 2026.10.7 ...") is a shape no HTML
+ * error page or truncated download can produce.
+ */
+export async function cloudflaredVersion(command, { spawnImpl = spawn, timeoutMs = 20_000 } = {}) {
+  return new Promise((resolve) => {
+    let output = "";
+    let child;
+    try {
+      child = spawnImpl(command, ["--version"], { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    } catch {
+      return resolve(null);
+    }
+    const done = (value) => {
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      try { child.kill("SIGKILL"); } catch { /* already gone */ }
+      done(null);
+    }, timeoutMs);
+    timer.unref?.();
+    child.stdout?.on("data", (chunk) => { output += String(chunk); });
+    child.stderr?.on("data", (chunk) => { output += String(chunk); });
+    child.once?.("error", () => done(null));
+    child.once?.("exit", () => {
+      const match = /cloudflared version v?(\d+\.\d+\.\d+\S*)/i.exec(output);
+      done(match ? match[1] : null);
+    });
+  });
+}
+
+/**
+ * Fetch the official binary to `<dataDir>` and hand back its path.
+ *
+ * Two details make this work where a naive `fetch` would not: GitHub redirects to
+ * a versioned asset host, and on machines behind a TLS-inspecting proxy (common in
+ * corporate networks and in China) the OS trust store is the only thing that
+ * verifies the certificate — so the request carries the system roots alongside
+ * Node's bundled ones.
+ */
+function downloadToFile(url, target, { log = () => {}, maxRedirects = 5, timeoutMs = 120_000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const ca = (() => {
+      try {
+        const system = typeof tls.getCACertificates === "function" ? tls.getCACertificates("system") : [];
+        return [...tls.rootCertificates, ...system];
+      } catch {
+        return undefined;
+      }
+    })();
+
+    const get = (current, redirectsLeft) => {
+      const request = https.get(current, {
+        ...(ca ? { ca } : {}),
+        headers: { "user-agent": "agentbridge-dsh-phone", accept: "application/octet-stream" },
+        timeout: timeoutMs,
+      }, (response) => {
+        const status = response.statusCode ?? 0;
+        if (status >= 300 && status < 400 && response.headers.location) {
+          response.resume();
+          if (redirectsLeft <= 0) return reject(new Error("too many redirects"));
+          return get(new URL(response.headers.location, current).href, redirectsLeft - 1);
+        }
+        if (status !== 200) {
+          response.resume();
+          return reject(new Error(`HTTP ${status} downloading ${current}`));
+        }
+        const expected = Number(response.headers["content-length"] ?? 0);
+        if (expected) log(`downloading ${(expected / 1024 / 1024).toFixed(1)} MB from Cloudflare`);
+        const file = createWriteStream(target);
+        let written = 0;
+        let nextReport = 10 * 1024 * 1024;
+        response.on("data", (chunk) => {
+          written += chunk.length;
+          // A 55 MB download on a slow link otherwise looks like a hang.
+          if (written >= nextReport) {
+            nextReport += 10 * 1024 * 1024;
+            log(`cloudflared download: ${(written / 1024 / 1024).toFixed(0)} MB${expected ? ` of ${(expected / 1024 / 1024).toFixed(0)}` : ""}`);
+          }
+        });
+        response.pipe(file);
+        file.on("finish", () => file.close(() => {
+          // A truncated download that still "finished" is the failure mode that
+          // would otherwise land a corrupt exe on disk.
+          if (expected && written !== expected) return reject(new Error(`truncated download: ${written} of ${expected} bytes`));
+          resolve(written);
+        }));
+        file.on("error", reject);
+        response.on("error", reject);
+      });
+      request.on("timeout", () => request.destroy(new Error("download timed out")));
+      request.on("error", reject);
+    };
+
+    get(url, maxRedirects);
+  });
+}
+
+/**
+ * The cloudflared this machine should use, downloaded on first need.
+ *
+ * A missing cloudflared used to mean "same Wi-Fi only", which made the plugin's
+ * remote mode an opt-in nobody opted into. Downloading the official build into the
+ * bridge's own data directory keeps it out of Program Files, needs no elevation,
+ * and can be removed by deleting one folder.
+ */
+export async function ensureCloudflared({
+  dataDir,
+  env = process.env,
+  log = () => {},
+  platform = process.platform,
+  arch = process.arch,
+  exists = existsSync,
+  download = downloadToFile,
+  verify = cloudflaredVersion,
+  now = () => new Date().toISOString(),
+} = {}) {
+  const override = String(env.AGENTBRIDGE_CLOUDFLARED ?? "").trim();
+  if (override) {
+    return exists(override) ? override : null;
+  }
+
+  const target = cloudflaredBinaryPath(dataDir, { platform });
+
+  if (exists(target)) {
+    const version = await verify(target);
+    if (version) return target;
+    log(`the downloaded cloudflared at ${target} does not run; removing it and fetching a fresh copy`);
+    try { rmSync(target, { force: true }); } catch { /* a locked file just fails the download below */ }
+  }
+
+  const url = String(env.AGENTBRIDGE_CLOUDFLARED_URL ?? "").trim() || cloudflaredAssetUrl({ platform, arch });
+  if (!url) {
+    log(`no official cloudflared build for ${platform}/${arch}; install one yourself and point AGENTBRIDGE_CLOUDFLARED at it`);
+    return null;
+  }
+  if (env.AGENTBRIDGE_NO_DOWNLOAD === "1") {
+    log("cloudflared is not installed and AGENTBRIDGE_NO_DOWNLOAD=1 forbids downloading it");
+    return null;
+  }
+
+  const temporary = `${target}.download`;
+  try {
+    mkdirSync(path.dirname(target), { recursive: true });
+    await download(url, temporary, { log });
+    const version = await verify(temporary);
+    if (!version) throw new Error("the downloaded file does not report a cloudflared version");
+    renameSync(temporary, target);
+    try {
+      writeFileSync(cloudflaredVersionPath(dataDir), JSON.stringify({ version, url, downloadedAt: now() }, null, 2), "utf8");
+    } catch {
+      // The record is a convenience, not a requirement.
+    }
+    log(`cloudflared ${version} is ready at ${target}`);
+    return target;
+  } catch (error) {
+    try { rmSync(temporary, { force: true }); } catch { /* nothing to clean */ }
+    log(`could not fetch cloudflared from ${url}: ${error instanceof Error ? error.message : String(error)}`);
+    return null;
+  }
+}
+
+export function accessKeyPath(dataDir) {
+  return path.join(dataDir, "access-key");
+}
+
+export function autostartTokenPath(dataDir) {
+  return path.join(dataDir, "autostart-token");
+}
+
+/**
+ * The key that gates a publicly exposed bridge.
+ *
+ * Read before generated, so the value survives restarts: the phone already holds a
+ * cookie for it, and regenerating on every launch would silently lock the phone
+ * out of its own bridge.
+ */
+export function ensureAccessKey(dataDir, { readFile = readFileSync, writeFile = writeFileSync, mkdir = mkdirSync, random } = {}) {
+  return ensureSecret(accessKeyPath(dataDir), dataDir, { readFile, writeFile, mkdir, random });
+}
+
+/**
+ * The secret that lets this plugin ask its own bridge to restart.
+ *
+ * A restart is how the advertised address changes (the tunnel hostname only
+ * exists once cloudflared is up), and the bridge accepts that request only from
+ * loopback *with this token* — so a random local page cannot stop the bridge, and
+ * a second, unrelated DSH profile cannot either.
+ */
+export function ensureAutostartToken(dataDir, options = {}) {
+  return ensureSecret(autostartTokenPath(dataDir), dataDir, options);
+}
+
+export function readAutostartToken(dataDir, { readFile = readFileSync } = {}) {
+  try {
+    return String(readFile(autostartTokenPath(dataDir), "utf8")).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function ensureSecret(target, dataDir, { readFile = readFileSync, writeFile = writeFileSync, mkdir = mkdirSync, random } = {}) {
+  try {
+    const existing = String(readFile(target, "utf8")).trim();
+    if (existing.length >= 16) return existing;
+  } catch {
+    // No usable secret on disk yet.
+  }
+  const secret = (random ?? (() => randomBytes(24).toString("base64url")))();
+  mkdir(dataDir, { recursive: true });
+  writeFile(target, secret, "utf8");
+  return secret;
+}
+
+export function tunnelStatePath(dataDir) {
+  return path.join(dataDir, "cloudflare-tunnel.json");
+}
+
+export function readTunnelState(dataDir, { readFile = readFileSync } = {}) {
+  try {
+    const parsed = JSON.parse(String(readFile(tunnelStatePath(dataDir), "utf8")));
+    if (!parsed || typeof parsed.url !== "string" || !Number.isInteger(parsed.pid)) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeTunnelState(dataDir, state, { writeFile = writeFileSync, mkdir = mkdirSync, rename = renameSync } = {}) {
+  mkdir(dataDir, { recursive: true });
+  const target = tunnelStatePath(dataDir);
+  const temporary = `${target}.tmp`;
+  writeFile(temporary, JSON.stringify(state, null, 2), "utf8");
+  rename(temporary, target);
+  return state;
+}
+
+function isAlive(pid, { kill = process.kill.bind(process) } = {}) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    // EPERM means "exists but not ours", which still counts as alive.
+    return error?.code === "EPERM";
+  }
+}
+
+/**
+ * Start cloudflared and wait for the hostname it prints.
+ *
+ * The child is detached on purpose: the tunnel outliving DSH means the URL in an
+ * already paired phone keeps working after the desktop restarts, and it also
+ * avoids killing the tunnel whenever the Electron host decides to reload.
+ *
+ * Reuse is keyed on the state file plus a live pid plus a matching origin: a
+ * tunnel pointing at the old port would advertise a URL that resolves to a 502.
+ */
+export async function startQuickTunnel({
+  command,
+  origin,
+  dataDir,
+  log = () => {},
+  timeoutMs = 40_000,
+  spawnImpl = spawn,
+  fetchImpl = globalThis.fetch,
+  kill = process.kill.bind(process),
+} = {}) {
+  if (!command) throw new Error("cloudflared was not found");
+  if (!origin) throw new Error("the tunnel needs an origin to forward to");
+
+  const previous = readTunnelState(dataDir);
+  if (previous && previous.origin === origin && isAlive(previous.pid, { kill })) {
+    const reachable = await probeTunnel(previous.url, fetchImpl);
+    if (reachable) {
+      log(`reusing the running Cloudflare tunnel at ${previous.url}`);
+      return { ...previous, reused: true };
+    }
+    log(`the recorded tunnel is no longer answering; starting a new one`);
+  }
+
+  const child = spawnImpl(command, ["tunnel", "--no-autoupdate", "--url", origin], {
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  const state = await new Promise((resolve, reject) => {
+    let output = "";
+    let settled = false;
+
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      if (error) reject(error);
+      else resolve(value);
+    };
+
+    const timer = setTimeout(() => {
+      const tail = output.trim().split(/\r?\n/).slice(-6).join(" | ");
+      try {
+        kill(child.pid, "SIGKILL");
+      } catch {
+        // Already gone.
+      }
+      finish(new Error(`cloudflared did not announce a hostname within ${Math.round(timeoutMs / 1000)}s${tail ? `: ${tail}` : ""}`));
+    }, timeoutMs);
+    timer.unref?.();
+
+    const onData = (chunk) => {
+      output += String(chunk);
+      const url = extractTunnelUrl(output);
+      if (!url) return;
+      finish(null, {
+        url,
+        pid: child.pid,
+        origin,
+        startedAt: new Date().toISOString(),
+      });
+    };
+
+    child.stdout?.on?.("data", onData);
+    child.stderr?.on?.("data", onData);
+    child.once?.("error", (error) => finish(new Error(`cloudflared could not start: ${error.message}`)));
+    child.once?.("exit", (code) => {
+      const tail = output.trim().split(/\r?\n/).slice(-6).join(" | ");
+      finish(new Error(`cloudflared exited with code ${code} before announcing a hostname${tail ? `: ${tail}` : ""}`));
+    });
+  });
+
+  // The tunnel is meant to outlive this process; the pipes are only for the banner.
+  child.unref?.();
+  child.stdout?.destroy?.();
+  child.stderr?.destroy?.();
+  return writeTunnelState(dataDir, state) && { ...state, reused: false };
+}
+
+/**
+ * Anything but a transport error means the tunnel exists.
+ *
+ * A 502 is the normal answer while the local bridge is down, and it still proves
+ * Cloudflare's edge knows this hostname.
+ */
+async function probeTunnel(url, fetchImpl = globalThis.fetch) {
+  try {
+    await fetchImpl(`${url}/api/health`, { signal: AbortSignal.timeout(6_000) });
+    return true;
+  } catch {
+    return false;
+  }
+}