machine-bridge-mcp 1.2.7 → 1.2.9

package/src/local/browser-bridge-http.mjs

@@ -0,0 +1,48 @@
+import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
+import { isAllowedLoopbackHost, pairingHtml, securityHeaders, sendJson } from "./browser-pairing-store.mjs";
+
+export function handleBrowserBridgeHttp(request, response, {
+  port,
+  token,
+  extensionConnected,
+  extensionStatusInfo,
+  extensionReloadRequired,
+}) {
+  const host = String(request.headers.host || "");
+  if (!isAllowedLoopbackHost(host, port)) {
+    response.writeHead(403, securityHeaders("text/plain; charset=utf-8"));
+    response.end("Forbidden\n");
+    return;
+  }
+  const url = new URL(request.url || "/", `http://${host}`);
+  if (request.method !== "GET") {
+    response.writeHead(405, { allow: "GET", "cache-control": "no-store" }).end();
+    return;
+  }
+  if (url.pathname === "/healthz") {
+    const extension = extensionStatusInfo();
+    sendJson(response, {
+      ok: true,
+      connected: extensionConnected(),
+      broker: "machine-bridge-browser",
+      expected_extension_version: EXPECTED_EXTENSION_VERSION,
+      extension_protocol: extension?.protocol || null,
+      extension_version: extension?.version || "",
+      extension_capabilities: extension?.capabilities || [],
+      extension_reload_required: extensionReloadRequired(),
+      controls_existing_profile: true,
+      controls_extension_profile: true,
+      machine_bridge_launches_browser: false,
+      profile_identity_verifiable: false,
+    });
+    return;
+  }
+  if (url.pathname === "/pair") {
+    const html = pairingHtml(port, token);
+    response.writeHead(200, securityHeaders("text/html; charset=utf-8"));
+    response.end(html);
+    return;
+  }
+  response.writeHead(404, securityHeaders("text/plain; charset=utf-8"));
+  response.end("Not found\n");
+}

package/src/local/browser-bridge.mjs

@@ -1,20 +1,18 @@
-import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
 import { resolve } from "node:path";
-import { WebSocket, WebSocketServer } from "ws";
+import { WebSocket } from "ws";
 import { createToolAuthorizer } from "./policy.mjs";
 import { assertStateMaintenanceAvailable, packageRoot } from "./state.mjs";
 import {
   BROWSER_EXTENSION_PROTOCOL, EXPECTED_EXTENSION_VERSION, MAX_BROWSER_MESSAGE_BYTES,
   closeProtocolSocket, normalizeCompatibleExtensionInfo, parseBrowserSocketMessage, parseExtensionHello, safeSocketSend,
 } from "./browser-extension-protocol.mjs";
-import {
-  isAllowedExtensionOrigin, isAllowedLoopbackHost, loadOrCreatePairing,
-  pairingHtml, savePairing, securityHeaders, sendJson,
-} from "./browser-pairing-store.mjs";
-import { clampInt } from "./browser-command.mjs";
+import { loadOrCreatePairing, savePairing } from "./browser-pairing-store.mjs";
 import { BrowserOperationService } from "./browser-operation-service.mjs";
 import { classifyOperationalError } from "./log.mjs";
+import { BrowserRequestRegistry } from "./browser-request-registry.mjs";
+import { handleBrowserBridgeHttp } from "./browser-bridge-http.mjs";
+import { BrowserBrokerRoutes } from "./browser-broker-routes.mjs";
+import { startBrowserBrokerServer } from "./browser-broker-server.mjs";
 
 const MAX_PORT_ATTEMPTS = 10;
 const MAX_PENDING = 32;
@@ -35,8 +33,6 @@ export class BrowserBridgeManager {
     this.socket = null;
     this.pendingExtensionSocket = null;
     this.upstream = null;
-    this.runtimeClients = new Set();
-    this.proxyRoutes = new Map();
     this.proxyExtensionConnected = false;
     this.extensionInfo = null;
     this.proxyExtensionInfo = null;
@@ -44,7 +40,18 @@ export class BrowserBridgeManager {
     this.extensionReloadRequiredFlag = false;
     this.recoveryTimer = null;
     this.stopping = false;
-    this.pending = new Map();
+    this.requestRegistry = new BrowserRequestRegistry({ maximum: MAX_PENDING });
+    this.pending = this.requestRegistry.pending;
+    this.brokerRoutes = new BrowserBrokerRoutes({
+      maximum: MAX_PENDING * 4,
+      getExtensionSocket: () => this.socket,
+      extensionConnected: () => this.extensionConnected(),
+      extensionStatusInfo: () => this.extensionStatusInfo(),
+      extensionReloadRequired: () => this.extensionReloadRequired(),
+    });
+    // Public aliases remain for diagnostics and compatibility with existing behavioral tests.
+    this.runtimeClients = this.brokerRoutes.clients;
+    this.proxyRoutes = this.brokerRoutes.routes;
     this.startPromise = null;
     this.startGeneration = 0;
     this.port = 0;
@@ -95,30 +102,15 @@ export class BrowserBridgeManager {
     await this.ensureStarted(context);
     this.throwIfCancelled(context);
     const transport = this.server ? this.socket : this.upstream;
-    const extensionConnected = this.extensionConnected();
-    if (!transport || transport.readyState !== 1 || !extensionConnected) {
+    if (!transport || transport.readyState !== 1 || !this.extensionConnected()) {
       throw new Error("browser extension is not connected; call pair_browser_extension after loading the packaged extension");
     }
-    if (this.pending.size >= MAX_PENDING) throw new Error("too many concurrent browser requests");
-    const id = `browser_${randomBytes(18).toString("base64url")}`;
-    return new Promise((resolvePromise, rejectPromise) => {
-      const timeoutMs = timeoutSeconds * 1000;
-      const timeout = setTimeout(() => {
-        this.pending.delete(id);
-        try { transport.send(JSON.stringify({ type: "cancel", id })); } catch {}
-        rejectPromise(new Error(`browser request timed out after ${timeoutSeconds}s`));
-      }, timeoutMs);
-      timeout.unref?.();
-      this.pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timeout, callId: context.callId || "" });
-      try {
-        const message = JSON.stringify({ type: "request", id, method, params, timeout_ms: timeoutMs });
-        if (Buffer.byteLength(message) > MAX_BROWSER_MESSAGE_BYTES) throw new Error("browser request exceeds maximum message size");
-        transport.send(message);
-      } catch (error) {
-        clearTimeout(timeout);
-        this.pending.delete(id);
-        rejectPromise(error);
-      }
+    return this.requestRegistry.request({
+      transport,
+      method,
+      params,
+      timeoutSeconds,
+      callId: context.callId || "",
     });
   }
 
@@ -182,43 +174,12 @@ export class BrowserBridgeManager {
 
   async listen(port) {
     this.port = port;
-    const server = createServer((request, response) => this.handleHttp(request, response));
-    const wss = new WebSocketServer({ noServer: true, maxPayload: MAX_BROWSER_MESSAGE_BYTES });
-    server.on("upgrade", (request, socket, head) => {
-      try {
-        const host = String(request.headers.host || "");
-        if (!isAllowedLoopbackHost(host, port)) {
-          socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
-          socket.destroy();
-          return;
-        }
-        const url = new URL(request.url || "/", `http://${host}`);
-        const protocol = String(request.headers["sec-websocket-protocol"] || "");
-        const origin = String(request.headers.origin || "");
-        let role = "";
-        if (url.pathname === "/extension" && protocol === `mbm.${this.token}` && isAllowedExtensionOrigin(origin)) role = "extension";
-        if (url.pathname === "/runtime" && protocol === `mbm-runtime.${this.token}` && !origin) role = "runtime";
-        if (!role) {
-          socket.write("HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n");
-          socket.destroy();
-          return;
-        }
-        wss.handleUpgrade(request, socket, head, (ws) => {
-          ws.bridgeRole = role;
-          wss.emit("connection", ws, request);
-        });
-      } catch {
-        socket.destroy();
-      }
-    });
-    wss.on("connection", (ws) => this.acceptSocket(ws, ws.bridgeRole));
-    await new Promise((resolvePromise, rejectPromise) => {
-      const onError = (error) => { cleanup(); try { wss.close(); } catch {} try { server.close(); } catch {} rejectPromise(error); };
-      const onListening = () => { cleanup(); resolvePromise(); };
-      const cleanup = () => { server.off("error", onError); server.off("listening", onListening); };
-      server.once("error", onError);
-      server.once("listening", onListening);
-      server.listen(port, "127.0.0.1");
+    const { server, wss } = await startBrowserBrokerServer({
+      port,
+      token: this.token,
+      maxPayload: MAX_BROWSER_MESSAGE_BYTES,
+      onHttp: (request, response) => this.handleHttp(request, response),
+      onSocket: (socket, role) => this.acceptSocket(socket, role),
     });
     this.server = server;
     this.wss = wss;
@@ -284,24 +245,7 @@ export class BrowserBridgeManager {
 
   acceptSocket(ws, role) {
     if (role === "runtime") {
-      this.runtimeClients.add(ws);
-      ws.on("message", (data) => this.handleRuntimeClientMessage(ws, data));
-      ws.on("close", () => {
-        this.runtimeClients.delete(ws);
-        for (const [id, route] of this.proxyRoutes) {
-          if (route.socket !== ws) continue;
-          clearTimeout(route.timeout);
-          this.proxyRoutes.delete(id);
-          try { this.socket?.send(JSON.stringify({ type: "cancel", id })); } catch {}
-        }
-      });
-      ws.on("error", () => {});
-      safeSocketSend(ws, {
-        type: "hello", role: "runtime", protocol: 1,
-        extension_connected: this.extensionConnected(),
-        extension_info: this.extensionStatusInfo(),
-        extension_reload_required: this.extensionReloadRequired(),
-      });
+      this.brokerRoutes.acceptClient(ws);
       return;
     }
     if (this.pendingExtensionSocket && this.pendingExtensionSocket.readyState === 1) {
@@ -386,73 +330,12 @@ export class BrowserBridgeManager {
       closeProtocolSocket(socket, 1002, "invalid extension protocol message");
       return;
     }
-    const pending = this.pending.get(message.id);
-    if (pending) {
-      clearTimeout(pending.timeout);
-      this.pending.delete(message.id);
-      if (message.ok === false) pending.reject(new Error(String(message.error || "browser operation failed").slice(0, 2000)));
-      else pending.resolve(message.result);
-      return;
-    }
-    const route = this.proxyRoutes.get(message.id);
-    if (!route) return;
-    clearTimeout(route.timeout);
-    this.proxyRoutes.delete(message.id);
-    try { route.socket.send(JSON.stringify({ ...message, id: route.id })); } catch {}
+    if (this.requestRegistry.settle(message)) return;
+    this.brokerRoutes.settleExtensionResponse(message);
   }
 
   handleRuntimeClientMessage(socket, data) {
-    const parsed = parseBrowserSocketMessage(data);
-    if (!parsed.ok) {
-      closeProtocolSocket(socket, parsed.code, parsed.reason);
-      return;
-    }
-    const message = parsed.message;
-    if (message.type === "ping") return;
-    if (message.type === "cancel" && typeof message.id === "string") {
-      for (const [routedId, route] of this.proxyRoutes) {
-        if (route.socket !== socket || route.id !== message.id) continue;
-        clearTimeout(route.timeout);
-        this.proxyRoutes.delete(routedId);
-        try { this.socket?.send(JSON.stringify({ type: "cancel", id: routedId })); } catch {}
-      }
-      return;
-    }
-    if (message.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") {
-      closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
-      return;
-    }
-    if (!this.extensionConnected()) {
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
-      return;
-    }
-    if (this.proxyRoutes.size >= MAX_PENDING * 4) {
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker is busy" });
-      return;
-    }
-    const routedId = `proxy_${randomBytes(18).toString("base64url")}`;
-    let timeoutMs;
-    try { timeoutMs = clampInt(message.timeout_ms, 30_000, 1_000, 185_000); }
-    catch {
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "invalid browser request timeout" });
-      return;
-    }
-    const timeout = setTimeout(() => {
-      const route = this.proxyRoutes.get(routedId);
-      if (!route) return;
-      this.proxyRoutes.delete(routedId);
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker request timed out" });
-      try { this.socket?.send(JSON.stringify({ type: "cancel", id: routedId })); } catch {}
-    }, timeoutMs);
-    timeout.unref?.();
-    this.proxyRoutes.set(routedId, { socket, id: message.id, timeout });
-    try {
-      this.socket.send(JSON.stringify({ ...message, id: routedId, timeout_ms: timeoutMs }));
-    } catch {
-      clearTimeout(timeout);
-      this.proxyRoutes.delete(routedId);
-      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension send failed" });
-    }
+    return this.brokerRoutes.handleClientMessage(socket, data);
   }
 
   handleUpstreamMessage(message) {
@@ -465,22 +348,12 @@ export class BrowserBridgeManager {
       return true;
     }
     if (message.type !== "response" || typeof message.id !== "string") return false;
-    const pending = this.pending.get(message.id);
-    if (!pending) return true;
-    clearTimeout(pending.timeout);
-    this.pending.delete(message.id);
-    if (message.ok === false) pending.reject(new Error(String(message.error || "browser operation failed").slice(0, 2000)));
-    else pending.resolve(message.result);
+    this.requestRegistry.settle(message);
     return true;
   }
 
   broadcastRuntimeStatus(connected) {
-    const message = {
-      type: "status", extension_connected: connected,
-      extension_info: connected ? this.extensionStatusInfo() : null,
-      extension_reload_required: this.extensionReloadRequired(),
-    };
-    for (const client of this.runtimeClients) safeSocketSend(client, message);
+    this.brokerRoutes.broadcastStatus(connected);
   }
 
   scheduleBrokerRecovery() {
@@ -497,71 +370,26 @@ export class BrowserBridgeManager {
   }
 
   handleHttp(request, response) {
-    const host = String(request.headers.host || "");
-    if (!isAllowedLoopbackHost(host, this.port)) {
-      response.writeHead(403, securityHeaders("text/plain; charset=utf-8"));
-      response.end("Forbidden\n");
-      return;
-    }
-    const url = new URL(request.url || "/", `http://${host}`);
-    if (request.method !== "GET") {
-      response.writeHead(405, { allow: "GET", "cache-control": "no-store" }).end();
-      return;
-    }
-    if (url.pathname === "/healthz") {
-      const extension = this.extensionStatusInfo();
-      sendJson(response, {
-        ok: true,
-        connected: this.extensionConnected(),
-        broker: "machine-bridge-browser",
-        expected_extension_version: EXPECTED_EXTENSION_VERSION,
-        extension_protocol: extension?.protocol || null,
-        extension_version: extension?.version || "",
-        extension_capabilities: extension?.capabilities || [],
-        extension_reload_required: this.extensionReloadRequired(),
-        controls_existing_profile: true,
-        controls_extension_profile: true,
-        machine_bridge_launches_browser: false,
-        profile_identity_verifiable: false,
-      });
-      return;
-    }
-    if (url.pathname === "/pair") {
-      const html = pairingHtml(this.port, this.token);
-      response.writeHead(200, securityHeaders("text/html; charset=utf-8"));
-      response.end(html);
-      return;
-    }
-    response.writeHead(404, securityHeaders("text/plain; charset=utf-8"));
-    response.end("Not found\n");
+    return handleBrowserBridgeHttp(request, response, {
+      port: this.port,
+      token: this.token,
+      extensionConnected: () => this.extensionConnected(),
+      extensionStatusInfo: () => this.extensionStatusInfo(),
+      extensionReloadRequired: () => this.extensionReloadRequired(),
+    });
   }
 
   cancelCall(callId) {
-    if (!callId) return;
     const transport = this.server ? this.socket : this.upstream;
-    for (const [id, pending] of this.pending) {
-      if (pending.callId !== callId) continue;
-      clearTimeout(pending.timeout);
-      this.pending.delete(id);
-      try { transport?.send(JSON.stringify({ type: "cancel", id })); } catch {}
-      pending.reject(new Error("browser request cancelled; a user-visible action may already have completed"));
-    }
+    this.requestRegistry.cancelCall(callId, transport);
   }
 
   rejectPending(message) {
-    for (const pending of this.pending.values()) {
-      clearTimeout(pending.timeout);
-      pending.reject(new Error(message));
-    }
-    this.pending.clear();
+    this.requestRegistry.rejectAll(message);
   }
 
   rejectProxyRoutes(message) {
-    for (const [id, route] of this.proxyRoutes) {
-      clearTimeout(route.timeout);
-      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message });
-      this.proxyRoutes.delete(id);
-    }
+    this.brokerRoutes.rejectAll(message);
   }
 
   stop() {
@@ -574,11 +402,10 @@ export class BrowserBridgeManager {
 
   closeBrokerTransports(message) {
     this.rejectPending(message);
-    this.rejectProxyRoutes(message);
     try { this.upstream?.close(1001, "runtime stopped"); } catch {}
     try { this.socket?.close(1001, "runtime stopped"); } catch {}
     try { this.pendingExtensionSocket?.close(1001, "runtime stopped"); } catch {}
-    for (const client of this.runtimeClients) try { client.close(1001, "runtime stopped"); } catch {}
+    this.brokerRoutes.close(message);
     this.upstream = null;
     this.socket = null;
     this.pendingExtensionSocket = null;
@@ -587,7 +414,6 @@ export class BrowserBridgeManager {
     this.proxyExtensionInfo = null;
     this.proxyExtensionReloadRequired = false;
     this.extensionReloadRequiredFlag = false;
-    this.runtimeClients.clear();
     try { this.wss?.close(); } catch {}
     try { this.server?.close(); } catch {}
     this.wss = null;

package/src/local/browser-broker-routes.mjs

@@ -0,0 +1,136 @@
+import { randomBytes } from "node:crypto";
+import { clampInt } from "./browser-command.mjs";
+import { closeProtocolSocket, parseBrowserSocketMessage, safeSocketSend } from "./browser-extension-protocol.mjs";
+
+export class BrowserBrokerRoutes {
+  constructor({ maximum, getExtensionSocket, extensionConnected, extensionStatusInfo, extensionReloadRequired }) {
+    this.maximum = maximum;
+    this.getExtensionSocket = getExtensionSocket;
+    this.extensionConnected = extensionConnected;
+    this.extensionStatusInfo = extensionStatusInfo;
+    this.extensionReloadRequired = extensionReloadRequired;
+    this.clients = new Set();
+    this.routes = new Map();
+  }
+
+  acceptClient(socket) {
+    this.clients.add(socket);
+    socket.on("message", (data) => this.handleClientMessage(socket, data));
+    socket.on("close", () => this.removeClient(socket));
+    socket.on("error", () => {});
+    safeSocketSend(socket, {
+      type: "hello",
+      role: "runtime",
+      protocol: 1,
+      extension_connected: this.extensionConnected(),
+      extension_info: this.extensionStatusInfo(),
+      extension_reload_required: this.extensionReloadRequired(),
+    });
+  }
+
+  removeClient(socket) {
+    this.clients.delete(socket);
+    for (const [id, route] of this.routes) {
+      if (route.socket !== socket) continue;
+      clearTimeout(route.timeout);
+      this.routes.delete(id);
+      this.sendExtension({ type: "cancel", id });
+    }
+  }
+
+  handleClientMessage(socket, data) {
+    const parsed = parseBrowserSocketMessage(data);
+    if (!parsed.ok) {
+      closeProtocolSocket(socket, parsed.code, parsed.reason);
+      return;
+    }
+    const message = parsed.message;
+    if (message.type === "ping") return;
+    if (message.type === "cancel" && typeof message.id === "string") {
+      this.cancelClientRequest(socket, message.id);
+      return;
+    }
+    if (message.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") {
+      closeProtocolSocket(socket, 1002, "invalid runtime protocol message");
+      return;
+    }
+    if (!this.extensionConnected()) {
+      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension is not connected" });
+      return;
+    }
+    if (this.routes.size >= this.maximum) {
+      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker is busy" });
+      return;
+    }
+    const routedId = `proxy_${randomBytes(18).toString("base64url")}`;
+    let timeoutMs;
+    try { timeoutMs = clampInt(message.timeout_ms, 30_000, 1_000, 185_000); }
+    catch {
+      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "invalid browser request timeout" });
+      return;
+    }
+    const timeout = setTimeout(() => {
+      const route = this.routes.get(routedId);
+      if (!route) return;
+      this.routes.delete(routedId);
+      safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser broker request timed out" });
+      this.sendExtension({ type: "cancel", id: routedId });
+    }, timeoutMs);
+    timeout.unref?.();
+    this.routes.set(routedId, { socket, id: message.id, timeout });
+    if (this.sendExtension({ ...message, id: routedId, timeout_ms: timeoutMs })) return;
+    clearTimeout(timeout);
+    this.routes.delete(routedId);
+    safeSocketSend(socket, { type: "response", id: message.id, ok: false, error: "browser extension send failed" });
+  }
+
+  cancelClientRequest(socket, requestId) {
+    for (const [routedId, route] of this.routes) {
+      if (route.socket !== socket || route.id !== requestId) continue;
+      clearTimeout(route.timeout);
+      this.routes.delete(routedId);
+      this.sendExtension({ type: "cancel", id: routedId });
+    }
+  }
+
+  settleExtensionResponse(message) {
+    const route = this.routes.get(message.id);
+    if (!route) return false;
+    clearTimeout(route.timeout);
+    this.routes.delete(message.id);
+    safeSocketSend(route.socket, { ...message, id: route.id });
+    return true;
+  }
+
+  broadcastStatus(connected) {
+    const message = {
+      type: "status",
+      extension_connected: connected,
+      extension_info: connected ? this.extensionStatusInfo() : null,
+      extension_reload_required: this.extensionReloadRequired(),
+    };
+    for (const client of this.clients) safeSocketSend(client, message);
+  }
+
+  rejectAll(message) {
+    for (const [id, route] of this.routes) {
+      clearTimeout(route.timeout);
+      safeSocketSend(route.socket, { type: "response", id: route.id, ok: false, error: message });
+      this.routes.delete(id);
+    }
+  }
+
+  close(message) {
+    this.rejectAll(message);
+    for (const client of this.clients) {
+      try { client.close(1001, "runtime stopped"); } catch {}
+    }
+    this.clients.clear();
+  }
+
+  sendExtension(message) {
+    const socket = this.getExtensionSocket();
+    if (!socket || socket.readyState !== 1) return false;
+    return safeSocketSend(socket, message);
+  }
+}

package/src/local/browser-broker-server.mjs

@@ -0,0 +1,59 @@
+import { createServer } from "node:http";
+import { WebSocketServer } from "ws";
+import { isAllowedExtensionOrigin, isAllowedLoopbackHost } from "./browser-pairing-store.mjs";
+
+export async function startBrowserBrokerServer({ port, token, maxPayload, onHttp, onSocket }) {
+  const server = createServer(onHttp);
+  const wss = new WebSocketServer({ noServer: true, maxPayload });
+  server.on("upgrade", (request, socket, head) => {
+    try {
+      const host = String(request.headers.host || "");
+      if (!isAllowedLoopbackHost(host, port)) {
+        rejectUpgrade(socket, "403 Forbidden");
+        return;
+      }
+      const url = new URL(request.url || "/", `http://${host}`);
+      const protocol = String(request.headers["sec-websocket-protocol"] || "");
+      const origin = String(request.headers.origin || "");
+      let role = "";
+      if (url.pathname === "/extension" && protocol === `mbm.${token}` && isAllowedExtensionOrigin(origin)) role = "extension";
+      if (url.pathname === "/runtime" && protocol === `mbm-runtime.${token}` && !origin) role = "runtime";
+      if (!role) {
+        rejectUpgrade(socket, "401 Unauthorized");
+        return;
+      }
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        ws.bridgeRole = role;
+        wss.emit("connection", ws, request);
+      });
+    } catch {
+      socket.destroy();
+    }
+  });
+  wss.on("connection", (ws) => onSocket(ws, ws.bridgeRole));
+  await new Promise((resolvePromise, rejectPromise) => {
+    const cleanup = () => {
+      server.off("error", onError);
+      server.off("listening", onListening);
+    };
+    const onError = (error) => {
+      cleanup();
+      try { wss.close(); } catch {}
+      try { server.close(); } catch {}
+      rejectPromise(error);
+    };
+    const onListening = () => {
+      cleanup();
+      resolvePromise();
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, "127.0.0.1");
+  });
+  return { server, wss };
+}
+
+function rejectUpgrade(socket, status) {
+  socket.write(`HTTP/1.1 ${status}\r\nConnection: close\r\n\r\n`);
+  socket.destroy();
+}

package/src/local/browser-request-registry.mjs

@@ -0,0 +1,67 @@
+import { randomBytes } from "node:crypto";
+import { MAX_BROWSER_MESSAGE_BYTES } from "./browser-extension-protocol.mjs";
+
+export class BrowserRequestRegistry {
+  constructor({ maximum = 32 } = {}) {
+    this.maximum = maximum;
+    this.pending = new Map();
+  }
+
+  request({ transport, method, params, timeoutSeconds, callId = "" }) {
+    if (this.pending.size >= this.maximum) throw new Error("too many concurrent browser requests");
+    const id = `browser_${randomBytes(18).toString("base64url")}`;
+    return new Promise((resolvePromise, rejectPromise) => {
+      const timeoutMs = timeoutSeconds * 1000;
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        sendCancelQuietly(transport, id);
+        rejectPromise(new Error(`browser request timed out after ${timeoutSeconds}s`));
+      }, timeoutMs);
+      timeout.unref?.();
+      this.pending.set(id, { resolve: resolvePromise, reject: rejectPromise, timeout, callId });
+      try {
+        const message = JSON.stringify({ type: "request", id, method, params, timeout_ms: timeoutMs });
+        if (Buffer.byteLength(message) > MAX_BROWSER_MESSAGE_BYTES) throw new Error("browser request exceeds maximum message size");
+        transport.send(message);
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pending.delete(id);
+        rejectPromise(error);
+      }
+    });
+  }
+
+  settle(message) {
+    if (message?.type !== "response" || typeof message.id !== "string") return false;
+    const pending = this.pending.get(message.id);
+    if (!pending) return false;
+    clearTimeout(pending.timeout);
+    this.pending.delete(message.id);
+    if (message.ok === false) pending.reject(new Error(String(message.error || "browser operation failed").slice(0, 2000)));
+    else pending.resolve(message.result);
+    return true;
+  }
+
+  cancelCall(callId, transport) {
+    if (!callId) return;
+    for (const [id, pending] of this.pending) {
+      if (pending.callId !== callId) continue;
+      clearTimeout(pending.timeout);
+      this.pending.delete(id);
+      sendCancelQuietly(transport, id);
+      pending.reject(new Error("browser request cancelled; a user-visible action may already have completed"));
+    }
+  }
+
+  rejectAll(message) {
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new Error(message));
+    }
+    this.pending.clear();
+  }
+}
+
+function sendCancelQuietly(transport, id) {
+  try { transport?.send(JSON.stringify({ type: "cancel", id })); } catch {}
+}