@automatebrowser/mcp 0.3.0

package/dist/relay.js

@@ -0,0 +1,919 @@
+import {
+  RELAY_ROLE,
+  WHOLE_TAB,
+  createAuthChallenge,
+  debugLog,
+  getAuthToken,
+  isControlClaim,
+  isControlHello,
+  isControlRelease,
+  isControlSend,
+  isLoopbackHost,
+  log,
+  logPath,
+  mcpConfig,
+  parseFrame,
+  probePort,
+  verifyAuthResponse
+} from "./chunk-R5JREBXQ.js";
+
+// src/ws.ts
+import { WebSocketServer } from "ws";
+var MAX_BIND_ROUNDS = 3;
+var INITIAL_BACKOFF_MS = 100;
+var DEFAULT_MAX_PAYLOAD_BYTES = 64 * 1048576;
+var DEFAULT_EXTENSION_ORIGIN = "chrome-extension://bjfgambnhccakkhmkepdoekmckoijdlc";
+function configuredExtensionOrigins() {
+  const raw = process.env.AUTOMATE_BROWSER_EXTENSION_ORIGINS;
+  const values = raw ? raw.split(",").map((v) => v.trim()).filter(Boolean) : [DEFAULT_EXTENSION_ORIGIN];
+  return new Set(values);
+}
+function maxPayloadBytes() {
+  const n = Number(process.env.AUTOMATE_BROWSER_WS_MAX_PAYLOAD_BYTES);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_PAYLOAD_BYTES;
+}
+function isAllowedWsOrigin(origin) {
+  if (!origin) return true;
+  return configuredExtensionOrigins().has(origin);
+}
+function bindOnce(port, host) {
+  return new Promise((resolve, reject) => {
+    const wss = new WebSocketServer({
+      host,
+      port,
+      maxPayload: maxPayloadBytes(),
+      verifyClient(info, done) {
+        if (isAllowedWsOrigin(info.origin)) {
+          done(true);
+          return;
+        }
+        log.warn(`[ws] rejected websocket origin ${info.origin || "(none)"}`);
+        done(false, 403, "Forbidden");
+      }
+    });
+    const onError = (err) => {
+      wss.off("listening", onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      wss.off("error", onError);
+      resolve(wss);
+    };
+    wss.once("error", onError);
+    wss.once("listening", onListening);
+  });
+}
+async function createWebSocketServer(range = mcpConfig.wsPortRange, host = "127.0.0.1") {
+  const [start, end] = range;
+  let lastErr;
+  for (let round = 0; round < MAX_BIND_ROUNDS; round++) {
+    for (let port = start; port <= end; port++) {
+      try {
+        const wss = await bindOnce(port, host);
+        log.info(`[ws] listening on ws://${host}:${port}`);
+        return { wss, port };
+      } catch (err) {
+        lastErr = err;
+        if (err?.code !== "EADDRINUSE") {
+          throw err;
+        }
+        debugLog(`[ws] port ${port} in use, trying next`);
+      }
+    }
+    const backoff = INITIAL_BACKOFF_MS * 2 ** round;
+    debugLog(
+      `[ws] ports ${start}-${end} all in use (round ${round + 1}/${MAX_BIND_ROUNDS}), retrying in ${backoff}ms`
+    );
+    await new Promise((r) => setTimeout(r, backoff));
+  }
+  throw new Error(
+    `No free port in range ${start}-${end}. Another automate-browser instance is likely running \u2014 close it and try again. Last error: ${String(lastErr)}`
+  );
+}
+
+// src/relay/log-file.ts
+import { appendFileSync } from "fs";
+var LEVELS = { debug: 10, info: 20, warn: 30, error: 40 };
+var minLevel = LEVELS[(process.env.AUTOMATE_BROWSER_LOG_LEVEL ?? "info").toLowerCase()] ?? LEVELS.info;
+var foreground = process.env.AUTOMATE_BROWSER_RELAY_FOREGROUND === "1";
+var RELAY_LOG_PATH = logPath("automate-browser-relay.log");
+function emit(level, args) {
+  if (LEVELS[level] < minLevel) return;
+  const body = args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" ");
+  const line = `[${(/* @__PURE__ */ new Date()).toISOString()}] [relay] [${level}] ${body}`;
+  try {
+    appendFileSync(RELAY_LOG_PATH, line + "\n");
+  } catch {
+  }
+  if (foreground) {
+    console.error(line);
+  }
+}
+var rlog = {
+  debug: (...a) => emit("debug", a),
+  info: (...a) => emit("info", a),
+  warn: (...a) => emit("warn", a),
+  error: (...a) => emit("error", a)
+};
+
+// src/relay/relay.ts
+import { randomUUID as randomUUID3 } from "crypto";
+
+// src/relay/browsers.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/vendor/messaging/ws-sender.ts
+import { randomUUID } from "crypto";
+import { WebSocket } from "ws";
+var DEFAULT_TIMEOUT_MS = 8e3;
+function parseResponse(raw) {
+  try {
+    const parsed = JSON.parse(String(raw));
+    return parsed !== null && typeof parsed === "object" ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function createSocketMessageSender(ws) {
+  function sendSocketMessage(type, payload, options = { timeoutMs: DEFAULT_TIMEOUT_MS }) {
+    return new Promise((resolve, reject) => {
+      if (!ws || ws.readyState !== WebSocket.OPEN) {
+        reject(new Error("WebSocket is not connected"));
+        return;
+      }
+      const id = randomUUID();
+      const cleanup = () => {
+        clearTimeout(timer);
+        ws.off("message", onMessage);
+      };
+      const onMessage = (raw) => {
+        const msg = parseResponse(raw);
+        if (!msg || msg.type !== "messageResponse") return;
+        const body = msg.payload;
+        if (!body || body.requestId !== id) return;
+        cleanup();
+        if (body.error) {
+          const err = body.error;
+          reject(
+            new Error(
+              typeof err === "string" ? err : err?.message || JSON.stringify(err)
+            )
+          );
+        } else {
+          resolve(body.result);
+        }
+      };
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error("Socket message timeout"));
+      }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+      ws.on("message", onMessage);
+      try {
+        ws.send(JSON.stringify({ id, type, payload }));
+      } catch (error) {
+        cleanup();
+        reject(error);
+      }
+    });
+  }
+  return { sendSocketMessage };
+}
+
+// src/relay/browsers.ts
+var BrowserRegistry = class {
+  _map = /* @__PURE__ */ new Map();
+  add(ws, meta) {
+    const id = randomUUID2();
+    const sender = createSocketMessageSender(ws).sendSocketMessage;
+    this._map.set(id, { id, ws, sender, meta, claims: /* @__PURE__ */ new Map() });
+    return id;
+  }
+  updateMeta(id, partial) {
+    const c = this._map.get(id);
+    if (!c) return;
+    Object.assign(
+      c.meta,
+      Object.fromEntries(Object.entries(partial).filter(([, v]) => v !== void 0))
+    );
+  }
+  remove(id) {
+    this._map.delete(id);
+  }
+  get(id) {
+    return this._map.get(id);
+  }
+  list() {
+    return [...this._map.values()];
+  }
+  size() {
+    return this._map.size;
+  }
+  /** The live (non-expired) claim on a given tab key, lazily clearing a lapsed one. */
+  liveClaim(id, tabKey) {
+    const c = this._map.get(id);
+    const claim = c?.claims.get(tabKey);
+    if (!claim) return void 0;
+    if (claim.leaseExpiry <= Date.now()) {
+      c.claims.delete(tabKey);
+      return void 0;
+    }
+    return claim;
+  }
+  /** All live claims on a browser (lazily clearing lapsed ones), with their tab ids. */
+  liveClaimsFor(id) {
+    const c = this._map.get(id);
+    if (!c) return [];
+    const now = Date.now();
+    const out = [];
+    for (const [tabId, claim] of c.claims) {
+      if (claim.leaseExpiry <= now) {
+        c.claims.delete(tabId);
+        continue;
+      }
+      out.push({ ...claim, tabId });
+    }
+    return out;
+  }
+  setClaim(id, tabKey, claim) {
+    const c = this._map.get(id);
+    if (c) c.claims.set(tabKey, claim);
+  }
+  clearClaim(id, tabKey) {
+    const c = this._map.get(id);
+    c?.claims.delete(tabKey);
+  }
+  /**
+   * Drop every claim this controller holds on one browser. Returns the tab keys
+   * that were freed (so the caller can decide whether to broadcast).
+   */
+  releaseClaimsOnBrowser(id, controllerId) {
+    const c = this._map.get(id);
+    if (!c) return [];
+    const freed = [];
+    for (const [tabKey, claim] of c.claims) {
+      if (claim.controllerId === controllerId) {
+        c.claims.delete(tabKey);
+        freed.push(tabKey);
+      }
+    }
+    return freed;
+  }
+  /** Drop every claim owned by a controller; returns the affected {browserId, tabId}. */
+  releaseByController(controllerId) {
+    const hit = [];
+    for (const c of this._map.values()) {
+      for (const [tabKey, claim] of c.claims) {
+        if (claim.controllerId === controllerId) {
+          c.claims.delete(tabKey);
+          hit.push({ browserId: c.id, tabId: tabKey });
+        }
+      }
+    }
+    return hit;
+  }
+  /**
+   * Serialisable roster for control frames. `active` is decided per-controller
+   * (Context recomputes it), so it is always false here. Live (non-expired)
+   * claims are included so controllers can show who is driving each tab.
+   */
+  info() {
+    return this.list().map((c) => {
+      const claims = this.liveClaimsFor(c.id);
+      return {
+        ...c.meta,
+        id: c.id,
+        active: false,
+        ...claims.length ? { claims } : {}
+      };
+    });
+  }
+};
+
+// src/relay/relay.ts
+var ROLE_TIMEOUT_MS = 3e3;
+var HEARTBEAT_INTERVAL_MS = 2e4;
+var IDLE_EXIT_MS = numEnv("AUTOMATE_BROWSER_RELAY_IDLE_MS", 3e5);
+var LEASE_TTL_MS = numEnv("AUTOMATE_BROWSER_LEASE_TTL_MS", 6e4);
+var RATE_WINDOW_MS = numEnv("AUTOMATE_BROWSER_WS_RATE_WINDOW_MS", 1e3);
+var RATE_MAX_MESSAGES = numEnv("AUTOMATE_BROWSER_WS_RATE_MAX", 120);
+var CONTROLLER_STALE_MS = numEnv("AUTOMATE_BROWSER_CONTROLLER_STALE_MS", 45e3);
+var REAP_INTERVAL_MS = Math.max(1e3, Math.floor(CONTROLLER_STALE_MS / 3));
+function numEnv(name, fallback) {
+  const n = Number(process.env[name]);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+function safeClose(ws, code = 1008, reason = "policy violation") {
+  try {
+    ws.close(code, reason);
+  } catch {
+  }
+}
+function isPlainObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isTabGone(msg) {
+  return /no tab with id|no drivable tab|tab .*not found|invalid tab id|cannot access a chrome/i.test(
+    msg
+  );
+}
+function isIdentifyFrame(msg) {
+  return isPlainObject(msg) && msg.type === "identify" && isPlainObject(msg.payload);
+}
+var str = (v) => typeof v === "string" ? v : void 0;
+function validEnvelope(msg) {
+  return isPlainObject(msg) && typeof msg.type === "string" && (msg.id === void 0 || typeof msg.id === "string") && (msg.payload === void 0 || isPlainObject(msg.payload));
+}
+function startRelay(wss, port, version2, host = "127.0.0.1") {
+  const browsers = new BrowserRegistry();
+  const controllers = /* @__PURE__ */ new Map();
+  const token = getAuthToken();
+  let idleTimer;
+  const peerCount = () => browsers.size() + controllers.size;
+  function armIdleExit() {
+    if (idleTimer || peerCount() > 0) return;
+    idleTimer = setTimeout(() => {
+      if (peerCount() === 0) {
+        rlog.info("idle with no peers; exiting");
+        try {
+          wss.close();
+        } catch {
+        }
+        process.exit(0);
+      }
+    }, IDLE_EXIT_MS);
+    idleTimer.unref?.();
+  }
+  function cancelIdleExit() {
+    if (idleTimer) {
+      clearTimeout(idleTimer);
+      idleTimer = void 0;
+    }
+  }
+  function displayName(c) {
+    for (const other of controllers.values()) {
+      if (other.id !== c.id && other.name === c.name) {
+        return c.pid ? `${c.name} (pid ${c.pid})` : `${c.name} (${c.id.slice(0, 8)})`;
+      }
+    }
+    return c.name;
+  }
+  function nameOf(id) {
+    const c = id ? controllers.get(id) : void 0;
+    return c ? displayName(c) : "an agent";
+  }
+  function dropController(id, reason) {
+    const c = controllers.get(id);
+    if (!c) return;
+    const freed = browsers.releaseByController(id);
+    controllers.delete(id);
+    rlog.info(
+      `controller dropped id=${id.slice(0, 8)} name="${c.name}" reason=${reason} freed=${freed.length} (controllers=${controllers.size})`
+    );
+    safeClose(c.ws, 1e3, reason);
+  }
+  function peerList() {
+    return [...controllers.values()].map((c) => ({ id: c.id, name: displayName(c) }));
+  }
+  function broadcastBrowsers() {
+    if (controllers.size === 0) return;
+    const browsersInfo = browsers.info();
+    const peers = peerList();
+    for (const c of controllers.values()) {
+      try {
+        c.ws.send(
+          JSON.stringify({
+            type: "control.browsers",
+            payload: {
+              browsers: browsersInfo,
+              controllers: peers.map((p) => ({ ...p, self: p.id === c.id }))
+            }
+          })
+        );
+      } catch {
+      }
+    }
+  }
+  function broadcastAgents() {
+    if (browsers.size() === 0) return;
+    const peers = peerList();
+    for (const b of browsers.list()) {
+      const claims = browsers.liveClaimsFor(b.id);
+      try {
+        b.ws.send(JSON.stringify({ type: "agents", payload: { claims, controllers: peers } }));
+      } catch {
+      }
+    }
+  }
+  function broadcastRoster() {
+    broadcastBrowsers();
+    broadcastAgents();
+  }
+  const reaper = setInterval(() => {
+    if (controllers.size === 0) return;
+    const cutoff = Date.now() - CONTROLLER_STALE_MS;
+    const stale = [...controllers.values()].filter((c) => c.lastSeenAt < cutoff);
+    if (stale.length === 0) return;
+    for (const c of stale) dropController(c.id, "stale");
+    broadcastRoster();
+    armIdleExit();
+  }, REAP_INTERVAL_MS);
+  reaper.unref?.();
+  wss.on("connection", (ws) => {
+    cancelIdleExit();
+    const authChallenge = token ? createAuthChallenge() : void 0;
+    try {
+      ws.send(
+        JSON.stringify({
+          id: randomUUID3(),
+          type: "hello",
+          payload: {
+            server: "automate-browser",
+            version: version2,
+            port,
+            role: RELAY_ROLE,
+            ...authChallenge ? { auth: authChallenge } : {}
+          }
+        })
+      );
+    } catch {
+    }
+    let role;
+    let browserId;
+    let controllerId;
+    let rateWindowStartedAt = Date.now();
+    let rateCount = 0;
+    const roleTimer = setTimeout(() => {
+      if (!role) {
+        try {
+          ws.close();
+        } catch {
+        }
+      }
+    }, ROLE_TIMEOUT_MS);
+    roleTimer.unref?.();
+    let alive = true;
+    const onPong = () => {
+      alive = true;
+    };
+    ws.on("pong", onPong);
+    const hb = setInterval(() => {
+      if (!alive) {
+        try {
+          ws.terminate();
+        } catch {
+        }
+        clearInterval(hb);
+        return;
+      }
+      alive = false;
+      try {
+        ws.ping();
+      } catch {
+        clearInterval(hb);
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+    hb.unref?.();
+    async function handleControlSend(frame) {
+      const {
+        requestId,
+        browserId: targetId,
+        tabId,
+        noClaim,
+        toolType,
+        toolPayload,
+        timeoutMs
+      } = frame.payload;
+      const reply = (result, error, extra) => {
+        try {
+          ws.send(
+            JSON.stringify({
+              type: "control.response",
+              payload: { requestId, result, error, ...extra ?? {} }
+            })
+          );
+        } catch {
+        }
+      };
+      const target = targetId ? browsers.get(targetId) : browsers.size() === 1 ? browsers.list()[0] : void 0;
+      if (!target) {
+        reply(void 0, "No connected tab found", { errorCode: "no_browser" });
+        return;
+      }
+      const me = controllerId;
+      const ctrl = controllers.get(me);
+      const myName = nameOf(me);
+      const takeNotice = () => {
+        const n = ctrl?.takeoverNotices.get(target.id);
+        if (n) ctrl.takeoverNotices.delete(target.id);
+        return n;
+      };
+      const forwardPayload = tabId != null && isPlainObject(toolPayload) ? { ...toolPayload, __bmcpTabId: tabId } : toolPayload;
+      const forward = async (notice) => {
+        try {
+          const result = await target.sender(toolType, forwardPayload, {
+            timeoutMs
+          });
+          reply(result, void 0, notice ? { notice } : void 0);
+        } catch (e) {
+          const msg = e?.message || String(e);
+          if (tabId != null && isTabGone(msg)) {
+            browsers.clearClaim(target.id, tabId);
+            broadcastRoster();
+            reply(void 0, msg, {
+              errorCode: "tab_gone",
+              browserId: target.id,
+              tabId
+            });
+            return;
+          }
+          reply(void 0, msg);
+        }
+      };
+      if (noClaim) {
+        await forward();
+        return;
+      }
+      const tabKey = tabId ?? WHOLE_TAB;
+      const live = browsers.liveClaimsFor(target.id);
+      const conflict = tabKey === WHOLE_TAB ? (
+        // A whole-browser drive conflicts with ANY claim by another controller.
+        live.find((c) => c.controllerId !== me)
+      ) : (
+        // A tab drive conflicts only with a WHOLE held by another, or the SAME tab.
+        live.find(
+          (c) => c.controllerId !== me && (c.tabId === WHOLE_TAB || c.tabId === tabKey)
+        )
+      );
+      if (conflict) {
+        reply(void 0, "claimed", {
+          errorCode: "claimed",
+          claimedBy: conflict.controllerName,
+          browserId: target.id,
+          tabId: conflict.tabId,
+          leaseExpiry: conflict.leaseExpiry,
+          notice: takeNotice()
+        });
+        return;
+      }
+      const wasUnclaimed = !browsers.liveClaim(target.id, tabKey);
+      browsers.setClaim(target.id, tabKey, {
+        controllerId: me,
+        controllerName: myName,
+        leaseExpiry: Date.now() + LEASE_TTL_MS
+      });
+      if (wasUnclaimed) broadcastRoster();
+      await forward(takeNotice());
+    }
+    function handleControlClaim(frame) {
+      const { requestId, browserId: browserId2, tabId, force } = frame.payload;
+      const send = (p) => {
+        try {
+          ws.send(JSON.stringify({ type: "control.claimResult", payload: { requestId, ...p } }));
+        } catch {
+        }
+      };
+      const target = browsers.get(browserId2);
+      if (!target) {
+        send({ ok: false, errorCode: "no_browser", browserId: browserId2 });
+        return;
+      }
+      const me = controllerId;
+      const tabKey = tabId ?? WHOLE_TAB;
+      const live = browsers.liveClaimsFor(browserId2);
+      const blockers = tabKey === WHOLE_TAB ? live.filter((c) => c.controllerId !== me) : live.filter(
+        (c) => c.controllerId !== me && (c.tabId === WHOLE_TAB || c.tabId === tabKey)
+      );
+      if (blockers.length && !force) {
+        const b = blockers[0];
+        send({
+          ok: false,
+          errorCode: "claimed",
+          browserId: browserId2,
+          tabId: b.tabId,
+          claimedBy: b.controllerName,
+          leaseExpiry: b.leaseExpiry
+        });
+        return;
+      }
+      if (blockers.length && force) {
+        for (const b of blockers) {
+          const prev = controllers.get(b.controllerId);
+          const which = b.tabId === WHOLE_TAB ? "" : ` (tab ${b.tabId})`;
+          const message = `Heads up: your control of ${target.meta.browser}` + (target.meta.label ? ` "${target.meta.label}"` : "") + `${which} was taken over by "${nameOf(me)}".`;
+          let pushed = false;
+          if (prev) {
+            try {
+              prev.ws.send(
+                JSON.stringify({
+                  type: "control.leaseLost",
+                  payload: {
+                    browserId: browserId2,
+                    ...b.tabId === WHOLE_TAB ? {} : { tabId: b.tabId },
+                    takenBy: nameOf(me),
+                    message
+                  }
+                })
+              );
+              pushed = true;
+            } catch {
+            }
+          }
+          if (!pushed) prev?.takeoverNotices.set(browserId2, message);
+          browsers.clearClaim(browserId2, b.tabId);
+        }
+      }
+      const claim = {
+        controllerId: me,
+        controllerName: nameOf(me),
+        leaseExpiry: Date.now() + LEASE_TTL_MS
+      };
+      browsers.setClaim(browserId2, tabKey, claim);
+      broadcastRoster();
+      send({ ok: true, browserId: browserId2, tabId: tabKey, claim });
+    }
+    function handleControlRelease(frame) {
+      const { requestId, browserId: browserId2, tabId } = frame.payload;
+      const me = controllerId;
+      let released = false;
+      if (browserId2) {
+        if (tabId != null) {
+          const live = browsers.liveClaim(browserId2, tabId);
+          if (live && live.controllerId === me) {
+            browsers.clearClaim(browserId2, tabId);
+            released = true;
+          }
+        } else {
+          released = browsers.releaseClaimsOnBrowser(browserId2, me).length > 0;
+        }
+      } else {
+        released = browsers.releaseByController(me).length > 0;
+      }
+      if (released) broadcastRoster();
+      try {
+        ws.send(
+          JSON.stringify({
+            type: "control.claimResult",
+            payload: { requestId, ok: true, browserId: browserId2 }
+          })
+        );
+      } catch {
+      }
+    }
+    const onMessage = (raw) => {
+      const now = Date.now();
+      if (now - rateWindowStartedAt > RATE_WINDOW_MS) {
+        rateWindowStartedAt = now;
+        rateCount = 0;
+      }
+      rateCount += 1;
+      if (rateCount > RATE_MAX_MESSAGES) {
+        rlog.info("socket rejected \u2014 websocket message rate limit exceeded");
+        safeClose(ws, 1008, "rate limit exceeded");
+        return;
+      }
+      const msg = parseFrame(raw);
+      if (!msg) {
+        rlog.info("socket rejected \u2014 frame is not a JSON object");
+        safeClose(ws, 1003, "malformed frame");
+        return;
+      }
+      if (!validEnvelope(msg)) {
+        rlog.info("socket rejected \u2014 invalid frame envelope");
+        safeClose(ws, 1003, "invalid frame");
+        return;
+      }
+      if (role === "controller" && controllerId) {
+        const me = controllers.get(controllerId);
+        if (me) me.lastSeenAt = now;
+      }
+      if (msg.type === "ping") {
+        try {
+          ws.send(JSON.stringify({ type: "pong" }));
+        } catch {
+        }
+        return;
+      }
+      if (msg.type === "control.ping") {
+        try {
+          ws.send(JSON.stringify({ type: "control.pong" }));
+        } catch {
+        }
+        return;
+      }
+      if (msg.type === "control.bye") {
+        try {
+          ws.close();
+        } catch {
+        }
+        return;
+      }
+      if (!role) {
+        if (isIdentifyFrame(msg)) {
+          if (token && !verifyAuthResponse(token, authChallenge?.challenge ?? "", msg.payload.auth)) {
+            rlog.info("browser identify rejected \u2014 auth proof mismatch; closing");
+            safeClose(ws, 1008, "auth failed");
+            return;
+          }
+          role = "browser";
+          clearTimeout(roleTimer);
+          const p = msg.payload ?? {};
+          const meta = {
+            browser: str(p.browser) || "unknown",
+            browserVersion: str(p.browserVersion),
+            label: str(p.label),
+            instanceId: str(p.instanceId),
+            tabId: typeof p.tabId === "number" ? p.tabId : void 0,
+            tabUrl: str(p.tabUrl),
+            tabTitle: str(p.tabTitle),
+            connectedAt: Date.now()
+          };
+          browserId = browsers.add(ws, meta);
+          rlog.info(
+            `browser connected id=${browserId.slice(0, 8)} browser=${meta.browser}` + (meta.label ? ` label="${meta.label}"` : "") + ` (browsers=${browsers.size()})`
+          );
+          broadcastRoster();
+          return;
+        }
+        if (isControlHello(msg)) {
+          if (token && !verifyAuthResponse(token, authChallenge?.challenge ?? "", msg.payload.auth)) {
+            rlog.info("controller rejected \u2014 auth proof mismatch; closing");
+            safeClose(ws, 1008, "auth failed");
+            return;
+          }
+          role = "controller";
+          clearTimeout(roleTimer);
+          controllerId = randomUUID3();
+          const ctrlName = msg.payload?.name && String(msg.payload.name).trim() || `mcp-${msg.payload?.pid ?? "?"}`;
+          const instanceId = msg.payload?.instanceId && String(msg.payload.instanceId).trim() || void 0;
+          if (instanceId) {
+            for (const prev of controllers.values()) {
+              if (prev.instanceId === instanceId) dropController(prev.id, "superseded");
+            }
+          }
+          controllers.set(controllerId, {
+            id: controllerId,
+            ws,
+            name: ctrlName,
+            pid: typeof msg.payload?.pid === "number" ? msg.payload.pid : void 0,
+            instanceId,
+            lastSeenAt: Date.now(),
+            takeoverNotices: /* @__PURE__ */ new Map()
+          });
+          rlog.info(
+            `controller connected id=${controllerId.slice(0, 8)} name="${ctrlName}" (controllers=${controllers.size})`
+          );
+          try {
+            ws.send(
+              JSON.stringify({
+                type: "control.welcome",
+                payload: {
+                  ctrlId: controllerId,
+                  // Disambiguated, so this controller reports the same name to its
+                  // user that every peer and browser popup sees for it (P0-E).
+                  name: nameOf(controllerId),
+                  relayVersion: version2,
+                  relayHost: host,
+                  browsers: browsers.info(),
+                  controllers: peerList().map((p) => ({
+                    ...p,
+                    self: p.id === controllerId
+                  }))
+                }
+              })
+            );
+          } catch {
+          }
+          broadcastRoster();
+          return;
+        }
+        rlog.info(`socket ignored unknown first frame type=${msg.type}`);
+        return;
+      }
+      if (role === "browser" && msg.type === "identify" && browserId) {
+        const p = msg.payload ?? {};
+        browsers.updateMeta(browserId, {
+          browser: str(p.browser),
+          browserVersion: str(p.browserVersion),
+          label: str(p.label),
+          instanceId: str(p.instanceId),
+          tabId: typeof p.tabId === "number" ? p.tabId : void 0,
+          tabUrl: str(p.tabUrl),
+          tabTitle: str(p.tabTitle)
+        });
+        broadcastBrowsers();
+        return;
+      }
+      if (role === "controller" && isControlSend(msg)) {
+        void handleControlSend(msg);
+        return;
+      }
+      if (role === "controller" && isControlClaim(msg)) {
+        handleControlClaim(msg);
+        return;
+      }
+      if (role === "controller" && isControlRelease(msg)) {
+        handleControlRelease(msg);
+        return;
+      }
+    };
+    const onClose = () => {
+      clearTimeout(roleTimer);
+      clearInterval(hb);
+      ws.off("pong", onPong);
+      ws.off("message", onMessage);
+      if (role === "browser" && browserId) {
+        browsers.remove(browserId);
+        rlog.info(`browser removed id=${browserId.slice(0, 8)} (browsers=${browsers.size()})`);
+        broadcastBrowsers();
+      } else if (role === "controller" && controllerId) {
+        const freed = browsers.releaseByController(controllerId);
+        controllers.delete(controllerId);
+        rlog.info(
+          `controller removed id=${controllerId.slice(0, 8)} freed=${freed.length} (controllers=${controllers.size})`
+        );
+        broadcastRoster();
+      }
+      armIdleExit();
+    };
+    ws.on("message", onMessage);
+    ws.once("close", onClose);
+    ws.once("error", (err) => {
+      if (/max payload/i.test(String(err))) {
+        rlog.error(
+          `socket dropped: a peer sent a frame larger than the ${process.env.AUTOMATE_BROWSER_WS_MAX_PAYLOAD_BYTES ?? "64 MiB"} limit (${String(err)}). The peer will reconnect, but the request it was answering is lost and will surface as a timeout. Raise AUTOMATE_BROWSER_WS_MAX_PAYLOAD_BYTES if this is a legitimate reply.`
+        );
+        return;
+      }
+      rlog.info("socket error", String(err));
+    });
+  });
+  rlog.info(`relay listening on ws://${host}:${port}`);
+  return {
+    port,
+    close: () => {
+      clearInterval(reaper);
+      try {
+        wss.close();
+      } catch {
+      }
+    }
+  };
+}
+
+// src/relay/index.ts
+var version = process.env.AUTOMATE_BROWSER_RELAY_VERSION ?? mcpConfig.server.version;
+function resolveHost() {
+  const raw = process.env.AUTOMATE_BROWSER_RELAY_HOST?.trim();
+  if (!raw) return "127.0.0.1";
+  if (isLoopbackHost(raw)) return raw;
+  if (!getAuthToken()) {
+    rlog.error(
+      `AUTOMATE_BROWSER_RELAY_HOST=${raw} would make this relay reachable from other machines, but AUTOMATE_BROWSER_TOKEN is not set. Refusing to listen without a shared secret \u2014 set AUTOMATE_BROWSER_TOKEN to the same value here and in the browser extension's popup, or unset AUTOMATE_BROWSER_RELAY_HOST to stay on loopback.`
+    );
+    return null;
+  }
+  rlog.warn(
+    `binding ${raw} \u2014 this relay is reachable from other machines on the network (token required, and every peer must prove it).`
+  );
+  return raw;
+}
+async function main() {
+  const host = resolveHost();
+  if (host === null) {
+    process.exit(1);
+    return;
+  }
+  let bound;
+  try {
+    bound = await createWebSocketServer(mcpConfig.wsPortRange, host);
+  } catch (e) {
+    rlog.error("failed to bind any port in range; exiting", String(e));
+    process.exit(0);
+    return;
+  }
+  const { wss, port } = bound;
+  const [start, end] = mcpConfig.wsPortRange;
+  for (let p = start; p < port; p++) {
+    const hello = await probePort(p, 400);
+    if (hello && hello.role === "relay") {
+      rlog.info(`another relay already on :${p}; exiting (this would be :${port})`);
+      try {
+        wss.close();
+      } catch {
+      }
+      process.exit(0);
+      return;
+    }
+  }
+  for (let p = start; p <= end; p++) {
+    if (p === port) continue;
+    const hello = await probePort(p, 400);
+    if (hello && hello.server === "automate-browser" && hello.role !== "relay") {
+      rlog.warn(
+        `legacy AutomateBrowser server detected on :${p} \u2014 it may capture browsers; remove the old npx config and restart that IDE`
+      );
+    }
+  }
+  startRelay(wss, port, version, host);
+}
+void main();