machine-bridge-mcp 0.13.0 → 0.15.0

package/browser-extension/pairing.js

@@ -2,7 +2,7 @@
   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 || !portMeta || !tokenMeta) return;
+  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;

package/browser-extension/service-worker.js

@@ -1,8 +1,12 @@
+importScripts("devtools-input.js", "browser-operations.js");
+
 let socket = null;
 let reconnectTimer = null;
 let reconnectAttempt = 0;
 let keepaliveTimer = null;
 const MAX_RESULT_BYTES = 7 * 1024 * 1024;
+const BROWSER_EXTENSION_PROTOCOL = 3;
+const HANDSHAKE_TIMEOUT_MS = 3000;
 const activeRequests = new Map();
 
 chrome.runtime.onInstalled.addListener(() => { ensureReconnectAlarm(); void connectFromStorage(); });
@@ -20,7 +24,7 @@ chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
 chrome.action.onClicked.addListener((tab) => void handleActionClick(tab));
 
 async function handleActionClick(tab) {
-  if (tab?.id && /^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(tab.url || ""))) {
+  if (tab?.id && parsePairingPage(tab.url)) {
     await confirmRepairFromTab(tab);
     return;
   }
@@ -30,8 +34,28 @@ async function handleActionClick(tab) {
 }
 
 function pairingUrlFromEndpoint(endpoint) {
-  const match = /^ws:\/\/127\.0\.0\.1:(\d+)\/extension$/.exec(String(endpoint || ""));
-  return match ? `http://127.0.0.1:${match[1]}/pair` : "";
+  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) {
@@ -54,21 +78,38 @@ function ignoreOptionalPromise(value) {
 async function pairConfiguration(rawEndpoint, rawToken, { replace, senderUrl }) {
   const endpoint = String(rawEndpoint || "");
   const token = String(rawToken || "");
-  if (!/^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(senderUrl || ""))) return { ok: false, error: "invalid_pairing_page" };
-  if (!/^ws:\/\/127\.0\.0\.1:\d+\/extension$/.test(endpoint) || !/^[A-Za-z0-9_-]{32,100}$/.test(token)) return { ok: false, error: "invalid_pairing_material" };
+  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 current = await chrome.storage.local.get(["endpoint", "token"]);
   const alreadyPaired = Boolean(current.endpoint && current.token);
+  const samePairing = current.endpoint === endpoint && current.token === token;
+  if (alreadyPaired && samePairing
+      && socket?.bridgeReady === true
+      && socket.readyState === WebSocket.OPEN
+      && socket.machineBridgeEndpoint === endpoint
+      && 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 };
   }
-  await chrome.storage.local.set({ endpoint, token });
   setConnectionState("connecting");
-  connect(endpoint, token);
-  return { ok: true, replaced: alreadyPaired && (current.endpoint !== endpoint || current.token !== token) };
+  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) };
+  } catch (error) {
+    if (current.endpoint && current.token) void connect(current.endpoint, current.token).catch(() => {});
+    throw error;
+  }
 }
 
 async function confirmRepairFromTab(tab) {
-  if (!tab?.id || !/^http:\/\/127\.0\.0\.1:\d+\/pair(?:$|[?#])/.test(String(tab.url || ""))) return;
+  if (!tab?.id || !parsePairingPage(tab.url)) return;
   try {
     const [result] = await chrome.scripting.executeScript({
       target: { tabId: tab.id },
@@ -86,7 +127,17 @@ async function confirmRepairFromTab(tab) {
       },
       args: [paired.ok === true],
     });
-  } catch {}
+  } catch {
+    try {
+      await chrome.scripting.executeScript({
+        target: { tabId: tab.id },
+        func: () => {
+          const status = document.getElementById("status");
+          if (status) status.textContent = "Pairing failed. Reload this page and confirm that the expected extension build is loaded.";
+        },
+      });
+    } catch {}
+  }
 }
 
 ensureReconnectAlarm();
@@ -101,13 +152,13 @@ async function connectFromStorage() {
   const value = await chrome.storage.local.get(["endpoint", "token"]);
   if (value.endpoint && value.token) {
     setConnectionState("connecting");
-    connect(value.endpoint, value.token);
+    void connect(value.endpoint, value.token).catch(() => {});
   } else {
     setConnectionState("unconfigured");
   }
 }
 
-function connect(endpoint, token) {
+function connect(endpoint, token, { reconnect = true } = {}) {
   clearTimeout(reconnectTimer);
   reconnectTimer = null;
   if (socket) {
@@ -115,48 +166,106 @@ function connect(endpoint, token) {
   }
   const ws = new WebSocket(endpoint, [`mbm.${token}`]);
   socket = ws;
-  ws.onopen = () => {
-    if (socket !== ws) {
-      try { ws.close(); } catch {}
-      return;
-    }
-    reconnectAttempt = 0;
-    setConnectionState("connected");
-    clearInterval(keepaliveTimer);
-    keepaliveTimer = setInterval(() => { if (socket === ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" })); }, 20000);
-  };
-  ws.onmessage = (event) => void handleMessage(ws, event.data);
-  ws.onerror = () => {};
-  ws.onclose = () => {
-    if (socket !== ws) return;
-    clearInterval(keepaliveTimer);
-    keepaliveTimer = null;
-    socket = null;
-    setConnectionState("disconnected");
-    scheduleReconnect(endpoint, token);
-  };
+  ws.bridgeReady = false;
+  ws.serverHelloSeen = false;
+  ws.machineBridgeEndpoint = endpoint;
+  ws.machineBridgeToken = token;
+  ws.reconnectEnabled = reconnect;
+  setConnectionState("connecting");
+  return new Promise((resolvePromise, rejectPromise) => {
+    let settled = false;
+    const settle = (error = null) => {
+      if (settled) return;
+      settled = true;
+      if (error) rejectPromise(error); else resolvePromise(ws);
+    };
+    ws.onopen = () => {
+      if (socket !== ws) {
+        try { ws.close(); } catch {}
+        settle(new Error("browser connection was superseded"));
+        return;
+      }
+      ws.handshakeTimer = setTimeout(() => {
+        try { ws.close(1002, "browser broker handshake timed out"); } catch {}
+      }, HANDSHAKE_TIMEOUT_MS);
+    };
+    ws.onmessage = (event) => void handleMessage(ws, event.data, () => settle());
+    ws.onerror = () => {};
+    ws.onclose = () => {
+      clearTimeout(ws.handshakeTimer);
+      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);
+    };
+  });
 }
 
 function scheduleReconnect(endpoint, token) {
   clearTimeout(reconnectTimer);
   const delay = Math.min(30000, 1000 * 2 ** Math.min(reconnectAttempt++, 5));
-  reconnectTimer = setTimeout(() => connect(endpoint, token), delay);
+  reconnectTimer = setTimeout(() => { void connect(endpoint, token).catch(() => {}); }, delay);
 }
 
-async function handleMessage(ws, raw) {
+async function handleMessage(ws, raw, onReady = () => {}) {
   let message;
-  try { message = JSON.parse(String(raw)); } catch { return; }
+  try { message = JSON.parse(String(raw)); } catch {
+    try { ws.close(1007, "invalid broker JSON"); } catch {}
+    return;
+  }
+  if (message?.type === "hello") {
+    if (ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
+      try { ws.close(1002, "browser broker protocol mismatch"); } catch {}
+      return;
+    }
+    ws.serverHelloSeen = true;
+    const manifest = chrome.runtime.getManifest();
+    ws.send(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",
+      ],
+    }));
+    return;
+  }
+  if (message?.type === "hello_ack") {
+    if (ws.bridgeReady || !ws.serverHelloSeen || message.role !== "extension" || message.protocol !== BROWSER_EXTENSION_PROTOCOL) {
+      try { ws.close(1002, "invalid browser broker acknowledgement"); } catch {}
+      return;
+    }
+    clearTimeout(ws.handshakeTimer);
+    ws.bridgeReady = true;
+    reconnectAttempt = 0;
+    setConnectionState("connected");
+    clearInterval(keepaliveTimer);
+    keepaliveTimer = setInterval(() => {
+      if (socket === ws && ws.bridgeReady && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "ping" }));
+    }, 20000);
+    onReady();
+    return;
+  }
+  if (!ws.bridgeReady) {
+    try { ws.close(1002, "browser broker acknowledgement required"); } catch {}
+    return;
+  }
   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;
-  const state = { cancelled: false };
+  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 || {});
+    const result = await dispatch(message.method, message.params || {}, state);
     throwIfCancelled(state);
     sendResponse(ws, message.id, true, result);
   } catch (error) {
@@ -166,6 +275,12 @@ async function handleMessage(ws, raw) {
   }
 }
 
+function cancelRequestsForSocket(closedSocket) {
+  for (const state of activeRequests.values()) {
+    if (state.socket === closedSocket) state.cancelled = true;
+  }
+}
+
 function throwIfCancelled(state) {
   if (state.cancelled) throw new Error("browser request cancelled");
 }
@@ -179,228 +294,13 @@ function sendResponse(ws, id, ok, result, error = "") {
   try { ws.send(payload); } catch {}
 }
 
-async function dispatch(method, params) {
-  if (method === "list_tabs") return listTabs(params);
-  if (method === "get_source") return getSource(params);
-  if (method === "inspect_page") return inspectPage(params);
-  if (method === "action") return browserAction(params);
-  if (method === "fill_form") return fillForm(params);
-  if (method === "upload_files") return uploadFiles(params);
-  if (method === "screenshot") return screenshot(params);
-  throw new Error(`unknown browser method: ${method}`);
-}
 
-async function listTabs(params) {
-  const query = params.currentWindow ? { currentWindow: true } : {};
-  const tabs = await chrome.tabs.query(query);
-  return {
-    tabs: tabs
-      .filter((tab) => params.includePinned !== false || !tab.pinned)
-      .map((tab) => ({
-        id: tab.id,
-        window_id: tab.windowId,
-        active: tab.active,
-        pinned: tab.pinned,
-        audible: tab.audible,
-        discarded: tab.discarded,
-        status: tab.status,
-        title: tab.title || "",
-        url: tab.url || "",
-      })),
-  };
+function browserOperations() {
+  const api = globalThis.__machineBridgeBrowserOperations;
+  if (!api || typeof api.dispatch !== "function") throw new Error("browser operations module is unavailable");
+  return api;
 }
 
-function scriptTarget(tabId, frameId, allFrames) {
-  if (Number.isInteger(frameId)) return { tabId, frameIds: [frameId] };
-  if (allFrames) return { tabId, allFrames: true };
-  return { tabId };
-}
-
-async function resolveTab(tabId) {
-  if (Number.isInteger(tabId)) return chrome.tabs.get(tabId);
-  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
-  if (!tab?.id) throw new Error("no active browser tab");
-  return tab;
-}
-
-async function getSource(params) {
-  const tab = await resolveTab(params.tabId);
-  assertPageTab(tab);
-  const maxBytes = Number(params.maxBytes) || 1024 * 1024;
-  const executions = await chrome.scripting.executeScript({
-    target: scriptTarget(tab.id, params.frameId, params.allFrames === true),
-    func: (limit) => {
-      const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>\n` : "";
-      const source = `${doctype}${document.documentElement?.outerHTML || ""}`;
-      const encoder = new TextEncoder();
-      const bytes = encoder.encode(source);
-      if (bytes.byteLength <= limit) return { source, bytes: bytes.byteLength, truncated: false, url: location.href };
-      const decoder = new TextDecoder();
-      return { source: decoder.decode(bytes.slice(0, limit)), bytes: bytes.byteLength, truncated: true, url: location.href };
-    },
-    args: [maxBytes],
-  });
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", frames: executions.map((item) => ({ frame_id: item.frameId, ...item.result })) };
-}
-
-async function inspectPage(params) {
-  const tab = await resolveTab(params.tabId);
-  assertPageTab(tab);
-  const executions = await executePageAutomation(
-    scriptTarget(tab.id, params.frameId, params.allFrames === true),
-    "inspect",
-    { maxElements: Number(params.maxElements) || 300, includeValues: params.includeValues === true },
-  );
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", frames: executions.map((item) => ({ frame_id: item.frameId, ...item.result })) };
-}
-
-async function browserAction(params) {
-  const tab = await resolveTab(params.tabId);
-  if (params.action === "navigate") {
-    if (!params.url) throw new Error("navigate requires url");
-    const waiter = beginTabWait(tab.id, params.waitFor);
-    try {
-      const updated = await chrome.tabs.update(tab.id, { url: params.url });
-      await waiter.promise;
-      return publicTab(await chrome.tabs.get(updated.id));
-    } catch (error) {
-      waiter.cancel();
-      throw error;
-    }
-  }
-  if (params.action === "reload") {
-    const waiter = beginTabWait(tab.id, params.waitFor);
-    try {
-      await chrome.tabs.reload(tab.id);
-      await waiter.promise;
-      return publicTab(await chrome.tabs.get(tab.id));
-    } catch (error) {
-      waiter.cancel();
-      throw error;
-    }
-  }
-  if (params.action === "back" || params.action === "forward") {
-    const waiter = beginTabWait(tab.id, params.waitFor);
-    try {
-      if (params.action === "back") await chrome.tabs.goBack(tab.id);
-      else await chrome.tabs.goForward(tab.id);
-      await waiter.promise;
-      return publicTab(await chrome.tabs.get(tab.id));
-    } catch (error) {
-      waiter.cancel();
-      throw error;
-    }
-  }
-  assertPageTab(tab);
-  const waiter = beginTabWait(tab.id, params.waitFor);
-  let execution;
-  try {
-    [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "action", params);
-    await waiter.promise;
-  } catch (error) {
-    waiter.cancel();
-    throw error;
-  }
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
-}
-
-async function fillForm(params) {
-  const tab = await resolveTab(params.tabId);
-  assertPageTab(tab);
-  const waiter = beginTabWait(tab.id, params.waitFor);
-  let execution;
-  try {
-    [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "fillForm", params);
-    await waiter.promise;
-  } catch (error) {
-    waiter.cancel();
-    throw error;
-  }
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
-}
-
-async function uploadFiles(params) {
-  const tab = await resolveTab(params.tabId);
-  assertPageTab(tab);
-  const [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "uploadFiles", params);
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", ...execution.result };
-}
-
-async function screenshot(params) {
-  const tab = await resolveTab(params.tabId);
-  await chrome.tabs.update(tab.id, { active: true });
-  await chrome.windows.update(tab.windowId, { focused: true });
-  const data = await chrome.tabs.captureVisibleTab(tab.windowId, {
-    format: params.format === "jpeg" ? "jpeg" : "png",
-    quality: Number(params.quality) || 90,
-  });
-  return { tab_id: tab.id, title: tab.title || "", url: tab.url || "", data };
-}
-
-function publicTab(tab) {
-  return { tab_id: tab.id, window_id: tab.windowId, title: tab.title || "", url: tab.url || "", status: tab.status || "" };
-}
-
-function assertPageTab(tab) {
-  const url = String(tab.url || "");
-  if (!/^(https?|file):/i.test(url)) throw new Error("this page cannot be scripted by a browser extension");
-}
-
-function beginTabWait(tabId, mode) {
-  if (!mode || mode === "none") return { promise: Promise.resolve(), cancel() {} };
-  let settled = false;
-  let navigationStarted = false;
-  let pollTimer = null;
-  let timeout = null;
-  let resolveWait;
-  let rejectWait;
-  const promise = new Promise((resolvePromise, rejectPromise) => {
-    resolveWait = resolvePromise;
-    rejectWait = rejectPromise;
-  });
-  const cleanup = () => {
-    clearTimeout(timeout);
-    clearTimeout(pollTimer);
-    chrome.tabs.onUpdated.removeListener(listener);
-  };
-  const settle = (error = null) => {
-    if (settled) return;
-    settled = true;
-    cleanup();
-    if (error) rejectWait(error); else resolveWait();
-  };
-  const pollReadyState = async () => {
-    if (settled || !navigationStarted || mode !== "domcontentloaded") return;
-    try {
-      const [execution] = await chrome.scripting.executeScript({ target: { tabId }, func: () => document.readyState });
-      if (["interactive", "complete"].includes(execution?.result)) {
-        settle();
-        return;
-      }
-    } catch {}
-    pollTimer = setTimeout(pollReadyState, 100);
-  };
-  const listener = (updatedId, changeInfo, tab) => {
-    if (updatedId !== tabId || settled) return;
-    if (changeInfo.status === "loading" || typeof changeInfo.url === "string") navigationStarted = true;
-    if (!navigationStarted) return;
-    if (mode === "complete" && (changeInfo.status === "complete" || (typeof changeInfo.url === "string" && tab.status === "complete"))) settle();
-    if (mode === "domcontentloaded") void pollReadyState();
-  };
-  chrome.tabs.onUpdated.addListener(listener);
-  timeout = setTimeout(() => settle(new Error("browser navigation wait timed out")), 30000);
-  return { promise, cancel: () => settle() };
-}
-
-function executePageAutomation(target, method, params) {
-  return chrome.scripting.executeScript({ target, files: ["page-automation.js"] })
-    .then(() => chrome.scripting.executeScript({
-      target,
-      func: (operation, payload) => {
-        const api = globalThis.__machineBridgePageAutomation;
-        if (!api || typeof api[operation] !== "function") throw new Error("page automation module is unavailable");
-        return api[operation](payload);
-      },
-      args: [method, params],
-    }));
+function dispatch(method, params, state) {
+  return browserOperations().dispatch(method, params, state);
 }

package/docs/ARCHITECTURE.md

@@ -60,7 +60,7 @@ See [Session instructions, skills, commands, and capability discovery](AGENT_CON
 
 `BrowserBridgeManager` owns a loopback HTTP/WebSocket broker. The first runtime for the machine-level state root becomes broker owner; additional workspaces and stdio runtimes authenticate to `/runtime` and proxy through the same extension socket. This preserves one extension pairing while allowing multiple local MCP runtimes.
 
-The packaged Manifest V3 extension runs in the user's existing Chromium profile. Its service worker is transport/orchestration only; a fixed packaged `page-automation.js` module is injected into selected frames to expose DOM operations in the correct execution world. It supports accessible frames, open Shadow DOM roots, structured actions, multi-field forms, resource-backed file inputs, and screenshots. The extension never receives arbitrary caller-provided code. The broker validates loopback hostnames, extension origin, bearer subprotocols, message sizes, concurrency, and timeouts. Pairing material is owner-only and omitted from MCP/log output.
+The packaged Manifest V3 extension runs in the user's existing Chromium profile. Its service worker is limited to pairing, transport, acknowledged protocol readiness, cancellation, and response routing. Fixed `browser-operations.js` owns tab lifecycle, aggregate frame/source budgets, waits, screenshots, and input-backend selection; fixed `page-automation.js` is injected into selected frames for snapshot-version-2 semantics, stable refs, bounded DOM/text traversal, actionability checks, open-Shadow-DOM traversal, structured DOM operations, multi-field forms, and resource-backed file inputs. Fixed `devtools-input.js` exposes only bounded mouse, keyboard, and text sequences through the Chromium debugger API; callers cannot select CDP methods. Trusted sessions attach for one action and detach in `finally`; DOM fallback is allowed only before any DevTools Input dispatch, preventing duplicate side effects after an ambiguous command failure. Protocol 3 requires bidirectional `hello`/`hello_ack` plus exact packaged-version and capability equality; pairing state and replacement are committed only after validation, so an invalid candidate cannot displace or overwrite the working configuration. The broker validates loopback hostnames, canonical extension IDs, matching pairing/broker ports, bearer subprotocols, message sizes, concurrency, and deadlines. Pairing material is owner-only and omitted from MCP/log output.
 
 See [Local application and browser automation](LOCAL_AUTOMATION.md).
 

package/docs/AUDIT.md

@@ -1,6 +1,18 @@
 # Engineering and security audit
 
-This document records the cross-cutting audit initiated for version 0.12.0, the 0.12.2 cross-platform CI follow-up, and the 0.13.0 architecture/automatic-routing follow-up. It complements, but does not replace, the continuously enforced contracts in `SECURITY.md`, `docs/ENGINEERING.md`, and the test suite.
+This document records the cross-cutting audit initiated for version 0.12.0, the 0.12.2 cross-platform CI follow-up, and the 0.13.0 architecture/automatic-routing follow-up, plus the 0.15.0 daily-browser and cross-platform hardening review. It complements, but does not replace, the continuously enforced contracts in `SECURITY.md`, `docs/ENGINEERING.md`, and the test suite.
+
+## 2026-07-13 daily-browser and cross-platform hardening follow-up
+
+The review first distinguished installation from actual connectivity. The user identified the target as their ordinary Chrome profile and manually loaded the unpacked extension there; it was initially unpaired. After opening the genuine loopback pairing page, a localhost-only live fixture verified that this connected Chrome instance could create and close a real tab, return semantic snapshot refs, traverse an open Shadow DOM, fill a multi-field form, issue trusted text and pointer input, wait for final DOM state, and capture a screenshot without reading unrelated tabs. The product now states the narrower machine-verifiable fact: Machine Bridge does not launch a browser, but an extension cannot infer whether its host profile is the user's daily or isolated profile.
+
+Fault injection then found several state-machine issues that a success-only smoke test could not reveal. WebSocket `open` was treated as extension readiness before protocol validation; pairing state was written before the candidate authenticated; `input_mode: auto` replayed a DOM action after any DevTools failure even when an Input command might already have taken effect; screenshot capture focused the browser window and did not restore the previous active tab; navigation wait used a hidden 30-second deadline independent of the request; and replacement could leave direct/proxied requests pending. Protocol 3 now requires `hello`/`hello_ack` with exact packaged-version/capability equality, persists pairing only after acknowledgement, validates a canonical extension ID plus matching loopback ports, propagates the request deadline, rejects ambiguous post-dispatch retries, restores tab state without stealing focus, and fails interrupted routes with retry guidance.
+
+Hostile-page analysis found that previous limits were result limits rather than work limits: every frame received the full source/element allowance, `outerHTML` was built before truncation, interactive elements and Shadow roots were fully enumerated before slicing, page-controlled strings were not uniformly bounded, and whole-page `innerText` was materialized for waits. Version 0.15.0 applies aggregate budgets across at most 64 frames, uses iterative bounded DOM serialization, limits each page scan to 100,000 nodes, reusable refs to a 10,000-entry LRU, and text search to 2 MiB, bounds metadata, removes URL userinfo, treats secret-like contenteditable controls as sensitive, and reports truncation explicitly. Multi-field failures now identify possible earlier mutations without returning values.
+
+The extension architecture was also corrected: the service worker now owns only pairing/transport/readiness/cancellation/response routing, while fixed `browser-operations.js` owns tab and page orchestration. An executable line-count invariant prevents those concerns from silently merging again. Outside the browser path, the review found that Windows Scheduled Task command construction did not implement CRT backslash-before-quote rules; drive-root or trailing-backslash arguments could be misparsed. A dedicated quoting primitive and platform regression test correct that boundary.
+
+The same pass rechecked Worker OAuth/PKCE, registration/code/token limits, process sessions, managed jobs, state deletion, log redaction/rotation, package contents, dependencies, open issues, and current CI. No additional high-impact code change was justified in those areas. Their documented residuals remain: canonical `full` intentionally exposes the local user's authority, service logs are trimmed at startup rather than continuously, and same-user malicious code or an MCP host can still operate outside Machine Bridge's control.
 
 ## 2026-07-13 architecture and automatic-routing follow-up
 

package/docs/LOCAL_AUTOMATION.md

@@ -13,15 +13,17 @@ Launching a separate automation browser is predictable but loses the user's ordi
 
 The extension works with the current profile and supports:
 
-- listing existing tabs;
+- listing, creating, activating, and closing tabs;
 - reading the current serialized DOM HTML from the main frame or accessible subframes;
-- discovering interactive controls, labels, roles, placeholders, and field metadata across accessible frames and open Shadow DOM roots;
-- structured navigation, click, focus, fill, select, check, uncheck, key press, and form submission;
+- discovering interactive controls, bounded per-document element references, actionability state, geometry, labels, roles, placeholders, and field metadata across accessible frames and open Shadow DOM roots;
+- waiting for bounded combinations of URL, load state, page text, and element state;
+- structured navigation, click, double-click, hover, focus, fill, type-text, select, check, uncheck, key press, scroll-into-view, and form submission;
+- automatic existence/visibility/enabled/editable/stability/hit-target checks before actions, with fixed DevTools mouse/keyboard input for top-frame interactions and a controlled DOM fallback;
 - multi-field complex form filling in one operation, bounded to 200 fields and 4 MiB of aggregate text;
 - populating file inputs from registered local resource files;
 - visible-tab screenshots.
 
-Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. After upgrading Machine Bridge, reload the unpacked extension from the browser extensions page so its packaged scripts match the new runtime. Browser-internal pages, extension stores, some PDF/plugin viewers, cross-origin frames denied to the extension, and pages restricted by enterprise policy may not be scriptable.
+Current support targets Chrome, Chromium, Microsoft Edge, Brave, Vivaldi, and compatible Chromium browsers. The extension must be loaded into the user profile to be controlled; it is not installed into Playwright or an isolated automation profile. After every Machine Bridge upgrade, reload the unpacked extension so packaged scripts, protocol, and permissions match the runtime. Version 0.15.0 requires protocol 3 with broker `hello_ack`; the badge and pairing page report success only after protocol/version/capability validation. Pairing material is persisted only after that acknowledgement, an invalid candidate cannot overwrite the previous pairing, and `browser status` reports the expected packaged build, authenticated connected build/protocol/capabilities, and `extension_reload_required`; exact version equality is required in addition to protocol and capabilities. Browser-internal pages, extension stores, some PDF/plugin viewers, inaccessible cross-origin frames, and pages restricted by enterprise policy remain unscriptable.
 
 ## One-time browser setup
 
@@ -53,17 +55,19 @@ The broker is machine-global rather than workspace-global. One local owner liste
 
 ## Browser tools
 
-- `browser_status` reports broker role, extension connection, supported operations, pairing URL, and extension path without returning the pairing token.
+- `browser_status` reports broker role, authenticated extension protocol/version/capabilities, reload state, supported operations, pairing URL, and extension path without returning the pairing token.
 - `pair_browser_extension` opens the local pairing page and returns setup steps.
 - `browser_list_tabs` lists current tabs.
-- `browser_get_source` returns bounded current DOM HTML for selected frames.
-- `browser_inspect_page` returns bounded interactive-element metadata.
-- `browser_action` performs one structured navigation or DOM action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected.
-- `browser_fill_form` fills up to 200 fields and can submit once.
+- `browser_manage_tabs` creates, activates, or closes a selected tab.
+- `browser_get_source` returns a bounded iterative DOM serialization. `max_bytes` is one aggregate request budget across at most 64 accessible frames; omitted frames and node/byte truncation are explicit.
+- `browser_inspect_page` returns snapshot version 2 with one aggregate `max_elements` budget, at most 64 accessible frames, a 100,000-node per-frame scan ceiling, bounded page-controlled strings, URL-userinfo redaction, and explicit scan/frame truncation. Each control includes a reusable `ref` plus visibility, enabled/editable state, and viewport geometry. References are held in a 10,000-entry per-frame LRU; navigation, element replacement, or bounded eviction makes an older ref stale and requires a new inspection.
+- `browser_wait` waits until all supplied URL, load-state, page-text, and element-state conditions are true.
+- `browser_action` performs one structured navigation or page action. Navigation accepts absolute `http`, `https`, or `file` URLs; script/data schemes are rejected. Pointer and keyboard actions default to `input_mode: auto`, which uses fixed trusted DevTools input in the top frame and falls back to DOM only when no `Input` command has started. Once dispatch begins, failure has an unknown outcome and must be inspected before retrying; automatic replay is forbidden. `trusted` always forbids fallback; `dom` never attaches the debugger.
+- `browser_fill_form` fills up to 200 fields and can submit once. If a later field fails, the error states how many earlier fields may already have changed without returning their values.
 - `browser_upload_files` sets a file input from up to eight registered local resources. Caller filenames must be safe single-component names; derived names have controls and separators removed. MIME overrides must be canonical media types.
-- `browser_screenshot` returns native MCP image content.
+- `browser_screenshot` returns native MCP image content, temporarily activates the selected tab only when required, restores the previous active tab when safe, and never focuses another browser window.
 
-Selectors can use CSS, ID, field name, label text, visible text, ARIA/implicit role, placeholder, and a zero-based match index. The fixed page module traverses open Shadow DOM roots; closed shadow roots remain inaccessible. For frame-specific work, inspect all frames first and then pass `frame_id` to an action.
+Selectors can use the `ref` returned by inspection, CSS, ID, field name, label text, visible text, ARIA/implicit role, placeholder, and a zero-based match index. `ref` cannot be combined with other fields and becomes stale after navigation or element replacement. Non-ref selectors that match multiple controls fail explicitly unless `index` disambiguates them. The fixed page module traverses open Shadow DOM roots; closed shadow roots remain inaccessible. For frame-specific work, inspect all frames first and then pass `frame_id` to an action. Trusted input currently targets the top frame because DevTools coordinates are top-level; use `input_mode: dom` for an explicitly selected subframe.
 
 ## Sensitive form values and files
 
@@ -100,13 +104,13 @@ The browser extension has broad page access because generic source inspection an
 The implementation reduces avoidable risk as follows:
 
 - all browser/app tools are `full`-only;
-- no arbitrary evaluation or caller-provided script source is accepted;
-- loopback HTTP validates `Host`; extension WebSockets require a random bearer subprotocol and a `chrome-extension://` origin;
+- no arbitrary evaluation, caller-provided script source, or caller-selected DevTools method is accepted; trusted input exposes only fixed `Input.dispatchMouseEvent`, `Input.dispatchKeyEvent`, and `Input.insertText` sequences;
+- loopback HTTP validates `Host`; extension WebSockets require a random bearer subprotocol and a canonical `chrome-extension://` origin whose host is a 32-character Chromium extension ID; pairing-page and broker ports must match;
 - runtime-to-broker connections require a separate authenticated subprotocol;
 - the pairing token is stored owner-only, embedded only in the non-cacheable local pairing page, and omitted from MCP results and logs;
 - an established extension pairing cannot be silently replaced by another localhost page; replacement requires clicking the extension action on the active pairing page;
 - arguments, form values, page source, screenshots, and results are not operational log data;
-- message, source, form-field, upload, traversal, concurrency, proxy-route, and timeout limits are enforced;
+- message, aggregate source/element/frame, form-field, upload, DOM-node/text, concurrency, proxy-route, actionability, and request-deadline limits are enforced; ambiguous selectors, stale refs, hidden/disabled/edit-blocked controls, moving targets, and obscured pointer targets fail explicitly;
 - MCP cancellation clears local and broker pending state and propagates a cancellation signal to the extension; an action already delivered to a page or application may still have completed;
 - resource-backed text and files are not returned after injection.