machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/browser-extension/pairing-bootstrap.js

@@ -0,0 +1,42 @@
+(() => {
+  const GRANT = /^(\d{13})\.([A-Za-z0-9_-]{22})\.([A-Za-z0-9_-]{43})$/;
+  const PAIRING_GRANT_TTL_MS = 30_000;
+
+  async function bootstrapPairing(port, grant, now = Date.now()) {
+    const auth = globalThis.__machineBridgeBrokerAuth?.internal;
+    if (!auth) throw new Error("browser broker authentication module is unavailable");
+    const normalizedPort = Number(port);
+    const match = GRANT.exec(String(grant || ""));
+    const current = Number(now);
+    if (!Number.isInteger(normalizedPort) || normalizedPort < 1024 || normalizedPort > 65535 || !match || !Number.isFinite(current)) {
+      throw new Error("browser pairing bootstrap is invalid");
+    }
+    const expiresAt = Number(match[1]);
+    if (expiresAt < current || expiresAt - current > PAIRING_GRANT_TTL_MS) throw new Error("browser pairing bootstrap expired");
+    const grantId = `${match[1]}.${match[2]}`;
+    const secret = match[3];
+    const clientChallenge = auth.randomBase64Url(24);
+    const authUrl = new URL(`http://127.0.0.1:${normalizedPort}/pair-auth`);
+    authUrl.searchParams.set("grant", grantId);
+    authUrl.searchParams.set("challenge", clientChallenge);
+    const initProof = await auth.hmac(secret, `machine-bridge-browser-pair-init-v2\0${grantId}\0${clientChallenge}`);
+    authUrl.searchParams.set("init", initProof);
+    const first = await auth.brokerFetch(authUrl, "GET");
+    if (first.status !== 204) throw new Error("browser pairing broker authentication failed");
+    const serverNonce = String(first.headers.get("x-machine-bridge-broker-nonce") || "");
+    const serverProof = String(first.headers.get("x-machine-bridge-broker-proof") || "");
+    if (!auth.noncePattern.test(serverNonce) || !auth.proofPattern.test(serverProof)) throw new Error("browser pairing broker authentication failed");
+    const expected = await auth.hmac(secret, `machine-bridge-browser-pair-server-v2\0${grantId}\0${clientChallenge}\0${serverNonce}`);
+    if (!auth.fixedEqual(expected, serverProof)) throw new Error("browser pairing broker authentication failed");
+    const clientProof = await auth.hmac(secret, `machine-bridge-browser-pair-client-v2\0${grantId}\0${clientChallenge}\0${serverNonce}`);
+    authUrl.searchParams.set("nonce", serverNonce);
+    authUrl.searchParams.set("proof", clientProof);
+    const second = await auth.brokerFetch(authUrl, "POST");
+    if (second.status !== 204) throw new Error("browser pairing broker authentication failed");
+    const token = String(second.headers.get("x-machine-bridge-extension-token") || "");
+    if (!auth.tokenPattern.test(token)) throw new Error("browser pairing broker returned an invalid extension credential");
+    return { endpoint: `ws://127.0.0.1:${normalizedPort}/extension`, token };
+  }
+
+  globalThis.__machineBridgePairingBootstrap = Object.freeze({ bootstrapPairing });
+})();

package/browser-extension/pairing.js

@@ -1,19 +1,35 @@
 (() => {
-  const marker = document.querySelector('meta[name="machine-bridge-browser-pair"]');
-  const portMeta = document.querySelector('meta[name="machine-bridge-browser-port"]');
-  const tokenMeta = document.querySelector('meta[name="machine-bridge-browser-token"]');
-  if (marker?.content !== "1" || !portMeta || !tokenMeta) return;
-  const token = tokenMeta.content;
-  const port = Number(portMeta.content);
-  if (!/^[A-Za-z0-9_-]{32,100}$/.test(token) || !Number.isInteger(port) || port < 1024 || port > 65535) return;
-  chrome.runtime.sendMessage({ type: "pair", endpoint: `ws://127.0.0.1:${port}/extension`, token }, (response) => {
-    const status = document.getElementById("status");
+  let parsed;
+  try { parsed = new URL(location.href); } catch { return; }
+  const pagePort = Number(parsed.port);
+  const fragment = parsed.hash.startsWith("#") ? new URLSearchParams(parsed.hash.slice(1)) : null;
+  const brokerPort = Number(fragment?.get("broker_port"));
+  const grant = String(fragment?.get("grant") || "");
+  if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || parsed.pathname !== "/pair"
+      || parsed.username || parsed.password || parsed.search || fragment?.size !== 2
+      || !Number.isInteger(pagePort) || pagePort < 1024 || pagePort > 65535
+      || !Number.isInteger(brokerPort) || brokerPort < 1024 || brokerPort > 65535
+      || !/^\d{13}\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}$/.test(grant)) return;
+  try { history.replaceState(null, "", parsed.pathname); } catch { return; }
+  if (location.hash) return;
+
+  const updateStatus = (text) => {
+    const apply = () => { const status = document.getElementById("status"); if (status) status.textContent = text; };
+    if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", apply, { once: true });
+    else apply();
+  };
+  chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+    if (message?.type === "machine_bridge_pairing_material") { sendResponse({ port: brokerPort, grant }); return false; }
+    if (message?.type === "machine_bridge_pairing_status") { updateStatus(String(message.text || "")); return false; }
+    return false;
+  });
+  chrome.runtime.sendMessage({ type: "pair_bootstrap", port: brokerPort, grant }, (response) => {
     if (chrome.runtime.lastError || response?.ok !== true) {
-      if (status) status.textContent = response?.requires_manual_repair
+      updateStatus(response?.requires_manual_repair
         ? "This extension is already paired to different local state. Click the Machine Bridge extension icon while this page is active to confirm re-pairing."
-        : "Pairing failed. Confirm the local Machine Bridge runtime is running, then reload this page.";
+        : "Pairing failed. Run pair_browser_extension with opening enabled again.");
       return;
     }
-    if (status) status.textContent = "Paired. You may close this tab.";
+    updateStatus("Paired. You may close this tab.");
   });
 })();

package/browser-extension/service-worker.js

@@ -1,63 +1,59 @@
-importScripts("devtools-input.js", "browser-operations.js");
-
+importScripts("browser-error-boundary.js", "broker-auth.js", "pairing-bootstrap.js", "broker-liveness.js", "devtools-session.js", "devtools-input.js", "devtools-observation.js", "browser-operations.js"); const brokerLiveness = globalThis.__machineBridgeBrokerLiveness;
 let socket = null;
 let reconnectTimer = null;
 let reconnectAttempt = 0;
-let keepaliveTimer = null;
+let connectGeneration = 0;
+let authenticating = false;
 const MAX_RESULT_BYTES = 7 * 1024 * 1024;
 const BROWSER_EXTENSION_PROTOCOL = 3;
 const HANDSHAKE_TIMEOUT_MS = 3000;
+const MAX_ACTIVE_REQUESTS = 32;
 const activeRequests = new Map();
-
 chrome.runtime.onInstalled.addListener(() => { ensureReconnectAlarm(); void connectFromStorage(); });
 chrome.runtime.onStartup.addListener(() => { ensureReconnectAlarm(); void connectFromStorage(); });
 chrome.alarms.onAlarm.addListener((alarm) => {
   if (alarm.name === "machine-bridge-reconnect") void connectFromStorage();
 });
 chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
-  if (message?.type !== "pair") return false;
-  pairConfiguration(message.endpoint, message.token, { replace: false, senderUrl: sender.url || "" })
+  if (message?.type === "machine_bridge_internal_delay") {
+    if (sender?.id !== chrome.runtime.id) return false;
+    const delayMs = message.delay_ms;
+    if (!Number.isSafeInteger(delayMs) || delayMs < 1 || delayMs > 250) {
+      sendResponse({ ok: false });
+      return false;
+    }
+    setTimeout(() => sendResponse({ ok: true }), delayMs);
+    return true;
+  }
+  if (message?.type !== "pair_bootstrap") return false;
+  pairFromBootstrap(message.port, message.grant, { replace: false })
     .then(sendResponse)
     .catch(() => sendResponse({ ok: false }));
   return true;
 });
 chrome.action.onClicked.addListener((tab) => void handleActionClick(tab));
-
 async function handleActionClick(tab) {
-  if (tab?.id && parsePairingPage(tab.url)) {
-    await confirmRepairFromTab(tab);
+  const pairingPage = tab?.id ? browserBrokerAuth().parsePairingPage(tab.url) : null;
+  if (pairingPage) {
+    try {
+      const material = await chrome.tabs.sendMessage(tab.id, { type: "machine_bridge_pairing_material" });
+      if (material?.grant && Number.isInteger(Number(material.port))) {
+        const paired = await pairFromBootstrap(material.port, material.grant, { replace: true });
+        await setPairingPageStatus(tab.id, paired.ok === true ? "Paired. You may close this tab." : "Pairing failed.");
+        return;
+      }
+    } catch {
+      // A token-free or stale pairing tab has no isolated bootstrap material; fall through to the explicit re-pair instruction.
+    }
+    await setPairingPageStatus(tab.id, "Pairing grant unavailable. Run pair_browser_extension with opening enabled again.")
+      .catch(() => { /* The stale pairing tab may already be gone; status decoration is best-effort. */ });
     return;
   }
   const current = await chrome.storage.local.get(["endpoint"]);
-  const pairUrl = pairingUrlFromEndpoint(current.endpoint) || "http://127.0.0.1:39393/pair";
+  const pairUrl = browserBrokerAuth().pairingUrlFromEndpoint(current.endpoint) || "http://127.0.0.1:39393/pair";
   await chrome.tabs.create({ url: pairUrl });
 }
 
-function pairingUrlFromEndpoint(endpoint) {
-  const parsed = parseBrokerEndpoint(endpoint);
-  return parsed ? `http://127.0.0.1:${parsed.port}/pair` : "";
-}
-
-function parsePairingPage(value) {
-  let parsed;
-  try { parsed = new URL(String(value || "")); } catch { return null; }
-  const port = Number(parsed.port);
-  if (parsed.protocol !== "http:" || parsed.hostname !== "127.0.0.1" || parsed.pathname !== "/pair"
-      || parsed.username || parsed.password || parsed.search || parsed.hash
-      || !Number.isInteger(port) || port < 1024 || port > 65535) return null;
-  return parsed;
-}
-
-function parseBrokerEndpoint(value) {
-  let parsed;
-  try { parsed = new URL(String(value || "")); } catch { return null; }
-  const port = Number(parsed.port);
-  if (parsed.protocol !== "ws:" || parsed.hostname !== "127.0.0.1" || parsed.pathname !== "/extension"
-      || parsed.username || parsed.password || parsed.search || parsed.hash
-      || !Number.isInteger(port) || port < 1024 || port > 65535) return null;
-  return parsed;
-}
-
 function setConnectionState(state) {
   const badge = state === "connected" ? "ON" : state === "connecting" ? "..." : state === "unconfigured" ? "?" : "!";
   const title = state === "connected"
@@ -74,7 +70,7 @@ function setConnectionState(state) {
 function ignoreBrowserApiCall(operation) {
   try {
     const value = operation();
-    if (value && typeof value.catch === "function") value.catch(() => {});
+    if (value && typeof value.catch === "function") value.catch(() => { /* Browser UI decoration is optional. */ });
   } catch {
     // Browser UI decoration is optional and must not disrupt broker connectivity.
   }
@@ -91,18 +87,24 @@ function closeSocketQuietly(ws, code, reason) {
 function sendSocketQuietly(ws, payload) {
   try {
     ws.send(payload);
+    return true;
   } catch {
     // A response cannot be recovered after the broker socket closes.
+    return false;
   }
 }
 
-async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl }) {
+async function pairFromBootstrap(port, grant, { replace }) {
+  const bootstrap = browserPairingBootstrap();
+  const candidate = await bootstrap.bootstrapPairing(port, grant);
+  return pairConfiguration(candidate.endpoint, candidate.token, { replace });
+}
+
+async function pairConfiguration(rawEndpoint, rawToken, { replace }) {
   const endpoint = String(rawEndpoint || "");
   const token = String(rawToken || "");
-  const pairingPage = parsePairingPage(senderUrl);
-  const brokerEndpoint = parseBrokerEndpoint(endpoint);
-  if (!pairingPage) return { ok: false, error: "invalid_pairing_page" };
-  if (!brokerEndpoint || pairingPage.port !== brokerEndpoint.port || !/^[A-Za-z0-9_-]{32,100}$/.test(token)) return { ok: false, error: "invalid_pairing_material" };
+  const brokerEndpoint = browserBrokerAuth().parseBrokerEndpoint(endpoint);
+  if (!brokerEndpoint || !/^[A-Za-z0-9_-]{32,100}$/.test(token)) return { ok: false, error: "invalid_pairing_material" };
   const current = await chrome.storage.local.get(["endpoint", "token"]);
   const alreadyPaired = Boolean(current.endpoint && current.token);
   const samePairing = current.endpoint === endpoint && current.token === token;
@@ -113,54 +115,32 @@ async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl })
       && socket.machineBridgeToken === token) {
     return { ok: true, replaced: false, already_connected: true };
   }
-  if (alreadyPaired && !replace && (current.endpoint !== endpoint || current.token !== token)) {
-    return { ok: false, requires_manual_repair: true };
-  }
+  if (alreadyPaired && !replace && !samePairing) return { ok: false, requires_manual_repair: true };
   setConnectionState("connecting");
   try {
     const connectedSocket = await connect(endpoint, token, { reconnect: false });
     await chrome.storage.local.set({ endpoint, token });
     connectedSocket.reconnectEnabled = true;
-    if (connectedSocket.readyState !== WebSocket.OPEN || connectedSocket.bridgeReady !== true) void connect(endpoint, token).catch(() => {});
-    return { ok: true, replaced: alreadyPaired && (current.endpoint !== endpoint || current.token !== token) };
+    if (connectedSocket.readyState !== WebSocket.OPEN || connectedSocket.bridgeReady !== true) {
+      void connect(endpoint, token).catch(() => { /* The reconnect state machine owns subsequent retries. */ });
+    }
+    return { ok: true, replaced: alreadyPaired && !samePairing };
   } catch (error) {
-    if (current.endpoint && current.token) void connect(current.endpoint, current.token).catch(() => {});
+    if (current.endpoint && current.token) {
+      void connect(current.endpoint, current.token).catch(() => { /* Preserve the primary pairing error; prior-pair recovery is best-effort. */ });
+    }
     throw error;
   }
 }
 
-async function confirmRepairFromTab(tab) {
-  if (!tab?.id || !parsePairingPage(tab.url)) return;
-  try {
-    const [result] = await chrome.scripting.executeScript({
-      target: { tabId: tab.id },
-      func: () => ({
-        endpoint: `ws://127.0.0.1:${document.querySelector('meta[name="machine-bridge-browser-port"]')?.content || ""}/extension`,
-        token: document.querySelector('meta[name="machine-bridge-browser-token"]')?.content || "",
-      }),
-    });
-    const paired = await pairConfiguration(result?.result?.endpoint, result?.result?.token, { replace: true, senderUrl: tab.url });
-    await setPairingPageStatus(
-      tab.id,
-      paired.ok === true ? "Paired. You may close this tab." : "Pairing failed.",
-    );
-  } catch {
-    ignoreBrowserApiCall(() => setPairingPageStatus(
-      tab.id,
-      "Pairing failed. Reload this page and confirm that the expected extension build is loaded.",
-    ));
-  }
+function setPairingPageStatus(tabId, text) {
+  return chrome.tabs.sendMessage(tabId, { type: "machine_bridge_pairing_status", text });
 }
 
-function setPairingPageStatus(tabId, text) {
-  return chrome.scripting.executeScript({
-    target: { tabId },
-    func: (value) => {
-      const status = document.getElementById("status");
-      if (status) status.textContent = value;
-    },
-    args: [text],
-  });
+function browserPairingBootstrap() {
+  const bootstrap = globalThis.__machineBridgePairingBootstrap;
+  if (!bootstrap || typeof bootstrap.bootstrapPairing !== "function") throw new Error("browser pairing bootstrap module is unavailable");
+  return bootstrap;
 }
 
 ensureReconnectAlarm();
@@ -171,30 +151,44 @@ function ensureReconnectAlarm() {
 }
 
 async function connectFromStorage() {
-  if (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING)) return;
+  if (authenticating || (socket && (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING))) return;
   const value = await chrome.storage.local.get(["endpoint", "token"]);
   if (value.endpoint && value.token) {
     setConnectionState("connecting");
-    void connect(value.endpoint, value.token).catch(() => {});
+    void connect(value.endpoint, value.token).catch(() => { /* Connection close/retry state is reflected by the socket lifecycle. */ });
   } else {
     setConnectionState("unconfigured");
   }
 }
 
-function connect(endpoint, token, { reconnect = true } = {}) {
+async function connect(endpoint, token, { reconnect = true } = {}) {
+  const generation = ++connectGeneration;
   clearTimeout(reconnectTimer);
   reconnectTimer = null;
   if (socket) {
+    socket.reconnectEnabled = false;
+    clearInterval(socket.keepaliveTimer);
+    socket.keepaliveTimer = null;
+    brokerLiveness.clear(socket);
+    cancelRequestsForSocket(socket);
     closeSocketQuietly(socket);
+    socket = null;
   }
-  const ws = new WebSocket(endpoint, [`mbm.${token}`]);
+  authenticating = true;
+  setConnectionState("connecting");
+  let protocol;
+  try { protocol = await extensionBrokerProtocol(endpoint, token); }
+  finally { if (generation === connectGeneration) authenticating = false; }
+  if (generation !== connectGeneration) throw new Error("browser connection was superseded");
+  const ws = new WebSocket(endpoint, [protocol]);
   socket = ws;
   ws.bridgeReady = false;
   ws.serverHelloSeen = false;
   ws.machineBridgeEndpoint = endpoint;
   ws.machineBridgeToken = token;
   ws.reconnectEnabled = reconnect;
-  setConnectionState("connecting");
+  ws.keepaliveTimer = null;
+  brokerLiveness.initialize(ws);
   return new Promise((resolvePromise, rejectPromise) => {
     let settled = false;
     const settle = (error = null) => {
@@ -213,14 +207,15 @@ function connect(endpoint, token, { reconnect = true } = {}) {
       }, HANDSHAKE_TIMEOUT_MS);
     };
     ws.onmessage = (event) => void handleMessage(ws, event.data, () => settle());
-    ws.onerror = () => {};
+    ws.onerror = () => { /* WebSocket close owns failure settlement and reconnect classification. */ };
     ws.onclose = () => {
       clearTimeout(ws.handshakeTimer);
+      clearInterval(ws.keepaliveTimer);
+      brokerLiveness.clear(ws);
+      ws.keepaliveTimer = null;
+      cancelRequestsForSocket(ws);
       if (!ws.bridgeReady) settle(new Error("browser broker handshake failed"));
       if (socket !== ws) return;
-      clearInterval(keepaliveTimer);
-      keepaliveTimer = null;
-      cancelRequestsForSocket(ws);
       socket = null;
       setConnectionState("disconnected");
       if (ws.reconnectEnabled) scheduleReconnect(endpoint, token);
@@ -228,10 +223,20 @@ function connect(endpoint, token, { reconnect = true } = {}) {
   });
 }
 
+function browserBrokerAuth() {
+  const auth = globalThis.__machineBridgeBrokerAuth;
+  if (!auth || typeof auth.extensionProtocol !== "function") throw new Error("browser broker authentication module is unavailable");
+  return auth;
+}
+
+function extensionBrokerProtocol(endpoint, token) { return browserBrokerAuth().extensionProtocol(endpoint, token); }
+
 function scheduleReconnect(endpoint, token) {
   clearTimeout(reconnectTimer);
   const delay = Math.min(30000, 1000 * 2 ** Math.min(reconnectAttempt++, 5));
-  reconnectTimer = setTimeout(() => { void connect(endpoint, token).catch(() => {}); }, delay);
+  reconnectTimer = setTimeout(() => {
+    void connect(endpoint, token).catch(() => { /* A failed attempt schedules or awaits the next reconnect trigger. */ });
+  }, delay);
 }
 
 async function handleMessage(ws, raw, onReady = () => {}) {
@@ -247,15 +252,16 @@ async function handleMessage(ws, raw, onReady = () => {}) {
     }
     ws.serverHelloSeen = true;
     const manifest = chrome.runtime.getManifest();
-    ws.send(JSON.stringify({
+    const helloSent = sendSocketQuietly(ws, JSON.stringify({
       type: "hello",
       role: "extension",
       protocol: BROWSER_EXTENSION_PROTOCOL,
       version: manifest.version_name || manifest.version,
-      capabilities: [
-        "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
-      ],
+      extension_id: chrome.runtime.id,
+      capabilities: ["semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
+        "cdp_accessibility_snapshot", "cdp_surface_screenshot", "computer_observation_v1", "backend_node_trusted_input"],
     }));
+    if (!helloSent) closeSocketQuietly(ws, 1011, "browser extension hello failed");
     return;
   }
   if (message?.type === "hello_ack") {
@@ -265,12 +271,13 @@ async function handleMessage(ws, raw, onReady = () => {}) {
     }
     clearTimeout(ws.handshakeTimer);
     ws.bridgeReady = true;
+    brokerLiveness.negotiate(ws, message.pong_watchdog);
     reconnectAttempt = 0;
     setConnectionState("connected");
-    clearInterval(keepaliveTimer);
-    keepaliveTimer = setInterval(() => {
-      if (socket === ws && ws.bridgeReady && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" }));
-    }, 20000);
+    clearInterval(ws.keepaliveTimer);
+    ws.keepaliveTimer = setInterval(() => brokerLiveness.keepalive(
+      ws, socket === ws, sendSocketQuietly, closeSocketQuietly,
+    ), 20000);
     onReady();
     return;
   }
@@ -278,21 +285,36 @@ async function handleMessage(ws, raw, onReady = () => {}) {
     closeSocketQuietly(ws, 1002, "browser broker acknowledgement required");
     return;
   }
+  if (message?.type === "pong") return brokerLiveness.handlePong(ws, message, closeSocketQuietly);
   if (message?.type === "cancel" && typeof message.id === "string") {
     const state = activeRequests.get(message.id);
     if (state) state.cancelled = true;
     return;
   }
   if (message?.type !== "request" || typeof message.id !== "string" || typeof message.method !== "string") return;
+  if (activeRequests.has(message.id)) {
+    closeSocketQuietly(ws, 1002, "duplicate browser request id");
+    return;
+  }
+  if (activeRequests.size >= MAX_ACTIVE_REQUESTS) {
+    if (!sendResponse(ws, message.id, false, null, "too many concurrent browser requests")) {
+      closeSocketQuietly(ws, 1011, "browser overload response delivery failed");
+    }
+    return;
+  }
   const state = { cancelled: false, timeoutMs: browserOperations().boundedRequestTimeout(message.timeout_ms), socket: ws };
   activeRequests.set(message.id, state);
   try {
     throwIfCancelled(state);
     const result = await dispatch(message.method, message.params || {}, state);
     throwIfCancelled(state);
-    sendResponse(ws, message.id, true, result);
+    if (!sendResponse(ws, message.id, true, result, "", message.method)) {
+      closeSocketQuietly(ws, 1011, "browser response delivery failed");
+    }
   } catch (error) {
-    if (!state.cancelled) sendResponse(ws, message.id, false, null, String(error?.message || error).slice(0, 2000));
+    if (!state.cancelled && !sendResponse(ws, message.id, false, null, globalThis.__machineBridgeBrowserErrorBoundary.publicError(error))) {
+      closeSocketQuietly(ws, 1011, "browser error delivery failed");
+    }
   } finally {
     activeRequests.delete(message.id);
   }
@@ -308,19 +330,17 @@ function throwIfCancelled(state) {
   if (state.cancelled) throw new Error("browser request cancelled");
 }
 
-function sendResponse(ws, id, ok, result, error = "") {
-  if (ws.readyState !== WebSocket.OPEN) return;
-  let payload = JSON.stringify({ type: "response", id, ok, ...(ok ? { result } : { error }) });
-  if (new TextEncoder().encode(payload).byteLength > MAX_RESULT_BYTES) {
-    payload = JSON.stringify({ type: "response", id, ok: false, error: "browser result exceeds maximum size" });
-  }
-  sendSocketQuietly(ws, payload);
+function sendResponse(ws, id, ok, result, error = "", method = "") {
+  if (ws.readyState !== WebSocket.OPEN) return false;
+  const payload = browserOperations().responsePayload({ id, ok, result, error, method, maxBytes: MAX_RESULT_BYTES });
+  return sendSocketQuietly(ws, payload);
 }
 
-
 function browserOperations() {
   const api = globalThis.__machineBridgeBrowserOperations;
-  if (!api || typeof api.dispatch !== "function") throw new Error("browser operations module is unavailable");
+  if (!api || typeof api.dispatch !== "function" || typeof api.methodMayMutate !== "function" || typeof api.responsePayload !== "function") {
+    throw new Error("browser operations module is unavailable");
+  }
   return api;
 }
 

package/docs/AGENT_CONTEXT.md

@@ -8,13 +8,13 @@ This approximates a local coding agent without pretending that the MCP server ow
 
 - `session_bootstrap` returns built-in working agreements, bounded automatic project facts, explicit instruction text, and a refresh fingerprint.
 - `agent_context` returns the complete target-specific instruction chain, skill summaries, and command registry.
-- `resolve_task_capabilities` rescans default/project context and ranks skills/commands for the current task, optionally loading the best skill; the runtime also adds application and browser capability metadata.
+- `resolve_task_capabilities` rescans default/project context, ranks skills/commands and effective-policy-visible tools, returns bounded set-level execution routes with ambiguity/fallback metadata, and optionally loads the best skill. Direct Bash remains available whenever the effective policy permits it.
 - `list_local_skills` searches discovered `SKILL.md` bundles.
 - `load_local_skill` returns one skill entrypoint and bounded file inventory without execution.
 - `list_local_commands` returns effective registered commands.
 - `run_local_command` executes a registered direct-argv command when policy permits.
 
-Both stdio and remote Worker connection initialization attempt `session_bootstrap`. Its instruction text is appended to the MCP `initialize` result. Because a host may reuse one MCP connection across conversations, the explicit tool and per-task `resolve_task_capabilities` call remain necessary to refresh and reapply instructions reliably. `server_info.observability.capability_routing` and `project_overview.capabilityRouting` report whether those calls reached the local runtime, their counts and timestamps, loaded-source flags, selected capability metadata, and a runtime-keyed HMAC task fingerprint. Raw task text is not retained.
+MCP `2026-07-28` `server/discover` is intentionally static and does not call the daemon bootstrap path. Every executable request carries current protocol metadata, and clients use the explicit `session_bootstrap` or capability-resolution tools when refreshed local context is needed; `initialize` and protocol-session state are not served. Because a host may reuse one transport connection across conversations, call `resolve_task_capabilities` when the current task depends on refreshed project instructions, local skills/registered commands, or application/browser route selection. Straightforward file, Git, or shell work can use the already exposed tools directly without adding a resolver round trip. For shallow workspace identity/inventory without loading skills, commands, instruction bodies, or exact tool membership, use `project_overview` with `detail: "summary"`; reserve `agent_context` and `resolve_task_capabilities` for tasks that actually require those heavier context surfaces. A host may return the previous `refresh.fingerprint` as `known_refresh_fingerprint`; a match suppresses only unchanged static instruction metadata, not the fresh task-specific scan or routing when resolution is requested. Local stdio `server_info.observability.capability_routing` and both transports’ `project_overview.capabilityRouting` report whether those calls reached the local runtime, their counts and timestamps, loaded-source flags, selected capability metadata, primary route, ambiguity class, score gap, and a runtime-keyed HMAC task fingerprint. Raw task text is not retained.
 
 ## Useful defaults without configuration
 
@@ -106,11 +106,11 @@ chmod 600 ~/.config/machine-bridge-mcp/agent.json ~/.config/machine-bridge-mcp/M
 
 The file must be a non-empty, regular, non-symbolic-link UTF-8 file and is bounded by the hard instruction-file limit. Relative values are resolved from the user's home directory. Keep credentials, tokens, private keys, and unrelated personal data out of instruction files.
 
-Changes are discovered on the next `session_bootstrap`, `agent_context`, or `resolve_task_capabilities` call and do not require daemon restart. Because an MCP host may reuse a connection and may not call those tools automatically, start a new conversation or reconnect the MCP client when revised global instructions must be present in initialization context from the beginning.
+Changes are discovered on the next `session_bootstrap`, `agent_context`, or `resolve_task_capabilities` call and do not require daemon restart. `server/discover` does not load local project instructions, so starting a new conversation or reconnecting is not a substitute for an explicit refresh call.
 
 `model_instructions_file`, `builtin_instructions`, and `automatic_project_context` are global-only. Project manifests cannot set or override them. The global model file and the two boolean controls are honored under workspace-confined profiles; other user-manifest fields that would widen filesystem/skill/command scope remain ignored there.
 
-In remote mode, the selected instruction text and enabled automatic project facts necessarily traverse the user's Cloudflare Worker and authorized MCP host as part of initialization. Do not put credentials or private records in instructions.
+In remote mode, selected instruction text and enabled automatic project facts necessarily traverse the user's Cloudflare Worker and authorized MCP host when an explicit context/bootstrap call returns them. Do not put credentials or private records in instructions.
 
 ## Instruction precedence
 
@@ -190,15 +190,17 @@ description: Review a release without publishing it.
 
 The entrypoint requires non-empty `name` and `description`. Invalid bundles are skipped with bounded warnings. Symlinked skill directories are followed after canonical policy validation; symbolic-link entrypoint files are rejected. Traversal, depth, entries, summaries, content, and inventory are bounded.
 
-No persistent skill or project-context index is trusted as authoritative. `session_bootstrap`, `agent_context`, and `resolve_task_capabilities` rebuild the relevant context; skill-list/load calls rescan effective roots. The refresh fingerprint changes when built-in/default context, explicit instruction hashes, skill hashes, command definitions, or relevant configuration changes. Newly created or edited files are visible without restarting the daemon or changing the MCP tool catalog.
+No persistent skill or project-context index is trusted as authoritative. `session_bootstrap`, `agent_context`, and `resolve_task_capabilities` rebuild the relevant context; skill-list/load calls rescan effective roots. The refresh fingerprint binds the target/scope, configuration paths, instruction source/precedence/content identity, skill source identity, and complete registered-command definition including cwd and timeout. A matching `known_refresh_fingerprint` permits response compaction only; task ranking, effective-policy filtering, installed-application matching, and route scoring still run. Newly created or edited files are visible without restarting the daemon or changing the MCP tool catalog.
 
 ## Progressive disclosure and task selection
 
-`agent_context` returns bounded skill metadata. `load_local_skill` returns full instructions only for one selected bundle. `resolve_task_capabilities` tokenizes the current task, ranks skill names/descriptions and command names/descriptions/argv, returns matches with scores, and loads the leading skill only when its relevance threshold is met. Under canonical `full`, it also compares the task with installed application names on every call; application discovery is cached briefly and refreshed after a bounded interval.
+`agent_context` returns bounded skill metadata. `load_local_skill` returns full instructions only for one selected bundle. `resolve_task_capabilities` tokenizes the current task, ranks skill names/descriptions, command names/descriptions/argv, and public tool definitions, then scores compatible execution surfaces as sets. It returns a schema-versioned envelope with the primary route, alternatives, ambiguity, fallback routes, ranked tools, and failure-aware guidance. Scores are relative within the current response, not probabilities or values to compare across package versions. Registered commands, direct Bash/argv, interactive sessions, durable jobs, files/Git, browser, applications, protected resources, and diagnostics remain separate choices; the advice does not hide or disable any effective-policy-visible tool.
+
+The resolver compares the task with cached installed-application names for every authenticated policy profile. This is an intentional read-only inventory surface: delegated roles may see application names and launcher/bundle identifiers, while external paths remain projected. Action routes are still filtered through the authenticated account/daemon policy intersection, so a delegated reviewer connected to a full daemon can discover an installed application without acquiring launch, Accessibility, browser, shell, or write authority.
 
 Matching remains deterministic and local. Hyphens, underscores, dots, and whitespace are normalized; common English inflections are reduced to a small canonical form; and a bounded Chinese/English workflow vocabulary covers creation, improvement, installation, search, current/official documentation, verification, testing, frontend/design, browser/web, email, performance, and security intents. Capability-name token matches receive more weight than incidental words in a long description. This lets Chinese tasks select English-metadata skills such as `skill-creator`, `web-research-cli`, and `skill-installer`, while avoiding the prior tie where generic “create” wording could select `frontend-design`. An explicitly named skill or registered command still receives the strongest deterministic boost.
 
-This ranking is deterministic local assistance, not semantic certainty. Weak positive matches remain visible for diagnosis, but only a skill meeting the selection threshold is recommended for loading. The model must still evaluate whether the selected skill applies. Machine Bridge does not execute skill scripts implicitly and does not fabricate a dynamically named MCP tool per skill.
+This ranking is deterministic local assistance, not semantic certainty. Weak positive matches remain visible for diagnosis, but only a skill meeting the selection threshold is recommended for loading. A high-ambiguity result tells the host to compare the competing route sets rather than over-trust one name. Fallbacks are recovery alternatives, not permission to evade a host or policy denial. The model must still evaluate whether the selected skill and route apply. Machine Bridge does not execute skill scripts implicitly and does not fabricate a dynamically named MCP tool per skill.
 
 ## Registered and automatic package commands
 
@@ -213,12 +215,13 @@ Directly invoking `npm run`, `pnpm run`, `yarn run`, or `bun run` does not make
 ## Recommended host workflow
 
 1. consume MCP initialization instructions, including the built-in baseline and automatic project facts;
-2. call `resolve_task_capabilities` with the complete user task and target path;
+2. when the task needs refreshed instructions, local skill/command discovery, or application/browser route selection, call `resolve_task_capabilities` with the complete user task and target path; otherwise use the already exposed direct tool;
 3. apply explicit global/project instructions over lower-precedence defaults;
 4. follow the selected skill only after checking relevance;
-5. prefer registered commands for stable workflows;
+5. use the returned route set as advice: prefer registered commands for stable workflows, direct Bash for efficient ad hoc composition, process sessions for interactive work, and managed jobs for disconnect-surviving multi-step work;
 6. use structured application/browser tools where applicable;
-7. inspect before mutation or submission and report operations performed.
+7. inspect stable state after ambiguous mutation failures before retrying;
+8. inspect before mutation or submission and report operations performed.
 
 Machine Bridge can automatically discover, refresh, rank, and load capabilities. Actual invocation remains a host/model decision. This boundary cannot be removed by server architecture alone.