machine-bridge-mcp 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.15.0 - 2026-07-13
+
+### Daily-profile browser verification and protocol safety
+
+- Verify the unpacked extension in the user's ordinary Chrome profile with a localhost-only live smoke test covering the acknowledged protocol handshake, real tab lifecycle, semantic inspection, open Shadow DOM, complex form fill, fixed DevTools text/click input, waits, screenshot capture, and cleanup. `browser status` and loopback health now report extension version/protocol, that Machine Bridge did not launch the browser, and the fact that daily-vs-isolated profile identity is not machine-verifiable.
+- Upgrade the extension protocol to an acknowledged `hello`/`hello_ack` state machine with exact packaged-version, protocol, and capability equality. WebSocket open is no longer treated as authenticated readiness, pairing material is persisted only after a successful capability handshake, failed candidate pairing preserves the prior configuration, pairing-page and broker ports must match, and extension WebSocket origins require a canonical 32-character Chromium extension ID.
+- Prevent duplicate side effects after an ambiguous trusted-input failure. `auto` falls back to DOM only before any DevTools `Input` command starts; after dispatch begins, the operation fails with an explicit unknown-outcome instruction to inspect the page before retrying. Screenshot capture temporarily activates only the requested tab, never focuses its window, and restores the previous active tab unless the user changed it concurrently.
+
+### Bounded page processing and extension architecture
+
+- Apply `max_bytes` and `max_elements` as aggregate request budgets across at most 64 accessible frames. Replace full `outerHTML` construction with a bounded iterative DOM serializer, cap page scans at 100,000 nodes, bound page-controlled metadata/text, cap reusable refs at 10,000 per frame, redact URL userinfo, mark contenteditable secret controls as sensitive, and report frame/node/text/ref truncation explicitly.
+- Report partial multi-field form mutation precisely when a later field or submission fails. Navigation waits now inherit the bounded request deadline rather than using a hidden fixed 30-second timer.
+- Extract tab/page/wait/source/screenshot orchestration into fixed `browser-operations.js`; the Manifest V3 service worker now owns only pairing, transport, acknowledged readiness, cancellation, and response routing. Architecture tests enforce this responsibility boundary.
+
+### Cross-platform audit and regression coverage
+
+- Replace ad-hoc Windows Scheduled Task argument quoting with the Windows CRT-compatible backslash/quote algorithm, including drive-root and trailing-backslash paths.
+- Add behavior tests for handshake readiness, provisional pairing persistence, trusted-input replay prevention, focus restoration, aggregate frame/source budgets, hostile DOM/text bounds, partial form failure, strict extension origins, and Windows command-line quoting. Synchronize architecture, security, operations, testing, audit, and tool documentation.
+
 ## 0.14.0 - 2026-07-13
 
 ### Windows installation and OAuth callback reliability

package/README.md

@@ -185,7 +185,7 @@ Skill discovery follows Codex-style progressive disclosure. Default project root
 Under canonical `full`, Machine Bridge also exposes structured local automation:
 
 - installed application discovery/opening and macOS Accessibility inspection/actions;
-- a packaged Chromium extension that controls the user's existing daily browser profile, active tabs, login state, and windows;
+- a packaged Chromium extension that controls the profile into which the user loads it, including that profile's tabs, login state, and windows; Machine Bridge does not launch a separate browser process;
 - current DOM source and frame/open-Shadow-DOM inspection, stable semantic element references, actionability waits, fixed trusted mouse/keyboard input, explicit browser waits, tab management, complex multi-field forms, resource-backed secret fields, resource-backed file uploads, and screenshots.
 
 One-time browser setup:
@@ -195,7 +195,7 @@ machine-mcp browser setup
 machine-mcp browser status
 ```
 
-Load the printed unpacked-extension directory once in Chrome, Edge, Brave, Vivaldi, or another compatible Chromium browser. After an upgrade that adds permissions, reload the unpacked extension and accept the browser prompt; trusted input uses the Chromium `debugger` permission only for fixed, short-lived DevTools Input commands. The extension badge reports connection state, and clicking it opens the saved local pairing page. The local pairing token remains in owner-only state and the loopback pairing page; it is not returned through MCP. For a mass-market release, distribute the same extension as a signed browser-store build rather than asking end users to enable Developer mode. See [Local application and browser automation](docs/LOCAL_AUTOMATION.md).
+Load the printed unpacked-extension directory in the Chromium profile you actually use; Machine Bridge does not install it into Playwright or a separate automation profile. After every Machine Bridge upgrade, reload the unpacked extension and accept any new browser permission. `machine-mcp browser status` reports both the expected packaged extension build and the authenticated connected build/protocol, and states that Machine Bridge did not launch the browser. It cannot infer whether the extension was loaded into a daily or isolated profile; that is determined by where the user installed it. Trusted input uses the Chromium `debugger` permission only for fixed, short-lived DevTools Input commands. The badge shows `ON` only after the broker acknowledges the version/capability handshake. The local pairing token remains in owner-only state and non-cacheable loopback HTML; it is not returned through MCP. For a mass-market release, distribute the same extension as a signed browser-store build rather than asking end users to enable Developer mode. See [Local application and browser automation](docs/LOCAL_AUTOMATION.md).
 
 Machine Bridge can discover, refresh, rank, and load capabilities automatically. The ChatGPT/MCP host still owns tool selection and approval, so the server cannot force a host to expose or invoke a recommended skill, command, app, or browser operation. Check `server_info.observability.capability_routing` or `project_overview.capabilityRouting` to distinguish “the host never called the resolver” from “the resolver ran but found no relevant capability.”
 
@@ -347,13 +347,13 @@ The exact `tools/list` response reflects the active local policy. Definitions co
 - `pair_browser_extension`
 - `browser_list_tabs`
 - `browser_manage_tabs` — create, activate, or close tabs
-- `browser_get_source` — bounded current DOM HTML, including selected frames
-- `browser_inspect_page` — semantic controls, stable per-document refs, state, and geometry
+- `browser_get_source` — bounded current DOM HTML with one aggregate byte budget across up to 64 accessible frames
+- `browser_inspect_page` — semantic controls, bounded LRU refs, state, geometry, and explicit frame/node/ref truncation metadata
 - `browser_wait` — bounded URL/load/text/element-state waits
-- `browser_action` — actionability checks plus `auto`, `trusted`, or `dom` input mode
+- `browser_action` — actionability checks plus `auto`, `trusted`, or `dom` input mode; ambiguous post-dispatch failures are never replayed through DOM
 - `browser_fill_form`
 - `browser_upload_files` — registered local resources to file inputs
-- `browser_screenshot`
+- `browser_screenshot` — restores the prior active tab and does not focus another window
 
 
 ### Mutation

package/SECURITY.md

@@ -73,11 +73,11 @@ The global `model_instructions_file` is an explicit user trust decision. It is r
 
 Canonical `full` exposes structured browser and desktop UI authority. The browser extension operates the user's existing Chromium profile, including active login state, and has broad host access plus Chromium `debugger` permission so it can inspect arbitrary pages, fill complex forms, and issue trusted input. An authorized client may therefore read page content, click controls, submit forms, upload registered files, and cause transactions with the user's browser identity. macOS Accessibility actions similarly operate applications with the local user's UI authority.
 
-The browser loopback broker validates loopback `Host`, requires a random owner-only bearer subprotocol, accepts extension sockets only with a `chrome-extension://` origin, and authenticates additional local runtimes separately. Initial extension pairing is trust-on-first-use; after pairing, a different localhost page cannot replace the stored broker unless the user clicks the extension action while the genuine pairing page is active. The pairing token is never returned by MCP or written to operational logs. These controls defend against casual cross-origin and DNS-rebinding access; they do not protect against malicious code already running as the same OS user or a compromised browser extension profile.
+The browser loopback broker validates loopback `Host`, requires a random owner-only bearer subprotocol, accepts extension sockets only from a canonical 32-character Chromium extension ID, requires the pairing page and WebSocket endpoint to use the same loopback port, and authenticates additional local runtimes separately. Initial extension pairing is trust-on-first-use; after pairing, a different localhost page cannot replace the stored broker unless the user clicks the extension action while the genuine pairing page is active. The pairing token is never returned by MCP or written to operational logs. These controls defend against casual cross-origin and DNS-rebinding access; they do not protect against malicious code already running as the same OS user or a compromised browser extension profile.
 
-Caller-supplied JavaScript, AppleScript, JXA source, and arbitrary DevTools methods are deliberately unsupported. Actions use fixed implementation code and structured selectors. The debugger adapter is restricted to fixed `Input` commands, attaches only around one trusted action, and detaches in `finally`; `input_mode` makes fallback behavior explicit. The broker validates a versioned extension capability hello before activating a connection and does not let an invalid replacement candidate displace an already compatible extension. This removes an avoidable arbitrary-evaluation surface but does not make DOM or Accessibility actions safe. Pages can contain prompt injection, misleading labels, hidden consequences, cross-origin frames unavailable to inspection, or state that changes between inspection and submission. High-impact account, financial, legal, medical, publishing, deletion, and purchase actions require contextual review and any host/user confirmation the client provides.
+Caller-supplied JavaScript, AppleScript, JXA source, and arbitrary DevTools methods are deliberately unsupported. Actions use fixed implementation code and structured selectors. The debugger adapter is restricted to fixed `Input` commands, attaches only around one trusted action, and detaches in `finally`. `auto` falls back only before any Input dispatch; after dispatch begins, failure is reported as an unknown outcome and is never replayed through DOM. The broker and extension require a protocol-3 `hello`/`hello_ack` exchange plus exact packaged-version and capability equality before either reports readiness. Pairing material is persisted only after acknowledgement, and an invalid replacement candidate cannot displace the current connection or overwrite its stored endpoint/token. This removes an avoidable arbitrary-evaluation surface but does not make DOM or Accessibility actions safe. Pages can contain prompt injection, misleading labels, hidden consequences, cross-origin frames unavailable to inspection, or state that changes between inspection and submission. High-impact account, financial, legal, medical, publishing, deletion, and purchase actions require contextual review and any host/user confirmation the client provides.
 
-Text and file resources can be injected locally so their contents do not appear in MCP arguments or results. The destination page/application still receives the value, and remote tool metadata/results still traverse the Worker and host. Page source and screenshots can themselves contain secrets. Browser/app tool arguments, source, screenshots, field values, and results are intentionally omitted from operational logs.
+Text and file resources can be injected locally so their contents do not appear in MCP arguments or results. The destination page/application still receives the value, and remote tool metadata/results still traverse the Worker and host. Page source and screenshots can themselves contain secrets. Source/inspection budgets are aggregate across frames, page-controlled metadata is bounded, URL userinfo is removed from semantic snapshots, and contenteditable controls with secret-like identity are treated as sensitive; these limits reduce accidental exposure but do not classify every possible secret. Browser/app tool arguments, source, screenshots, field values, and results are intentionally omitted from operational logs.
 
 ## Filesystem exposure
 

package/browser-extension/browser-operations.js

@@ -0,0 +1,515 @@
+(() => {
+  if (globalThis.__machineBridgeBrowserOperations) return;
+
+  const MAX_ACCESSIBLE_FRAMES = 64;
+
+  async function dispatch(method, params, state) {
+    if (method === "list_tabs") return listTabs(params);
+    if (method === "manage_tabs") return manageTabs(params);
+    if (method === "wait") return browserWait(params, state);
+    if (method === "get_source") return getSource(params, state);
+    if (method === "inspect_page") return inspectPage(params, state);
+    if (method === "action") return browserAction(params, state);
+    if (method === "fill_form") return fillForm(params, state);
+    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 || "",
+        })),
+    };
+  }
+  
+  
+  async function manageTabs(params) {
+    if (params.action === "new") {
+      const tab = await chrome.tabs.create({ url: params.url || "about:blank", active: params.active !== false });
+      return { action: "new", ...publicTab(tab) };
+    }
+    const tab = await chrome.tabs.get(params.tabId);
+    if (params.action === "activate") {
+      await chrome.tabs.update(tab.id, { active: true });
+      await chrome.windows.update(tab.windowId, { focused: true });
+      return { action: "activate", ...publicTab(await chrome.tabs.get(tab.id)) };
+    }
+    if (params.action === "close") {
+      const result = { action: "close", closed: true, ...publicTab(tab) };
+      await chrome.tabs.remove(tab.id);
+      return result;
+    }
+    throw new Error("unsupported browser tab action");
+  }
+  
+  async function browserWait(params, state) {
+    const tab = await resolveTab(params.tabId);
+    const deadline = Date.now() + Math.max(1, Number(params.timeoutMs) || 30000);
+    let last = null;
+    while (Date.now() <= deadline) {
+      throwIfCancelled(state);
+      const current = await chrome.tabs.get(tab.id);
+      const urlMatched = !params.urlContains || String(current.url || "").includes(params.urlContains);
+      const needsPage = Boolean(params.selector || params.text || params.loadState);
+      let page = { matched: true, ready_state: current.status || "" };
+      if (needsPage) {
+        try {
+          assertPageTab(current);
+          const [execution] = await executePageAutomation(scriptTarget(current.id, params.frameId, false), "checkWait", params);
+          page = execution?.result || { matched: false };
+        } catch (error) {
+          const message = String(error?.message || error).replace(/\s+/g, " ").slice(0, 500);
+          if (message.includes("invalid CSS selector") || message.includes("selector matched")) throw new Error(message);
+          page = { matched: false, error: message };
+        }
+      }
+      last = { url_matched: urlMatched, ...page };
+      if (urlMatched && page.matched === true) {
+        return { ok: true, tab_id: current.id, title: current.title || "", url: current.url || "", condition: last };
+      }
+      await delay(200);
+    }
+    throw new Error(`browser wait timed out; last condition: ${JSON.stringify(last || {})}`);
+  }
+  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, state) {
+    const tab = await resolveTab(params.tabId);
+    assertPageTab(tab);
+    const maxBytes = Math.max(1, Number(params.maxBytes) || 1024 * 1024);
+    const selection = await discoverPageFrames(tab.id, params.frameId, params.allFrames === true);
+    let remainingBytes = maxBytes;
+    const frames = [];
+    for (let index = 0; index < selection.frames.length && remainingBytes > 0; index += 1) {
+      throwIfCancelled(state);
+      const remainingFrames = selection.frames.length - index;
+      const frameBudget = Math.max(1, Math.floor(remainingBytes / remainingFrames));
+      const [execution] = await chrome.scripting.executeScript({
+        target: { tabId: tab.id, frameIds: [selection.frames[index].frameId] },
+        func: boundedDocumentSource,
+        args: [frameBudget],
+      });
+      const result = execution?.result || { source: "", bytes: 0, returned_bytes: 0, truncated: true, url: selection.frames[index].url };
+      const returnedBytes = Math.max(0, Math.min(frameBudget, Number(result.returned_bytes ?? result.bytes) || 0));
+      remainingBytes -= returnedBytes;
+      frames.push({ frame_id: execution?.frameId ?? selection.frames[index].frameId, ...result, returned_bytes: returnedBytes, bytes: returnedBytes });
+    }
+    return {
+      tab_id: tab.id,
+      title: tab.title || "",
+      url: tab.url || "",
+      frames,
+      returned_bytes: maxBytes - remainingBytes,
+      max_bytes: maxBytes,
+      frames_truncated: selection.truncated || frames.length < selection.frames.length,
+    };
+  }
+  
+  async function inspectPage(params, state) {
+    const tab = await resolveTab(params.tabId);
+    assertPageTab(tab);
+    const maxElements = Math.max(1, Number(params.maxElements) || 300);
+    const selection = await discoverPageFrames(tab.id, params.frameId, params.allFrames === true, maxElements);
+    let remainingElements = maxElements;
+    const frames = [];
+    for (let index = 0; index < selection.frames.length && remainingElements > 0; index += 1) {
+      throwIfCancelled(state);
+      const remainingFrames = selection.frames.length - index;
+      const frameBudget = Math.max(1, Math.floor(remainingElements / remainingFrames));
+      const [execution] = await executePageAutomation(
+        { tabId: tab.id, frameIds: [selection.frames[index].frameId] },
+        "inspect",
+        { maxElements: frameBudget, includeValues: params.includeValues === true },
+      );
+      const result = execution?.result || { elements: [], truncated: true };
+      const used = Math.min(frameBudget, Array.isArray(result.elements) ? result.elements.length : 0);
+      remainingElements -= used;
+      frames.push({ frame_id: execution?.frameId ?? selection.frames[index].frameId, ...result });
+    }
+    return {
+      tab_id: tab.id,
+      title: tab.title || "",
+      url: tab.url || "",
+      frames,
+      total_elements: maxElements - remainingElements,
+      max_elements: maxElements,
+      frames_truncated: selection.truncated,
+    };
+  }
+  
+  async function discoverPageFrames(tabId, frameId, allFrames, resultBudget = MAX_ACCESSIBLE_FRAMES) {
+    if (Number.isInteger(frameId)) return { frames: [{ frameId, url: "" }], truncated: false };
+    if (!allFrames) return { frames: [{ frameId: 0, url: "" }], truncated: false };
+    const executions = await chrome.scripting.executeScript({
+      target: { tabId, allFrames: true },
+      func: () => ({ url: String(location.href || "").slice(0, 8192) }),
+    });
+    const ordered = executions
+      .filter((item) => Number.isInteger(item.frameId))
+      .map((item) => ({ frameId: item.frameId, url: item.result?.url || "" }))
+      .sort((left, right) => (left.frameId === 0 ? -1 : right.frameId === 0 ? 1 : left.frameId - right.frameId));
+    const limit = Math.max(1, Math.min(MAX_ACCESSIBLE_FRAMES, Number(resultBudget) || 1));
+    return { frames: ordered.slice(0, limit), truncated: ordered.length > limit };
+  }
+  
+  function boundedDocumentSource(limit) {
+    const maxBytes = Math.max(1, Number(limit) || 1);
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    const VOID_ELEMENTS = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+    const MAX_NODES = 100000;
+    const MAX_ATTRIBUTES = 256;
+    const MAX_ATTRIBUTE_CHARS = 4096;
+    const MAX_TEXT_CHARS = 32768;
+    let returnedBytes = 0;
+    let budgetExhausted = false;
+    let safetyTruncated = false;
+    let visitedNodes = 0;
+    let openShadowRoots = 0;
+  
+    const append = (raw) => {
+      if (budgetExhausted) return false;
+      let text = String(raw || "");
+      const remaining = maxBytes - returnedBytes;
+      if (remaining <= 0) { budgetExhausted = true; return false; }
+      const maxChars = Math.max(1024, remaining);
+      if (text.length > maxChars) { text = text.slice(0, maxChars); safetyTruncated = true; }
+      const bytes = encoder.encode(text);
+      if (bytes.byteLength <= remaining) {
+        chunks.push(text);
+        returnedBytes += bytes.byteLength;
+        return true;
+      }
+      chunks.push(decoder.decode(bytes.slice(0, remaining)));
+      returnedBytes = maxBytes;
+      budgetExhausted = true;
+      return false;
+    };
+    const bounded = (value, maxChars) => {
+      const text = String(value || "");
+      if (text.length > maxChars) safetyTruncated = true;
+      return text.slice(0, maxChars);
+    };
+    const escapeText = (value) => bounded(value, MAX_TEXT_CHARS).replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+    const escapeAttribute = (value) => bounded(value, MAX_ATTRIBUTE_CHARS).replaceAll("&", "&amp;").replaceAll('"', "&quot;");
+  
+    if (document.doctype) append(`<!DOCTYPE ${bounded(document.doctype.name || "html", 100)}>\n`);
+    const stack = [...document.childNodes].reverse().map((node) => ({ node }));
+    while (stack.length && !budgetExhausted) {
+      if (visitedNodes >= MAX_NODES) { safetyTruncated = true; break; }
+      const item = stack.pop();
+      if (item.raw) { append(item.raw); continue; }
+      if (item.close) { append(item.close); continue; }
+      const node = item.node;
+      if (!node || node.nodeType === 10) continue;
+      visitedNodes += 1;
+      if (node.nodeType === 1) {
+        const tag = bounded(node.tagName || "div", 100).toLowerCase();
+        if (!append(`<${tag}`)) break;
+        const attributes = node.attributes || [];
+        const attributeCount = Math.min(Number(attributes.length) || 0, MAX_ATTRIBUTES);
+        for (let attributeIndex = 0; attributeIndex < attributeCount; attributeIndex += 1) {
+          const attribute = attributes[attributeIndex] || attributes.item?.(attributeIndex);
+          if (!attribute) continue;
+          if (!append(` ${bounded(attribute.name, 200)}="${escapeAttribute(attribute.value)}"`)) break;
+        }
+        if ((Number(attributes.length) || 0) > MAX_ATTRIBUTES) safetyTruncated = true;
+        if (!append(">")) break;
+        if (VOID_ELEMENTS.has(tag)) continue;
+        stack.push({ close: `</${tag}>` });
+        const shadowChildren = node.shadowRoot?.childNodes || [];
+        if ((Number(shadowChildren.length) || 0) > 0) {
+          openShadowRoots += 1;
+          stack.push({ raw: "</template>" });
+          for (let index = (Number(shadowChildren.length) || 0) - 1; index >= 0; index -= 1) stack.push({ node: shadowChildren[index] || shadowChildren.item?.(index) });
+          stack.push({ raw: '<template data-machine-bridge-shadow-root="open">' });
+        }
+        const children = node.content?.childNodes || node.childNodes || [];
+        for (let index = (Number(children.length) || 0) - 1; index >= 0; index -= 1) stack.push({ node: children[index] || children.item?.(index) });
+        continue;
+      }
+      if (node.nodeType === 3) {
+        const parentTag = String(node.parentElement?.tagName || "").toLowerCase();
+        append(parentTag === "script" || parentTag === "style" ? bounded(node.data, MAX_TEXT_CHARS) : escapeText(node.data));
+        continue;
+      }
+      if (node.nodeType === 8) append(`<!--${bounded(node.data, MAX_TEXT_CHARS).replaceAll("--", "- -")}-->`);
+    }
+    if (safetyTruncated && !budgetExhausted) append("<!-- machine-bridge source truncated by safety limit -->");
+    return {
+      source: chunks.join(""),
+      bytes: returnedBytes,
+      returned_bytes: returnedBytes,
+      truncated: budgetExhausted || safetyTruncated || stack.length > 0,
+      visited_nodes: visitedNodes,
+      node_limit: MAX_NODES,
+      open_shadow_roots: openShadowRoots,
+      url: String(location.href || "").slice(0, 8192),
+    };
+  }
+  
+  async function browserAction(params, state) {
+    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, state?.timeoutMs, state);
+      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, state?.timeoutMs, state);
+      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, state?.timeoutMs, state);
+      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, state?.timeoutMs, state);
+    let result;
+    try {
+      result = await performPageAction(tab, params);
+      await waiter.promise;
+    } catch (error) {
+      waiter.cancel();
+      throw error;
+    }
+    const current = await chrome.tabs.get(tab.id).catch(() => tab);
+    return { tab_id: current.id, title: current.title || "", url: current.url || "", ...result };
+  }
+  
+  async function performPageAction(tab, params) {
+    const trustedActions = new Set(["click", "double_click", "hover", "press", "type_text"]);
+    if (params.inputMode === "trusted" && !trustedActions.has(params.action)) {
+      throw new Error("trusted input is unavailable for this action");
+    }
+    const wantsTrusted = params.inputMode !== "dom" && trustedActions.has(params.action);
+    const topFrame = !Number.isInteger(params.frameId) || params.frameId === 0;
+    if (wantsTrusted && !topFrame && params.inputMode === "trusted") {
+      throw new Error("trusted input currently requires the top frame; use input_mode=dom for a subframe");
+    }
+    if (wantsTrusted && topFrame) {
+      const [prepared] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "prepareAction", params);
+      try {
+        const api = globalThis.__machineBridgeDevtoolsInput;
+        if (!api?.perform) {
+          const unavailable = new Error("trusted input module is unavailable");
+          Object.defineProperty(unavailable, "safeToFallback", { value: true });
+          throw unavailable;
+        }
+        await api.perform(tab.id, params.action, {
+          point: prepared.result?.point,
+          key: params.key || params.value || "Enter",
+          text: params.value || "",
+        });
+        return { ...prepared.result, input_mode: "trusted", trusted_input_fallback: false };
+      } catch (error) {
+        if (params.inputMode === "trusted") throw error;
+        if (error?.safeToFallback !== true) {
+          const detail = String(error?.message || error).replace(/\s+/g, " ").slice(0, 500);
+          throw new Error(`trusted browser input may have been partially dispatched; the action outcome is unknown. Inspect the page before retrying. (${detail})`);
+        }
+        const [fallback] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "action", params);
+        return {
+          ...fallback.result,
+          input_mode: "dom",
+          trusted_input_fallback: true,
+          fallback_reason: String(error?.message || error).slice(0, 500),
+        };
+      }
+    }
+    const [execution] = await executePageAutomation(scriptTarget(tab.id, params.frameId, false), "action", params);
+    return { ...execution.result, input_mode: "dom", trusted_input_fallback: false };
+  }
+  async function fillForm(params, state) {
+    const tab = await resolveTab(params.tabId);
+    assertPageTab(tab);
+    const waiter = beginTabWait(tab.id, params.waitFor, state?.timeoutMs, state);
+    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);
+    const [previousActive] = await chrome.tabs.query({ active: true, windowId: tab.windowId });
+    const changedActiveTab = previousActive?.id !== tab.id;
+    if (changedActiveTab) await chrome.tabs.update(tab.id, { active: true });
+    try {
+      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 };
+    } finally {
+      if (changedActiveTab && previousActive?.id) {
+        const [currentActive] = await chrome.tabs.query({ active: true, windowId: tab.windowId }).catch(() => []);
+        if (currentActive?.id === tab.id) await chrome.tabs.update(previousActive.id, { active: true }).catch(() => {});
+      }
+    }
+  }
+  
+  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, requestTimeoutMs = 30000, state = null) {
+    if (!mode || mode === "none") return { promise: Promise.resolve(), cancel() {} };
+    const waitTimeoutMs = Math.max(1000, boundedRequestTimeout(requestTimeoutMs) - 1000);
+    let settled = false;
+    let navigationStarted = false;
+    let pollTimer = null;
+    let cancellationTimer = null;
+    let timeout = null;
+    let lastPollError = "";
+    let resolveWait;
+    let rejectWait;
+    const promise = new Promise((resolvePromise, rejectPromise) => {
+      resolveWait = resolvePromise;
+      rejectWait = rejectPromise;
+    });
+    const cleanup = () => {
+      clearTimeout(timeout);
+      clearTimeout(pollTimer);
+      clearTimeout(cancellationTimer);
+      chrome.tabs.onUpdated.removeListener(listener);
+      chrome.tabs.onRemoved?.removeListener(removedListener);
+    };
+    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 (error) {
+        lastPollError = String(error?.message || error).replace(/\s+/g, " ").slice(0, 300);
+      }
+      pollTimer = setTimeout(pollReadyState, 100);
+    };
+    const pollCancellation = () => {
+      if (settled) return;
+      if (state?.cancelled) { settle(new Error("browser request cancelled")); return; }
+      cancellationTimer = setTimeout(pollCancellation, 100);
+    };
+    const removedListener = (removedId) => {
+      if (removedId === tabId) settle(new Error("browser tab closed during navigation wait"));
+    };
+    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);
+    chrome.tabs.onRemoved?.addListener(removedListener);
+    pollCancellation();
+    timeout = setTimeout(() => settle(new Error(`browser navigation wait timed out${lastPollError ? `: ${lastPollError}` : ""}`)), waitTimeoutMs);
+    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 delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  function boundedRequestTimeout(value) {
+    const timeout = Number(value);
+    if (!Number.isFinite(timeout)) return 30000;
+    return Math.max(1000, Math.min(185000, Math.floor(timeout)));
+  }
+
+  function throwIfCancelled(state) {
+    if (state?.cancelled) throw new Error("browser request cancelled");
+  }
+
+  Object.defineProperty(globalThis, "__machineBridgeBrowserOperations", {
+    value: Object.freeze({ dispatch, boundedRequestTimeout, boundedDocumentSource }),
+    configurable: false,
+  });
+})();

package/browser-extension/devtools-input.js

@@ -39,13 +39,18 @@
   async function withDebugger(tabId, operation) {
     const target = { tabId };
     let attached = false;
+    let dispatchStarted = false;
     try {
       await chrome.debugger.attach(target, "1.3");
       attached = true;
-      const send = (method, params = {}) => chrome.debugger.sendCommand(target, method, params);
+      const send = (method, params = {}) => {
+        dispatchStarted = true;
+        return chrome.debugger.sendCommand(target, method, params);
+      };
       return await operation(send);
     } catch (error) {
-      throw new Error(`trusted browser input unavailable: ${cleanError(error)}`);
+      if (error?.machineBridgeTrustedInput === true) throw error;
+      throw trustedInputError(error, { safeToFallback: !dispatchStarted, dispatchStarted });
     } finally {
       if (attached) {
         try { await chrome.debugger.detach(target); } catch {}
@@ -125,6 +130,16 @@
     return { x, y };
   }
 
+  function trustedInputError(error, { safeToFallback, dispatchStarted }) {
+    const wrapped = new Error(`trusted browser input unavailable: ${cleanError(error)}`);
+    Object.defineProperties(wrapped, {
+      machineBridgeTrustedInput: { value: true },
+      safeToFallback: { value: safeToFallback === true },
+      dispatchStarted: { value: dispatchStarted === true },
+    });
+    return wrapped;
+  }
+
   function cleanError(error) {
     return String(error?.message || error || "unknown error").replace(/\s+/g, " ").slice(0, 500);
   }

package/browser-extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Machine Bridge Browser",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "Connects the current Chromium browser profile to the local Machine Bridge runtime for user-authorized automation.",
   "permissions": [
     "tabs",
@@ -30,5 +30,5 @@
   "action": {
     "default_title": "Machine Bridge Browser"
   },
-  "version_name": "0.14.0"
+  "version_name": "0.15.0"
 }