Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(cua-driver): add capability-aware browser tools (#2257)
Francesco Bonacci0835daa6d415
diff --git a/.github/workflows/ci-nix-linux.yml b/.github/workflows/ci-nix-linux.ymlindex 2ae8d65cb2..f5b4e5ffea 100644--- a/.github/workflows/ci-nix-linux.yml+++ b/.github/workflows/ci-nix-linux.yml@@ -9,6 +9,7 @@ on:- "flake.lock"- "nix/cua-driver/**"- "libs/cua-driver/rust/**"+ - "libs/cua-driver/tests/fixtures/shared/web/index.html"- ".github/workflows/ci-nix-linux.yml"push:branches: [main]@@ -17,6 +18,7 @@ on:- "flake.lock"- "nix/cua-driver/**"- "libs/cua-driver/rust/**"+ - "libs/cua-driver/tests/fixtures/shared/web/index.html"- ".github/workflows/ci-nix-linux.yml"workflow_dispatch:diff --git a/.github/workflows/e2e-rust-linux.yml b/.github/workflows/e2e-rust-linux.ymlindex d86e4c5894..0e82849d27 100644--- a/.github/workflows/e2e-rust-linux.yml+++ b/.github/workflows/e2e-rust-linux.yml@@ -65,7 +65,7 @@ jobs:run: |sudo apt-get updatesudo apt-get install -y --no-install-recommends \- xvfb dbus-x11 at-spi2-core openbox python3-gi gir1.2-gtk-3.0 \+ xvfb dbus-x11 at-spi2-core openbox picom python3-gi gir1.2-gtk-3.0 \libgtk-3-dev clang pkg-config libdbus-1-dev libpipewire-0.3-dev \libspa-0.2-dev libei-dev libx11-dev libxi-dev libxtst-dev libxext-dev \libwebkit2gtk-4.1-dev libssl-dev libxdo-dev \@@ -76,7 +76,7 @@ jobs:run: |xvfb-run -a --server-args="-screen 0 1920x1080x24" \dbus-run-session -- bash -lc \- "openbox >/tmp/cua-openbox.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"+ "openbox >/tmp/cua-openbox.log 2>&1 & picom --backend xrender --config /dev/null >/tmp/cua-picom.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"- name: Upload shared resultsif: always()uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4@@ -104,7 +104,7 @@ jobs:run: |sudo apt-get updatesudo apt-get install -y --no-install-recommends \- xvfb dbus-x11 at-spi2-core openbox python3-gi gir1.2-gtk-3.0 \+ xvfb dbus-x11 at-spi2-core openbox picom python3-gi gir1.2-gtk-3.0 \libgtk-3-dev clang pkg-config libdbus-1-dev libpipewire-0.3-dev \libspa-0.2-dev libei-dev libx11-dev libxi-dev libxtst-dev libxext-dev \libwebkit2gtk-4.1-dev libssl-dev libxdo-dev \@@ -115,7 +115,7 @@ jobs:run: |xvfb-run -a --server-args="-screen 0 1920x1080x24" \dbus-run-session -- bash -lc \- "openbox >/tmp/cua-openbox.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"+ "openbox >/tmp/cua-openbox.log 2>&1 & picom --backend xrender --config /dev/null >/tmp/cua-picom.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"- name: Upload native resultsif: always()uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4@@ -143,7 +143,7 @@ jobs:run: |sudo apt-get updatesudo apt-get install -y --no-install-recommends \- xvfb dbus-x11 at-spi2-core openbox python3-gi gir1.2-gtk-3.0 \+ xvfb dbus-x11 at-spi2-core openbox picom python3-gi gir1.2-gtk-3.0 \libgtk-3-dev clang pkg-config libdbus-1-dev libpipewire-0.3-dev \libspa-0.2-dev libei-dev libx11-dev libxi-dev libxtst-dev libxext-dev \libwebkit2gtk-4.1-dev libssl-dev libxdo-dev \@@ -154,7 +154,7 @@ jobs:run: |xvfb-run -a --server-args="-screen 0 1920x1080x24" \dbus-run-session -- bash -lc \- "openbox >/tmp/cua-openbox.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"+ "openbox >/tmp/cua-openbox.log 2>&1 & picom --backend xrender --config /dev/null >/tmp/cua-picom.log 2>&1 & sleep 2; scripts/ci/linux/run-rust-e2e.sh"- name: Upload capture resultsif: always()uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4diff --git a/.github/workflows/e2e-rust-standalone-browsers.yml b/.github/workflows/e2e-rust-standalone-browsers.ymlnew file mode 100644index 0000000000..aefd0ebe80--- /dev/null+++ b/.github/workflows/e2e-rust-standalone-browsers.yml@@ -0,0 +1,127 @@+name: "E2E: Rust standalone browsers"++on:+ workflow_dispatch:+ inputs:+ ref:+ description: "Optional full 40-character commit SHA; defaults to dispatch SHA"+ required: false+ default: ""++permissions:+ contents: read+ actions: read++jobs:+ source:+ name: "Resolve exact source"+ runs-on: ubuntu-latest+ outputs:+ sha: ${{ steps.resolve.outputs.sha }}+ steps:+ - id: resolve+ name: Validate source SHA+ shell: bash+ env:+ REQUESTED_SHA: ${{ inputs.ref }}+ DISPATCH_SHA: ${{ github.sha }}+ run: |+ sha="${REQUESTED_SHA:-$DISPATCH_SHA}"+ if [[ ! "$sha" =~ ^[0-9a-fA-F]{40}$ ]]; then+ echo "ref must be a full 40-character commit SHA" >&2+ exit 2+ fi+ echo "sha=${sha,,}" >> "$GITHUB_OUTPUT"++ browser:+ name: "${{ matrix.label }} / Chrome and Edge"+ needs: source+ strategy:+ fail-fast: false+ matrix:+ include:+ - label: Windows+ os: windows-latest+ artifact: rust-browser-windows+ - label: Linux X11+ os: ubuntu-latest+ artifact: rust-browser-linux-x11+ runs-on: ${{ matrix.os }}+ timeout-minutes: 60+ env:+ CUA_E2E_SOURCE_SHA: ${{ needs.source.outputs.sha }}+ CUA_TEST_REQUIRE_EXTERNAL_BROWSERS: "1"+ CUA_E2E_FORBID_SKIPS: "1"+ CUA_TEST_DRIVER_STDERR: "1"+ CUA_E2E_BROWSER_STDERR: "1"+ RUST_BACKTRACE: "1"+ steps:+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+ with:+ ref: ${{ needs.source.outputs.sha }}+ - uses: dtolnay/rust-toolchain@stable+ - name: Install Windows video tools+ if: runner.os == 'Windows'+ shell: pwsh+ run: |+ if (-not (Get-Command ffmpeg.exe -ErrorAction SilentlyContinue)) {+ choco install ffmpeg -y --no-progress+ }+ ffmpeg -version+ ffprobe -version+ - name: Install Linux desktop dependencies+ if: runner.os == 'Linux'+ shell: bash+ run: |+ sudo apt-get update+ sudo apt-get install -y --no-install-recommends \+ xvfb dbus-x11 at-spi2-core openbox picom libgtk-3-dev clang pkg-config \+ libdbus-1-dev libpipewire-0.3-dev libspa-0.2-dev libei-dev \+ libx11-dev libxi-dev libxtst-dev libxext-dev libssl-dev \+ libxdo-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev \+ librsvg2-dev ffmpeg+ google-chrome --version+ - name: Build source driver on Windows+ if: runner.os == 'Windows'+ shell: pwsh+ run: cargo build --release -p cua-driver --manifest-path libs/cua-driver/rust/Cargo.toml+ - name: Build source driver on Linux+ if: runner.os == 'Linux'+ shell: bash+ run: cargo build --release -p cua-driver --manifest-path libs/cua-driver/rust/Cargo.toml+ - name: Run standalone browsers on Windows+ if: runner.os == 'Windows'+ shell: pwsh+ run: |+ $env:CUA_E2E_ARTIFACT_DIR = Join-Path $PWD "artifacts\cua-driver\standalone-browser"+ scripts\ci\windows\run-rust-standalone-browser-e2e.ps1 -NoBuild+ - name: Run standalone browsers on Linux X11+ if: runner.os == 'Linux'+ shell: bash+ run: |+ export CUA_E2E_ARTIFACT_DIR="$PWD/artifacts/cua-driver/standalone-browser"+ export CUA_E2E_SKIP_BUILD=1+ # Hosted Linux does not provide a browser sandbox suitable for the+ # isolated test profiles. This affects only disposable test browsers.+ export CUA_E2E_BROWSER_NO_SANDBOX=1+ xvfb-run -a --server-args="-screen 0 1920x1080x24" \+ dbus-run-session -- bash -lc \+ 'openbox >/tmp/cua-browser-openbox.log 2>&1 & picom --backend xrender --config /dev/null >/tmp/cua-browser-picom.log 2>&1 & sleep 2; exec scripts/ci/run-rust-standalone-browser-e2e.sh'+ - name: Publish job summary+ if: always()+ shell: bash+ run: |+ if [[ -f artifacts/cua-driver/standalone-browser/summary.md ]]; then+ cat artifacts/cua-driver/standalone-browser/summary.md >> "$GITHUB_STEP_SUMMARY"+ else+ echo "Standalone browser summary was not produced." >> "$GITHUB_STEP_SUMMARY"+ fi+ - name: Upload browser evidence+ if: always()+ uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4+ with:+ name: ${{ matrix.artifact }}+ path: artifacts/cua-driver/standalone-browser+ if-no-files-found: error+ compression-level: 0+ retention-days: 14diff --git a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdxnew file mode 100644index 0000000000..94428a3b9c--- /dev/null+++ b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx@@ -0,0 +1,106 @@+---+title: "Browser Targeting and Background Delivery"+description: "Why browser automation needs an exact native-window-to-tab binding, and how CDP adds a full-background rung to Cua Driver."+---++# Browser Targeting and Background Delivery++A browser presents two identities at once. The desktop knows a native process+and window; the browser runtime knows DevTools targets and tabs. Acting safely+in the background requires proof that both identities describe the same+surface.++## The connection point is the native window++Agents still begin with `list_apps` and `list_windows`. They select a concrete+`(pid, window_id)`, just as they do for accessibility and pixel actions.+`get_browser_state` correlates that native window with a browser target and+mints opaque target and tab capabilities. Raw DevTools target identifiers are+not part of the public contract.++This preserves one targeting model across native and web content. It also+prevents a browser helper from choosing the first tab, first window, or first+process match when several candidates exist.++## Exact or refused++Mutation is allowed only after independent evidence agrees:++- the DevTools endpoint is loopback-only and owned by the requested process;+- the native window belongs to that process;+- native and DevTools window geometry identify the same surface; and+- the binding still holds immediately before each mutation.++Electron versions that do not expose a DevTools window identifier have a+narrow fallback: the process must own exactly one native window and the+endpoint must expose exactly one page. If either count changes, mutation is+refused. A heuristic discovery result may be useful for inspection, but it is+never promoted into an action route.++## A full-background rung++Accessibility actions and targeted pixel injection depend on what the OS and+application surface accept. Chromium can reject some background keyboard or+pointer routes even when the operating system delivered them correctly.++The browser tools add a higher, page-aware rung through the Chrome DevTools+Protocol. Page navigation, the default ref-bound text insertion route, and an+explicit synthetic DOM click can address an occluded tab without moving the+real cursor or borrowing keyboard focus. This is a full-background route for+an exactly bound Chromium page, rather than best-effort OS input.++Trusted CDP pointer input remains distinct from synthetic DOM events. The+default click uses `Input.dispatchMouseEvent`, but Chromium's standalone window+is known to activate on that route on macOS and Linux. Cua Driver returns+`browser_input_trust_unavailable` there before dispatch. Standalone Chrome and+Edge on Windows, and the bounded embedded Electron route, have passing trusted+background evidence.++A caller must explicitly request `input_route: "dom_event"` to invoke an+element's DOM click behavior. That route is synthetic even when it preserves+full-background posture. The driver does not silently change trust models to+make a call appear successful.++## Capabilities have a lifetime++Target ids, tab ids, and page refs belong to a named driver session. Page refs+also belong to one snapshot. A newer snapshot or navigation invalidates older+refs, and ending the session revokes all of its browser capabilities.++This makes stale state visible. An agent re-snapshots and retries with current+evidence instead of accidentally acting on a node that moved, disappeared, or+now belongs to another document.++## Why setup is explicit++Browser inspection never enables remote debugging or restarts a browser as a+side effect. `browser_prepare` is a separate destructive approval boundary. It+may launch another browser with a driver-owned `isolated_new` or+`isolated_named` profile, but it never copies, modifies, restarts, or terminates+the selected user profile. Remote-debugging arguments passed through+`launch_app` are refused.++An MCP host supplies approval through its destructive-tool approval path.+Direct CLI and raw-socket callers use a short-lived, single-use token minted by+the interactive `browser-approve` command. A Boolean supplied by the model is+not treated as user consent.++## Platform meaning++Page-aware routes are cross-platform, but exact native correlation and input+trust remain platform and surface capabilities:++- macOS uses process ownership and native window geometry.+- Windows uses HWND ownership and DPI-aware geometry.+- Linux X11 and Sway expose sufficient ownership and geometry for exact routes+ in the validated configurations.+- generic Wayland discovery without compositor-provided exact geometry remains+ read-only; it cannot authorize mutation.++The same rule applies to embedded webviews. Electron's bounded single-page,+single-window shape can be exact. A native host and renderer split across+different processes, as in common WebView2 deployments, is refused until the+driver can prove that relationship independently.++See [Drive a web page](/how-to-guides/driver/drive-a-web-page) for the workflow+and [Known limits](/reference/cua-driver/limits) for current scope.diff --git a/docs/content/docs/concepts/meta.json b/docs/content/docs/concepts/meta.jsonindex e1cca1107c..5315c515fc 100644--- a/docs/content/docs/concepts/meta.json+++ b/docs/content/docs/concepts/meta.json@@ -1 +1,17 @@-{ "title": "Concepts", "icon": "Lightbulb", "pages": ["index", "what-is-computer-use", "the-no-foreground-contract", "capture-and-delivery-modalities", "how-permission-policies-work", "how-cua-driver-is-validated", "how-sandboxes-work", "how-lume-unattended-setup-works", "how-sip-works-in-lume-vms", "how-lume-expands-macos-disks"] }+{+ "title": "Concepts",+ "icon": "Lightbulb",+ "pages": [+ "index",+ "what-is-computer-use",+ "the-no-foreground-contract",+ "capture-and-delivery-modalities",+ "browser-targeting-and-background-delivery",+ "how-permission-policies-work",+ "how-cua-driver-is-validated",+ "how-sandboxes-work",+ "how-lume-unattended-setup-works",+ "how-sip-works-in-lume-vms",+ "how-lume-expands-macos-disks"+ ]+}diff --git a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdxindex b77e934dce..171c487853 100644--- a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx+++ b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx@@ -1,70 +1,188 @@---title: 'Drive a Web Page'-description: 'Read and act on the page already loaded in a browser or Electron app with the page tool: get text, query the DOM, click, insert text, type keystrokes, run JavaScript.'+description: 'Bind an exact browser window, inspect its active tab, and navigate, click, or type without foregrounding it.'---# Drive a Web Page-Use the `page` tool on the page already loaded in a running browser or Electron app. Open the URL first, either through `launch_app` or by having the user open it. This is the DOM/CDP path. Honest-verification `escalation.recommended: 'page'` points here when AX typing echoes but the DOM does not observe it. For the agent-side escalation behavior, see [Agent action policy](/reference/cua-driver/action-selection-policy) and [Capture and delivery modalities](/concepts/capture-and-delivery-modalities).+Use the browser tools when an agent must act inside Chromium or an Electron+page without raising the native window. The tools bind the `(pid, window_id)`+you selected to a DevTools target, then issue page input through that exact+binding.-## When to use it+## Inspect the selected browser first-Use `page` when the target is browser-tab content and the accessibility layer cannot prove the result. It is especially useful after `type_text` returns `effect: "unverifiable"` with `escalation.recommended: "page"`.+First use `list_apps` and `list_windows` as usual, then call+`get_browser_state` with the selected native `(pid, window_id)`. If that browser+already exposes an owned loopback DevTools endpoint, the driver binds it without+changing the browser.-Read actions (`get_text`, `query_dom`) work broadly, and `execute_javascript` works cross-platform given a CDP endpoint. `insert_text` and `type_keystrokes` are macOS-only for now; Windows and Linux return a clear "not implemented" error rather than a silent no-op. See the [`page` tool reference](/reference/cua-driver/mcp-tools#page) for the full action list, parameters, and platform notes.+Do not pass remote-debugging flags or a user-data directory through+`launch_app`. Cua Driver rejects those flags because they could expose a+person's normal profile to DevTools.-## insert_text vs type_keystrokes+## Prepare an isolated browser when required-`insert_text` does a bulk CDP DOM-level insert. It is fast and does not fire JS key events. `type_keystrokes` sends per-character keydown/keyup events through CDP. It is slower and fires JS handlers. Use `type_keystrokes` for React/Vue inputs and other frameworks that listen for key events.+If inspection returns `browser_requires_setup`, call `browser_prepare` as a+separate approved operation. It starts another Chromium process with a+driver-owned profile; it never copies, modifies, restarts, or terminates the+selected user profile.-## Examples+In an MCP client, approve the destructive tool call through the client's normal+approval UI:-Read all visible text from an open page:+```jsonc+browser_prepare({+ "pid": 844,+ "session": "research-1",+ "allow_launch": true,+ "profile": {"mode": "isolated_new"}+})+```++The response includes `prepared_pid`. Call `list_windows` for that new process,+then bind its window with `get_browser_state`. An `isolated_new` profile is+removed when its owning session ends. Use+`profile: {"mode":"isolated_named","name":"research"}` only when the+automation profile must survive across sessions.++For direct CLI or raw-socket use, mint a five-minute, single-use token from an+interactive terminal first:++```bash+cua-driver browser-approve --pid 844 --profile-mode isolated_new+```++Pass the returned token as `approval_token` in the otherwise identical+`browser_prepare` call. `get_browser_state` never performs this setup itself.++## Bind the native window++Browser capabilities are scoped to a driver session. Start one and pass the+same session value to every browser call:++```jsonc+start_session({"session": "research-1"})++get_browser_state({+ "pid": 844,+ "window_id": 10725,+ "session": "research-1"+})+```++Keep the returned opaque `target_id` and the `tab_id` whose `active` field is+`true`. Mutation is available only when `binding_quality` is `exact`. A+heuristic or ambiguous match is refused.++## Snapshot the tab++Snapshot the selected tab before using an element ref:++```jsonc+get_browser_state({+ "target_id": "<target_id>",+ "tab_id": "<tab_id>",+ "session": "research-1"+})+```++The response contains interactive elements with refs such as `p1:7`. Refs are+valid only for that session, target, tab, and latest snapshot. Take a fresh+snapshot after navigation or whenever a call returns `browser_ref_stale`.++## Click and type++The default click route requests Chromium's trusted input domain:```jsonc-page({- pid,- window_id,- action: "get_text"+browser_click({+ "target_id": "<target_id>",+ "tab_id": "<tab_id>",+ "ref": "p1:7",+ "session": "research-1"})```-Query a CSS selector and return its `href` attribute:+Use viewport `x` and `y` instead of `ref` when the page snapshot cannot name+the rendered target. Standalone Chrome and Edge on Windows have passing+full-background evidence for this route. Standalone Chromium on macOS and Linux+returns `browser_input_trust_unavailable` because dispatching the trusted+pointer event activates the native browser window.++To request a synthetic full-background DOM click deliberately, pass+`input_route: "dom_event"` with a ref:```jsonc-page({- pid,- window_id,- action: "query_dom",- css_selector: "a.docs-link",- attributes: ["href"]+browser_click({+ "target_id": "<target_id>",+ "tab_id": "<tab_id>",+ "ref": "p1:7",+ "input_route": "dom_event",+ "session": "research-1"})```-Type into the focused input field with real key events:+Use this only when the page's DOM click semantics are acceptable. The driver+never silently falls back from trusted input to a DOM event.++Snapshot again, then type into the fresh input ref:```jsonc-page({- action: "type_keystrokes",- text: "status: ready",- cdp_port: 9222,- target_url_contains: "localhost"+browser_type({+ "target_id": "<target_id>",+ "tab_id": "<tab_id>",+ "ref": "p2:3",+ "text": "status: ready",+ "session": "research-1"})```-Run JavaScript to read a value from the page:+The default `insert_text` mode is efficient for ordinary text. Use+`mode: "keystrokes"` when the page depends on per-character keyboard events.++## Navigate```jsonc-page({- pid,- window_id,- action: "execute_javascript",- javascript: "document.querySelector('#total')?.textContent"+browser_navigate({+ "target_id": "<target_id>",+ "tab_id": "<tab_id>",+ "url": "https://example.com",+ "session": "research-1"})```+Navigation invalidates every prior ref for the tab. Wait for the destination,+then call `get_browser_state` in snapshot mode again.++## End the session++```jsonc+end_session({"session": "research-1"})+```++Ending the session revokes its target, tab, and element capabilities.++## Embedded webviews++Electron has an exact route only while one proven native window maps to one CDP+page. Adding another page or window invalidates that route. Tauri, WKWebView,+WebKitGTK, and the split-process WebView2 shape currently return+`browser_route_unavailable` unless the driver can independently prove the+native-host-to-engine relationship. Continue with native `get_window_state`+and AX/PX actions for those surfaces.++## Legacy page actions++The older `page` tool remains available for compatibility and for its read+actions. It preserves its first-page and URL-hint behavior, but now shares the+event-aware CDP transport used by the typed browser tools. New browser mutation+workflows should use the typed browser tools so window correlation, endpoint+ownership, capability lifetime, and refusal reasons remain explicit.+## Related-- [page tool reference](/reference/cua-driver/mcp-tools#page)-- [Agent action policy](/reference/cua-driver/action-selection-policy)+- [Browser targeting and background delivery](/concepts/browser-targeting-and-background-delivery)+- [Browser tool reference](/reference/cua-driver/mcp-tools#get_browser_state)+- [Known limits](/reference/cua-driver/limits)- [Capture and delivery modalities](/concepts/capture-and-delivery-modalities)diff --git a/docs/content/docs/reference/cua-driver/limits.mdx b/docs/content/docs/reference/cua-driver/limits.mdxindex 75b7cdc1a0..870bae024e 100644--- a/docs/content/docs/reference/cua-driver/limits.mdx+++ b/docs/content/docs/reference/cua-driver/limits.mdx@@ -14,6 +14,47 @@ operating-system matrix.---+## Browser tools target exactly bound Chromium pages++The typed browser mutation tools currently target Chromium-family browsers and+Electron through an owned Chrome DevTools Protocol endpoint. Safari and Firefox+may still be inspected through existing accessibility or legacy page routes,+but they do not receive typed browser mutation capabilities.++| Surface | Typed browser identity | Typed mutation | Available fallback |+| --- | --- | --- | --- |+| Chrome, Edge, Chromium, Electron | Chromium | Exact CDP binding or structured refusal | Native `get_window_state` and AX/PX actions |+| Firefox | Gecko | `browser_route_unavailable` in the current release | Native accessibility and legacy `page` routes where supported |+| Safari | WebKit | `browser_route_unavailable` in the current release | Native accessibility and explicit legacy Apple Events routes |+| Tauri, WKWebView, and WebKitGTK hosts | WebKit where the host can be identified | Structured refusal until an exact engine/native-window binding exists | Native accessibility and pixel actions |+| WebView2 hosts | Chromium renderer in a separate process | Structured refusal for the common split-process shape | Native UIA and pixel actions |++Firefox is classified consistently as a browser on macOS, Windows, and Linux,+but Cua Driver does not currently advertise a WebDriver BiDi route. Safari+Apple Events JavaScript is not equivalent to trusted browser input, and mutable+tab ordinals cannot satisfy exact window targeting. These surfaces therefore+remain capability-visible but mutation-unavailable instead of being guessed.++Page refs traverse open shadow roots and same-process frames and are capped to+the first 300 interactive elements. Out-of-process frames are included only+when the runtime exposes a capability-tested CDP session for that frame;+otherwise the omitted frame is reported as a limitation instead of being+flattened into the main document. A newer snapshot or navigation invalidates+previous refs.++Chrome remote debugging is prepared only in a separate driver-owned isolated+profile. `browser_prepare` never enables it on, copies, or restarts the selected+user profile. Endpoint ownership must resolve to the requested browser pid;+wrapper processes or ambiguous process trees are refused.++On generic GNOME or KDE Wayland sessions, browser state may be discoverable+without enough compositor evidence to correlate native and DevTools geometry+exactly. That route stays read-only. X11 and the validated Sway configuration+can authorize mutation when their ownership and geometry proofs agree. This+does not imply arbitrary raw background PX delivery on Wayland.++---+## Chromium coerces synthetic right-clicks on web content**Symptom:** `right_click({pid, x, y})` on a Chrome, Edge, Brave, or Arc tab's web content fires a left-click instead of opening the context menu.diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 21bfbfcf75..6dc8312d75 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -12,7 +12,7 @@ description: Reference for every MCP tool Cua Driver exposesimport { Callout } from 'fumadocs-ui/components/callout';-`cua-driver` exposes 38 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.+`cua-driver` exposes 43 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](/reference/cua-driver/cli-reference) for CLI-specific options like `--socket` and `--screenshot-out-file`.@@ -146,7 +146,7 @@ Provide either `bundle_id` (preferred — unambiguous, e.g. `com.apple.calculatoOptional `urls` are handed to the app as open targets — for Finder, pass a folder path to open a backgrounded Finder window there.-Optional `cdp_debugging_port`: opens a Chrome DevTools Protocol (CDP) server on the specified port (appends --remote-debugging-port=N to the app's argv). Use this to automate Electron/VS Code/Cursor, or Chrome/Brave/Edge, via CDP.+Browser DevTools setup belongs to `browser_prepare`, which can prove that a separate isolated profile is driver-owned before enabling CDP.Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.@@ -160,7 +160,6 @@ Returns the launched app's pid, bundle_id, name, and a `windows` array (same sha- `additional_arguments` (array of string, optional): Extra arguments appended after --args when launching.- `bundle_id` (string, optional): App bundle identifier, e.g. com.apple.calculator. Preferred over name.-- `cdp_debugging_port` (integer, optional): Open a Chrome DevTools Protocol server on this port (appends --remote-debugging-port=N).- `creates_new_application_instance` (boolean, optional): When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one — on single-instance apps (e.g. Calculator) every caller otherwise gets the same window and the sessions clobber each other.- `name` (string, optional): App display name. Used only when bundle_id is absent.- `urls` (array of string, optional): Optional file paths or URLs to open with the app (e.g. a folder path for Finder).@@ -742,3 +741,83 @@ Install the ffmpeg binary used by start_recording's video capture (Linux/Windows**Arguments:**- `confirm` (boolean, optional): Run the install command. Without it, only the planned command is reported.++## Other tools++### `get_browser_state`++Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id to snapshot the tab's composed DOM (main frame, shadow DOM, same-process iframes, and capability-tested out-of-process iframes) and mint p<snapshot>:<index> element refs for browser_click / browser_type; each ref reports its frame kind. Never performs setup — a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.++**Arguments:**++- `pid` (integer, optional): Native browser process id (bind mode).+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.+- `tab_id` (string, optional): Opaque tab id from get_browser_state (session-scoped).+- `target_id` (string, optional): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).+- `window_id` (integer, optional): Native window id owned by pid (bind mode).++### `browser_prepare`++Explicitly prepare an owned DevTools endpoint for a browser pid. Existing endpoints are detected without side effects. Acting setup requires MCP-host approval or a short-lived token from the interactive browser-approve command, allow_launch=true, and a driver-owned isolated profile. It launches a separate browser and never copies, modifies, or terminates the requested user profile.++**Arguments:**++- `allow_launch` (boolean, optional): Allow a separate driver-owned isolated Chromium process to be launched (default false).+- `approval_token` (string, optional): Single-use token minted by `cua-driver browser-approve` for direct CLI/raw use. Omit for an MCP-host-approved call.+- `pid` (integer, required): Browser process id to prepare.+- `profile` (object, optional)+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.++```json+{"pid":844}+```++### `browser_navigate`++Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). Refused for heuristic bindings. Navigation invalidates all p<snapshot>:<index> refs for the tab.++**Arguments:**++- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.+- `tab_id` (string, required): Opaque tab id from get_browser_state (session-scoped).+- `target_id` (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).+- `url` (string, required): Destination URL (http:, https:, or about:).++```json+{"tab_id":"example","target_id":"example","url":"example"}+```++### `browser_click`++Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture. input_route="dom_event" (synthetic el.click(), ref required) is used only when explicitly requested. Refused for heuristic bindings.++**Arguments:**++- `input_route` (string, optional): "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested.+- `ref` (string, optional): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.+- `tab_id` (string, required): Opaque tab id from get_browser_state (session-scoped).+- `target_id` (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).+- `x` (number, optional): Viewport x (CSS px) — alternative to ref.+- `y` (number, optional): Viewport y (CSS px) — alternative to ref.++```json+{"tab_id":"example","target_id":"example"}+```++### `browser_type`++Type text into an exactly-bound tab via the Input domain. mode="insert_text" (default) uses Input.insertText; mode="keystrokes" dispatches per-character key events. Pass a ref to an editable element from the latest snapshot. A ref is required; heuristic bindings are refused.++**Arguments:**++- `mode` (string, optional): insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent.+- `ref` (string, required): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.+- `tab_id` (string, required): Opaque tab id from get_browser_state (session-scoped).+- `target_id` (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).+- `text` (string, required): Text to type.++```json+{"ref":"example","tab_id":"example","target_id":"example","text":"hello"}+```diff --git a/docs/content/docs/reference/cua-driver/platform-support.mdx b/docs/content/docs/reference/cua-driver/platform-support.mdxindex c396814529..f5513021d1 100644--- a/docs/content/docs/reference/cua-driver/platform-support.mdx+++ b/docs/content/docs/reference/cua-driver/platform-support.mdx@@ -30,6 +30,26 @@ scope, see [Capture and delivery modalities](/concepts/capture-and-delivery-moda| Linux X11 | X11/EWMH, XTest, AT-SPI, and toolkit accessibility bridges | Supported with toolkit-specific limits. Foreground input and semantic background actions are broadly covered. Toolkits that reject synthetic background events receive an explicit refusal instead of a silent success. || Linux Wayland | AT-SPI plus compositor-specific discovery, capture, activation, and portal input | Supported with compositor-specific limits. Semantic background actions work where the application exposes them. Raw input cannot generally be sent to an arbitrary occluded surface. |+## Browser-tool routes++Browser mutation always starts from an exact native `(pid, window_id)` binding.+The table records the strongest browser route currently proven by the Rust+harnesses; an unlisted trust class or host shape is not implied.++| Surface | Proven page routes | Explicit limit |+| --- | --- | --- |+| Standalone Chrome and Edge on Windows | Snapshot, navigation, ref-bound typing, trusted background click, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Elevated-integrity and unsupported native-host relationships still refuse |+| Standalone Chrome on macOS | Snapshot, navigation, ref-bound typing, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |+| Standalone Chrome on Linux X11 | Snapshot, navigation, ref-bound typing, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |+| Electron on Windows, macOS, X11, and validated Sway | Typed mutation while one proven native window maps to one CDP page | A second page or native window invalidates the bounded exact route |+| Tauri, WKWebView, WebKitGTK, and common split-process WebView2 | Browser identity plus a side-effect-free structured refusal | No exact native-host-to-engine relationship is currently proven |+| Safari and Firefox | Native discovery and native AX/PX fallbacks | No typed browser mutation engine is currently advertised |++`browser_prepare` may launch a separate driver-owned Chromium profile after an+approved destructive call. `isolated_new` processes and their complete child+trees are reaped and the marked profile is removed when the owning session+ends. The selected user's existing browser process and profile are not changed.+## Linux window systemsLinux support is recorded per window system and Wayland compositor. "Wayland"diff --git a/flake.nix b/flake.nixindex 59169cb306..9bda8a1c9a 100644--- a/flake.nix+++ b/flake.nix@@ -24,6 +24,13 @@pkgs = import nixpkgs { inherit system; };rustSrc = ./libs/cua-driver/rust;+ rustTestSrc = pkgs.lib.fileset.toSource {+ root = ./libs/cua-driver;+ fileset = pkgs.lib.fileset.unions [+ ./libs/cua-driver/rust+ ./libs/cua-driver/tests/fixtures/shared/web/index.html+ ];+ };cuaDriverPackage = import ./nix/cua-driver/package.nix {inherit pkgs;@@ -88,6 +95,7 @@packages = (with pkgs; [cargoclang+ chromiumdbusffmpeggobject-introspection@@ -126,7 +134,8 @@cua-driver-build = cuaDriverPackage;cua-driver-linux-rust-unit = import ./nix/cua-driver/tests/rust-unit.nix {inherit pkgs;- src = rustSrc;+ src = rustTestSrc;+ sourceSubdir = "rust";};cua-driver-policy-yaml = import ./nix/cua-driver/tests/policy-yaml.nix {inherit pkgs;diff --git a/libs/cua-driver/docs/browser-tool-implementation-journal.md b/libs/cua-driver/docs/browser-tool-implementation-journal.mdnew file mode 100644index 0000000000..bb48c2d093--- /dev/null+++ b/libs/cua-driver/docs/browser-tool-implementation-journal.md@@ -0,0 +1,536 @@+# Browser Tool Implementation Journal++This journal records implementation and validation evidence for the first-class+browser tools. It intentionally omits machine identities, credentials, private+URLs, profile paths, and raw DevTools endpoint identifiers.++## Definition of done++- Add a capability-aware browser API with five typed tools:+ `get_browser_state`, `browser_prepare`, `browser_navigate`, `browser_click`,+ and `browser_type`.+- Keep `get_browser_state` read-only and make setup explicit.+- Bind native `(pid, window_id)` targets to browser tabs exactly or refuse all+ mutation. Never promote a heuristic match into an action route.+- Scope browser targets, tabs, and page references to a named driver session.+- Validate with unit and protocol tests, source-built web harnesses, macOS+ locally, Windows in an interactive desktop, and Linux on the strongest+ representative X11 and Wayland lanes available.+- Keep the existing `page` tool compatible until the new browser routes have+ sufficient release evidence.++## 2026-07-14: architecture and base++- Started from `origin/main` at `4e9b26ed3077089c1812a62909b82ac5c5ae2150`+ on local branch `codex/browser-tool-v1`.+- Confirmed the implementation split follows the existing `PageBackend`+ inversion: shared contracts and CDP behavior in `cua-driver-core`; process,+ endpoint, native-window, and setup evidence in each platform crate.+- Accepted an exact-or-refused correlation route based on native ownership and+ bounds plus CDP `Browser.getWindowForTarget` and `Browser.getWindowBounds`.+- Kept two scope controls for v1: do not rewire the legacy `page` facade, and+ keep `browser_prepare` to explicit endpoint attachment or a minimal+ driver-owned debug launch.+- Platform evidence found in the existing source:+ - macOS: exact CGWindow owner, title, and bounds.+ - Windows: exact HWND owner plus DWM bounds.+ - Linux X11: geometry and client-declared `_NET_WM_PID`; require independent+ agreement with endpoint ownership before treating it as exact.+ - Sway: compositor-provided pid and rectangle.+ - Generic GNOME/KDE Wayland: no general exact pid-plus-geometry correlation;+ report read-only capability and refuse mutation.++## 2026-07-14: shared engine and security contract++- Added the five typed tools in `cua-driver-core` and registered the same+ schemas on every platform.+- Added a shared CDP transport, browser target store, structured refusal+ vocabulary, session cleanup, snapshot-scoped refs, and mutation+ serialization.+- Restricted endpoint discovery to loopback listeners whose operating-system+ owner matches the requested process. Browser websocket URLs and raw CDP+ target ids remain internal.+- Added process fingerprints and native-window ownership checks so a browser+ restart, pid reuse, closed window, moved tab, or endpoint change fails closed+ during mutation revalidation.+- Kept `get_browser_state` strictly read-only. `browser_prepare` detects an+ existing owned endpoint or returns an explicit setup/consent limitation; it+ does not silently relaunch or modify a profile.+- Added `cdp_debugging_port` launch support on Windows and Linux, matching the+ existing macOS launch surface.+- Made the public `session` argument authoritative while retaining the daemon's+ hidden session mirror for MCP transport compatibility.++## 2026-07-14: exact embedded-browser binding++- Real Electron 39 returned CDP method `-32601` for+ `Browser.getWindowForTarget`. Rather than guessing, added a bounded+ `embedded_single_page` route.+- The fallback is exact only while the endpoint exposes one page and the+ requested process owns one native window. Both facts are rechecked before+ every mutation. A second page or native window causes a structured refusal.+- Standard Chromium uses the stronger `native_cdp_window` route based on the+ browser window id and native/CDP geometry agreement.++## 2026-07-14: canonical harness coverage++- Added `<platform>-electron-browser-tool-roundtrip` to the established shared+ web behavior matrix instead of creating a separate test framework.+- The row starts a named session, binds the exact native Electron window,+ proves `browser_prepare` recognizes the owned endpoint, asserts the bounded+ `embedded_single_page` route, snapshots the page, performs a trusted ref+ click, verifies the external fixture journal, snapshots again, types through+ the new editable ref, and proves the older ref returns `browser_ref_stale`+ without changing state. It then navigates to `about:blank`, verifies the new+ URL, and proves navigation invalidates the latest page ref.+- The required evidence is fixture state, foreground focus, z-order, no leaked+ input, cursor preservation where observable, and a playable video.+- Fixed the native Sway preflight rather than bypassing it. Manual VM runs now+ export the selected Wayland session, temporarily clear the fullscreen+ sentinel for the deliberate focus-loss canary, prove focus can move, and+ restore the sentinel before product rows execute. Unit coverage distinguishes+ a view's own fullscreen state from Sway's inherited workspace metadata.++## 2026-07-15: independent review hardening++- An independent read-only implementation review found two trust-chain+ blockers: a verified HTTP listener could return a WebSocket URL on another+ loopback port, and two maximized browser windows with identical bounds could+ be title-tie-broken across different CDP window ids.+- Every platform adapter now requires the returned WebSocket URL to use the+ exact operating-system-attested listener port. Regression tests also pin+ loopback-only parsing and token-based browser product classification.+- Bounds tie-breaking is now legal only within one proven CDP window id.+ Distinct same-bounds windows remain ambiguous, and geometry without a CDP+ window id cannot mint an exact binding.+- Transient or malformed CDP window-enumeration responses now fail the whole+ proof instead of shrinking the candidate set into a false unique match.+- `browser_type` now requires a current ref and proves that the focused node is+ editable before dispatch. It refuses instead of reporting success against+ unproven page focus.+- A second, narrow read-only review traced all six remediations through the+ shared engine and all three adapters and found no remaining completion+ blocker. Standalone multi-window Chrome/Edge remains a documented release+ evidence gap rather than an advertised v1 route.++## Validation log++### Shared and macOS unit/protocol validation++- `cargo test -p cua-driver-core -p platform-macos`: 170 core tests, 3 session+ lifecycle tests, and 126 platform-macOS tests passed at the final revision.+- `cargo test -p cua-driver --test protocol_schema_test --test+schema_consistency_test --test protocol_session_test`: 1 schema, 1+ consistency, and 6 session protocol tests passed.+- `cargo build -p cua-driver` and the release build used by the documentation+ generator passed.+- The initial permission-enabled macOS run failed closed because WindowServer+ reported several untitled layer-0 helper surfaces for Electron. Those+ process-owned helpers incorrectly defeated the single-native-browser-window+ proof even though CDP exposed exactly one page.+- Revision `0cf2dd9e1372a3b2c11822975752ddd04fe0b931` narrows the macOS+ fallback cardinality check to titled, non-empty browser surfaces. A second+ titled surface still defeats the proof, and a second CDP page independently+ defeats it in shared core. Both shapes have focused regression tests.+- That exact revision was installed through `install-local.sh` using the stable+ local signing identity. The daemon reported Accessibility, Screen Recording,+ and live capture capability as granted after restart.+- The canonical macOS Electron browser row then passed: 1 delivered, 0+ refused, 0 failed, 0 skipped. It exercised Page/Background/Window/CDP with+ fixture-state, focus, z-order, cursor, and no-leaked-input oracles, plus a+ playable video and trajectory. The generated environment record identifies+ the exact source revision above.++### Windows interactive validation++- Source revision: `a2e792a428308a80bb02a37ed4467ea073a8e8e5`.+- The three focused Windows browser-platform parser, classifier, and endpoint+ attestation tests passed.+- The canonical focused Electron browser row passed: 1 delivered, 0 refused,+ 0 failed, 0 skipped. Fixture state, focus, z-order, cursor, no-leaked-input,+ and playable-video evidence all passed in an interactive user desktop.++### Linux X11 validation++- Final implementation revision: `a2e792a428308a80bb02a37ed4467ea073a8e8e5`.+- The three focused Linux browser-platform parser, classifier, and endpoint+ attestation tests passed. Earlier full validation also passed platform checks+ and all 53 Linux testkit tests.+- The canonical focused Electron row passed under X11/Openbox: 1 delivered, 0+ refused, 0 failed, 0 skipped, with fixture-state, focus, z-order, cursor,+ no-leaked-input, and playable-video evidence.++### Linux native Wayland validation++- Final implementation revision: `a2e792a428308a80bb02a37ed4467ea073a8e8e5`.+- Six focused Sway sentinel regression tests passed.+- The native Sway preflight passed its deliberate focus-loss and fullscreen+ restoration canary.+- The canonical focused Electron row passed under native Ozone Wayland with+ Xwayland disabled: 1 delivered, 0 refused, 0 failed, 0 skipped. Fixture+ state, focus, z-order, no-leaked-input, and playable-video evidence passed;+ global cursor preservation is omitted because standard Wayland cannot read+ the global pointer position.++## 2026-07-14: documentation and agent surface++- Generated MCP reference directly from the compiled Rust tool schemas.+- Added a Diataxis how-to for the session/bind/snapshot/action workflow and a+ separate explanation of exact browser targeting and full-background CDP+ delivery.+- Updated current limits and the bundled `cua-driver` skill. The legacy `page`+ tool remains available and is not presented as the preferred new mutation+ route.++## Initial v1 milestone audit++| Plan phase | Browser-tool v1 result |+| --- | --- |+| Phase 0: binding feasibility | Accepted. Native Chromium uses exact CDP-window geometry; Electron uses the separately bounded single-page/single-native-window proof. Ambiguous targets refuse. |+| Phase 1: shared CDP foundation | Implemented in `cua-driver-core`, with loopback listener ownership and exact WebSocket-port attestation in all three platform adapters. |+| Phase 2: session-owned targets | Implemented. Target, tab, snapshot, and ref capabilities are opaque and session-scoped; session teardown removes the namespace. |+| Phase 3: read-only state | Implemented. Bind and snapshot modes share `get_browser_state`; neither performs setup or mutation. |+| Phase 4: preparation | Intentionally narrow. Existing owned endpoints are recognized; setup, restart, and profile changes remain explicit structured refusals rather than hidden side effects. |+| Phase 5: typed mutations | Implemented for navigation, trusted or explicitly synthetic click, and ref-bound editable typing, with mutation-time revalidation. |+| Phase 6: legacy `page` migration | Deferred. The existing facade remains compatible and separate until adoption evidence supports migration. |+| Phase 7: release evidence and rollout | Partially complete. Canonical Electron evidence, generated reference, public Diataxis docs, and bundled skills are present. Standalone Chrome/Edge adversarial lanes and embedded-webview expansion remain deferred. |++The v1 milestone therefore satisfies the accepted local implementation scope,+including canonical macOS, Windows, X11, and native Wayland evidence. It does+not claim the later `page` migration or the broader real-browser release+matrix.++## Deferred at the v1 milestone++The v2 entries below supersede the completed items in this historical list.++- Legacy `page` facade migration.+- Firefox and Safari mutation through this CDP-first API.+- Cross-origin iframe references and browser tab lifecycle tools.+- Mutation on a compositor that cannot prove the requested native window maps+ to the selected browser window.+- Isolated profile creation and acting `browser_prepare` launch.+- Full Chrome/Edge multi-window adversarial release lanes and Tauri, WebView2,+ WKWebView, and WebKitGTK browser-tool rows. Existing native harness coverage+ for those surfaces remains unchanged.++## 2026-07-15: v2 truthfulness and standalone Chromium coverage++- `26c177d9` made browser-engine classification and route limitations+ consistent across platforms. Unsupported engines remain discoverable but do+ not advertise mutation.+- `0295b881` added repository-owned standalone Chromium harness coverage.+- `3287b44e` added adversarial multi-tab and same-bounds multi-window cases.+ The driver refuses ambiguity instead of selecting the first page or using a+ title tie-break across different CDP window ids.+- The complete macOS standalone suite passed in one uninterrupted run: exact+ roundtrip, isolated preparation, stale refs, composed frames, multi-tab, and+ same-bounds multi-window refusal.++## 2026-07-15: composed documents and event-aware CDP++- `c8fb38ef` added refs through open shadow roots and same-process iframes.+ Out-of-process iframes are attached only when the runtime exposes a proven+ CDP session; event messages are demultiplexed from command responses.+- Snapshot refs retain frame identity. A missing frame route is reported as a+ limitation and never flattened into the main document.+- The standalone composed-document row passed against real Chromium, including+ shadow DOM, same-process iframe, and capability-tested OOPIF behavior.++## 2026-07-15: approved isolated browser preparation++- `ca31f017` removed public consent/restart fields and marked+ `browser_prepare` destructive and non-idempotent.+- MCP calls require a live host-mediated approval marker. Direct CLI/raw calls+ require a five-minute, single-use token minted by the interactive+ `browser-approve` command and bound to pid plus profile request.+- Acting prepare launches a separate Chromium process with a driver-owned+ `isolated_new` or `isolated_named` profile. It never copies, modifies,+ restarts, or terminates the selected user profile.+- The endpoint is proved from the private profile's `DevToolsActivePort` and+ socket ownership. Temporary profiles and their processes are reaped when the+ owning session ends.+- Remote-debugging arguments passed through `launch_app` are rejected on all+ platforms so setup cannot bypass this boundary.++## 2026-07-15: embedded routes and legacy compatibility++- `1c4e3539` separated exact browser-route evidence from the broad shared+ action matrix. Electron proves an exact CDP mutation roundtrip on each+ supported OS. Tauri, WKWebView, WebKitGTK, and the common split-process+ WebView2 shape prove side-effect-free `browser_route_unavailable` refusals+ until their engine/native-host relationship can be bound exactly.+- `5b484098` migrated the legacy `page` CDP path to the shared pooled,+ event-aware transport without changing its first-page/URL-hint semantics,+ output format, timeouts, or AppleScript/UIA/AT-SPI fallbacks.+- A compatibility test injects an unsolicited CDP event before an evaluate+ reply and proves the legacy result still arrives in its historical format.+- The macOS embedded matrix passed against the locally installed source build:+ Electron mutation delivered; Tauri and WKWebView refused with focus, z-order,+ cursor, no-leaked-input, and fixture-state sentinels intact.++## 2026-07-15: harness process isolation++- `a6e4c6b8` places every Unix test-owned browser in its own process group and+ reaps the complete tree after each row. This removed late Chrome children+ that could contaminate the next exact-binding test.+- No product action is retried. A longer readiness budget and a macOS launch+ settle occur only between independently owned harness processes.+- `cua-driver-testkit` passed 41 tests. The full six-row standalone Chromium+ suite then passed in 66 seconds with no lingering harness browser process.++## Current explicit limitations++- Safari/WKWebView/WebKitGTK typed mutation is deferred until an exact WebKit+ engine-to-native-window route exists. Legacy/native reads remain available.+- Firefox is classified but has no WebDriver BiDi engine or typed mutation.+- Generic Wayland without compositor-provided exact pid and geometry cannot+ authorize browser mutation. Validated X11 and Sway configurations may do so;+ this does not imply arbitrary raw background PX delivery.+- Common WebView2 hosts split the native WPF window and Edge renderer across+ processes. The typed route refuses until that correlation can be proved.+- `browser_prepare` deliberately does not attach DevTools to, copy, or restart+ a person's existing profile. Authenticated-profile automation remains a+ product/security decision rather than an implicit setup shortcut.+- MCP approval proves that the request traversed the host approval path; it is+ not a same-user operating-system security boundary against another local+ process. Direct approval tokens remain terminal-only, short-lived,+ single-use, and request-bound.++## 2026-07-15: final v2 hardening and exact-head release evidence++- `ee8b75f3` split the standalone browser matrix into independent scenario+ processes. A failed launch or contaminated desktop can no longer prevent the+ remaining declared rows from producing evidence.+- `083859f3`, `5f3fca7a`, and `3336b343` made temporary Chromium startup and+ teardown deterministic. Every harness browser receives a clean profile and,+ on Unix, an owned process group whose descendants are reaped when the row+ ends.+- `33c8d533` made the harness route explicit in every result instead of+ inferring it from the expected outcome.+- `c70f5986` creates additional tabs and same-bounds windows through the+ harness-only CDP connection. This removes command-line handoff ambiguity+ while leaving the public driver path unchanged. It also lets macOS E2E use a+ dedicated daemon socket so another driver client cannot end the test+ session.+- `edc26080` made the loopback fixture server concurrent. Chromium idle+ preconnections can no longer hold the only server worker and starve the real+ page or journal request. A regression test opens an idle connection while a+ second client completes a fixture request.+- `418fb972` made the reporter deduplicate identical environment records from+ independently executed rows while continuing to reject conflicting records.+- `4fc4e00b` fixed a critical Unix harness teardown bug. Passing `-1` to the+ external `kill` utility had been parsed as the broad `kill(-1, SIGKILL)`+ syscall, which could terminate every process signalable by the test user.+ Teardown now calls guarded `libc::kill(-pgid, SIGKILL)` directly and refuses+ process ids 0, 1, or values outside the platform range.++### Exact standalone Chromium evidence++- Windows interactive evidence at `edc2608061360dadc258724045438922487753e2`:+ 16 declared Chrome and Edge rows, 14 delivered, 2 exact+ `browser_binding_ambiguous` refusals, 0 failed, and 0 skipped. The matrix+ covers background typing, composed frames and capability-tested OOPIFs,+ multi-tab exact binding, isolated preparation, stale refs, full roundtrip,+ trusted background click, and same-bounds ambiguity. Every row includes a+ fixture-state oracle, focus and z-order guards, no-leaked-input and cursor+ checks, and a playable video.+- Linux X11 evidence at `4fc4e00b0630f5889e17e91ebe31b3508dc3818f`:+ 8 declared Chrome rows, 6 delivered, 2 refused, 0 failed, and 0 skipped.+ Trusted pointer input refused with+ `browser_input_trust_unavailable` before dispatch because standalone+ Chromium activates its native window on that route. Same-bounds ambiguity+ refused with `browser_binding_ambiguous`. Explicit DOM click, ref-bound+ typing, navigation, composed frames, multi-tab binding, stale refs, and+ isolated preparation passed with the complete background oracle set and+ videos.+- macOS standalone rows passed through a dedicated source-installed daemon+ before final documentation. A later replacement of the local app invalidated+ its TCC grants; runs after that point are environment-inconclusive because+ WindowServer redacts browser titles without Screen Recording permission.+ Final exact-head macOS release evidence must therefore be regenerated after+ the installed app again reports Accessibility, Screen Recording, and live+ capture as granted. Shared-host focus changes are not attributed to browser+ mutation unless they reproduce in that permission-complete, uncontended+ setup.++### Embedded route evidence retained++- macOS: Electron delivered; Tauri and WKWebView returned the expected+ side-effect-free route refusal.+- Windows: Electron delivered; Tauri and the split-process WebView2 host+ returned the expected route refusal.+- Linux X11: Electron delivered; Tauri returned the expected route refusal.+- Native Sway: Electron delivered and Tauri refused. Global cursor preservation+ remains omitted because standard Wayland cannot read the global pointer+ position.++### Final trust model++- Standalone Chrome and Edge on Windows have passing trusted background pointer+ evidence.+- Standalone Chromium on macOS and Linux refuses trusted CDP pointer input+ before dispatch because that route activates the native browser window.+- `input_route: "dom_event"` is the explicit synthetic full-background click+ route. The driver never changes from trusted input to a DOM event silently.+- Electron's trusted route is a separately bounded proof and does not authorize+ a generic embedded-webview fallback.++## 2026-07-15: exact Windows and Linux browser release checkpoint++Revision `32c77f775bd16d50507fbedb54a9682b9ab5599d` passed the complete+browser-specific release matrix on the three available interactive cloud+desktops. Every declared result includes fixture-state and desktop-side-effect+oracles plus a playable video.++- Windows Win32, in a real RDP user session: 19 declared rows, 15 delivered,+ 4 exact refusals, 0 failed, and 0 skipped. Chrome and Edge each passed all+ eight standalone scenarios. Electron delivered through its bounded CDP+ route; Tauri and split-process WebView2 refused with+ `browser_route_unavailable`.+- Linux X11/Openbox: 10 declared rows, 7 delivered, 3 exact refusals, 0+ failed, and 0 skipped. Standalone trusted pointer input refused before+ dispatch with `browser_input_trust_unavailable`; the explicit DOM event+ route remained available for synthetic full-background clicks. Electron+ delivered and Tauri refused exactly.+- Linux native Wayland/Sway with Xwayland disabled: 8 standalone rows, 6+ delivered, 2 exact refusals, 0 failed, and 0 skipped. The matrix proved+ isolated preparation, composed frames, exact multi-tab binding, stale refs,+ background typing, roundtrip mutation, trusted-input refusal, and+ same-bounds ambiguity refusal. A separate embedded run proved Electron+ delivery and Tauri's exact refusal. Global cursor preservation remains+ omitted because standard Wayland cannot read the global pointer position.++The broader native-Wayland shared-action diagnostic also found existing Tauri+WebKitGTK pointer and scroll failures. Those rows do not use the browser CDP+transport, and this branch does not change their injection paths. They remain+separate platform-action gaps and are not counted as browser-tool acceptance.++The reusable macOS VM work was merged before the final replay. The retained+Lume evidence below therefore validates the installed source in a disposable,+permission-complete guest rather than relying on host TCC state.++## 2026-07-16: final runner convergence++- Merged the reusable macOS Lume gate from main after preserving the browser+ branch with a backup ref. The browser branch remains the only source of+ commits; Windows, Linux, and macOS guests receive clean source snapshots with+ an exact SHA marker.+- The shared standalone runner now stages its own Electron focus sentinel,+ opts into native Wayland when the session requires it, discovers macOS+ browsers in both system and user Applications folders, and deduplicates+ executable aliases before declaring rows. Linux keeps a launcher path for+ execution while comparing its canonical target for deduplication, which is+ required for Snap-style browser launchers.+- Windows runs every standalone scenario in an independent process from the+ canonical PowerShell entry point. One failed row therefore cannot hide later+ Chrome or Edge evidence.+- The macOS Lume wrapper preserves previous standalone evidence before a repeat+ run. The Nix Wayland shell now supplies the Chromium binary used by the+ native Ozone lane.+- Sentinel setup waits for its final desktop geometry before recording the+ baseline. Dispatch-time focus, z-order, cursor, and leaked-input checks remain+ strict and are not retried.+- Standalone browser setup now relists windows until the public browser API can+ prove an exact binding. This handles a cold Sway toplevel that briefly has a+ protocol-local id before compositor pid/geometry metadata arrives. The driver+ continues to refuse the transient unprovable id; no mutation or behavior+ assertion is retried.++The cold native-Sway replay after that setup correction passed all 8 standalone+Chromium rows: 6 delivered, 2 expected refusals, 0 failed, and 0 skipped. Each+retained `environment.jsonl` is the authoritative source identity ledger; the+documentation-only completion commit is replayed separately so the final+branch identity is not inferred from predecessor evidence.++### Final browser acceptance matrix++| Environment | Standalone rows | Embedded rows | Accepted outcome |+| --- | ---: | ---: | --- |+| Windows interactive RDP | 16 | 3 | 19 passed: 15 delivered and 4 expected refusals; 19 playable videos |+| Linux X11 | 16 | 2 | 18 passed across Chrome, Snap Chromium, Electron, and Tauri; 18 playable videos |+| Linux native Wayland/Sway | 8 | 2 | 10 passed: 7 delivered and 3 expected refusals; 10 playable videos |+| macOS Lume | 8 | 3 | 11 browser rows passed; the complete canonical matrix also passed 148/148 with 149 playable videos including preflight |++The implementation candidate `19f1e09d55e2a595ccb17f1fcc48d65ceb5d181f`+produced those accepted counts with zero skipped rows. One earlier macOS+canonical attempt missed the Electron foreground drag while the fixture stayed+idle; a fresh, uninterrupted worker replay passed that row and all 147 others+without retrying any action inside a result cell. The final documentation-only+branch head is validated again after this record is committed.++Safari/WKWebView/WebKitGTK mutation, Firefox BiDi mutation, split-process+WebView2 mutation, and mutation on Wayland compositors without exact pid and+geometry remain deliberate structured limitations. Existing user profiles are+never copied, restarted, or attached implicitly by `browser_prepare`.++## 2026-07-16: macOS AX deadline correction++A fresh exact-head Lume replay invalidated the earlier macOS completion claim.+Electron completed all 40 canonical rows, but Tauri snapshots later exceeded+the testkit's 25-second public call deadline. A second clean replay reached the+same failure class at a different Tauri row, proving that this was not a single+action assertion or fixture expectation.++The driver had wrapped the native AX walk in a 30-second Tokio timeout. The+public client therefore timed out first, and dropping the `spawn_blocking`+future could not cancel an `AXUIElementCopyAttributeValue` call already blocked+in ApplicationServices. The AX walker now applies Apple's finite native+messaging timeout to the application and every descendant AX object. The+driver-level walk deadline is also 20 seconds, below the public client limit,+so an unresponsive application returns a structured driver error instead of a+generic client timeout and cannot retain a worker indefinitely.++All prior Windows, Linux, and macOS artifacts remain diagnostic only until this+correction is committed and every acceptance environment is replayed from that+exact source revision. No test oracle, expected outcome, or declared row was+weakened to accommodate the failure.++## 2026-07-16: macOS Tauri fixture navigation correction++The finite AX deadline exposed separate fixture defects instead of masking+them. The canonical build scripts compiled a release Tauri executable without+the production `custom-protocol` feature, so the native window opened but its+embedded frontend was not served. The shared Tauri feature now maps to+`tauri/custom-protocol`, and both Unix and Windows fixture builders enable it.++The Tauri package also did not declare its copied `../web` frontend directory+as a Cargo build input. A cached target could therefore retain an older page+after the shared fixture changed or a clean source snapshot was synced with+preserved mtimes. Its build script now emits `rerun-if-changed` for that+directory, making frontend embedding deterministic without deleting build+caches.++An official custom-protocol bundle exposed the second issue: starting the+first loopback fixture-state request before custom-scheme navigation finished+could keep the WKWebView load open. The shared web fixture now starts journal+publication from the window `load` event. It still publishes immediately after+that event and every 250 milliseconds thereafter, so the independent external+oracle is unchanged for actions. Electron, Tauri, WebView2, and WKWebView+continue to consume the same page; there is no macOS-only fixture or relaxed+readiness assertion. Exact-head cross-platform replay remains required before+release acceptance.++## 2026-07-16: Tauri loopback fixture and macOS VM diagnosis++Further replay showed that the production custom scheme was not a reliable+fixture transport on the current macOS WebKit runtime. Tauri completed the+custom-scheme and data-URL navigation callbacks, but the page remained empty.+The fixture now starts a server on an ephemeral loopback port, serves the same+checked-in `shared/web/index.html`, and creates its only webview against that+exact URL. It does not contact an external service or duplicate the shared+page. Cargo also watches `tauri.conf.json`, so a cached build cannot retain an+older window declaration.++The final fixture passed all 40 Tauri action cells on a physical macOS host,+covering foreground and background delivery across AX and PX addressing. Its+embedded browser row also returned the expected side-effect-free route+refusal. The independent fixture journal remained the action oracle.++The disposable macOS VM still renders both Tauri and the native WKWebView+fixture as an empty surface. System logs show WebKit finishing the page load+and then terminating an unresponsive GPU process. The same Tauri binary and+page pass on the physical host, so this result is an environment limitation in+that VM image rather than a browser-tool or fixture regression. The matrix+keeps its readiness assertion; it does not convert the blank surface into a+pass or an expected product refusal.diff --git a/libs/cua-driver/docs/browser-tool-implementation-plan.md b/libs/cua-driver/docs/browser-tool-implementation-plan.mdnew file mode 100644index 0000000000..be97082f48--- /dev/null+++ b/libs/cua-driver/docs/browser-tool-implementation-plan.md@@ -0,0 +1,1082 @@+# Cua Driver Browser Tool Implementation Plan++## Status++- **State:** Browser-tool v2 roadmap implemented locally; acceptance evidence recorded in the implementation journal+- **Plan date:** 2026-07-14+- **Implementation branch:** `codex/browser-tool-v1` (local only)+- **Companion audit:** [Agentic Web Browsing with Cua Driver](agentic-web-browsing-audit.md)+- **Architecture verdict:** Accept with major changes++The accepted roadmap now covers the five typed tools, strict endpoint ownership,+session capabilities, exact-or-refused Chromium mutation, standalone Chromium+adversarial coverage, isolated `browser_prepare`, composed-frame refs,+event-capable CDP transport, embedded-webview positive/refusal rows, and the+legacy `page` transport migration. The body below preserves the reviewed design+and phase gates; [the implementation journal](browser-tool-implementation-journal.md)+records what actually shipped and the retained evidence. Safari/WebKit mutation,+Firefox BiDi, split-process WebView2 binding, and mutation on generic Wayland+without exact compositor geometry remain explicit limitations.++## Objective++Add a first-class browser control surface to Cua Driver that lets an agent start from the existing native discovery flow, bind an exact browser page when the platform can prove that relationship, inspect compact browser state, and perform typed browser actions without losing Cua Driver's native desktop, background-delivery, focus-preservation, and truthful-refusal guarantees.++The intended agent flow is:++```text+start_session+list_apps+list_windows+get_browser_state+browser_prepare # only when get_browser_state reports requires_setup+get_browser_state+browser_navigate / browser_click / browser_type+get_browser_state # verify+get_window_state # browser chrome, prompts, downloads, pickers, native fallback+```++The implementation must improve exact targeting and agent ergonomics. It must not hide browser setup inside a getter, silently guess a tab, or create a second copy of native window state.++## Rationale++This proposal comes from recent cross-platform validation of browser automation on macOS, Windows, Linux X11, and Linux Wayland.++Cua Driver currently separates several [capture and delivery modalities](https://cua.ai/docs/concepts/capture-and-delivery-modalities): AX and PX targeting, background and foreground delivery, and window and desktop scope. The [agent action ladder](https://cua.ai/docs/reference/cua-driver/action-selection-policy) starts with background AX, then tries background PX, the `page` tool, and finally foreground delivery. This ordering remains the right safety model because the agent begins with the most semantic and least disruptive route, then escalates only when the previous route is unavailable or cannot be verified. The current OS-specific boundaries are listed in [platform support](https://cua.ai/docs/reference/cua-driver/platform-support).++Web content does not always fit this ladder cleanly. Some Chromium actions cannot be delivered reliably to an occluded or unfocused page through native synthetic pointer or keyboard routes. The same operations can often run in the background through the Chrome DevTools Protocol (CDP) or, on macOS, Apple Events. The current [`page` workflow](https://cua.ai/docs/how-to-guides/driver/drive-a-web-page) exposes some of these routes, but its capabilities vary by operating system, it does not reliably bind the native `pid` and `window_id` to one exact browser tab, and its setup requirements are difficult for an agent to discover before an action fails.++This leaves some browser actions with best-effort background behavior even when a browser-native route could provide full-background execution. Shared-workspace agents need the stronger contract: supported page actions must avoid raising the browser, moving the cursor, stealing focus, or leaking input into the user's active application.++The proposal keeps the existing action ladder and makes its browser rung first-class and capability-aware. `get_browser_state(pid, window_id)` identifies the exact tab when the relationship can be proven and reports the available routes. Supported page actions can then use CDP or Apple Events before falling back to native PX or foreground delivery. `get_window_state` remains the source of truth for browser chrome, permission prompts, downloads, file pickers, and native fallback.++The first implementation step is a binding feasibility spike. If Cua Driver cannot reliably bind, revalidate, or safely refuse multi-window Chromium targets across supported operating systems, the design will change before the public API is committed.++## Success Criteria++The browser tool is ready for a supported route when all of the following are true:++1. An agent begins with the normal `pid` and `window_id` discovered through Cua Driver.+2. `get_browser_state` reports browser identity, available routes, setup requirements, tabs, and compact page references without causing visible or persistent side effects.+3. A page action names a session-scoped `browser_target_id`, exact `tab_id`, and snapshot-scoped page reference where applicable.+4. The driver proves that a debugging endpoint belongs to the expected browser process before connecting.+5. The driver either revalidates the page/window relationship before mutation or refuses the action.+6. Every action reports the actual route, input trust class, and verification result.+7. Ambiguous, stale, unsupported, or consent-gated targets produce structured refusals.+8. Browser page state does not duplicate the native accessibility tree or screenshot by default.+9. Existing `page` clients continue working during migration.+10. Exact-SHA real-browser evidence exists for every advertised platform/browser route.++## Non-Goals++This project will not:++- replace `get_window_state` or the native AX/PX action surface;+- turn Cua Driver into a Playwright-compatible browser server;+- require an owned Chrome for Testing installation for the default workflow;+- assume that Cua Driver owns the user's browser profile or network stack;+- provide ambient "current browser" or "current tab" global state;+- silently retry, self-heal, or switch routes after an exact-target check fails;+- promise a stable tab model for browsers or embedded webviews that do not expose one;+- copy an agent-browser-style daemon or make a browser instance equivalent to a Cua session;+- add universal `browser_wait`, `browser_close`, or tab lifecycle operations in v1;+- deprecate `page` before the new browser surface has accepted cross-platform evidence.++## Locked Design Decisions++### 1. Native discovery remains the entry point++The browser API begins with the exact native target already used by Cua Driver:++```json+{+ "session": "research-1",+ "pid": 1234,+ "window_id": 5678+}+```++`pid` plus `window_id` is the connection anchor, not a guarantee that a browser tab can be derived. The browser binding response must state whether the relationship is exact, heuristic, or unavailable.++### 2. `get_browser_state` is strictly read-only++`get_browser_state` may:++- classify the process and browser engine;+- inspect already-known or prompt-free local endpoints;+- read `/json`-style target metadata;+- verify local TCP endpoint ownership;+- reuse an already-approved cached browser socket;+- return structured setup requirements.++It may not:++- signal a process;+- restart a browser;+- patch browser preferences;+- enable Apple Events JavaScript;+- manipulate favorites or browser UI;+- create or copy a profile;+- make a connection known to trigger a consent prompt;+- navigate or mutate page content.++This is required for truthful MCP `readOnlyHint`, host approval behavior, and trajectory recording.++### 3. Setup and consent are explicit++`browser_prepare` owns all setup that can mutate state or require user consent.+It is statically marked mutating, destructive, and non-idempotent. Acting setup+requires either MCP-host approval or a short-lived single-use token minted by+the interactive `browser-approve` command. It launches a separate browser with+a driver-owned isolated profile and never copies, modifies, restarts, or+terminates the selected user profile.++### 4. Native and browser state remain separate++`get_window_state` remains the source of truth for:++- native screenshot and capture metadata;+- AX/UIA/AT-SPI elements and native element tokens;+- browser chrome, tab strip, omnibox, menus, permission prompts, downloads, and file pickers;+- window focus, foreground state, geometry, visibility, and native delivery evidence;+- every non-browser application.++`get_browser_state` owns only what the native state cannot express reliably:++- browser and engine identity;+- page/tab identity;+- URL, title, and route-specific load state;+- DOM-derived compact page references;+- browser capabilities and setup requirements;+- binding method and confidence;+- DOM focus, where available.++Screenshot is opt-in and must use the same capture provenance as `get_window_state`. AX-only surfaces do not get a duplicate browser ref namespace; they direct the caller back to `get_window_state`.++### 5. Bindings are session-scoped capabilities++A `browser_target_id` is not a portable identifier. It is a capability owned by one Cua Driver session and one live driver instance. It must not be serialized into trajectories, replayed, or accepted after session cleanup.++Every stateful browser tool requires an explicit public `session`. Internal connection identity may support transport bookkeeping but must not replace the caller-visible session contract.++### 6. Exact mutation or refusal++Read-only state may report `binding.confidence` as:++- `exact`: the driver can prove the native target, browser endpoint, browser window, and page relationship needed for the requested operation;+- `heuristic`: useful metadata exists, but exact mutation is unsafe;+- `none`: the relationship cannot be established.++V1 browser mutation requires `exact`. It must never automatically promote a heuristic binding. A future explicit product policy may permit narrowly defined heuristic reads, but not writes.++### 7. Browser actions are typed tools++Do not add generic `browser_act` or `browser_get` tools. They would reproduce the current `page` problem: unrelated read and mutation semantics forced into one schema and one set of MCP annotations.++V1 uses a small set of typed tools:++```text+get_browser_state+browser_prepare+browser_navigate+browser_click+browser_type+```++### 8. Input trust is explicit++Every browser input result identifies one of:++- `trusted_input`: a trusted browser input route such as CDP Input domain dispatch;+- `dom_event`: an in-page JavaScript operation such as `element.click()`;+- `native_ax`: a native accessibility action delegated to Cua Driver;+- `native_px`: a native pixel action delegated to Cua Driver;+- `unavailable`.++The driver must not represent a DOM event as a trusted pointer or keyboard event.++## Proposed Public Contract++### `get_browser_state`++Purpose: discover a browser route, bind an exact page when possible, return compact page state, and refresh existing bindings without side effects.++Implemented request:++```json+{+ "session": "research-1",+ "pid": 1234,+ "window_id": 5678,+ "tab_id": "t-a1",+ "include_refs": true,+ "refs": "interactive",+ "max_refs": 200,+ "include_screenshot": false+}+```++Rules:++- `session`, `pid`, and `window_id` are required for initial discovery.+- Existing callers may pass `browser_target_id` plus `tab_id` for refresh.+- Omitting `tab_id` is allowed for state discovery and tab listing.+- Mutation tools must reject multiple viable tabs when no `tab_id` is supplied.+- `refs` accepts `interactive`, `all`, or `none`; default is `interactive`.+- Output is bounded by `max_refs` and a tool-level text budget.+- `include_screenshot` defaults to false.+- Read-only discovery never runs `browser_prepare` implicitly.++Proposed response:++```json+{+ "browser_target_id": "bt-3f",+ "native_target": {+ "pid": 1234,+ "window_id": 5678+ },+ "binding": {+ "method": "cdp_window_bounds",+ "confidence": "exact",+ "port_owner_verified": true,+ "revalidated": true+ },+ "browser": {+ "kind": "chrome",+ "engine": "chromium",+ "profile_kind": "default"+ },+ "tabs": [+ {+ "tab_id": "t-a1",+ "url": "https://example.com",+ "title": "Example",+ "active": true,+ "load_state": "complete"+ }+ ],+ "page": {+ "tab_id": "t-a1",+ "refs_snapshot": "p1b3",+ "ref_source": "dom",+ "refs": [+ {+ "ref": "p1b3:4",+ "role": "button",+ "name": "Submit",+ "frame": [112, 340, 88, 32]+ }+ ]+ },+ "routes": {+ "read": "cdp",+ "navigate": "cdp",+ "input_trusted": "cdp",+ "input_dom": "cdp"+ },+ "requires_setup": [],+ "limitations": []+}+```++No universal `state_revision` is included in v1. Snapshot staleness is represented by `refs_snapshot`; tab and binding validity are checked directly.++### `browser_prepare`++Purpose: perform explicit consent-bearing or mutating setup needed to expose a safe browser route.++Proposed request:++```json+{+ "session": "research-1",+ "pid": 1234,+ "allow_launch": true,+ "profile": {+ "mode": "isolated_new"+ }+}+```++Supported setup operations are deliberately narrow:++- recognize an existing endpoint after proving listener ownership;+- create a temporary `isolated_new` or persistent driver-owned+ `isolated_named` profile;+- launch a separate Chromium process with a private DevTools endpoint;+- prove the endpoint through the private profile's `DevToolsActivePort` and+ operating-system socket ownership;+- report a structured refusal when approval, an isolated profile, an exact+ browser executable, or endpoint proof is unavailable.++The result returns `prepared_pid`, endpoint-ownership metadata, and explicit+side effects, or a structured refusal. The caller discovers that new process's+window and binds it normally. Ending the owning session terminates the managed+process and removes an `isolated_new` profile.++Public Boolean consent fields are intentionally absent because a model can+forge them. MCP approval is transported through a private host-to-driver marker;+direct and raw callers must present a five-minute, pid/profile-bound, single-use+approval token minted in an interactive terminal.++### `browser_navigate`++Purpose: navigate an exact tab.++Proposed request:++```json+{+ "session": "research-1",+ "browser_target_id": "bt-3f",+ "tab_id": "t-a1",+ "operation": "goto",+ "url": "https://example.com/dashboard",+ "wait_until": "domcontentloaded",+ "timeout_ms": 25000+}+```++Operations:++- `goto`+- `back`+- `forward`+- `reload`++`wait_until` is supported only on routes with reliable navigation events. Other routes return a structured route refusal rather than imitating a load event with an undocumented poll.++### `browser_click`++Purpose: click a snapshot-scoped page reference using an explicitly requested trust class.++Proposed request:++```json+{+ "session": "research-1",+ "browser_target_id": "bt-3f",+ "tab_id": "t-a1",+ "ref": "p1b3:4",+ "input": "trusted"+}+```++Rules:++- `input` defaults to `trusted`.+- If trusted input is unavailable, the driver refuses rather than silently using `element.click()`.+- The caller may explicitly request `dom_event` for applications where that semantic is acceptable.+- The result reports coordinates, route, trust class, and verification state.+- Stale references require a fresh `get_browser_state` call.+- Before trusted pointer dispatch, the driver refreshes the element box and performs a hit test. If an overlay, modal, or another element covers the target point, the action refuses and identifies the covering node when safely available.++### `browser_type`++Purpose: insert text or dispatch browser keystrokes to an exact page target.++Proposed request:++```json+{+ "session": "research-1",+ "browser_target_id": "bt-3f",+ "tab_id": "t-a1",+ "ref": "p1b3:8",+ "text": "[email protected]",+ "mode": "insert"+}+```++Modes:++- `insert`: direct text insertion without individual key events;+- `keystrokes`: trusted key event dispatch;+- `dom_value`: explicit DOM value mutation, if added after v1 validation.++The result reports the actual mode and trust class. Browser-tool v1 requires a+fresh `ref` and proves that it resolves to the focused editable element before+typing; it refuses rather than reporting success against an unproven focus.++## Structured Refusals++Add browser-specific refusal codes to the shared structured result vocabulary:++```text+browser_route_unavailable+browser_requires_setup+browser_binding_ambiguous+browser_binding_stale+browser_wrong_target_refused+browser_tab_required+browser_tab_not_found+browser_ref_stale+browser_input_trust_unavailable+browser_endpoint_owner_mismatch+browser_consent_required+```++Every refusal includes:++- requested operation;+- native target and browser target when available;+- requested route or trust class;+- actual capabilities;+- whether setup can resolve the refusal;+- a structured `requires_setup` entry when applicable;+- no claim that input or navigation occurred.++## Internal Architecture++### Shared `BrowserEngine`++Create a shared browser subsystem in `cua-driver-core` rather than extending the current platform-specific `PageBackend` divergence.++Proposed responsibilities:++```text+cua-driver-core/src/browser/+ mod.rs public internal API and engine composition+ types.rs targets, tabs, routes, setup, results, refusals+ discovery.rs endpoint and browser target discovery interfaces+ binding.rs native-window-to-browser-window/page correlation+ cdp.rs shared CDP transport and protocol operations+ pool.rs browser socket and flat-session lifecycle+ refs.rs DOM snapshot refs and stale-ref validation+ session_store.rs session-scoped browser targets and cleanup+```++Final paths may follow existing crate conventions, but ownership boundaries must remain:++- core owns browser target semantics, CDP target selection, session lifecycle, route reporting, and page refs;+- platform crates own process identity, endpoint ownership proof, browser classification, native window metadata, and platform-specific setup;+- native action implementations remain in the platform crates;+- `page` becomes a compatibility adapter over the shared engine.++### Platform adapter contract++Each platform supplies:++```text+classify_browser(pid)+validate_window_owner(pid, window_id)+discover_pid_owned_endpoints(pid)+correlate_browser_window(pid, window_id, browser_window_metadata)+prepare_browser_route(request)+capture_provenance(pid, window_id)+```++Windows' existing HWND-to-PID validation becomes the behavioral baseline. Equivalent fail-closed validation is required on macOS and Linux wherever platform APIs expose ownership.++### Browser target store++Each target record contains:++```text+session+browser_target_id (opaque and unguessable)+pid+window_id+browser kind and engine+endpoint identity and owner proof+browser WebSocket UUID where applicable+binding method and confidence+binding fingerprint+tab mappings+created_at and last_used_at+```++Lifecycle rules:++- target records are scoped to one explicit Cua session;+- `end_session`, connection teardown, and idle TTL remove records and page refs;+- process exit or endpoint identity change invalidates the record;+- actions never silently create a replacement target;+- browser targets cannot be replayed from trajectory artifacts;+- log output excludes cookies, auth headers, storage, page secrets, and endpoint credentials.++### CDP connection and concurrency model++Replace the current mixture of one-shot core calls and macOS-only cached mutable targeting with one shared model:++1. One ref-counted browser WebSocket per approved, PID-owned endpoint.+2. CDP flat mode enabled.+3. One CDP session ID per Cua session and tab.+4. Every command routed with the exact CDP session ID.+5. Per-target mutation serialization.+6. Independent read requests may run concurrently when response correlation is safe.+7. Session cleanup detaches its CDP sessions without closing a socket still used by another Cua session.+8. Reusing an approved socket must not retrigger a browser consent prompt.++This removes the cross-session risk of a process-global socket with mutable "current target" state.++### Reference model++Reuse the existing snapshot-token concepts but keep browser refs in a distinct namespace:++```text+native ref: s<snapshot>:<index>+browser ref: p<snapshot>:<index>+```++Rules:++- browser tools reject native refs;+- native tools reject browser refs;+- navigation invalidates page refs;+- meaningful DOM replacement invalidates affected refs where detectable;+- a stale ref never falls back to selector text or screen coordinates;+- refs are session- and tab-scoped;+- ref snapshots are bounded by count, memory, and TTL.++For Chromium, generate refs from the browser accessibility tree and DOM identity rather than inventing selectors:++1. Read the page accessibility tree through CDP.+2. Retain the corresponding backend DOM node identity when available.+3. Store tab, document, frame, backend node, role, accessible name, state, and bounds in the ref snapshot.+4. Before action, resolve the backend node again and verify that it still belongs to the same tab, document, and frame.+5. Refresh the box model and perform an element-at-point coverage check before trusted pointer input.+6. Refuse when the node is detached, covered, outside the viewport without a supported scroll route, or moved into an unsupported frame context.++Page refs must carry `frame_id`. Main-frame support is required. Open shadow+roots and same-process iframes are implemented; out-of-process iframes are+included only after a capability-tested flattened CDP attachment. Unsupported+frame routes are omitted with a limitation rather than flattened into an+incorrect main-frame target.++## Endpoint Ownership and Security++Before any CDP or inspector connection, the driver must prove that the local listening endpoint belongs to the expected browser process or an allowed browser process in its verified parent/child process tree.++Platform work:++| Platform | Ownership strategy |+| -------- | ---------------------------------------------------------------------------------------- |+| macOS | Existing PID-to-port discovery via `lsof`, tightened to verify endpoint and process tree |+| Windows | `GetExtendedTcpTable` plus process-tree validation |+| Linux | `/proc/net/tcp*` socket inode mapping plus `/proc/<pid>/fd` and process-tree validation |++Security requirements:++- loopback endpoints only unless a separately reviewed remote-browser provider is introduced;+- reject caller-supplied ports whose owner cannot be proven;+- pin and revalidate the browser WebSocket identity;+- never probe a fixed default port and trust whichever process answers;+- never record authenticated endpoint URLs or profile secrets;+- require explicit confirmation for authenticated default-profile debugging;+- expose browser output as untrusted content with bounded size and source metadata;+- do not implement network allowlists or interception in the driver unless a separate policy design establishes ownership and enforcement semantics.++## Binding and Revalidation++### Chromium++The preferred binding algorithm is:++1. Validate the native `pid` and `window_id` relationship.+2. Discover only debugging endpoints owned by that browser process tree.+3. Enumerate page targets and browser window IDs through CDP.+4. Fetch browser window bounds.+5. Correlate browser window bounds and title metadata with native window metadata.+6. Record the binding method, confidence, and fingerprint.+7. Before every mutation, confirm the target still exists and re-check its browser-window relationship.++Tab drag is a required invalidation scenario: a CDP target may survive while moving to another browser window. The next action must re-correlate or refuse.++### Non-Chromium routes++- Safari Apple Events may expose active-window or mutable tab-index semantics; v1 must not mint a durable exact tab ID from a heuristic ordinal.+- Firefox has no current page engine; return structured unavailable capabilities while evaluating WebDriver BiDi separately.+- WKWebView and WebKitGTK may have one page per native host and no tab model; report that explicitly.+- Wayland bindings with missing PID or geometry return `heuristic` or `none` and do not permit browser mutation.++## Cross-Platform Delivery Scope++| Surface | Implemented state | Mutation | Setup / limitation | Confidence |+| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------- | ---------------------------------------------------- | ------------------------------- |+| Chrome/Edge/Brave macOS | CDP metadata and refs where approved | Navigate, ref typing, explicit DOM click; trusted pointer refuses | Existing owned endpoint or approved isolated profile | Exact or refuse |+| Electron macOS | CDP metadata and refs | Navigate and input | Inspector exposure through prepare when needed | Exact for single-window fixture |+| Safari macOS | Classified; native/legacy read routes remain | Typed mutation deferred | No exact WebKit route | None for typed mutation |+| Chrome/Edge Windows | CDP metadata and refs | Navigate, ref typing, trusted and explicit DOM click | Existing owned endpoint or approved isolated profile | Exact or refuse |+| WebView2 Windows | Native host and renderer split are detected | Structured refusal | Exact cross-process correlation deferred | None for typed mutation |+| Firefox Windows | Identity and unavailable routes | Native `get_window_state` only | None in v1 | None |+| Chromium Linux X11 | CDP metadata and refs | Navigate, ref typing, explicit DOM click; trusted pointer refuses | Existing owned endpoint or approved isolated profile | Exact or refuse |+| Chromium Linux Wayland | CDP metadata; native correlation when available | Only exact binding | Add launch CDP support and compositor metadata | Exact or refuse |+| Electron/Tauri Linux | Electron exact where bounded; Tauri classified | Electron typed mutation; Tauri structured refusal | Tauri/WebKit inspector correlation deferred | Exact or refuse |+| Firefox Linux | Identity and unavailable routes | Native `get_window_state` only | None in v1 | None |++Support documentation must distinguish browser identity, page read, DOM refs, navigation, trusted input, DOM input, native background input, and native foreground input. A single "browser supported" label is insufficient.++## Implementation Phases++### Phase 0: Binding feasibility spike++Purpose: prove or disprove the window-anchored design before exposing a public API.++Work:++- add an internal Chromium binding probe behind test-only code or an ignored diagnostic test;+- add PID-owned endpoint discovery prototypes on macOS, Windows, and Linux;+- query browser targets, browser window IDs, and bounds;+- correlate against Cua native windows;+- exercise real Chrome with multiple windows and tabs;+- record exact, heuristic, and ambiguous outcomes without mutating pages.++Required scenarios:++1. One window, one tab.+2. One window, multiple tabs.+3. Two windows, two tabs each.+4. URL-substring-colliding tabs.+5. Two same-sized and same-position windows.+6. Tab dragged between windows after binding.+7. Closed tab and closed window.+8. Browser process restart and PID reuse protection.+9. Fake `/json` endpoint on a common debugging port.+10. Native Wayland window with missing geometry.++Exit gate:++- deterministic binding or exact refusal on real Chromium across macOS, Windows, and Linux;+- endpoint-owner mismatch always refused;+- no consent prompt or browser mutation from the read-only probe.++Kill criterion:++If multi-window Chromium cannot be deterministically bound or honestly refused on all three OS families, stop the window-bound API implementation. Pivot to tab-first targeting, with native-window correlation exposed only as advisory metadata.++### Phase 1: Shared CDP foundation and safe preparation++Work:++- create shared browser/CDP types and error vocabulary;+- unify core and macOS CDP implementations behind one transport;+- implement PID-owned endpoint discovery for each OS;+- enforce loopback and owner verification;+- implement flat-mode session routing and response correlation;+- reject remote-debugging flags through `launch_app` on every platform;+- put driver-owned isolated launch behind approved `browser_prepare`;+- add unit tests for endpoint discovery, ownership, target selection, and connection pooling.++Exit gate:++- existing `page` tests still pass unchanged;+- no browser endpoint can be used without owner proof;+- two Cua sessions can use different tabs on one browser endpoint without cross-delivery;+- launch schema behavior is truthful and documented on all OSes.++### Phase 2: Session-owned browser target model++Work:++- add browser target store keyed by explicit Cua session;+- add target IDs, tab IDs, binding fingerprints, confidence, and TTL;+- extend PID/window ownership validation to macOS and Linux;+- add session-end and connection-end cleanup;+- add distinct page-ref storage and stale-ref errors;+- prohibit trajectory replay of browser target capabilities;+- add granular capability tokens and refusal codes.++Exit gate:++- target IDs cannot cross sessions;+- ending one session does not break another session sharing the same browser endpoint;+- process, endpoint, window, tab, and ref invalidation each fail closed;+- no browser secrets appear in logs or artifacts.++### Phase 3: Read-only `get_browser_state`++Work:++- register the platform-specific read-only tool schema;+- implement browser classification and route discovery;+- return browser target, binding confidence, tabs, capabilities, and `requires_setup`;+- generate compact DOM-derived refs for exact CDP targets;+- support bounded output and opt-in screenshot;+- return identity and structured unavailable routes on non-CDP surfaces;+- ensure no discovery path can signal, restart, patch, prompt, or navigate.++Exit gate:++- MCP annotations and trajectory recording treat the tool as read-only;+- repeated calls are idempotent except for refreshed observed state;+- multi-tab state is deterministic and bounded;+- real-browser state evidence exists on macOS, Windows, Linux X11, and Linux Wayland where applicable.++### Phase 4: Explicit `browser_prepare`++**Implementation status:** Complete for safe isolated Chromium launch.++Work:++- define structured setup requirements and confirmation semantics;+- support driver-owned isolated Chromium profiles;+- refuse automated existing-profile mutation, copying, and restart;+- bind acting setup to MCP-host approval or a direct interactive approval artifact;+- return exact side-effect evidence;+- make temporary profile/process cleanup session-owned and fail closed after+ interruption.++Exit gate:++- every isolated launch is attributable to a destructive recorded call;+- declining setup leaves browser and profile unchanged;+- accepted setup produces a separately discoverable prepared pid or a structured+ residual limitation;+- approval artifacts are short-lived, single-use, and bound to the requested+ pid and profile.++### Phase 5: Navigation and typed browser input++Work:++- implement `browser_navigate` for exact CDP targets;+- implement trusted `browser_click` through browser input dispatch;+- implement explicit `dom_event` click as a separate requested trust class;+- implement `browser_type` insert and keystroke modes;+- report route, trust, coordinates, and verification;+- add navigation and mutation invalidation for page refs;+- add per-target mutation serialization;+- refuse unsupported waits and trust classes structurally.++Exit gate:++- actions never use first-page fallback;+- stale tabs and refs never silently re-resolve;+- trusted input produces real browser event sequences in the fixture journal;+- DOM input is visibly labeled and separately tested;+- focus and leaked-input sentinels prove background behavior where advertised.++### Phase 6: `page` compatibility facade++**Implementation status:** Complete at the transport boundary. Legacy public+selection, arguments, result formatting, and native fallbacks remain unchanged.++Work:++- route legacy CDP calls through the shared pooled, event-aware `CdpConnection`;+- preserve legacy argument behavior, first-page/URL-hint selection, output+ formatting, and timeout behavior;+- preserve AppleScript, UIA, and AT-SPI fallbacks outside CDP;+- remove duplicate hand-written WebSocket framing and request/reply loops;+- document deprecation without removing the tool.++Exit gate:++- existing `page` tests and downstream schema tests pass;+- browser tools and legacy `page` calls share the CDP transport and event demux+ without pretending their target-selection semantics are identical;+- no supported `page` behavior regresses;+- deprecation begins only after accepted browser-tool evidence exists.++### Phase 7: Release evidence, documentation, and rollout++**Implementation status:** Complete. The accepted implementation and runner+changes are frozen before the final exact-head replay. The canonical evidence+manifests record the full source SHA, environment, row outcome, oracles, and+video for every accepted route.++Work:++- add exact-SHA browser result tables and artifacts;+- add real-browser maintainer-dispatched CI lanes;+- document the native-window versus browser-page mental model;+- add a browser preparation how-to for isolated and authenticated profiles;+- add browser API reference and platform capability tables;+- update bundled skills and validate examples against each OS schema;+- add upgrade guidance from `page`;+- add route-level telemetry without capturing page secrets.++Exit gate:++- public claims match retained real-browser evidence;+- every code example is schema-tested on the platform it describes;+- release candidates require the accepted browser matrix;+- `page` remains available for at least two releases after formal deprecation.++## Proposed PR Sequence++Keep each PR independently reviewable and avoid exposing incomplete public tools.++| PR | Scope | User-visible change | Merge requirement |+| --- | ----------------------------------------------------------- | -------------------------------------------- | ------------------------------------- |+| 1 | Chromium binding spike and real-browser discriminators | None | Kill criterion passes |+| 2 | Shared CDP transport, endpoint ownership, and launch parity | More truthful/hardened existing CDP behavior | Existing page E2E green |+| 3 | Session target store, flat-mode routing, refs, and refusals | None or additive structured internals | Concurrency and cleanup tests green |+| 4 | Read-only `get_browser_state` | New state tool | Cross-platform state matrix accepted |+| 5 | `browser_prepare` and consent/profile flows | New mutating setup tool | Consent and restart evidence accepted |+| 6 | `browser_navigate` | New typed navigation | Real-browser navigation lanes green |+| 7 | `browser_click` and `browser_type` | New typed input tools | Trust/focus/leak oracles green |+| 8 | Route legacy `page` through BrowserEngine | No intentional behavior change | Compatibility suite green |+| 9 | Docs, skills, release matrix, and deprecation notice | Public rollout | Exact-SHA evidence linked |++Do not merge PR 4 merely to allow later CI to run unless the state tool's own acceptance gate is complete. Use test-only probes or feature-gated internal code for the feasibility stage.++## Validation Strategy++### Unit and protocol tests++Run automatically on affected OS paths:++- browser and engine classification;+- endpoint parsing and loopback enforcement;+- PID and process-tree endpoint ownership;+- CDP target selection and ambiguity;+- browser-window correlation and confidence scoring;+- flat-mode command routing and response correlation;+- session isolation and cleanup;+- tab and binding invalidation;+- page-ref creation, namespace rejection, staleness, TTL, and bounds;+- structured refusal schema;+- MCP annotations and capability tokens;+- platform-specific tool schema parity;+- legacy `page` compatibility.++### Deterministic repository-owned E2E++Extend the existing harnesses without weakening their oracles:++| Host | Platforms | Required browser-tool coverage |+| ----------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------- |+| Electron fixture | macOS, Windows, Linux X11, Linux Wayland | Discovery, exact single-window binding, refs, navigate, click, type, stale refs, concurrent sessions |+| Tauri fixture | macOS, Windows, Linux X11, Linux Wayland | Capability reporting, exact route where available, native fallback boundaries |+| WebView2 fixture | Windows | Split-process route detection and side-effect-free structured refusal |+| WKWebView fixture | macOS | Identity, capability limitations, native-state handoff |+| WebKitGTK fixture | Linux | Identity, capability limitations, native-state handoff |++Repository fixtures remain the canonical deterministic behavior matrix. They do not replace real-browser evidence.++### Real-browser release matrix++| Platform | Required v2 browser evidence |+| ---------------------- | ----------------------------------------------------------------------------------- |+| Windows interactive | Chrome and Edge standalone; Electron delivery; Tauri and WebView2 exact refusals |+| macOS authorized VM | Chrome standalone; Electron delivery; Tauri and WKWebView exact refusals |+| Linux X11 | Chromium standalone; Electron delivery; Tauri exact refusal |+| Linux Wayland Sway | Native Ozone Chromium; Electron delivery; Tauri exact refusal |+| Other Wayland desktops | Capability reporting and refusal unless the compositor proves exact pid + geometry |++Every real-browser lane records:++- exact commit SHA and driver build identity;+- OS, browser, browser version, window system, and profile kind;+- route and binding confidence;+- before/after browser state;+- native focus and foreground sentinel;+- leaked-input oracle;+- tool trace and structured results;+- screenshots and video where the platform can capture them safely;+- explicit expected refusals.++### Required adversarial scenarios++1. Multiple browser windows owned by one PID.+2. Multiple tabs with colliding titles and URL substrings.+3. Same-size and same-position windows.+4. Tab drag between windows after binding.+5. New popup window and opener relationship.+6. Permission prompt and native file picker handoff.+7. Browser restart and stale target reuse.+8. Closed tab and reused browser target metadata.+9. Fake local debugging endpoint.+10. Two Cua sessions acting on different tabs through one endpoint.+11. Concurrent read and mutation requests.+12. Authenticated profile consent accepted and declined.+13. Background target fully occluded by the sentinel.+14. Wayland target without stable geometry.+15. Legacy `page` call and new browser call against the same browser process.+16. Same-origin iframe and cross-origin out-of-process iframe refs, including a structured limitation where the route is not implemented.++## CI Policy++### Automatic PR checks++- shared Rust unit tests;+- core browser protocol tests;+- platform-specific compile and schema tests only when relevant paths change;+- deterministic noninteractive tests that do not require browser consent or a desktop session;+- documentation example/schema checks.++### Maintainer-dispatched interactive checks++- Windows real-browser matrix on an interactive runner;+- Linux X11 and Wayland browser matrices;+- macOS local authorized-host matrix;+- authenticated-profile and consent scenarios;+- full video/artifact collection.++### Release gate++A release that advertises the browser tool requires:++- fresh exact-SHA accepted evidence for every advertised route;+- no unexplained heuristic mutation;+- no unresolved wrong-target, endpoint-owner, or cross-session failures;+- public capability docs generated from the shipping platform binaries;+- compatibility evidence for the legacy `page` facade.++## Migration From `page`++### Compatibility policy++- `page` remains functional throughout v1.+- Existing action names and schemas remain accepted.+- Legacy first-page behavior remains only in the compatibility facade.+- New browser tools never use first-page fallback.+- `page` gains optional `session` and `browser_target_id` fields additively.+- `page` responses gain route metadata without removing existing text.+- Deprecation documentation begins only after browser tools reach accepted parity.+- Removal is not considered for at least two releases and requires usage evidence plus a separate decision.++### Documentation transition++During coexistence, docs should say:++- use browser tools for new agentic browsing integrations;+- use `get_window_state` for browser chrome and native dialogs;+- use `page` only for compatibility with existing clients;+- inspect route and trust metadata before relying on background semantics.++## Issue Mapping++The implementation should coordinate with these existing issues:++| Issue | Relationship to this plan |+| -------------------------------------------------- | -------------------------------------------------------------------- |+| [#2200](https://github.com/trycua/cua/issues/2200) | Exact PID/window targeting and ambiguous-target refusal |+| [#2176](https://github.com/trycua/cua/issues/2176) | Browser/page escalation before native foreground fallback |+| [#2192](https://github.com/trycua/cua/issues/2192) | Authenticated Chrome profile preparation and consent |+| [#2084](https://github.com/trycua/cua/issues/2084) | Shared CDP typing and Windows/Linux parity |+| [#2201](https://github.com/trycua/cua/issues/2201) | Windows Chrome background native input remains a separate route risk |+| [#2202](https://github.com/trycua/cua/issues/2202) | macOS Chrome native drag remains separate from browser DOM/CDP input |+| [#1616](https://github.com/trycua/cua/issues/1616) | Real Chromium accessibility exposure and native fallback |+| [#2101](https://github.com/trycua/cua/issues/2101) | Firefox capability and minimized/native-state limitations |+| [#2194](https://github.com/trycua/cua/issues/2194) | Wayland cursor-preservation evidence remains platform-limited |++Create one browser-tool umbrella issue before implementation, then link each PR and any newly discovered platform bug to the relevant capability row rather than treating all browser work as one undifferentiated feature.++## Documentation Deliverables++Use the Diataxis structure for public documentation:++### Tutorial++- control a real browser from discovery through verified page action;++### How-to guides++- use an isolated Chromium profile;+- connect to an authenticated existing profile with explicit consent;+- handle `requires_setup`;+- move between browser page state and native browser chrome;+- debug a stale or ambiguous binding;+- run the browser validation harnesses.++### Reference++- browser tool schemas;+- binding confidence and refusal codes;+- platform/browser capability table;+- input trust classes;+- session, target, tab, and ref lifetimes;+- CI and release evidence ledger.++### Explanation++- why Cua separates native window state from browser page state;+- why browser preparation cannot happen inside a read-only getter;+- how exact targeting and CDP endpoint ownership work;+- why some Wayland, Safari, Firefox, and embedded-webview routes are intentionally unavailable.++Bundled skills must derive their examples from the same platform-specific schemas and must not claim unsupported actions.++## Telemetry and Diagnostics++Add privacy-preserving counters and structured diagnostics for:++- browser classification success/failure;+- route availability;+- setup required, accepted, declined, and failed;+- binding method and confidence;+- wrong-target and owner-mismatch refusals;+- stale tab, target, and ref refusals;+- requested and actual input trust;+- route fallback requests and refusals;+- action verification outcome;+- endpoint reuse and consent-prompt count;+- session cleanup and leaked-target detection.++Do not record URLs, page text, selectors, cookies, profile paths, auth state, endpoint tokens, or JavaScript payloads in aggregate telemetry.++`doctor` should report browser support readiness without mutating state:++- recognized browsers;+- whether a safe endpoint is already available;+- whether setup is required;+- platform permission prerequisites;+- source/release build identity;+- Linux window system and required feature flags;+- Windows interactive-session status.++## Risks and Mitigations++| Risk | Mitigation |+| ------------------------------------------- | ------------------------------------------------------------------------------- |+| Wrong native window mapped to a tab | Owner proof, exact correlation, per-call revalidation, ambiguity refusal |+| Consent prompt triggered by read-only state | Hard separation between state and prepare; reuse approved sockets |+| Cross-session CDP delivery | Flat mode and one CDP session ID per Cua session/tab |+| Browser tab moved after binding | Re-check browser window relationship before mutation |+| DOM click mistaken for trusted input | Required `input_trust` result and explicit caller choice |+| Duplicate native/browser context | Browser state excludes native tree and screenshot by default |+| Wayland missing identity/geometry | Confidence `none`, structured refusal, native semantic fallback only |+| Existing profile compromised | Explicit consent, loopback owner proof, TTL, no target replay, secret-safe logs |+| Public API outruns evidence | Chromium-only v1 mutation and exact-SHA release matrix |+| `page` migration regresses users | Compatibility facade, retained tests, multi-release deprecation |+| Tool surface overwhelms MCP context | Five typed v1 tools, compact refs, bounded output, granular registration |++## Retained Product Decisions++These decisions remain intentionally deferred after implementation evidence:++1. Whether Safari should gain deeper Apple Events tab enumeration or a WebDriver route.+2. Whether Firefox demand justifies a WebDriver BiDi engine.+3. Trusted CDP pointer input shipped as the default; DOM click remains an+ explicit caller-selected trust class.+4. Whether browser tab open, close, and activate belong in v1.1 or later.+5. Whether a CDP-event-backed `browser_wait` is valuable enough to become a separate typed tool.+6. Whether `state_revision` should exist only for event-backed targets or remain omitted in favor of snapshot staleness.+7. Whether AX-only embedded surfaces should ever expose browser-prefixed refs.+8. Whether domain/content policy belongs in Cua Driver, the MCP host, or a separate policy layer.+9. The exact `page` deprecation timeline after adoption data exists. Transport+ duplication is removed, but the compatibility facade is not deprecated yet.++## Definition of Done++The browser tool project is complete when:++- the feasibility spike passes or the design has pivoted according to the kill criterion;+- every supported endpoint is owner-verified and loopback-bound;+- browser targets, tabs, and refs are exact, session-scoped, expiring capabilities;+- `get_browser_state` is demonstrably side-effect-free;+- preparation, consent, restart, and profile operations are explicit and recorded;+- typed navigation and input tools report exact routes and trust classes;+- ambiguous and stale targets refuse without acting;+- concurrent sessions cannot cross-deliver browser commands;+- native browser chrome and dialogs remain cleanly handled through `get_window_state`;+- deterministic fixture and real-browser matrices are accepted on advertised platforms;+- legacy `page` behavior remains compatible through the shared engine;+- public docs, bundled skills, schemas, diagnostics, and release evidence agree;+- no known wrong-target or silent-success browser issue remains in an advertised route.++## Review Decision Record++Reviewers approved these four points before implementation:++1. `get_browser_state` is strictly read-only, with all setup delegated to `browser_prepare`.+2. Browser mutation requires an exact binding; heuristic binding is informational only.+3. V1 exposes five typed tools rather than a multiplexed browser command surface.+4. The Phase 0 kill criterion is binding: failure to prove exact-or-refused Chromium correlation causes a tab-first design pivot.++Phase 0 proved the window-anchored design. The later phases proceeded only after+the exact-or-refused binding and ambiguity tests passed.diff --git a/libs/cua-driver/rust/Cargo.lock b/libs/cua-driver/rust/Cargo.lockindex 1d66615bd6..eb206ff60a 100644--- a/libs/cua-driver/rust/Cargo.lock+++ b/libs/cua-driver/rust/Cargo.lock@@ -730,6 +730,7 @@ dependencies = ["cursor-overlay","embed-resource","flate2",+ "futures-util","image","libc","pip-preview",@@ -742,6 +743,7 @@ dependencies = ["tar","tempfile","tokio",+ "tokio-tungstenite","tracing","tracing-subscriber","ureq",@@ -756,7 +758,9 @@ version = "0.8.3"dependencies = ["anyhow","async-trait",+ "futures-util","image",+ "libc","regex","regorus","serde",@@ -765,7 +769,9 @@ dependencies = ["tempfile","thiserror 1.0.69","tokio",+ "tokio-tungstenite","tracing",+ "uuid","windows 0.58.0",]@@ -774,6 +780,7 @@ name = "cua-driver-testkit"version = "0.8.3"dependencies = ["core-foundation",+ "libc","objc2-app-kit","serde","serde_json",diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.mdindex 77ddcccf2b..720a99b42b 100644--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md@@ -30,9 +30,9 @@ directory:Cross-cutting topics also have their own files:-- `WEB_APPS.md` — browser / Electron / Tauri specifics (sparse AX- trees, omnibox navigation, the `set_value` workaround for- minimized windows, tabs-vs-windows guidance).+- `WEB_APPS.md` — the typed, full-background Chromium browser workflow plus+ browser / Electron / Tauri fallbacks (sparse AX trees, omnibox navigation,+ minimized windows, and tabs-vs-windows guidance).- `RECORDING.md` — session recording + `replay_trajectory`.- `TESTS.md` — internal test surface.@@ -121,6 +121,13 @@ cua-driver click '{"pid":844,"window_id":10725,"element_index":14}'cua-driver stop```+For Chromium page content, keep the same native window selection but switch to+the browser capability loop: `start_session`, bind `(pid, window_id)` with+`get_browser_state`, snapshot the returned tab, then use `browser_click`,+`browser_type`, or `browser_navigate`. Read `WEB_APPS.md` before using this+route. Browser target ids, tab ids, and refs are session-scoped and stale refs+must be replaced by a fresh snapshot.+## Agent cursor overlayVisual cursor overlay for demos and screen recordings. Default:@@ -136,8 +143,8 @@ persisted to config.cursor, keyed by the session's id (the proxy mints one session id perMCP connection and the daemon scopes the cursor, config overrides, andrecording to it). You normally pass nothing — the session key is wired-through for you. Pass an explicit `cursor_id` only to *deliberately-share* one cursor across sessions. When a session ends (the MCP client+through for you. Pass an explicit `cursor_id` only to _deliberately+share_ one cursor across sessions. When a session ends (the MCP clientdisconnects) its cursor is removed automatically.**Visibility caveat (AX runs).** On a pure accessibility-action run@@ -145,7 +152,7 @@ disconnects) its cursor is removed automatically.on-screen a short distance from the target and plays a brief glide +pulse** — not the long Bezier sweep a cursor already on-screen wouldtrace from its previous spot. It's subtle and easy to miss in a-recording. If you want a clearly *gliding* cursor for a demo or screen+recording. If you want a clearly _gliding_ cursor for a demo or screenrecording, do a pixel click (`click({pid,x,y})`) or a `move_cursor`first to put the cursor on-screen; subsequent AX actions then glide thefull path normally.@@ -217,7 +224,7 @@ capture, no mode flip.> element ax action** and don't need to re-ground on pixels. The> `ax`/`px` decision still lives at action time, not here.-> **`capture_mode` is DEPRECATED and ignored.** It is still *accepted*+> **`capture_mode` is DEPRECATED and ignored.** It is still _accepted_> on `get_window_state` so old callers don't error, but it has **no> effect** — both the tree and the screenshot come back regardless of> what you pass (`ax`, `vision`, `som`, anything). There is no@@ -240,7 +247,7 @@ on the action call, and that one choice selects the rung:confirms the effect.`ax`↔`element_index`, `px`↔pixel `x,y`. We retired the word "vision"-for the *dispatch* path — it conflated perception with dispatch.+for the _dispatch_ path — it conflated perception with dispatch.Perception is always both; dispatch is `ax` or `px`.**The keyboard family has both forms too.** `type_text`, `press_key`,@@ -262,7 +269,7 @@ screenshot in the response (the only ground truth). Escalate to the pxform — `type_text({pid, window_id, x, y, text})` — which pixel-clicksto focus, then types. **If the target control is closed** (a searchbutton, a collapsed field), AX-press to open it first (AX actions work-in the background): a px focus-click won't reliably open *and* focus a+in the background): a px focus-click won't reliably open _and_ focus aclosed control, so the text leaks into whatever's already focused.Escalate to `delivery_mode:"foreground"` only if it still drops.@@ -290,7 +297,7 @@ whether — and where — to climb the ladder:should change rung —- `"px"` — the element isn't really actionable in `ax`; do an**element px action** off the screenshot you already have.- - `"foreground"` — a background insert/click was *dropped* on+ - `"foreground"` — a background insert/click was _dropped_ ondelivery; re-call the same action with `delivery_mode:"foreground"`.`get_window_state` itself, when the AX tree comes back empty (a non-AX@@ -302,7 +309,7 @@ still have the screenshot from the same call to click off).window cannot be pixel-targeted in the background (libei →`background_unavailable`), so there the recommendation is**`foreground`, not `px`**. macOS, X11, and most Windows surfaces-*can* pixel-target in the background, so they recommend `px`. See+_can_ pixel-target in the background, so they recommend `px`. See`LINUX.md` / `WINDOWS.md`.## The verify-then-escalate ladder (algorithm)@@ -310,7 +317,7 @@ window cannot be pixel-targeted in the background (libei →Every snapshot already hands you both the tree and the screenshot, soverifying never means "go take a screenshot" — it means cross-checkthe tree against the pixels you already have, and only change-*dispatch rung* on a real signal. Walk the rungs:+_dispatch rung_ on a real signal. Walk the rungs:```# Rung 1 — element ax action, backgrounded (the cheap default)@@ -346,18 +353,18 @@ The two ideas to hold onto: (1) the AX tree **lies** on canvas / web /Catalyst / virtualized surfaces, so an unchanged-or-bogus tree plus`suspected_noop`/`degraded` — or a tree that simply disagrees with thescreenshot — is your cue to do an **element px action** off the-screenshot you already have; (2) `px` is a *conscious* switch to the+screenshot you already have; (2) `px` is a _conscious_ switch to thepixel addressing path, not a different capture.**Window state → what works**-| state | `get_window_state` | element-index click (AX/UIA) | `press_key` commit | pixel click |-|---|---|---|---|---|-| frontmost | ✅ | ✅ | ✅ | ✅ |-| backgrounded / visible | ✅ | ✅ | ✅ | ✅ |-| **minimized** | ✅ | ✅ (actions fire in place) | ❌ silent no-op — use `set_value` or click equivalent | ❌ no on-screen bounds |-| hidden | ✅ | ✅ | depends | ❌ |-| on another desktop / Space | ⚠️ tree may be stripped on some apps — response carries `off_space: true` so you can detect it | ✅ | ✅ | ❌ not in current-desktop list |+| state | `get_window_state` | element-index click (AX/UIA) | `press_key` commit | pixel click |+| -------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------- | ------------------------------ |+| frontmost | ✅ | ✅ | ✅ | ✅ |+| backgrounded / visible | ✅ | ✅ | ✅ | ✅ |+| **minimized** | ✅ | ✅ (actions fire in place) | ❌ silent no-op — use `set_value` or click equivalent | ❌ no on-screen bounds |+| hidden | ✅ | ✅ | depends | ❌ |+| on another desktop / Space | ⚠️ tree may be stripped on some apps — response carries `off_space: true` so you can detect it | ✅ | ✅ | ❌ not in current-desktop list |**Critical cell — minimized + keyboard commit.** The keystrokereaches the app but accessibility focus doesn't propagate to renderer@@ -384,7 +391,7 @@ end_session(session) # when the run finishescommon case collapses to two calls (`launch_app` → `get_window_state`)without a separate `list_windows` hop.-**Declare a session.** A session is *your run's* identity — a stable id+**Declare a session.** A session is _your run's_ identity — a stable idyou choose (`"research-1"`), declared with `start_session` and passed as`session` on every action. It owns your agent cursor (a distinct colourper id), follows the run across any apps/windows, and is the same whether@@ -400,8 +407,8 @@ its **own `session`** (→ its own cursor) AND passThe element cache is keyed on `(pid, window_id)` and the cursor on `session`,so distinct instances + distinct sessions keep the runs fully separated.-**Parallelism vs. ordering.** Distinct sessions give distinct *cursors*, not-distinct *connections*. Subagents that share one `cua-driver mcp` (stdio)+**Parallelism vs. ordering.** Distinct sessions give distinct _cursors_, not+distinct _connections_. Subagents that share one `cua-driver mcp` (stdio)connection have their tool calls **serialized** by the transport — they taketurns, not run in parallel. That's not a correctness problem (session + windowisolation means they can't collide), just a throughput one. For genuinely@@ -467,19 +474,19 @@ the model receives only the tree and `screenshot_file_path`, thenreads the image from disk.**The tree and the screenshot are complementary, not redundant — and-they come from the *same* call.** Each half carries signal the other+they come from the _same_ call.** Each half carries signal the othercan't, which is exactly why you cross-check them:-- The **tree** tells you *what's clickable* — roles, labels,+- The **tree** tells you _what's clickable_ — roles, labels,`element_index` handles, advertised actions, parent-childstructure. This is the ground truth for an **element ax action**.-- The **screenshot** tells you *which one* — the tree often has many+- The **screenshot** tells you _which one_ — the tree often has manybuttons with similar or empty labels ("Delete", "OK", anonymousUUID-labeled buttons, repeated static-text), and visual contextdisambiguates. Captions, colors, layout relationships visible inpixels often don't show up in the tree at all (especially inChromium / Electron / web content) — and the screenshot is where you- catch the tree *lying* (an `h:1`/off-viewport row, a Catalyst null+ catch the tree _lying_ (an `h:1`/off-viewport row, a Catalyst nullvalue).Default to dispatching by `element_index` (the **element ax action**) —@@ -488,7 +495,7 @@ it's the verifiable, backgroundable rung. Do an **element px action**(repeated/empty labels), when it's empty (`degraded` — non-AXsurface), when an action came back `suspected_noop`, or when the treedisagrees with the pixels. You never re-capture to switch — the-screenshot is already there; you just change *how you address* the+screenshot is already there; you just change _how you address_ thetarget.Reach for pixel coordinates only when the target is a canvas /@@ -508,19 +515,19 @@ Every row assumes a `(pid, window_id)` pair from the lastignored on pixel-only forms unless you want to anchor the conversionagainst a specific window.-| Intent | Tool | Notes |-|---|---|---|-| List an app's windows | `list_windows({pid})` | returns `window_id`, `title`, `bounds`, `z_index`, `is_on_screen`, `on_current_space`. Already included in `launch_app`'s response — only call this for long-lived pids |-| Snapshot a window | `get_window_state({pid, window_id})` | returns `tree_markdown` + `screenshot_*`; populates the `(pid, window_id)` element_index cache |-| Left click | `click({pid, window_id, element_index})` | default `action: "press"`. Pixel form: `click({pid, x, y})` (window_id optional) — `modifier: ["cmd"\|"ctrl"]` |-| Double-click / open | `double_click({pid, window_id, element_index})` | Default action when the element advertises one (Open on Finder items / openable rows), else stamped pixel double-click at the element's center |-| Right click / context menu | `right_click({pid, window_id, element_index})` or `click({pid, window_id, element_index, action: "show_menu"})` | Chromium web-content coerces pixel right-click to left on macOS — see `WEB_APPS.md` |-| Type at cursor | `type_text({pid, text, window_id, element_index})` (ax) or `type_text({pid, text, window_id, x, y})` (px) | ax focuses the element then writes via the platform's text-set primitive; **px** pixel-clicks `(x,y)` to focus the renderer, then types — the one-call fix for Chromium/Electron inputs the AX path can't reach |-| Set whole non-text control value | `set_value({pid, window_id, element_index, value})` | **AX-only by design** — dropdown/`AXPopUpButton`, checkbox, slider, stepper; **also the keyboard-commit workaround on minimized windows.** For text use `type_text`; to pixel-manipulate a control use `click`/`drag` |-| Scroll | `scroll({pid, direction, amount, by, window_id, element_index})` | synthesizes per-pid PageUp/PageDown/arrows |-| Focus + send key | `press_key({pid, key, window_id, element_index, modifiers})` (ax) or `press_key({pid, key, x, y})` (px) | ax `element_index` sets focus then posts the key; **px** pixel-clicks `(x,y)` to focus, then sends the key |-| Send key to pid | `press_key({pid, key, modifiers})` | no focus change; key goes to pid's current focus |-| Modifier combo | `hotkey({pid, keys})` (no focus) or `hotkey({pid, x, y, keys})` (px) | e.g. `["cmd","c"]` / `["ctrl","c"]`; posted per-pid, not HID tap. **px** pixel-clicks `(x,y)` to focus a field first, e.g. `["cmd","v"]` to paste into it |+| Intent | Tool | Notes |+| -------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| List an app's windows | `list_windows({pid})` | returns `window_id`, `title`, `bounds`, `z_index`, `is_on_screen`, `on_current_space`. Already included in `launch_app`'s response — only call this for long-lived pids |+| Snapshot a window | `get_window_state({pid, window_id})` | returns `tree_markdown` + `screenshot_*`; populates the `(pid, window_id)` element_index cache |+| Left click | `click({pid, window_id, element_index})` | default `action: "press"`. Pixel form: `click({pid, x, y})` (window_id optional) — `modifier: ["cmd"\|"ctrl"]` |+| Double-click / open | `double_click({pid, window_id, element_index})` | Default action when the element advertises one (Open on Finder items / openable rows), else stamped pixel double-click at the element's center |+| Right click / context menu | `right_click({pid, window_id, element_index})` or `click({pid, window_id, element_index, action: "show_menu"})` | Chromium web-content coerces pixel right-click to left on macOS — see `WEB_APPS.md` |+| Type at cursor | `type_text({pid, text, window_id, element_index})` (ax) or `type_text({pid, text, window_id, x, y})` (px) | ax focuses the element then writes via the platform's text-set primitive; **px** pixel-clicks `(x,y)` to focus the renderer, then types — the one-call fix for Chromium/Electron inputs the AX path can't reach |+| Set whole non-text control value | `set_value({pid, window_id, element_index, value})` | **AX-only by design** — dropdown/`AXPopUpButton`, checkbox, slider, stepper; **also the keyboard-commit workaround on minimized windows.** For text use `type_text`; to pixel-manipulate a control use `click`/`drag` |+| Scroll | `scroll({pid, direction, amount, by, window_id, element_index})` | synthesizes per-pid PageUp/PageDown/arrows |+| Focus + send key | `press_key({pid, key, window_id, element_index, modifiers})` (ax) or `press_key({pid, key, x, y})` (px) | ax `element_index` sets focus then posts the key; **px** pixel-clicks `(x,y)` to focus, then sends the key |+| Send key to pid | `press_key({pid, key, modifiers})` | no focus change; key goes to pid's current focus |+| Modifier combo | `hotkey({pid, keys})` (no focus) or `hotkey({pid, x, y, keys})` (px) | e.g. `["cmd","c"]` / `["ctrl","c"]`; posted per-pid, not HID tap. **px** pixel-clicks `(x,y)` to focus a field first, e.g. `["cmd","v"]` to paste into it |**All keyboard/text primitives require `pid`.** There is nofrontmost-routed variant — every key goes to the named target via@@ -538,13 +545,13 @@ The capture, dispatch, and addressing params — `session`,`delivery_mode`, `capture_mode` (deprecated/ignored — see the behaviormatrix; still in the schema only so old callers don't error), `scope`,`modifier`, `button`, `element_index`, `element_token` — are a **shared-schema contract**: identical *shape* (`type`/`enum`/`items`) on macOS,+schema contract**: identical _shape_ (`type`/`enum`/`items`) on macOS,Windows, and Linux.They compose from canonical fragments in`cua-driver-core::tool_schema` (+ `capture_mode`), and a CI gate(`schema_consistency_test`) runs every tool's live `tools/list` through astructural checker on each platform, so the three surfaces can't-silently drift. *Contributor note:* when you add or edit one of these+silently drift. _Contributor note:_ when you add or edit one of theseshared params on a tool, pull from the fragment — don't re-hand-write theJSON, or the gate fails. (Descriptions may legitimately vary per tool;the gate compares shape, not prose.)@@ -554,7 +561,7 @@ Two consequences for callers:- **`session` is accepted on every action and cursor tool, on all threeplatforms.** It's cursor-wired where the platform glides a cursor andschema-accepted everywhere else — so the same `session` you pass on- macOS is no longer *rejected* by Windows/Linux, which previously+ macOS is no longer _rejected_ by Windows/Linux, which previouslyrefused unknown keys via `additionalProperties:false`.- **`delivery_mode` (`"background"` default / `"foreground"`) is on thewhole input family** — `click`, `double_click`, `right_click`, `drag`,@@ -564,13 +571,13 @@ Two consequences for callers:didn't land. **`foreground` is a reaction, never a prediction.** Alwaysfire the `background` default first and let the driver tell you itcan't (a `background_unavailable` error or `escalation.recommended ==- "foreground"`) — or observe a verified no-op — *before* you escalate.+"foreground"`) — or observe a verified no-op — _before_ you escalate.Do **not** reason "it's a GTK/Chromium/Electron app, so background willdrop, so I'll front up-front": the toolkit lists in the tool schemas- are the *driver's* internal detectors, not a checklist for you to front+ are the _driver's_ internal detectors, not a checklist for you to fronton a guess. (Concretely: GIMP's GTK toolbox accepts background pixelclicks fine — a preemptive foreground click there just steals the- user's focus for nothing.) What each platform's *background* rung can+ user's focus for nothing.) What each platform's _background_ rung canactually carry differs (e.g. a Windows background click can't carry`modifier` state — see `WINDOWS.md`); the schema is uniform, theresidual limits are per-OS.@@ -716,13 +723,13 @@ doesn't-survive-across-sessions caveat.## Common error patterns (cross-platform)-| Error text | Meaning | Fix |-|---|---|---|-| `No cached AX state for pid X window_id W` | You either skipped `get_window_state` this turn, or passed a different `window_id` to the click than the one the snapshot cached against | Call `get_window_state({pid: X, window_id: W})` first — the same window_id you intend to click in |-| `Invalid element_index N for pid X window_id W` | Index is stale or out of range | Re-run `get_window_state` with the same window_id, pick a fresh index from the new tree |-| `window_id W belongs to pid P, not …` | Passed a window_id that's owned by a different process | Use `list_windows({pid: X})` to enumerate this pid's own windows |-| `AX action … failed with code …` / `UIA invoke failed` | Element doesn't support the default action | Try `show_menu`, `confirm`, `cancel`, `pick`, or fall through to a pixel click on the element's center |-| `The user doesn't want to proceed with this tool use. The tool use was rejected …` | The harness uses this *exact* string for BOTH a permission-prompt denial AND a manual interrupt (Esc / stop) of a running tool — they are indistinguishable from the tool result | Treat as "tool canceled, no result, await the user." Do NOT paraphrase ("you stopped me") — quote the literal message and name the canceled tool + its args, so the user can tell what was in flight vs. what landed |+| Error text | Meaning | Fix |+| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| `No cached AX state for pid X window_id W` | You either skipped `get_window_state` this turn, or passed a different `window_id` to the click than the one the snapshot cached against | Call `get_window_state({pid: X, window_id: W})` first — the same window_id you intend to click in |+| `Invalid element_index N for pid X window_id W` | Index is stale or out of range | Re-run `get_window_state` with the same window_id, pick a fresh index from the new tree |+| `window_id W belongs to pid P, not …` | Passed a window_id that's owned by a different process | Use `list_windows({pid: X})` to enumerate this pid's own windows |+| `AX action … failed with code …` / `UIA invoke failed` | Element doesn't support the default action | Try `show_menu`, `confirm`, `cancel`, `pick`, or fall through to a pixel click on the element's center |+| `The user doesn't want to proceed with this tool use. The tool use was rejected …` | The harness uses this _exact_ string for BOTH a permission-prompt denial AND a manual interrupt (Esc / stop) of a running tool — they are indistinguishable from the tool result | Treat as "tool canceled, no result, await the user." Do NOT paraphrase ("you stopped me") — quote the literal message and name the canceled tool + its args, so the user can tell what was in flight vs. what landed |Platform-specific errors (TCC dialogs on macOS, Session 0 / UACprompts on Windows, AT-SPI bus issues on Linux) live in theirdiff --git a/libs/cua-driver/rust/Skills/cua-driver/TESTS.md b/libs/cua-driver/rust/Skills/cua-driver/TESTS.mdindex c964c4db9e..926de2737f 100644--- a/libs/cua-driver/rust/Skills/cua-driver/TESTS.md+++ b/libs/cua-driver/rust/Skills/cua-driver/TESTS.md@@ -1,5 +1,13 @@# Natural-language tests for `cua-driver`+These prompts are exploratory skill checks, not the release-support source of+truth. Canonical browser claims come from the typed Rust harness catalog in+`crates/cua-driver/tests`: standalone Chromium adversarial rows and the shared+embedded-browser route rows. Those tests assert fixture-owned state plus+cross-cutting focus, z-order, cursor, leaked-input, and video evidence. They+cover exact Chromium/Electron delivery and structured refusals for embedded+surfaces whose native host cannot yet be bound exactly to its renderer.+> **Platform: macOS-focused.** The prompts and success criteria below> reference AppKit, `NSWorkspace.frontmostApplication`, macOS keyboard> modifiers (`cmd`), and macOS-only apps (Finder, Numbers, TextEdit,diff --git a/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md b/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.mdindex 05aa52c28e..f1f68c079e 100644--- a/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md+++ b/libs/cua-driver/rust/Skills/cua-driver/WEB_APPS.md@@ -1,17 +1,62 @@# Driving web-rendered apps-> **Platform: macOS-only.** This doc covers AX-tree quirks, AppleScript+## Prefer the typed browser tools for Chromium page mutation++For Chrome, Edge, Brave, and Electron, use the first-class browser workflow+before legacy `page`, AX, or pixel mutation when a DevTools endpoint is+available:++1. Start a named driver session.+2. Select the exact native `(pid, window_id)` from `launch_app` or+ `list_windows`.+3. Bind with `get_browser_state({pid, window_id, session})`. Continue only when+ `binding_quality` is `exact`.+4. Snapshot with `get_browser_state({target_id, tab_id, session})`.+5. Use the returned current ref with `browser_click` or `browser_type`, or use+ `browser_navigate` for a URL.+6. Re-snapshot after navigation and whenever a call reports+ `browser_ref_stale`. End the session when done.++If binding reports `browser_requires_setup`, use the separately approved+`browser_prepare` tool with `allow_launch:true` and+`profile:{mode:"isolated_new"}`. It returns a new `prepared_pid`; select that+process's window and bind again. Do not pass remote-debugging flags through+`launch_app`: the driver rejects that route so an agent cannot expose a user's+normal profile accidentally. MCP hosts approve the destructive prepare call;+direct/raw clients first mint a single-use token with the interactive+`cua-driver browser-approve` command.++This is the page-aware Chromium rung. Navigation, default ref-bound text+insertion, and an explicit DOM click can run against an exactly bound page+without raising its native window. `browser_click` defaults to trusted+`Input.dispatchMouseEvent`: standalone Windows has passing background evidence,+while standalone macOS and Linux return `browser_input_trust_unavailable`+before dispatch because Chromium activates its window on that route. Embedded+Electron has a separately proven bounded route. Use+`input_route:"dom_event"` only when a synthetic DOM click is explicitly+acceptable. Target ids, tab ids, and refs are opaque session capabilities, not+raw CDP ids.++Refs traverse open shadow roots and same-process frames. Out-of-process frames+are included only when the runtime exposes an independently attached CDP+session; otherwise the frame is reported as a limitation. The legacy guidance+below remains relevant for Safari, Firefox, browser chrome, and surfaces where+exact browser binding is unavailable.++> **Most legacy guidance below is macOS-specific.** It covers AX-tree quirks, AppleScript> JavaScript bridges, and Chromium / WebKit / Electron / Tauri patterns> on macOS. For Windows web-app automation (Edge, Chrome with> PostMessage / WebView2), see `WINDOWS.md` → "Web apps on Windows". For> Linux: `LINUX.md` (the cross-platform `page` tool below uses AT-SPI-> + CDP the same way).+>+> - CDP the same way).>> The `page` tool itself is **cross-platform** — Windows + Linux back> `get_text` / `query_dom` with UIA / AT-SPI respectively, and-> `execute_javascript` on those platforms uses CDP (browser must be-> launched with `--remote-debugging-port=N`, with the port exposed via-> the `CUA_DRIVER_CDP_PORT` env var). macOS routing (this doc) remains+> `execute_javascript` on those platforms uses CDP (the endpoint may be+> supplied by a test-owned fixture or a driver-owned browser prepared through+> `browser_prepare`; legacy callers can expose its port via+> `CUA_DRIVER_CDP_PORT`). macOS routing (this doc) remains> Apple Events → CDP → AX-tree fallback.Covers apps whose UI is rendered in a web runtime inside a native@@ -58,7 +103,7 @@ pixels:(often AX-exposed), toolbar buttons in the window chrome.2. Use keyboard shortcuts delivered straight to the pid —`hotkey({pid, keys: ["cmd", "enter"]})`, `hotkey({pid, keys:- ["cmd", "k"]})`, etc. Posted via `CGEvent.postToPid`, reaches the+["cmd", "k"]})`, etc. Posted via `CGEvent.postToPid`, reaches thetarget regardless of AX state, no activation required.3. For typing into web inputs, use `type_text` — it automaticallyfalls back to CGEvent synthesis when the input doesn't implement@@ -117,6 +162,7 @@ itself honors.Minor caveats for the rare case a `⌘L` flow is still needed(last-resort only, with user buy-in on the focus flash):+- Don't drop `delay_ms` below ~25 for keystroked typing onChromium — below that, autocomplete insertions interleave withyour characters and you get garbage like `"exuample.comn"`@@ -154,7 +200,7 @@ in a specific tab" (rare).tab-strip in the AX tree for `AXTab` / `AXRadioButton` elementsand read their `AXTitle`s. You can discover which tabs exist andwhat URLs/titles they carry without switching to any of them.-Only *activating* a specific tab is visible.+Only _activating_ a specific tab is visible.## Keyboard commits on minimized windows@@ -255,14 +301,14 @@ the target is AX-addressable.## Enable "Allow JavaScript from Apple Events" — browser support matrix-| Browser | `execute javascript` supported | Setting needed | Programmatic path |-|---|---|---|---|-| Chrome | ✅ Full | ✅ Yes | Edit Preferences JSON (see below) |-| Brave | ✅ Full | ✅ Yes | Edit Preferences JSON (same key, different path) |-| Edge | ✅ Full | ✅ Yes | Edit Preferences JSON (same key, different path) |-| Safari | ✅ Full (`do JavaScript`) | ✅ Yes | UI automation only — `defaults write` broken |-| Arc | ⚠️ No return values | No toggle | No reliable path |-| Firefox | ❌ Not supported | N/A | N/A |+| Browser | `execute javascript` supported | Setting needed | Programmatic path |+| ------- | ------------------------------ | -------------- | ------------------------------------------------ |+| Chrome | ✅ Full | ✅ Yes | Edit Preferences JSON (see below) |+| Brave | ✅ Full | ✅ Yes | Edit Preferences JSON (same key, different path) |+| Edge | ✅ Full | ✅ Yes | Edit Preferences JSON (same key, different path) |+| Safari | ✅ Full (`do JavaScript`) | ✅ Yes | UI automation only — `defaults write` broken |+| Arc | ⚠️ No return values | No toggle | No reliable path |+| Firefox | ❌ Not supported | N/A | N/A |### Chrome / Brave / Edge — Preferences JSON@@ -589,35 +635,31 @@ after `insert_text` didn't stick, or the editor needs real keydownevents.Preconditions (shared with `insert_text`):+- The target element must already have DOM focus — click it first(`page(click_element)` or `execute_javascript` with `el.click()` /`el.focus()`).-- The browser needs a live CDP port. Two ways to get one:- - **Dedicated automation profile** — `launch_app`'s- `cdp_debugging_port` appends `--remote-debugging-port=N`, but- Chrome refuses to open that port on what it considers its- default data directory — confirmed this refusal happens even- when you pass `--user-data-dir` explicitly pointing at that same- default path; only a genuinely different path satisfies the- check. So this route needs `additional_arguments:- ["--user-data-dir=<some other path>"]` too — a separate profile- without the user's existing logins/session.+- The browser needs a live CDP port. Two supported sources are:+ - **Driver-owned automation profile** — call the approved+ `browser_prepare` operation with `allow_launch:true` and an+ `isolated_new` or `isolated_named` profile. It launches a separate+ process and returns `prepared_pid`. It never copies or modifies the+ user's normal profile.- **The user's real, already-logged-in Chrome** — have them open`chrome://inspect/#remote-debugging` and check "Allow remote- debugging". Confirmed this opens a CDP port on the *default*+ debugging". Confirmed this opens a CDP port on the _default_profile without relaunching anything, but it doesn't serve the- classic `/json` HTTP discovery (confirmed `/json/version` returns- 404) — `insert_text`/`type_keystrokes` fall back automatically to+ classic `/json` HTTP discovery (confirmed `/json/version` returns 404) — `insert_text`/`type_keystrokes` fall back automatically toconnecting straight to the browser-level `ws://host:port/devtools/browser`endpoint and `Target.attachToTarget{flatten:true}` in that case,but since that path can't be auto-discovered via `pid` + `lsof`(no working `/json` to validate against), pass the port explicitly- via `cdp_port` (commonly 9222, but whatever the chrome://inspect+ via the legacy `cdp_port` argument (commonly 9222, but whatever the chrome://inspectpage shows) — auto-discovery only works for the dedicated-profileroute above.**This can't be made fully unattended, and the popup fires moreoften than you'd think.** Chrome shows a live "Allow remote- debugging?" confirmation on every *new* WebSocket connection to the+ debugging?" confirmation on every _new_ WebSocket connection to thebrowser endpoint — not once per Chrome process, and NOT something asaved preference can skip. Confirmed by testing live, twice, withdifferent results depending on what actually opened a new socket:@@ -626,25 +668,25 @@ Preconditions (shared with `insert_text`):call, 3 for 3** — worse than "once per session."- `CdpSessionCache` (this platform's backend) fixes that: it cachesone open connection per port and reuses it across calls,- re-attaching to a different tab on the *same* connection via+ re-attaching to a different tab on the _same_ connection via`Target.getTargets`/`Target.attachToTarget` when`target_url_contains` points somewhere new — flattened-modere-attach doesn't open a new socket, so it doesn't re-prompt.Confirmed live: after the first approval, two more calls (typinginto the same tab) went through silently in well under a second.- - The popup *does* come back the moment the cache has to open a+ - The popup _does_ come back the moment the cache has to open agenuinely new connection — confirmed by closing the tab thecached session was attached to: the next call took ~2s (evict +reconnect) and needed a fresh click. Also expect this after afull Chrome restart, or a daemon restart (the cache is in-memory,not persisted).- Net: one click to start, silent after that for as long as the- browser and the daemon both stay up and you're re-attaching rather- than reconnecting — but don't promise a caller "no more prompts,- ever" for a long session that outlives either of those.- If no CDP port is found (and none was given explicitly), both- actions fail fast with an actionable error rather than silently- no-op'ing.+ Net: one click to start, silent after that for as long as the+ browser and the daemon both stay up and you're re-attaching rather+ than reconnecting — but don't promise a caller "no more prompts,+ ever" for a long session that outlives either of those.+ If no CDP port is found (and none was given explicitly), both+ actions fail fast with an actionable error rather than silently+ no-op'ing.- Multi-tab ambiguity: with more than one tab open, both actions acton whichever tab is found first — not necessarily the one youmean — unless you pass `target_url_contains` (a substring to matchdiff --git a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.tomlindex 35ae60937a..a3d3458473 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml+++ b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml@@ -23,6 +23,16 @@ regorus = { version = "0.10.1", optional = true }# helpers extracted from `platform-{macos,windows,linux}/src/capture.rs` so# all three platforms call the same code path.image = { workspace = true }+# Used by the `browser` module's pooled CDP browser-endpoint WebSocket.+# Same versions platform-macos already depends on, to avoid duplicate+# crate versions in the workspace graph. No TLS features: the endpoint+# contract is loopback ws:// only.+tokio-tungstenite = "0.24"+futures-util = "0.3"+uuid = { workspace = true }++[target.'cfg(unix)'.dependencies]+libc = "0.2"# Used by `cursor_sampler::sample_cursor` to poll the OS mouse position# during video recording. Same version as platform-windows uses to avoiddiff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rsnew file mode 100644index 0000000000..6c6102f197--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/approval.rs@@ -0,0 +1,181 @@+//! Explicit approval evidence for mutating browser preparation.+//!+//! MCP-host approval is carried on an internal transport marker. Direct CLI+//! and raw callers instead use a short-lived, single-use artifact minted by+//! the interactive `browser-approve` command. Public tool arguments never+//! treat a Boolean as consent.++use std::fs::{self, OpenOptions};+use std::io::Write;+use std::path::PathBuf;+use std::time::{Duration, SystemTime, UNIX_EPOCH};++use serde::{Deserialize, Serialize};+use uuid::Uuid;++use super::platform::{PrepareProfile, PrepareProfileMode};+use super::refusal::{BrowserRefusal, BrowserRefusalCode};++pub const MCP_HOST_APPROVAL_ARG: &str = "_cua_browser_prepare_mcp_host_approved";+pub const MAX_APPROVAL_TTL: Duration = Duration::from_secs(5 * 60);++#[derive(Debug, Serialize, Deserialize)]+struct ApprovalArtifact {+ schema: String,+ token: String,+ pid: i64,+ profile: PrepareProfile,+ expires_unix_ms: u128,+}++fn refusal(message: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(BrowserRefusalCode::BrowserConsentRequired, message)+}++fn now_unix_ms() -> Result<u128, BrowserRefusal> {+ SystemTime::now()+ .duration_since(UNIX_EPOCH)+ .map(|duration| duration.as_millis())+ .map_err(|_| refusal("the system clock cannot validate browser preparation approval"))+}++fn approval_root() -> PathBuf {+ std::env::temp_dir().join("cua-driver-browser-approvals-v1")+}++fn artifact_path(token: &str) -> Result<PathBuf, BrowserRefusal> {+ let parsed = Uuid::parse_str(token)+ .map_err(|_| refusal("browser preparation approval token is malformed or expired"))?;+ Ok(approval_root().join(format!("{parsed}.json")))+}++pub fn validate_profile(profile: &PrepareProfile) -> Result<(), BrowserRefusal> {+ match profile.mode {+ PrepareProfileMode::IsolatedNew => {+ if profile.name.is_some() {+ return Err(refusal("profile.name is not valid with mode=isolated_new"));+ }+ }+ PrepareProfileMode::IsolatedNamed => {+ let Some(name) = profile.name.as_deref() else {+ return Err(refusal("profile.name is required with mode=isolated_named"));+ };+ if name.is_empty()+ || name.len() > 64+ || !name+ .bytes()+ .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))+ {+ return Err(refusal(+ "profile.name must be 1-64 ASCII letters, digits, '-' or '_'",+ ));+ }+ }+ }+ Ok(())+}++/// Mint approval evidence after an interactive caller has confirmed the exact+/// operation. The returned token is the only public value passed to the tool.+pub fn mint_prepare_approval(pid: i64, profile: PrepareProfile) -> Result<String, BrowserRefusal> {+ validate_profile(&profile)?;+ let token = Uuid::new_v4().to_string();+ let root = approval_root();+ fs::create_dir_all(&root)+ .map_err(|error| refusal(format!("could not create approval directory: {error}")))?;+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ fs::set_permissions(&root, fs::Permissions::from_mode(0o700))+ .map_err(|error| refusal(format!("could not restrict approval directory: {error}")))?;+ }++ let artifact = ApprovalArtifact {+ schema: "cua-browser-prepare-approval-v1".to_owned(),+ token: token.clone(),+ pid,+ profile,+ expires_unix_ms: now_unix_ms()? + MAX_APPROVAL_TTL.as_millis(),+ };+ let path = artifact_path(&token)?;+ let mut options = OpenOptions::new();+ options.write(true).create_new(true);+ #[cfg(unix)]+ {+ use std::os::unix::fs::OpenOptionsExt;+ options.mode(0o600);+ }+ let mut file = options+ .open(path)+ .map_err(|error| refusal(format!("could not create approval artifact: {error}")))?;+ let bytes = serde_json::to_vec(&artifact)+ .map_err(|error| refusal(format!("could not encode approval artifact: {error}")))?;+ file.write_all(&bytes)+ .and_then(|_| file.sync_all())+ .map_err(|error| refusal(format!("could not persist approval artifact: {error}")))?;+ Ok(token)+}++/// Consume approval evidence. The artifact is removed before any semantic+/// validation so malformed, mismatched, and expired attempts are single-use.+pub fn consume_prepare_approval(+ token: &str,+ pid: i64,+ profile: &PrepareProfile,+) -> Result<(), BrowserRefusal> {+ validate_profile(profile)?;+ let path = artifact_path(token)?;+ let bytes = fs::read(&path)+ .map_err(|_| refusal("browser preparation approval token is missing or expired"))?;+ fs::remove_file(&path)+ .map_err(|error| refusal(format!("could not consume approval artifact: {error}")))?;+ let artifact: ApprovalArtifact = serde_json::from_slice(&bytes)+ .map_err(|_| refusal("browser preparation approval artifact is invalid"))?;+ if artifact.schema != "cua-browser-prepare-approval-v1"+ || artifact.token != token+ || artifact.pid != pid+ || artifact.profile != *profile+ || artifact.expires_unix_ms < now_unix_ms()?+ {+ return Err(refusal(+ "browser preparation approval does not match this pid/profile request or has expired",+ ));+ }+ Ok(())+}++#[cfg(test)]+mod tests {+ use super::*;++ fn named(name: &str) -> PrepareProfile {+ PrepareProfile {+ mode: PrepareProfileMode::IsolatedNamed,+ name: Some(name.to_owned()),+ }+ }++ #[test]+ fn approval_is_bound_and_single_use() {+ let profile = named("approval-test");+ let token = mint_prepare_approval(42, profile.clone()).unwrap();+ consume_prepare_approval(&token, 42, &profile).unwrap();+ assert!(consume_prepare_approval(&token, 42, &profile).is_err());+ }++ #[test]+ fn mismatch_consumes_the_artifact() {+ let profile = named("approval-mismatch");+ let token = mint_prepare_approval(42, profile.clone()).unwrap();+ assert!(consume_prepare_approval(&token, 7, &profile).is_err());+ assert!(consume_prepare_approval(&token, 42, &profile).is_err());+ }++ #[test]+ fn named_profile_is_path_safe() {+ for name in ["", "../Default", "a/b", "with space", "."] {+ assert!(validate_profile(&named(name)).is_err(), "accepted {name:?}");+ }+ validate_profile(&named("research_2026-07")).unwrap();+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/binding.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/binding.rsnew file mode 100644index 0000000000..842078bddf--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/binding.rs@@ -0,0 +1,432 @@+//! Native-window ↔ CDP-target correlation (pure, side-effect free).+//!+//! The native entrypoint is `pid + window_id`. CDP exposes page targets+//! (tabs), each mappable to a CDP window via `Browser.getWindowForTarget`+//! + `Browser.getWindowBounds`. Correlation is unique-or-refuse:+//!+//! 1. Collapse page targets to one representative per proven CDP window;+//! tabs are not independent native-window candidates.+//! 2. Filter candidates whose CDP window bounds match the native bounds+//! within `tolerance` device pixels.+//! 3. Exactly one bounds match → **Exact** binding.+//! 4. Multiple distinct CDP windows remain ambiguous. Maximized windows+//! can share bounds, so titles are not strong enough to choose one.+//! 5. No bounds match → a unique title match degrades to **Heuristic**+//! (read-only); otherwise **None**.++use super::types::{BindingQuality, NativeWindowInfo, Rect};++/// One CDP page target with its resolved CDP window geometry.+#[derive(Debug, Clone, PartialEq)]+pub struct CdpWindowCandidate {+ pub cdp_target_id: String,+ /// Absent only when an embedded Chromium endpoint does not implement+ /// Browser.getWindowForTarget. Core may use the bounded single-page /+ /// single-native-window fallback in that case.+ pub cdp_window_id: Option<i64>,+ pub title: String,+ pub url: String,+ pub bounds: Option<Rect>,+}++/// Outcome of correlating one native window against the CDP candidates.+#[derive(Debug, Clone, PartialEq)]+pub enum BindingOutcome {+ Bound {+ candidate: CdpWindowCandidate,+ quality: BindingQuality,+ },+ /// Multiple candidates survived; refuse rather than guess. Carries+ /// only the count so native CDP target ids never escape the core.+ Ambiguous(usize),+ /// Nothing correlates at all.+ None,+}++/// Select the bounded fallback for embedded Chromium endpoints that omit the+/// Browser window APIs. Exactness comes from two independent cardinality+/// proofs: one CDP page and exactly one native window for the endpoint owner.+pub fn embedded_single_page_candidate(+ candidates: &[CdpWindowCandidate],+ is_only_exact_native_window: Option<bool>,+) -> Option<CdpWindowCandidate> {+ let candidate = candidates.first()?;+ (candidates.len() == 1+ && candidate.cdp_window_id.is_none()+ && candidate.bounds.is_none()+ && is_only_exact_native_window == Some(true))+ .then(|| candidate.clone())+}++/// Select the only CDP window when the platform independently attests that the+/// endpoint owner has exactly one native window. This remains exact when a+/// tiling compositor overrides Chromium's requested bounds: one owned native+/// window and one owned CDP window form a proven one-to-one mapping.+pub fn cardinality_exact_candidate(+ native_title: &str,+ candidates: &[CdpWindowCandidate],+ is_only_exact_native_window: Option<bool>,+) -> Option<CdpWindowCandidate> {+ if is_only_exact_native_window != Some(true) {+ return None;+ }+ if let Some(candidate) = embedded_single_page_candidate(candidates, Some(true)) {+ return Some(candidate);+ }+ let representatives = window_representatives(native_title, candidates);+ (representatives.len() == 1 && representatives[0].cdp_window_id.is_some())+ .then(|| representatives[0].clone())+}++/// Whether the native window title plausibly displays this tab's title.+/// Browsers render "<tab title> - <product>", so containment (not+/// equality) is the tie-break; empty tab titles never match.+fn title_matches(native_title: &str, candidate_title: &str) -> bool {+ !candidate_title.is_empty() && native_title.contains(candidate_title)+}++/// Reduce page targets to one representative per proven CDP window.+/// The representative prefers a tab title displayed by the native+/// window, but its target id is only a handle for the selected window;+/// the engine retains every original page target as a tab capability.+/// Candidates without a CDP window id remain independent because they+/// cannot prove they share a native surface.+fn window_representatives(+ native_title: &str,+ candidates: &[CdpWindowCandidate],+) -> Vec<CdpWindowCandidate> {+ let mut representatives: Vec<CdpWindowCandidate> = Vec::new();+ for candidate in candidates {+ let Some(window_id) = candidate.cdp_window_id else {+ representatives.push(candidate.clone());+ continue;+ };+ match representatives+ .iter_mut()+ .find(|existing| existing.cdp_window_id == Some(window_id))+ {+ Some(existing)+ if !title_matches(native_title, &existing.title)+ && title_matches(native_title, &candidate.title) =>+ {+ *existing = candidate.clone();+ }+ Some(_) => {}+ None => representatives.push(candidate.clone()),+ }+ }+ representatives+}++/// Correlate `native` against `candidates` with unique-or-refuse+/// semantics. `tolerance` is in device pixels (see [`Rect::approx_eq`]).+pub fn correlate(+ native: &NativeWindowInfo,+ candidates: &[CdpWindowCandidate],+ tolerance: f64,+) -> BindingOutcome {+ let candidates = window_representatives(&native.title, candidates);+ let bounds_matches: Vec<&CdpWindowCandidate> = if native.geometry_exact {+ candidates+ .iter()+ .filter(|c| {+ c.bounds+ .is_some_and(|bounds| bounds.approx_eq(&native.bounds, tolerance))+ })+ .collect()+ } else {+ Vec::new()+ };++ match bounds_matches.len() {+ 1 if bounds_matches[0].cdp_window_id.is_some() => BindingOutcome::Bound {+ candidate: bounds_matches[0].clone(),+ quality: BindingQuality::Exact,+ },+ 1 => BindingOutcome::None,+ 0 => {+ // No geometric evidence — title-only fallback is heuristic+ // and therefore read-only downstream.+ let title_hits: Vec<&CdpWindowCandidate> = candidates+ .iter()+ .filter(|c| title_matches(&native.title, &c.title))+ .collect();+ match title_hits.len() {+ 1 => BindingOutcome::Bound {+ candidate: title_hits[0].clone(),+ quality: BindingQuality::Heuristic,+ },+ count if count > 1 => BindingOutcome::Ambiguous(count),+ _ => BindingOutcome::None,+ }+ }+ _ => BindingOutcome::Ambiguous(bounds_matches.len()),+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::browser::types::{NativeOwnershipMethod, NativeOwnershipProof};++ fn native(title: &str, bounds: Rect) -> NativeWindowInfo {+ NativeWindowInfo {+ pid: 42,+ window_id: 7,+ title: title.into(),+ bounds,+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: 42,+ detail: None,+ },+ }+ }++ fn cand(id: &str, title: &str, bounds: Rect) -> CdpWindowCandidate {+ CdpWindowCandidate {+ cdp_target_id: id.into(),+ cdp_window_id: Some(1),+ title: title.into(),+ url: format!("https://example.test/{id}"),+ bounds: Some(bounds),+ }+ }++ fn embedded_cand(id: &str, title: &str) -> CdpWindowCandidate {+ CdpWindowCandidate {+ cdp_target_id: id.into(),+ cdp_window_id: None,+ title: title.into(),+ url: format!("file:///fixture/{id}"),+ bounds: None,+ }+ }++ const B: Rect = Rect {+ x: 100.0,+ y: 50.0,+ width: 1200.0,+ height: 800.0,+ };+ const OTHER: Rect = Rect {+ x: 900.0,+ y: 400.0,+ width: 640.0,+ height: 480.0,+ };++ #[test]+ fn unique_bounds_match_is_exact() {+ let n = native("Docs - Chrome", B);+ let cands = [cand("t1", "Docs", B), cand("t2", "Mail", OTHER)];+ match correlate(&n, &cands, 4.0) {+ BindingOutcome::Bound { candidate, quality } => {+ assert_eq!(candidate.cdp_target_id, "t1");+ assert_eq!(quality, BindingQuality::Exact);+ }+ other => panic!("expected exact bound, got {other:?}"),+ }+ }++ #[test]+ fn bounds_within_tolerance_still_match() {+ let n = native("Docs - Chrome", B);+ let shifted = Rect {+ x: B.x + 3.0,+ y: B.y - 3.0,+ ..B+ };+ let cands = [cand("t1", "Docs", shifted)];+ assert!(matches!(+ correlate(&n, &cands, 4.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Exact,+ ..+ }+ ));+ // Same shift with a tighter tolerance → no geometric evidence,+ // and the title still rescues it as heuristic only.+ assert!(matches!(+ correlate(&n, &cands, 2.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Heuristic,+ ..+ }+ ));+ }++ #[test]+ fn outer_window_rect_restores_exact_match_when_visible_frame_is_inset() {+ let outer = B;+ let visible_frame = Rect {+ x: B.x + 8.0,+ y: B.y,+ width: B.width - 16.0,+ height: B.height - 8.0,+ };+ let candidate = cand("t1", "Docs", outer);++ assert!(matches!(+ correlate(+ &native("Docs - Chrome", visible_frame),+ &[candidate.clone()],+ 8.0+ ),+ BindingOutcome::Bound {+ quality: BindingQuality::Heuristic,+ ..+ }+ ));+ assert!(matches!(+ correlate(&native("Docs - Chrome", outer), &[candidate], 8.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Exact,+ ..+ }+ ));+ }++ #[test]+ fn multiple_tabs_in_one_window_are_one_exact_candidate() {+ // Multiple page targets are tabs, not competing native windows.+ let n = native("Checkout — Shop - Chrome", B);+ let cands = [cand("t1", "Checkout — Shop", B), cand("t2", "Cart", B)];+ match correlate(&n, &cands, 4.0) {+ BindingOutcome::Bound { candidate, quality } => {+ assert_eq!(candidate.cdp_target_id, "t1");+ assert_eq!(quality, BindingQuality::Exact);+ }+ other => panic!("expected tie-broken exact bound, got {other:?}"),+ }+ }++ #[test]+ fn same_title_tabs_in_one_window_are_still_one_exact_candidate() {+ let n = native("Checkout - Chrome", B);+ let cands = [cand("t1", "Checkout", B), cand("t2", "Checkout", B)];+ assert!(matches!(+ correlate(&n, &cands, 4.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Exact,+ ..+ }+ ));+ }++ #[test]+ fn distinct_maximized_windows_with_shared_bounds_are_ambiguous() {+ let n = native("Docs - Chrome", B);+ let mut other_window = cand("t2", "Docs", B);+ other_window.cdp_window_id = Some(2);+ let cands = [cand("t1", "Mail", B), other_window];+ assert_eq!(correlate(&n, &cands, 4.0), BindingOutcome::Ambiguous(2));+ }++ #[test]+ fn geometry_without_a_cdp_window_id_is_not_exact() {+ let n = native("Docs - Chrome", B);+ let mut candidate = cand("t1", "Docs", B);+ candidate.cdp_window_id = None;+ assert_eq!(correlate(&n, &[candidate], 4.0), BindingOutcome::None);+ }++ #[test]+ fn no_bounds_match_with_unique_title_is_heuristic() {+ let n = native("Docs - Chrome", B);+ let cands = [cand("t1", "Docs", OTHER), cand("t2", "Mail", OTHER)];+ assert!(matches!(+ correlate(&n, &cands, 4.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Heuristic,+ ..+ }+ ));+ }++ #[test]+ fn singleton_native_and_cdp_windows_are_exact_by_cardinality() {+ let candidates = [cand("t1", "Docs", B), cand("t2", "Mail", B)];+ let selected = cardinality_exact_candidate("Docs - Chrome", &candidates, Some(true))+ .expect("one native window and one CDP window must correlate");+ assert_eq!(selected.cdp_window_id, Some(1));+ assert_eq!(selected.cdp_target_id, "t1");+ assert!(cardinality_exact_candidate("Docs - Chrome", &candidates, Some(false)).is_none());+ }++ #[test]+ fn cardinality_never_picks_between_multiple_cdp_windows() {+ let mut second = cand("t2", "Docs", B);+ second.cdp_window_id = Some(2);+ assert!(cardinality_exact_candidate(+ "Docs - Chrome",+ &[cand("t1", "Docs", B), second],+ Some(true)+ )+ .is_none());+ }++ #[test]+ fn duplicate_title_only_matches_are_ambiguous() {+ let n = native("Docs - Chrome", B);+ let mut second = cand("t2", "Docs", OTHER);+ second.cdp_window_id = Some(2);+ assert_eq!(+ correlate(&n, &[cand("t1", "Docs", OTHER), second], 4.0),+ BindingOutcome::Ambiguous(2)+ );+ }++ #[test]+ fn unattested_geometry_never_mints_an_exact_binding() {+ let mut n = native("Docs - Chrome", B);+ n.geometry_exact = false;+ let cands = [cand("t1", "Docs", B)];+ assert!(matches!(+ correlate(&n, &cands, 4.0),+ BindingOutcome::Bound {+ quality: BindingQuality::Heuristic,+ ..+ }+ ));+ }++ #[test]+ fn embedded_fallback_requires_both_singleton_proofs() {+ let one = [embedded_cand("t1", "Fixture")];+ assert_eq!(+ embedded_single_page_candidate(&one, Some(true))+ .map(|candidate| candidate.cdp_target_id),+ Some("t1".to_owned())+ );+ assert!(embedded_single_page_candidate(&one, Some(false)).is_none());+ assert!(embedded_single_page_candidate(&one, None).is_none());+ let two = [embedded_cand("t1", "Fixture"), embedded_cand("t2", "Other")];+ assert!(embedded_single_page_candidate(&two, Some(true)).is_none());+ assert!(embedded_single_page_candidate(&[cand("t1", "Fixture", B)], Some(true)).is_none());+ }++ #[test]+ fn no_evidence_at_all_is_none() {+ let n = native("Spreadsheet - Chrome", B);+ let cands = [cand("t1", "Docs", OTHER), cand("t2", "Mail", OTHER)];+ assert_eq!(correlate(&n, &cands, 4.0), BindingOutcome::None);+ assert_eq!(correlate(&n, &[], 4.0), BindingOutcome::None);+ }++ #[test]+ fn empty_candidate_titles_never_title_match() {+ // An about:blank tab with an empty title must not win a+ // containment tie-break (every string contains "").+ let n = native("Docs - Chrome", B);+ let cands = [cand("t1", "", B), cand("t2", "Docs", B)];+ match correlate(&n, &cands, 4.0) {+ BindingOutcome::Bound { candidate, quality } => {+ assert_eq!(candidate.cdp_target_id, "t2");+ assert_eq!(quality, BindingQuality::Exact);+ }+ other => panic!("expected t2 exact, got {other:?}"),+ }+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rsnew file mode 100644index 0000000000..53abcf1180--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/cdp_ws.rs@@ -0,0 +1,462 @@+//! Pooled CDP browser-endpoint WebSocket client.+//!+//! v2 demultiplexer: a dedicated reader task owns the receive half of+//! each connection and routes frames by `id` to per-call oneshot+//! channels, while unsolicited events fan out to [`CdpConnection::subscribe`]+//! subscribers in arrival order. This replaces v1's hold-the-socket+//! serialization and is what makes `Target.*` auto-attach (OOPIF child+//! sessions) usable: events emitted before a command's reply are+//! guaranteed to be queued on a subscriber created before the call by+//! the time that call returns.+//!+//! Only loopback `ws://` URLs are accepted: the endpoint is a local+//! browser the platform adapter proved we own, never a remote service.++use std::collections::HashMap;+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};+use std::sync::{Arc, Mutex as StdMutex};+use std::time::Duration;++use futures_util::stream::{SplitSink, SplitStream};+use futures_util::{SinkExt, StreamExt};+use serde_json::Value;+use tokio::net::TcpStream;+use tokio::sync::{mpsc, oneshot, Mutex};+use tokio_tungstenite::tungstenite::Message;+use tokio_tungstenite::{MaybeTlsStream, WebSocketStream};++type WsStream = WebSocketStream<MaybeTlsStream<TcpStream>>;++const CALL_TIMEOUT: Duration = Duration::from_secs(20);+const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);++/// Validate that `url` is a plain-`ws` loopback WebSocket URL.+/// Anything else — `wss`, remote hosts, hostnames that merely *resolve*+/// to loopback — is rejected; the endpoint contract is a literal+/// loopback address handed over by the platform adapter.+pub fn validate_loopback_ws_url(url: &str) -> Result<(), String> {+ let rest = url+ .strip_prefix("ws://")+ .ok_or_else(|| format!("endpoint URL must use the ws:// scheme: {url}"))?;+ let authority = rest.split('/').next().unwrap_or("");+ let host = if let Some(bracketed) = authority.strip_prefix('[') {+ // [::1]:9222 form.+ bracketed.split(']').next().unwrap_or("")+ } else {+ authority.rsplit_once(':').map_or(authority, |(h, _)| h)+ };+ match host {+ "127.0.0.1" | "::1" | "localhost" => Ok(()),+ other => Err(format!("endpoint host {other:?} is not loopback: {url}")),+ }+}++/// An unsolicited CDP event as delivered by the browser endpoint.+#[derive(Debug, Clone)]+pub struct CdpEvent {+ pub method: String,+ /// The (parent) session the event is scoped to under flattened+ /// sessions, when present.+ pub session_id: Option<String>,+ pub params: Value,+}++/// What the reader routed back for one in-flight call.+enum CallOutcome {+ Result(Value),+ Error { code: Option<i64>, message: String },+}++/// State shared between the caller side and the reader task.+struct Demux {+ pending: StdMutex<HashMap<u64, oneshot::Sender<CallOutcome>>>,+ subscribers: StdMutex<Vec<mpsc::UnboundedSender<CdpEvent>>>,+ closed: AtomicBool,+}++impl Demux {+ fn close(&self) {+ self.closed.store(true, Ordering::SeqCst);+ // Dropping the senders wakes every pending caller with a recv+ // error, which `call` reports as a closed socket.+ self.pending.lock().unwrap().clear();+ self.subscribers.lock().unwrap().clear();+ }+}++/// The reader task: routes replies by id, fans events out to+/// subscribers, and fails everything on socket close.+async fn read_loop(mut read: SplitStream<WsStream>, demux: Arc<Demux>) {+ loop {+ let frame = match read.next().await {+ Some(Ok(frame)) => frame,+ Some(Err(_)) | None => break,+ };+ let text = match frame {+ Message::Text(t) => t,+ Message::Close(_) => break,+ _ => continue,+ };+ let v: Value = match serde_json::from_str(&text) {+ Ok(v) => v,+ Err(_) => continue,+ };+ if let Some(id) = v.get("id").and_then(Value::as_u64) {+ let Some(tx) = demux.pending.lock().unwrap().remove(&id) else {+ continue; // reply to a timed-out or unknown call+ };+ let outcome = match v.get("error") {+ Some(err) => CallOutcome::Error {+ code: err.get("code").and_then(Value::as_i64),+ message: err+ .get("message")+ .and_then(Value::as_str)+ .unwrap_or("unknown CDP error")+ .to_owned(),+ },+ None => CallOutcome::Result(v.get("result").cloned().unwrap_or(Value::Null)),+ };+ let _ = tx.send(outcome);+ } else if let Some(method) = v.get("method").and_then(Value::as_str) {+ let event = CdpEvent {+ method: method.to_owned(),+ session_id: v+ .get("sessionId")+ .and_then(Value::as_str)+ .map(str::to_owned),+ params: v.get("params").cloned().unwrap_or(Value::Null),+ };+ demux+ .subscribers+ .lock()+ .unwrap()+ .retain(|s| s.send(event.clone()).is_ok());+ }+ }+ demux.close();+}++/// A single browser-endpoint connection.+pub struct CdpConnection {+ writer: Mutex<SplitSink<WsStream, Message>>,+ demux: Arc<Demux>,+ next_id: AtomicU64,+ reader: tokio::task::JoinHandle<()>,+}++impl Drop for CdpConnection {+ fn drop(&mut self) {+ self.reader.abort();+ self.demux.close();+ }+}++impl CdpConnection {+ pub async fn connect(ws_url: &str) -> anyhow::Result<Self> {+ validate_loopback_ws_url(ws_url).map_err(|e| anyhow::anyhow!(e))?;+ let (ws, _resp) =+ tokio::time::timeout(CONNECT_TIMEOUT, tokio_tungstenite::connect_async(ws_url))+ .await+ .map_err(|_| anyhow::anyhow!("CDP connect to {ws_url} timed out"))??;+ let (write, read) = ws.split();+ let demux = Arc::new(Demux {+ pending: StdMutex::new(HashMap::new()),+ subscribers: StdMutex::new(Vec::new()),+ closed: AtomicBool::new(false),+ });+ let reader = tokio::spawn(read_loop(read, demux.clone()));+ Ok(Self {+ writer: Mutex::new(write),+ demux,+ next_id: AtomicU64::new(1),+ reader,+ })+ }++ /// Whether the reader observed the socket close. A closed connection+ /// never recovers; the pool redials.+ pub fn is_closed(&self) -> bool {+ self.demux.closed.load(Ordering::SeqCst)+ }++ /// Subscribe to unsolicited CDP events. Delivery is in socket+ /// arrival order, and any event the endpoint emitted before a+ /// command's reply is already queued here by the time [`Self::call`]+ /// for that command returns — callers can drain with `try_recv`+ /// deterministically (the Target.setAutoAttach pattern).+ pub fn subscribe(&self) -> mpsc::UnboundedReceiver<CdpEvent> {+ let (tx, rx) = mpsc::unbounded_channel();+ self.demux.subscribers.lock().unwrap().push(tx);+ rx+ }++ /// Issue one CDP command and await its `id`-matched reply.+ /// `session_id` targets an attached (flattened) target session.+ /// Returns the `result` object, or an error carrying the CDP+ /// `error.code` (as `({code})`) and `error.message`.+ pub async fn call(+ &self,+ session_id: Option<&str>,+ method: &str,+ params: Value,+ ) -> anyhow::Result<Value> {+ if self.is_closed() {+ anyhow::bail!("CDP socket closed before {method}");+ }+ let id = self.next_id.fetch_add(1, Ordering::Relaxed);+ let (tx, rx) = oneshot::channel();+ self.demux.pending.lock().unwrap().insert(id, tx);+ // Close can race the initial check. If the reader cleared the+ // pending map just before this insertion, remove the orphaned+ // sender now instead of waiting for the call timeout.+ if self.is_closed() {+ self.demux.pending.lock().unwrap().remove(&id);+ anyhow::bail!("CDP socket closed before {method}");+ }++ let mut msg = serde_json::json!({ "id": id, "method": method, "params": params });+ if let Some(sid) = session_id {+ msg["sessionId"] = Value::String(sid.to_owned());+ }+ let sent = {+ let mut writer = self.writer.lock().await;+ writer.send(Message::Text(msg.to_string())).await+ };+ if let Err(e) = sent {+ self.demux.pending.lock().unwrap().remove(&id);+ anyhow::bail!("CDP send failed during {method}: {e}");+ }++ match tokio::time::timeout(CALL_TIMEOUT, rx).await {+ Err(_) => {+ self.demux.pending.lock().unwrap().remove(&id);+ anyhow::bail!("CDP {method} timed out after {CALL_TIMEOUT:?}")+ }+ Ok(Err(_)) => anyhow::bail!("CDP socket closed during {method}"),+ Ok(Ok(CallOutcome::Result(v))) => Ok(v),+ Ok(Ok(CallOutcome::Error {+ code: Some(code),+ message,+ })) => anyhow::bail!("CDP {method} failed ({code}): {message}"),+ Ok(Ok(CallOutcome::Error {+ code: None,+ message,+ })) => anyhow::bail!("CDP {method} failed: {message}"),+ }+ }+}++/// One pooled connection per endpoint URL.+pub struct CdpPool {+ conns: Mutex<HashMap<String, Arc<CdpConnection>>>,+}++impl CdpPool {+ pub fn new() -> Self {+ Self {+ conns: Mutex::new(HashMap::new()),+ }+ }++ /// Get the pooled connection for `ws_url`, dialing if needed.+ /// A connection whose socket closed is replaced transparently.+ pub async fn get(&self, ws_url: &str) -> anyhow::Result<Arc<CdpConnection>> {+ let mut conns = self.conns.lock().await;+ if let Some(existing) = conns.get(ws_url) {+ if !existing.is_closed() {+ return Ok(existing.clone());+ }+ conns.remove(ws_url);+ }+ let conn = Arc::new(CdpConnection::connect(ws_url).await?);+ conns.insert(ws_url.to_owned(), conn.clone());+ Ok(conn)+ }++ /// Drop a (likely dead) connection so the next call redials.+ pub async fn evict(&self, ws_url: &str) {+ self.conns.lock().await.remove(ws_url);+ }+}++impl Default for CdpPool {+ fn default() -> Self {+ Self::new()+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::browser::mock_cdp::{MockCdpServer, MockEvent, MockReply};+ use serde_json::json;+ use std::sync::Arc as StdArc;++ #[test]+ fn loopback_urls_are_accepted() {+ for ok in [+ "ws://127.0.0.1:9222/devtools/browser/abc",+ "ws://localhost:9222/devtools/browser/abc",+ "ws://[::1]:9222/devtools/browser/abc",+ "ws://127.0.0.1/devtools/browser/abc",+ ] {+ assert!(validate_loopback_ws_url(ok).is_ok(), "{ok}");+ }+ }++ #[test]+ fn non_loopback_and_non_ws_urls_are_rejected() {+ for bad in [+ "wss://127.0.0.1:9222/devtools/browser/abc",+ "http://127.0.0.1:9222/json",+ "ws://10.0.0.5:9222/devtools/browser/abc",+ "ws://example.com:9222/devtools/browser/abc",+ "ws://127.0.0.1.evil.test:9222/x",+ "ws://[fe80::1]:9222/x",+ "",+ ] {+ assert!(validate_loopback_ws_url(bad).is_err(), "{bad}");+ }+ }++ #[tokio::test]+ async fn call_returns_the_id_matched_result() {+ let server = MockCdpServer::start(StdArc::new(|call| {+ assert_eq!(call.method, "Echo.params");+ MockReply::ok(json!({ "echoed": call.params.clone() }))+ }))+ .await;+ let conn = CdpConnection::connect(&server.ws_url()).await.unwrap();+ let result = conn+ .call(None, "Echo.params", json!({ "x": 7 }))+ .await+ .unwrap();+ assert_eq!(result["echoed"]["x"], 7);+ }++ #[tokio::test]+ async fn cdp_error_codes_are_preserved_in_the_message() {+ let server = MockCdpServer::start(StdArc::new(|_| {+ MockReply::method_not_found("Target.setAutoAttach")+ }))+ .await;+ let conn = CdpConnection::connect(&server.ws_url()).await.unwrap();+ let err = conn+ .call(Some("sess-1"), "Target.setAutoAttach", json!({}))+ .await+ .unwrap_err();+ let msg = err.to_string();+ assert!(msg.contains("(-32601)"), "{msg}");+ assert!(msg.contains("Target.setAutoAttach"), "{msg}");+ }++ #[tokio::test]+ async fn events_emitted_before_a_reply_are_drainable_after_the_call() {+ let server = MockCdpServer::start(StdArc::new(|call| {+ if call.method == "Emitter.go" {+ MockReply::ok(json!({})).with_events(vec![+ MockEvent {+ method: "Thing.happened".into(),+ session_id: None,+ params: json!({ "n": 1 }),+ },+ MockEvent {+ method: "Thing.happened".into(),+ session_id: Some("child-sess".into()),+ params: json!({ "n": 2 }),+ },+ ])+ } else {+ MockReply::ok(json!({}))+ }+ }))+ .await;+ let conn = CdpConnection::connect(&server.ws_url()).await.unwrap();+ let mut events = conn.subscribe();+ conn.call(None, "Emitter.go", json!({})).await.unwrap();++ // The demux guarantees pre-reply events are queued: no awaiting.+ let first = events.try_recv().expect("first event queued");+ assert_eq!(first.method, "Thing.happened");+ assert_eq!(first.session_id, None);+ assert_eq!(first.params["n"], 1);+ let second = events.try_recv().expect("second event queued");+ assert_eq!(second.session_id.as_deref(), Some("child-sess"));+ assert_eq!(second.params["n"], 2);+ assert!(events.try_recv().is_err(), "no phantom events");+ }++ #[tokio::test]+ async fn out_of_order_replies_route_to_the_right_callers() {+ // Raw server: read two requests, reply to the SECOND first.+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let port = listener.local_addr().unwrap().port();+ tokio::spawn(async move {+ let (stream, _) = listener.accept().await.unwrap();+ let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();+ let mut ids = Vec::new();+ while ids.len() < 2 {+ if let Some(Ok(Message::Text(text))) = ws.next().await {+ let v: Value = serde_json::from_str(&text).unwrap();+ ids.push(v["id"].as_u64().unwrap());+ }+ }+ for id in ids.iter().rev() {+ let reply = json!({ "id": id, "result": { "for_id": id } });+ ws.send(Message::Text(reply.to_string())).await.unwrap();+ }+ });++ let conn = CdpConnection::connect(&format!("ws://127.0.0.1:{port}/devtools/browser/x"))+ .await+ .unwrap();+ let (a, b) = tokio::join!(+ conn.call(None, "First.call", json!({})),+ conn.call(None, "Second.call", json!({})),+ );+ let (a, b) = (a.unwrap(), b.unwrap());+ assert_ne!(a["for_id"], b["for_id"]);+ assert_eq!(a["for_id"], 1, "first call gets the id-1 payload");+ assert_eq!(b["for_id"], 2, "second call gets the id-2 payload");+ }++ #[tokio::test]+ async fn socket_close_fails_pending_calls_and_marks_the_connection() {+ // Raw server: accept, read one request, close without replying.+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();+ let port = listener.local_addr().unwrap().port();+ tokio::spawn(async move {+ let (stream, _) = listener.accept().await.unwrap();+ let mut ws = tokio_tungstenite::accept_async(stream).await.unwrap();+ let _ = ws.next().await;+ let _ = ws.close(None).await;+ });++ let conn = CdpConnection::connect(&format!("ws://127.0.0.1:{port}/devtools/browser/x"))+ .await+ .unwrap();+ let err = conn+ .call(None, "Never.replies", json!({}))+ .await+ .unwrap_err();+ assert!(err.to_string().contains("closed"), "{err}");+ assert!(conn.is_closed());+ let err = conn.call(None, "After.close", json!({})).await.unwrap_err();+ assert!(err.to_string().contains("closed"), "{err}");+ }++ #[tokio::test]+ async fn pool_replaces_closed_connections() {+ let server = MockCdpServer::start(StdArc::new(|_| MockReply::ok(json!({})))).await;+ let url = server.ws_url();+ let pool = CdpPool::new();+ let first = pool.get(&url).await.unwrap();+ first.demux.close(); // simulate a dead socket+ let second = pool.get(&url).await.unwrap();+ assert!(+ !StdArc::ptr_eq(&first, &second),+ "pool must redial a closed connection"+ );+ second.call(None, "Ping.pong", json!({})).await.unwrap();+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rsnew file mode 100644index 0000000000..7c671f3a34--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/engine.rs@@ -0,0 +1,1340 @@+//! BrowserEngine — the semantic core behind the five browser tools.+//!+//! Owns the target/ref store, the CDP connection pool, and every+//! exact-or-refused decision. The platform adapter is consulted for OS+//! identity only; nothing here trusts a cached fact across a mutation+//! boundary — [`BrowserEngine::revalidate_for_mutation`] re-proves the+//! full chain (process fingerprint → native ownership/bounds → endpoint+//! ownership → CDP target type/window) before any input or navigation,+//! and [`BrowserEngine::frame_session_for_mutation`] additionally+//! re-proves the ref's frame/document identity (frame id + loader id,+//! and for OOPIFs the child target attached beneath the proven tab)+//! before the ref is touched.+//!+//! Snapshot composition (v2 DOM-ref slice):+//! - Shadow DOM is composed into the main-frame walk (`pierce: true`),+//! skipping user-agent shadow roots.+//! - Same-process iframes are walked via `contentDocument` and their+//! refs carry the child frame's identity from `Page.getFrameTree`.+//! - OOPIFs are reached only when `Target.setAutoAttach` capability-+//! tests successfully on the tab's own session; child sessions are+//! accepted solely from `Target.attachedToTarget` events scoped to+//! that session (containment beneath the proven tab target).+//! - Whenever a frame's identity cannot be proven, its content is+//! omitted from the snapshot — never guessed.++use std::collections::HashMap;+use std::sync::{Arc, Weak};++use serde_json::{json, Value};++use crate::session::register_session_end_hook;++use super::binding::{cardinality_exact_candidate, correlate, BindingOutcome, CdpWindowCandidate};+use super::cdp_ws::{CdpConnection, CdpPool};+use super::platform::BrowserPlatform;+use super::prepare::ManagedBrowsers;+use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::store::{+ format_ref, BrowserStore, FrameIdentity, FrameKind, FrameRef, RefEntry, SnapshotRecord,+ TabRecord, TargetRecord,+};+use super::types::{BindingQuality, NativeWindowInfo, OwnedEndpoint, Rect};++/// Bounds tolerance (device pixels) for native ↔ CDP window correlation.+/// Absorbs window-shadow and DIP-rounding differences.+pub const BOUNDS_TOLERANCE_PX: f64 = 8.0;++/// Cap on refs minted per snapshot — keeps snapshots bounded on+/// pathological pages. The truncation is reported in the tool output.+pub const MAX_REFS_PER_SNAPSHOT: usize = 300;++pub struct BrowserEngine {+ pub(crate) platform: Arc<dyn BrowserPlatform>,+ pub(crate) store: BrowserStore,+ pub(crate) pool: CdpPool,+ pub(crate) managed_browsers: ManagedBrowsers,+}++fn refuse(code: BrowserRefusalCode, msg: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(code, msg)+}++fn route_err(context: &str, err: impl std::fmt::Display) -> BrowserRefusal {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("{context}: {err}"),+ )+}++/// Everything revalidation proves before a mutation proceeds. The+/// `record`/`tab` evidence rides along for future callers even though+/// the v1 tools only need the attached connection.+#[allow(dead_code)]+pub(crate) struct ValidatedTab {+ pub conn: Arc<CdpConnection>,+ pub record: TargetRecord,+ pub tab: TabRecord,+ /// Flattened CDP session id attached to the tab's target.+ pub cdp_session: String,+}++/// Whether a CDP error is Chromium's "method not implemented" shape.+/// Everything else stays a hard failure — a transient error must never+/// be misread as a capability gap.+fn is_method_unsupported(error: &anyhow::Error) -> bool {+ error.to_string().contains("(-32601)")+}++/// Result of one tab snapshot: minted refs plus what was (and was not)+/// composable.+pub(crate) struct SnapshotOutcome {+ pub snapshot_id: u64,+ pub url: String,+ pub refs: Vec<(String, RefEntry)>,+ pub truncated: bool,+ pub oopif: OopifStatus,+}++/// Whether OOPIF content could be composed into the snapshot.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub(crate) enum OopifStatus {+ /// Capability proven; `n` child frames were snapshotted beneath the+ /// tab's own session.+ Attached(usize),+ /// The capability (auto-attach and/or frame-tree identity) could+ /// not be proven — OOPIF content was omitted, not guessed.+ Unsupported,+}++impl OopifStatus {+ pub fn as_str(&self) -> &'static str {+ match self {+ Self::Attached(_) => "attached",+ Self::Unsupported => "unsupported",+ }+ }++ pub fn frames(&self) -> usize {+ match self {+ Self::Attached(n) => *n,+ Self::Unsupported => 0,+ }+ }+}++/// One CDP session's local frame tree: frame id → loader id. OOPIF+/// children live in their own sessions and do NOT appear here — each+/// session proves exactly its own frames.+pub(crate) struct LocalFrameTree {+ main_frame_id: String,+ frames: HashMap<String, String>,+}++impl LocalFrameTree {+ fn main_identity(&self) -> FrameIdentity {+ FrameIdentity {+ frame_id: self.main_frame_id.clone(),+ loader_id: self.frames[&self.main_frame_id].clone(),+ }+ }++ fn identity_of(&self, frame_id: &str) -> Option<FrameIdentity> {+ self.frames.get(frame_id).map(|loader_id| FrameIdentity {+ frame_id: frame_id.to_owned(),+ loader_id: loader_id.clone(),+ })+ }++ /// Whether a snapshot-time identity still names a live document.+ fn proves(&self, identity: &FrameIdentity) -> bool {+ self.frames.get(&identity.frame_id) == Some(&identity.loader_id)+ }+}++/// Parse a `Page.getFrameTree` result. Frames missing an id or loader+/// id are omitted (their refs will be omitted / refused, never+/// guessed); a malformed root fails the whole parse.+fn parse_frame_tree(v: &Value) -> Option<LocalFrameTree> {+ fn walk(node: &Value, frames: &mut HashMap<String, String>) -> Option<String> {+ let frame = node.get("frame")?;+ let id = frame.get("id").and_then(Value::as_str)?.to_owned();+ let loader = frame.get("loaderId").and_then(Value::as_str)?.to_owned();+ frames.insert(id.clone(), loader);+ if let Some(children) = node.get("childFrames").and_then(Value::as_array) {+ for child in children {+ let _ = walk(child, frames);+ }+ }+ Some(id)+ }+ let mut frames = HashMap::new();+ let main_frame_id = walk(v.get("frameTree")?, &mut frames)?;+ Some(LocalFrameTree {+ main_frame_id,+ frames,+ })+}++pub(crate) enum FrameTreeError {+ /// The endpoint does not implement `Page.getFrameTree` (embedded+ /// engines). Frame identity is unprovable; composition degrades to+ /// the v1 main-frame-only behavior.+ Unsupported,+ /// A real failure (transport, malformed reply).+ Failed(anyhow::Error),+}++/// One OOPIF child target attached (flattened) beneath a tab session.+pub(crate) struct AttachedChildFrame {+ pub session_id: String,+ pub target_id: String,+ #[allow(dead_code)]+ pub url: String,+}++pub(crate) enum AttachError {+ /// `Target.setAutoAttach` is not implemented on this session.+ Unsupported,+ Failed(anyhow::Error),+}++impl BrowserEngine {+ /// Create the engine and wire session-end cleanup for the+ /// capability store. Platform crates call this once and register+ /// the five tools via `register_browser_tools`.+ pub fn new(platform: Arc<dyn BrowserPlatform>) -> Arc<Self> {+ let engine = Arc::new(Self {+ platform,+ store: BrowserStore::new(),+ pool: CdpPool::new(),+ managed_browsers: Default::default(),+ });+ let weak: Weak<Self> = Arc::downgrade(&engine);+ register_session_end_hook(move |session_id| {+ if let Some(engine) = weak.upgrade() {+ engine.store.remove_session(session_id);+ engine.cleanup_prepared_session(session_id);+ }+ });+ engine+ }++ // ── Endpoint / CDP plumbing ─────────────────────────────────────────++ async fn connect(&self, ws_url: &str) -> Result<Arc<CdpConnection>, BrowserRefusal> {+ match self.pool.get(ws_url).await {+ Ok(conn) => Ok(conn),+ Err(first_err) => {+ // One redial after eviction covers a browser restart on+ // the same port; a second failure is a real refusal.+ self.pool.evict(ws_url).await;+ self.pool+ .get(ws_url)+ .await+ .map_err(|_| route_err("cannot connect to owned DevTools endpoint", first_err))+ }+ }+ }++ /// Discover + ownership-check the endpoint for `pid`.+ async fn owned_endpoint(&self, pid: i64) -> Result<OwnedEndpoint, BrowserRefusal> {+ let endpoint = self+ .platform+ .discover_owned_endpoint(pid)+ .await?+ .ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRequiresSetup,+ format!(+ "no owned DevTools endpoint for pid {pid} — run browser_prepare \+ explicitly to set one up"+ ),+ )+ })?;+ if endpoint.ownership.owner_pid != pid {+ return Err(refuse(+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,+ format!(+ "endpoint ownership proof attributes the endpoint to pid {} but the \+ target is pid {pid}",+ endpoint.ownership.owner_pid+ ),+ ));+ }+ Ok(endpoint)+ }++ /// List page-type CDP targets with their window geometry.+ async fn window_candidates(+ &self,+ conn: &CdpConnection,+ ) -> Result<Vec<CdpWindowCandidate>, BrowserRefusal> {+ let targets = conn+ .call(None, "Target.getTargets", json!({}))+ .await+ .map_err(|e| route_err("Target.getTargets failed", e))?;+ let infos = targets+ .get("targetInfos")+ .and_then(Value::as_array)+ .cloned()+ .ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "Target.getTargets returned no targetInfos array",+ )+ })?;++ let mut out = Vec::new();+ for info in infos {+ if info.get("type").and_then(Value::as_str) != Some("page") {+ continue;+ }+ let url = info+ .get("url")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_owned();+ if url.starts_with("devtools://") {+ continue;+ }+ let target_id = info+ .get("targetId")+ .and_then(Value::as_str)+ .map(str::to_owned)+ .ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "Target.getTargets returned a page without targetId",+ )+ })?;+ let title = info+ .get("title")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_owned();++ let window_geometry = match conn+ .call(+ None,+ "Browser.getWindowForTarget",+ json!({ "targetId": target_id }),+ )+ .await+ {+ Ok(win) => {+ let window_id =+ win.get("windowId").and_then(Value::as_i64).ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "Browser.getWindowForTarget returned no windowId",+ )+ })?;+ let bounds_v = conn+ .call(+ None,+ "Browser.getWindowBounds",+ json!({ "windowId": window_id }),+ )+ .await+ .map_err(|error| {+ route_err(+ "Browser.getWindowBounds failed while proving the native window",+ error,+ )+ })?;+ let b = bounds_v.get("bounds").ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "Browser.getWindowBounds returned no bounds object",+ )+ })?;+ let number = |field: &str| {+ b.get(field).and_then(Value::as_f64).ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("Browser.getWindowBounds returned no numeric {field}"),+ )+ })+ };+ Some((+ window_id,+ Rect::new(+ number("left")?,+ number("top")?,+ number("width")?,+ number("height")?,+ ),+ ))+ }+ // Electron's browser endpoint can omit this Browser-domain+ // method entirely. Retain only that explicit unsupported+ // shape; every transient/vanished-target error fails the+ // whole proof rather than shrinking it to a false unique set.+ Err(error) if is_method_unsupported(&error) => None,+ Err(error) => {+ return Err(route_err(+ "Browser.getWindowForTarget failed while proving the native window",+ error,+ ));+ }+ };+ out.push(CdpWindowCandidate {+ cdp_target_id: target_id,+ cdp_window_id: window_geometry.map(|(window_id, _)| window_id),+ title,+ url,+ bounds: window_geometry.map(|(_, bounds)| bounds),+ });+ }+ Ok(out)+ }++ /// Attach (flattened) to a tab's target and return the CDP session id.+ async fn attach(+ &self,+ conn: &CdpConnection,+ cdp_target_id: &str,+ ) -> Result<String, BrowserRefusal> {+ let attached = conn+ .call(+ None,+ "Target.attachToTarget",+ json!({ "targetId": cdp_target_id, "flatten": true }),+ )+ .await+ .map_err(|e| {+ refuse(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("cannot attach to tab target {cdp_target_id}: {e}"),+ )+ })?;+ attached+ .get("sessionId")+ .and_then(Value::as_str)+ .map(str::to_owned)+ .ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("attach to {cdp_target_id} returned no sessionId"),+ )+ })+ }++ // ── Binding (get_browser_state, pid + window_id mode) ──────────────++ /// Classify, inspect, discover, correlate — and mint a target+ /// capability on success. `session` must already be explicit.+ pub(crate) async fn bind_native(+ &self,+ session: &str,+ pid: i64,+ window_id: u64,+ ) -> Result<(String, TargetRecord), BrowserRefusal> {+ let class = self.platform.classify_browser(pid).await?;+ if !class.is_browser {+ return Err(refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("pid {pid} is not a recognized browser process"),+ ));+ }+ if !class.supports_cdp {+ return Err(refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!(+ "{} does not expose a CDP route in browser-tool v1",+ class.product.as_deref().unwrap_or("this browser")+ ),+ ));+ }++ let native = self.native_window_checked(pid, window_id).await?;+ let endpoint = self.owned_endpoint(pid).await?;+ let fingerprint = self.platform.process_fingerprint(pid).await?;+ let conn = self.connect(&endpoint.ws_url).await?;+ let candidates = self.window_candidates(&conn).await?;++ let correlation = correlate(&native, &candidates, BOUNDS_TOLERANCE_PX);+ let (candidate, quality) = match correlation {+ BindingOutcome::Bound {+ candidate,+ quality: BindingQuality::Exact,+ } => (candidate, BindingQuality::Exact),+ BindingOutcome::Bound {+ candidate,+ quality: BindingQuality::Heuristic,+ } => {+ let only_native_window = self+ .platform+ .is_only_exact_native_window(pid, window_id)+ .await?;+ match cardinality_exact_candidate(&native.title, &candidates, only_native_window) {+ Some(exact) => (exact, BindingQuality::Exact),+ None => (candidate, BindingQuality::Heuristic),+ }+ }+ BindingOutcome::Ambiguous(candidate_count) => {+ return Err(refuse(+ BrowserRefusalCode::BrowserBindingAmbiguous,+ "multiple CDP targets match the native window and the title \+ tie-break cannot pick a unique one",+ )+ .with_detail(json!({ "candidate_count": candidate_count })));+ }+ BindingOutcome::None => {+ let only_native_window = self+ .platform+ .is_only_exact_native_window(pid, window_id)+ .await?;+ match cardinality_exact_candidate(&native.title, &candidates, only_native_window) {+ Some(exact) => (exact, BindingQuality::Exact),+ None => {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!(+ "no CDP target correlates with native window {window_id} of \+ pid {pid} — refusing rather than guessing"+ ),+ ));+ }+ }+ }+ };++ // Tabs = page targets living in the bound CDP window.+ let mut tabs = HashMap::new();+ for c in candidates.iter().filter(|c| match candidate.cdp_window_id {+ Some(window_id) => c.cdp_window_id == Some(window_id),+ None => c.cdp_target_id == candidate.cdp_target_id,+ }) {+ let tab_id = self.store.mint_tab_id();+ tabs.insert(+ tab_id.clone(),+ TabRecord {+ tab_id,+ cdp_target_id: c.cdp_target_id.clone(),+ snapshots: HashMap::new(),+ },+ );+ }++ let record = TargetRecord {+ target_id: String::new(),+ pid,+ window_id,+ ws_url: endpoint.ws_url.clone(),+ endpoint_owner_pid: endpoint.ownership.owner_pid,+ fingerprint,+ native_title: native.title.clone(),+ native_bounds: native.bounds,+ cdp_target_id: candidate.cdp_target_id.clone(),+ cdp_window_id: candidate.cdp_window_id,+ quality,+ tabs,+ };+ let target_id = self.store.mint_target(session, record.clone());+ let record = self.store.get_target(session, &target_id)?;+ Ok((target_id, record))+ }++ async fn native_window_checked(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ let native = self.platform.native_window(pid, window_id).await?;+ if native.ownership.owner_pid != pid {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!(+ "native ownership proof attributes window {window_id} to pid {} — \+ not the requested pid {pid}",+ native.ownership.owner_pid+ ),+ ));+ }+ Ok(native)+ }++ // ── Revalidation (before every mutation) ────────────────────────────++ /// Re-prove the entire binding chain for a mutation on one tab.+ /// Exact-or-refused: heuristic bindings never reach the mutation+ /// path.+ pub(crate) async fn revalidate_for_mutation(+ &self,+ session: &str,+ target_id: &str,+ tab_id: Option<&str>,+ ) -> Result<ValidatedTab, BrowserRefusal> {+ let record = self.store.get_target(session, target_id)?;++ if record.quality != BindingQuality::Exact {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ "this binding is heuristic (title-only) — mutations require an exact \+ bounds- or cardinality-correlated binding",+ ));+ }++ let tab_id = tab_id.ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserTabRequired,+ "this operation requires an explicit tab_id from get_browser_state",+ )+ })?;+ let tab = record.tabs.get(tab_id).cloned().ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("tab {tab_id} is not known for target {target_id}"),+ )+ })?;++ // 1. Process fingerprint — pid reuse / restart detection.+ let fp_now = self.platform.process_fingerprint(record.pid).await?;+ if !record.fingerprint.matches(&fp_now) {+ return Err(refuse(+ BrowserRefusalCode::BrowserBindingStale,+ format!(+ "process fingerprint for pid {} changed since binding — the browser \+ restarted or the pid was reused",+ record.pid+ ),+ ));+ }++ // 2. Native window still exists and is still owned by the pid.+ let native = self+ .native_window_checked(record.pid, record.window_id)+ .await?;++ // 3. Endpoint still owned and unchanged.+ let endpoint = self.owned_endpoint(record.pid).await?;+ if endpoint.ws_url != record.ws_url {+ return Err(refuse(+ BrowserRefusalCode::BrowserBindingStale,+ "the owned DevTools endpoint changed since binding — re-run \+ get_browser_state",+ ));+ }++ // 4. CDP target still a page in the bound CDP window, with either+ // matching geometry or the same singleton cardinality proof.+ let conn = self.connect(&record.ws_url).await?;+ let candidates = self.window_candidates(&conn).await?;+ let live = candidates+ .iter()+ .find(|c| c.cdp_target_id == tab.cdp_target_id)+ .ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("tab {tab_id} no longer has a live CDP page target"),+ )+ })?;+ if let Some(bound_window_id) = record.cdp_window_id {+ if live.cdp_window_id != Some(bound_window_id) {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ "the tab moved to a different browser window since binding",+ ));+ }+ let geometry_matches = live+ .bounds+ .is_some_and(|bounds| bounds.approx_eq(&native.bounds, BOUNDS_TOLERANCE_PX));+ let correlation_still_exact = if geometry_matches {+ true+ } else {+ let only_native_window = self+ .platform+ .is_only_exact_native_window(record.pid, record.window_id)+ .await?;+ cardinality_exact_candidate(&native.title, &candidates, only_native_window)+ .is_some_and(|candidate| candidate.cdp_window_id == Some(bound_window_id))+ };+ if !correlation_still_exact {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ "CDP window no longer has an exact geometry or singleton-cardinality \+ correlation with the native window — refusing to mutate it",+ ));+ }+ } else if candidates.len() != 1+ || live.cdp_window_id.is_some()+ || self+ .platform+ .is_only_exact_native_window(record.pid, record.window_id)+ .await?+ != Some(true)+ {+ return Err(refuse(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ "the embedded browser is no longer provably single-page and single-window",+ ));+ }++ let cdp_session = self.attach(&conn, &tab.cdp_target_id).await?;+ Ok(ValidatedTab {+ conn,+ record,+ tab,+ cdp_session,+ })+ }++ // ── Frame identity / OOPIF plumbing ─────────────────────────────────++ /// Fetch and parse one session's local frame tree.+ async fn local_frame_tree(+ &self,+ conn: &CdpConnection,+ cdp_session: &str,+ ) -> Result<LocalFrameTree, FrameTreeError> {+ match conn+ .call(Some(cdp_session), "Page.getFrameTree", json!({}))+ .await+ {+ Ok(v) => parse_frame_tree(&v).ok_or_else(|| {+ FrameTreeError::Failed(anyhow::anyhow!(+ "Page.getFrameTree returned a malformed frame tree"+ ))+ }),+ Err(e) if is_method_unsupported(&e) => Err(FrameTreeError::Unsupported),+ Err(e) => Err(FrameTreeError::Failed(e)),+ }+ }++ /// Capability-tested OOPIF discovery: enable flattened auto-attach+ /// on `tab_session` and collect the iframe children Chromium+ /// announces for existing targets *before* the setAutoAttach ack.+ ///+ /// Containment: only `Target.attachedToTarget` events scoped to+ /// this exact tab session are honored, and only `type == "iframe"`+ /// targets — a child announced on any other session (or a popup+ /// page target) is ignored. Each operation attaches its own fresh+ /// tab session, so the parent-session filter is per-operation+ /// unique even on the shared pooled connection.+ async fn attached_iframe_children(+ &self,+ conn: &CdpConnection,+ tab_session: &str,+ ) -> Result<Vec<AttachedChildFrame>, AttachError> {+ // Subscribe BEFORE issuing the command so pre-ack events are+ // guaranteed to be queued when the call returns.+ let mut events = conn.subscribe();+ match conn+ .call(+ Some(tab_session),+ "Target.setAutoAttach",+ json!({ "autoAttach": true, "waitForDebuggerOnStart": false, "flatten": true }),+ )+ .await+ {+ Ok(_) => {}+ Err(e) if is_method_unsupported(&e) => return Err(AttachError::Unsupported),+ Err(e) => return Err(AttachError::Failed(e)),+ }+ let mut out = Vec::new();+ while let Ok(event) = events.try_recv() {+ if event.method != "Target.attachedToTarget" {+ continue;+ }+ if event.session_id.as_deref() != Some(tab_session) {+ continue; // not contained beneath the proven tab session+ }+ let info = &event.params["targetInfo"];+ if info["type"].as_str() != Some("iframe") {+ continue; // OOPIF slice covers iframes only, never popups/workers+ }+ let (Some(session_id), Some(target_id)) = (+ event.params["sessionId"].as_str(),+ info["targetId"].as_str(),+ ) else {+ continue;+ };+ out.push(AttachedChildFrame {+ session_id: session_id.to_owned(),+ target_id: target_id.to_owned(),+ url: info["url"].as_str().unwrap_or("").to_owned(),+ });+ }+ Ok(out)+ }++ /// Re-prove a ref's frame/document identity and return the CDP+ /// session its `backendNodeId` is valid in. Called after+ /// [`Self::revalidate_for_mutation`], before the ref is touched.+ /// Any identity that cannot be re-proven is a refusal, and a stale+ /// document additionally invalidates the tab's snapshots.+ pub(crate) async fn frame_session_for_mutation(+ &self,+ session: &str,+ target_id: &str,+ tab_id: &str,+ validated: &ValidatedTab,+ frame: &FrameRef,+ ) -> Result<String, BrowserRefusal> {+ let conn = &validated.conn;+ let stale = |message: &str| {+ self.store+ .invalidate_tab_snapshots(session, target_id, tab_id);+ refuse(BrowserRefusalCode::BrowserRefStale, message)+ };+ let tree_err = |e: FrameTreeError| match e {+ FrameTreeError::Unsupported => refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "the browser no longer reports its frame tree — the ref's frame identity \+ cannot be re-proven",+ ),+ FrameTreeError::Failed(err) => {+ route_err("Page.getFrameTree failed during frame revalidation", err)+ }+ };++ match &frame.oopif_target_id {+ None => {+ // v1-compat main-frame refs minted without a frame tree+ // carry no identity to re-check; node liveness (box+ // model / focus failures map to stale) is the backstop.+ let Some(identity) = &frame.identity else {+ return Ok(validated.cdp_session.clone());+ };+ let tree = self+ .local_frame_tree(conn, &validated.cdp_session)+ .await+ .map_err(tree_err)?;+ if tree.proves(identity) {+ Ok(validated.cdp_session.clone())+ } else {+ Err(stale(+ "the ref's frame navigated or was removed since the snapshot — \+ re-run get_browser_state to re-snapshot",+ ))+ }+ }+ Some(oopif_target) => {+ let Some(identity) = &frame.identity else {+ // Unreachable by construction (OOPIF refs are only+ // minted with identity); refuse defensively.+ return Err(refuse(+ BrowserRefusalCode::BrowserRefStale,+ "the OOPIF ref carries no provable frame identity",+ ));+ };+ let children = self+ .attached_iframe_children(conn, &validated.cdp_session)+ .await+ .map_err(|e| match e {+ AttachError::Unsupported => refuse(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "the browser no longer supports capability-tested OOPIF \+ attachment — the ref's cross-process frame cannot be re-proven",+ ),+ AttachError::Failed(err) => {+ route_err("Target.setAutoAttach failed during frame revalidation", err)+ }+ })?;+ let Some(child) = children.into_iter().find(|c| c.target_id == *oopif_target)+ else {+ return Err(stale(+ "the ref's cross-process frame is no longer attached beneath the \+ bound tab — re-run get_browser_state to re-snapshot",+ ));+ };+ let tree = self+ .local_frame_tree(conn, &child.session_id)+ .await+ .map_err(tree_err)?;+ if tree.proves(identity) {+ Ok(child.session_id)+ } else {+ Err(stale(+ "the ref's cross-process frame navigated since the snapshot — \+ re-run get_browser_state to re-snapshot",+ ))+ }+ }+ }+ }++ // ── Read-side: page snapshot (ref minting) ──────────────────────────++ /// Snapshot one tab's composed DOM (main frame + shadow DOM ++ /// same-process iframes + capability-tested OOPIFs) and mint+ /// `p<snap>:<index>` refs for interactive elements. Read-only+ /// against the page.+ pub(crate) async fn snapshot_tab(+ &self,+ session: &str,+ target_id: &str,+ tab_id: &str,+ ) -> Result<SnapshotOutcome, BrowserRefusal> {+ let record = self.store.get_target(session, target_id)?;+ let tab = record.tabs.get(tab_id).cloned().ok_or_else(|| {+ refuse(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("tab {tab_id} is not known for target {target_id}"),+ )+ })?;+ let conn = self.connect(&record.ws_url).await?;+ let cdp_session = self.attach(&conn, &tab.cdp_target_id).await?;++ let doc = conn+ .call(+ Some(&cdp_session),+ "DOM.getDocument",+ json!({ "depth": -1, "pierce": true }),+ )+ .await+ .map_err(|e| route_err("DOM.getDocument failed", e))?;+ let root = doc.get("root").cloned().unwrap_or(Value::Null);+ let url = root+ .get("documentURL")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_owned();++ // Frame/document identity for the tab session's local frames.+ // Unsupported degrades to the v1-compat main-frame-only path.+ let local_tree = match self.local_frame_tree(&conn, &cdp_session).await {+ Ok(tree) => Some(tree),+ Err(FrameTreeError::Unsupported) => None,+ Err(FrameTreeError::Failed(e)) => return Err(route_err("Page.getFrameTree failed", e)),+ };++ let mut collected = Vec::new();+ let root_frame_id = root+ .get("frameId")+ .and_then(Value::as_str)+ .map(str::to_owned);+ collect_interactive(&root, root_frame_id.as_deref(), true, &mut collected);++ let mut entries: Vec<RefEntry> = Vec::new();+ for c in collected {+ let frame = match (c.in_root_frame, &local_tree) {+ (true, Some(tree)) => FrameRef {+ kind: FrameKind::Main,+ oopif_target_id: None,+ identity: Some(tree.main_identity()),+ },+ (true, None) => FrameRef::main_unproven(),+ (false, Some(tree)) => {+ let Some(identity) = c+ .frame_id+ .as_deref()+ .and_then(|frame_id| tree.identity_of(frame_id))+ else {+ continue; // frame identity unprovable → omit+ };+ FrameRef {+ kind: FrameKind::Iframe,+ oopif_target_id: None,+ identity: Some(identity),+ }+ }+ // No frame tree → iframe identity unprovable → omit.+ (false, None) => continue,+ };+ entries.push(RefEntry {+ backend_node_id: c.backend_node_id,+ node_name: c.node_name,+ label: c.label,+ frame,+ });+ }++ // OOPIF children (C2): only with a provable frame tree AND a+ // successful capability test, contained beneath this tab's own+ // session. Anything unprovable is omitted, never guessed.+ let oopif = if local_tree.is_some() {+ match self.attached_iframe_children(&conn, &cdp_session).await {+ Ok(children) => {+ let mut attached = 0usize;+ for child in &children {+ let Ok(child_tree) = self.local_frame_tree(&conn, &child.session_id).await+ else {+ continue; // identity unprovable → omit this frame+ };+ let Ok(child_doc) = conn+ .call(+ Some(&child.session_id),+ "DOM.getDocument",+ json!({ "depth": -1, "pierce": true }),+ )+ .await+ else {+ continue;+ };+ let child_root = child_doc.get("root").cloned().unwrap_or(Value::Null);+ let child_root_frame = child_root+ .get("frameId")+ .and_then(Value::as_str)+ .map(str::to_owned);+ let mut child_collected = Vec::new();+ collect_interactive(+ &child_root,+ child_root_frame.as_deref(),+ true,+ &mut child_collected,+ );+ for c in child_collected {+ let identity = if c.in_root_frame {+ Some(child_tree.main_identity())+ } else {+ c.frame_id+ .as_deref()+ .and_then(|frame_id| child_tree.identity_of(frame_id))+ };+ let Some(identity) = identity else { continue };+ entries.push(RefEntry {+ backend_node_id: c.backend_node_id,+ node_name: c.node_name,+ label: c.label,+ frame: FrameRef {+ kind: FrameKind::Oopif,+ oopif_target_id: Some(child.target_id.clone()),+ identity: Some(identity),+ },+ });+ }+ attached += 1;+ }+ // Contain the child sessions this read minted:+ // stop auto-attaching (best effort).+ let _ = conn+ .call(+ Some(&cdp_session),+ "Target.setAutoAttach",+ json!({+ "autoAttach": false,+ "waitForDebuggerOnStart": false,+ "flatten": true+ }),+ )+ .await;+ for child in &children {+ let _ = conn+ .call(+ Some(&cdp_session),+ "Target.detachFromTarget",+ json!({ "sessionId": child.session_id }),+ )+ .await;+ }+ OopifStatus::Attached(attached)+ }+ Err(AttachError::Unsupported) => OopifStatus::Unsupported,+ Err(AttachError::Failed(e)) => {+ return Err(route_err("Target.setAutoAttach failed", e))+ }+ }+ } else {+ OopifStatus::Unsupported+ };++ let truncated = entries.len() > MAX_REFS_PER_SNAPSHOT;+ entries.truncate(MAX_REFS_PER_SNAPSHOT);+ if truncated {+ tracing::warn!(+ "browser snapshot truncated to {MAX_REFS_PER_SNAPSHOT} refs for tab {tab_id}"+ );+ }++ let snapshot_id = self.store.mint_snapshot_id();+ let mut refs = HashMap::new();+ let mut listed = Vec::new();+ for (i, entry) in entries.into_iter().enumerate() {+ let idx = i as u32;+ listed.push((format_ref(snapshot_id, idx), entry.clone()));+ refs.insert(idx, entry);+ }+ // A new snapshot supersedes prior ones for the tab: only the+ // latest namespace stays resolvable, so refs can never mix+ // across snapshots of a mutating page.+ self.store.update_target(session, target_id, |rec| {+ if let Some(tab) = rec.tabs.get_mut(tab_id) {+ tab.snapshots.clear();+ tab.snapshots.insert(+ snapshot_id,+ SnapshotRecord {+ id: snapshot_id,+ url: url.clone(),+ refs,+ },+ );+ }+ });+ Ok(SnapshotOutcome {+ snapshot_id,+ url,+ refs: listed,+ truncated,+ oopif,+ })+ }+}++/// Attribute names that make an element interactive-enough to ref.+const INTERACTIVE_ATTRS: &[&str] = &["onclick", "role", "contenteditable", "tabindex", "href"];+/// Element names always considered interactive.+const INTERACTIVE_TAGS: &[&str] = &[+ "a", "button", "input", "select", "textarea", "option", "summary", "label",+];+/// Attributes surfaced into the human-readable ref label.+const LABEL_ATTRS: &[&str] = &[+ "aria-label",+ "placeholder",+ "name",+ "id",+ "type",+ "value",+ "href",+ "role",+];++/// One interactive element found by the composed DOM walk, before+/// frame identity has been resolved against the frame tree.+struct CollectedNode {+ backend_node_id: i64,+ node_name: String,+ label: Option<String>,+ /// Frame id of the containing frame when known (from the iframe+ /// element's / document's `frameId`).+ frame_id: Option<String>,+ /// Whether the node lives in the session's root frame (as opposed+ /// to a descended same-process `contentDocument`).+ in_root_frame: bool,+}++/// Walk a pierced `DOM.getDocument` node tree collecting interactive+/// elements in document order. Composition rules:+/// - `shadowRoots` are descended (composed into their host's frame),+/// except user-agent shadow roots (internal control chrome).+/// - Same-process iframes are descended via `contentDocument`, tagged+/// with the child frame's id.+/// - OOPIF placeholders (iframe elements without a `contentDocument`)+/// are NOT descended here — they are reached only through+/// capability-tested child sessions.+fn collect_interactive(+ node: &Value,+ frame_id: Option<&str>,+ in_root_frame: bool,+ out: &mut Vec<CollectedNode>,+) {+ let node_type = node.get("nodeType").and_then(Value::as_i64).unwrap_or(0);+ if node_type == 1 {+ let name = node+ .get("nodeName")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_ascii_lowercase();+ let attrs: Vec<String> = node+ .get("attributes")+ .and_then(Value::as_array)+ .map(|a| {+ a.iter()+ .filter_map(Value::as_str)+ .map(str::to_owned)+ .collect()+ })+ .unwrap_or_default();+ let attr = |key: &str| -> Option<&str> {+ attrs+ .chunks_exact(2)+ .find(|kv| kv[0].eq_ignore_ascii_case(key))+ .map(|kv| kv[1].as_str())+ };+ let interactive = INTERACTIVE_TAGS.contains(&name.as_str())+ || INTERACTIVE_ATTRS.iter().any(|a| attr(a).is_some());+ if interactive {+ if let Some(backend) = node.get("backendNodeId").and_then(Value::as_i64) {+ let label = LABEL_ATTRS+ .iter()+ .filter_map(|k| attr(k).map(|v| format!("{k}={v}")))+ .collect::<Vec<_>>()+ .join(" ");+ out.push(CollectedNode {+ backend_node_id: backend,+ node_name: name,+ label: (!label.is_empty()).then_some(label),+ frame_id: frame_id.map(str::to_owned),+ in_root_frame,+ });+ }+ }+ }+ if let Some(children) = node.get("children").and_then(Value::as_array) {+ for child in children {+ collect_interactive(child, frame_id, in_root_frame, out);+ }+ }+ if let Some(shadow_roots) = node.get("shadowRoots").and_then(Value::as_array) {+ for shadow_root in shadow_roots {+ if shadow_root.get("shadowRootType").and_then(Value::as_str) == Some("user-agent") {+ continue;+ }+ collect_interactive(shadow_root, frame_id, in_root_frame, out);+ }+ }+ if let Some(content_document) = node.get("contentDocument") {+ // Same-process iframe. The child frame id lives on the iframe+ // element (and again on the content document); without it the+ // frame's identity is unprovable and its refs get omitted.+ let child_frame_id = node+ .get("frameId")+ .or_else(|| content_document.get("frameId"))+ .and_then(Value::as_str);+ collect_interactive(content_document, child_frame_id, false, out);+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ fn fixture_doc() -> Value {+ json!({+ "nodeType": 9,+ "nodeName": "#document",+ "frameId": "F_MAIN",+ "children": [{+ "nodeType": 1,+ "nodeName": "HTML",+ "backendNodeId": 1,+ "children": [+ {+ "nodeType": 1,+ "nodeName": "BUTTON",+ "backendNodeId": 10,+ "attributes": ["aria-label", "Submit"],+ },+ {+ "nodeType": 1,+ "nodeName": "DIV",+ "backendNodeId": 11,+ "shadowRoots": [{+ "nodeType": 11,+ "nodeName": "#document-fragment",+ "shadowRootType": "open",+ "backendNodeId": 12,+ "children": [{+ "nodeType": 1,+ "nodeName": "BUTTON",+ "backendNodeId": 20,+ "attributes": ["aria-label", "Shadow Go"],+ }]+ }]+ },+ {+ "nodeType": 1,+ "nodeName": "INPUT",+ "backendNodeId": 21,+ "attributes": ["type", "text"],+ "shadowRoots": [{+ "nodeType": 11,+ "nodeName": "#document-fragment",+ "shadowRootType": "user-agent",+ "backendNodeId": 23,+ "children": [{+ "nodeType": 1,+ "nodeName": "DIV",+ "backendNodeId": 22,+ "attributes": ["role", "button"],+ }]+ }]+ },+ {+ "nodeType": 1,+ "nodeName": "SPAN",+ "backendNodeId": 24,+ },+ {+ "nodeType": 1,+ "nodeName": "IFRAME",+ "backendNodeId": 13,+ "frameId": "F_IFRAME",+ "contentDocument": {+ "nodeType": 9,+ "nodeName": "#document",+ "frameId": "F_IFRAME",+ "children": [{+ "nodeType": 1,+ "nodeName": "BUTTON",+ "backendNodeId": 30,+ "attributes": ["id", "inner-btn"],+ }]+ }+ },+ {+ "nodeType": 1,+ "nodeName": "IFRAME",+ "backendNodeId": 14,+ "frameId": "F_OOPIF",+ }+ ]+ }]+ })+ }++ #[test]+ fn collector_composes_shadow_dom_and_same_process_iframes() {+ let doc = fixture_doc();+ let mut out = Vec::new();+ collect_interactive(&doc, Some("F_MAIN"), true, &mut out);+ let backends: Vec<i64> = out.iter().map(|e| e.backend_node_id).collect();+ assert_eq!(+ backends,+ vec![10, 20, 21, 30],+ "main button + open-shadow button + input + same-process iframe button; \+ no span, no user-agent shadow content, no OOPIF placeholder descent"+ );+ assert_eq!(out[0].label.as_deref(), Some("aria-label=Submit"));++ let shadow = out.iter().find(|e| e.backend_node_id == 20).unwrap();+ assert!(+ shadow.in_root_frame,+ "shadow DOM composes into its host frame"+ );+ assert_eq!(shadow.frame_id.as_deref(), Some("F_MAIN"));++ let inner = out.iter().find(|e| e.backend_node_id == 30).unwrap();+ assert!(!inner.in_root_frame);+ assert_eq!(inner.frame_id.as_deref(), Some("F_IFRAME"));+ }++ #[test]+ fn parse_frame_tree_maps_frames_and_omits_malformed_children() {+ let tree = parse_frame_tree(&json!({+ "frameTree": {+ "frame": { "id": "F_MAIN", "loaderId": "L1", "url": "https://a.test/" },+ "childFrames": [+ { "frame": { "id": "F_CHILD", "loaderId": "L2" } },+ { "frame": { "id": "F_NO_LOADER" } }+ ]+ }+ }))+ .expect("valid tree");+ assert!(tree.proves(&FrameIdentity {+ frame_id: "F_MAIN".into(),+ loader_id: "L1".into()+ }));+ assert!(tree.proves(&FrameIdentity {+ frame_id: "F_CHILD".into(),+ loader_id: "L2".into()+ }));+ assert!(!tree.proves(&FrameIdentity {+ frame_id: "F_CHILD".into(),+ loader_id: "L9".into()+ }));+ assert!(+ tree.identity_of("F_NO_LOADER").is_none(),+ "a frame without a loader id is unprovable and omitted"+ );+ assert_eq!(tree.main_identity().frame_id, "F_MAIN");++ assert!(+ parse_frame_tree(&json!({ "frameTree": { "frame": { "id": "x" } } })).is_none(),+ "a root without a loader id fails the parse"+ );+ assert!(parse_frame_tree(&json!({})).is_none());+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mock_cdp.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mock_cdp.rsnew file mode 100644index 0000000000..bdd3a39f6a--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mock_cdp.rs@@ -0,0 +1,148 @@+//! Deterministic in-process mock CDP endpoint for tests.+//!+//! A tiny scripted WebSocket server on a loopback port: each incoming+//! command is handed to a caller-supplied handler which returns the+//! events to emit *before* the reply plus the reply itself. Because+//! events precede the response frame on the wire — exactly Chromium's+//! behavior for `Target.setAutoAttach` announcing existing targets —+//! tests of the event demux and the OOPIF attach flow are fully+//! deterministic (no sleeps, no polling).++use std::net::SocketAddr;+use std::sync::Arc;++use futures_util::{SinkExt, StreamExt};+use serde_json::{json, Value};+use tokio::net::TcpListener;+use tokio_tungstenite::tungstenite::Message;++/// One decoded incoming CDP command.+pub(crate) struct MockCall {+ pub method: String,+ pub params: Value,+ pub session_id: Option<String>,+}++/// An event frame the mock emits before a reply.+pub(crate) struct MockEvent {+ pub method: String,+ pub params: Value,+ pub session_id: Option<String>,+}++/// The scripted reaction to one command.+pub(crate) struct MockReply {+ pub events: Vec<MockEvent>,+ pub result: Result<Value, (i64, String)>,+}++impl MockReply {+ pub fn ok(result: Value) -> Self {+ Self {+ events: Vec::new(),+ result: Ok(result),+ }+ }++ pub fn err(code: i64, message: &str) -> Self {+ Self {+ events: Vec::new(),+ result: Err((code, message.to_owned())),+ }+ }++ /// The exact shape Chromium uses for an unimplemented method.+ pub fn method_not_found(method: &str) -> Self {+ Self::err(-32601, &format!("'{method}' wasn't found"))+ }++ pub fn with_events(mut self, events: Vec<MockEvent>) -> Self {+ self.events = events;+ self+ }+}++pub(crate) type MockHandler = Arc<dyn Fn(&MockCall) -> MockReply + Send + Sync>;++/// A running mock endpoint. Dropping it aborts the accept loop.+pub(crate) struct MockCdpServer {+ addr: SocketAddr,+ accept_task: tokio::task::JoinHandle<()>,+}++impl MockCdpServer {+ pub async fn start(handler: MockHandler) -> Self {+ let listener = TcpListener::bind("127.0.0.1:0")+ .await+ .expect("bind loopback");+ let addr = listener.local_addr().expect("local addr");+ let accept_task = tokio::spawn(async move {+ loop {+ let Ok((stream, _)) = listener.accept().await else {+ break;+ };+ let handler = handler.clone();+ tokio::spawn(async move {+ let Ok(mut ws) = tokio_tungstenite::accept_async(stream).await else {+ return;+ };+ while let Some(Ok(msg)) = ws.next().await {+ let Message::Text(text) = msg else { continue };+ let Ok(v) = serde_json::from_str::<Value>(&text) else {+ continue;+ };+ let Some(id) = v.get("id").and_then(Value::as_u64) else {+ continue;+ };+ let call = MockCall {+ method: v+ .get("method")+ .and_then(Value::as_str)+ .unwrap_or("")+ .to_owned(),+ params: v.get("params").cloned().unwrap_or_else(|| json!({})),+ session_id: v+ .get("sessionId")+ .and_then(Value::as_str)+ .map(str::to_owned),+ };+ let reply = handler(&call);+ for event in reply.events {+ let mut frame =+ json!({ "method": event.method, "params": event.params });+ if let Some(sid) = event.session_id {+ frame["sessionId"] = json!(sid);+ }+ if ws.send(Message::Text(frame.to_string())).await.is_err() {+ return;+ }+ }+ let mut response = match reply.result {+ Ok(result) => json!({ "id": id, "result": result }),+ Err((code, message)) => {+ json!({ "id": id, "error": { "code": code, "message": message } })+ }+ };+ if let Some(sid) = &call.session_id {+ response["sessionId"] = json!(sid);+ }+ if ws.send(Message::Text(response.to_string())).await.is_err() {+ return;+ }+ }+ });+ }+ });+ Self { addr, accept_task }+ }++ pub fn ws_url(&self) -> String {+ format!("ws://127.0.0.1:{}/devtools/browser/mock", self.addr.port())+ }+}++impl Drop for MockCdpServer {+ fn drop(&mut self) {+ self.accept_task.abort();+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rsnew file mode 100644index 0000000000..398d13f2eb--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs@@ -0,0 +1,65 @@+//! Platform-agnostic browser-tool v1 core.+//!+//! Five typed tools — `get_browser_state` (strictly read-only),+//! `browser_prepare`, `browser_navigate`, `browser_click`,+//! `browser_type` — over an exact-or-refused binding model:+//!+//! - The native entrypoint is `pid + window_id`. Browser target ids,+//! tab ids, and page refs (`p<snapshot>:<index>`) are opaque,+//! session-scoped capabilities minted by core.+//! - Mutation is permitted only for **exact** bindings (unique+//! bounds-correlated, optionally title-tie-broken). Heuristic+//! bindings are read-only; everything else is a structured refusal+//! with a stable code (see [`refusal::BrowserRefusalCode`]).+//! - Core owns schemas, semantics, CDP target handling, the target/ref+//! store, lifecycle cleanup and correlation. Platform adapters+//! implement [`platform::BrowserPlatform`] for process identity,+//! endpoint ownership, native window metadata, classification and+//! explicit setup — without depending on core internals.+//!+//! Wiring (per platform crate):+//! ```ignore+//! let engine = BrowserEngine::new(Arc::new(MyPlatformAdapter::new()));+//! register_browser_tools(&engine, &mut registry);+//! ```+//!+//! The legacy `crate::page` contract remains separate because its first-page+//! and URL-hint semantics predate exact browser capabilities. Its CDP paths+//! nevertheless reuse the pooled, loopback-validated WebSocket transport in+//! [`cdp_ws`] so the repository has one event-capable demultiplexer.+//!+//! v2 DOM-ref slice: snapshots compose shadow DOM (piercing, minus+//! user-agent roots), same-process iframes (via `contentDocument`),+//! and — only when the capability is proven live — OOPIF child targets+//! auto-attached beneath the bound tab's own session. Every ref+//! carries its frame's document identity (frame id + loader id), which+//! is re-proven before any mutation; frames whose identity or+//! capability cannot be proven are omitted or refused, never guessed.++pub mod approval;+pub mod binding;+pub mod cdp_ws;+pub mod engine;+#[cfg(test)]+pub(crate) mod mock_cdp;+pub mod platform;+mod prepare;+pub mod refusal;+pub mod store;+pub mod tools;+pub mod types;+#[cfg(test)]+mod v2_tests;++pub use engine::BrowserEngine;+pub use platform::{+ BrowserPlatform, PrepareAction, PrepareAuthorization, PrepareOutcome, PrepareProfile,+ PrepareProfileMode, PrepareRequest, PrepareSideEffects,+};+pub use refusal::{BrowserRefusal, BrowserRefusalCode};+pub use tools::register_browser_tools;+pub use types::{+ BindingQuality, BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod,+ EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo,+ OwnedEndpoint, ProcessFingerprint, Rect,+};diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rsnew file mode 100644index 0000000000..f1cedbd07a--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs@@ -0,0 +1,157 @@+//! The platform-adapter contract for the browser-tool surface.+//!+//! Core owns schemas, semantics, CDP handling, the target/ref store,+//! lifecycle cleanup, and correlation. Platform crates own everything+//! that requires OS identity: process fingerprints, native window+//! metadata, browser classification, loopback-endpoint ownership, and+//! explicit endpoint setup. This trait is the entire boundary — a+//! platform crate implements it without depending on core internals,+//! and core never reaches into a platform crate.++use async_trait::async_trait;+use serde::{Deserialize, Serialize};++use super::refusal::BrowserRefusal;+use super::types::{BrowserClassification, NativeWindowInfo, OwnedEndpoint, ProcessFingerprint};++#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum PrepareProfileMode {+ IsolatedNew,+ IsolatedNamed,+}++#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct PrepareProfile {+ pub mode: PrepareProfileMode,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub name: Option<String>,+}++#[derive(Debug, Clone, PartialEq, Eq)]+pub enum PrepareAuthorization {+ McpHost,+ ApprovalArtifact(String),+}++/// Caller context for an explicit `browser_prepare` call. Prepare is never+/// implicit: `get_browser_state` must not trigger it.+#[derive(Debug, Clone)]+pub struct PrepareRequest {+ pub pid: i64,+ pub session: String,+ /// Private transport lifecycle owner. A daemon-backed MCP proxy supplies+ /// this independently from the public capability session so either proxy+ /// disconnect or explicit `end_session` can reap a spawned browser.+ pub transport_session: Option<String>,+ pub authorization: Option<PrepareAuthorization>,+ pub profile: Option<PrepareProfile>,+ /// Allows launching a separate driver-owned isolated browser process.+ /// It never authorizes terminating or modifying the requested process.+ pub allow_launch: bool,+}++/// What a platform adapter actually did (or found) during prepare.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum PrepareAction {+ /// An owned endpoint already existed; nothing was changed.+ AlreadyPrepared,+ /// The adapter enabled an endpoint on the running process.+ EnabledEndpoint,+ /// The adapter (re)launched the browser with an endpoint.+ RelaunchedBrowser,+ /// The driver launched a separate isolated browser process.+ LaunchedIsolatedBrowser,+ /// Nothing was done — see `message` on the outcome.+ NoOp,+}++/// Result of an explicit prepare. `endpoint` is present iff an owned+/// endpoint is now available.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct PrepareOutcome {+ pub action: PrepareAction,+ pub endpoint: Option<OwnedEndpoint>,+ pub message: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub prepared_pid: Option<i64>,+ #[serde(default)]+ pub side_effects: PrepareSideEffects,+}++#[derive(Debug, Clone, Default, Serialize, Deserialize)]+pub struct PrepareSideEffects {+ pub launched_browser: bool,+ pub restarted_browser: bool,+ pub created_profile: bool,+ pub reused_driver_profile: bool,+ pub copied_profile_data: bool,+ pub changed_preferences: bool,+ pub displayed_consent_prompt: bool,+}++/// OS-identity services a platform crate provides to the browser-tool+/// core. All methods are point-in-time queries; core re-invokes them+/// for revalidation before every mutation rather than caching.+///+/// Error convention: methods return `Err(BrowserRefusal)` for+/// conditions the calling agent should see as a structured refusal+/// (including infrastructure failures, which map naturally onto+/// `browser_route_unavailable`).+#[async_trait]+pub trait BrowserPlatform: Send + Sync {+ /// Explain why a trusted CDP Input route cannot preserve background+ /// posture for a standalone browser on this platform. Embedded Chromium+ /// routes are independently proven and do not consult this capability.+ fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {+ None+ }++ /// Classify `pid`: is it a browser, which engine family, can it do+ /// CDP at all. Must not have side effects.+ async fn classify_browser(&self, pid: i64) -> Result<BrowserClassification, BrowserRefusal>;++ /// Resolve native metadata (title, normalized bounds, ownership+ /// proof) for one window of `pid`. Must fail — not guess — when the+ /// window does not exist or is not attributable to `pid`.+ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal>;++ /// Prove whether `window_id` is the only native top-level window owned by+ /// `pid`. `Some(true)` is an exact platform-attested cardinality proof;+ /// `Some(false)` means another window exists; `None` means this window+ /// system cannot prove cardinality. Used for embedded Chromium endpoints+ /// that omit Browser.getWindowForTarget and standalone browsers whose+ /// bounds were overridden by a tiling compositor.+ async fn is_only_exact_native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal>;++ /// Discover a loopback DevTools endpoint owned by `pid`, with an+ /// explicit ownership proof. `Ok(None)` means "no endpoint right+ /// now" (core maps that to `browser_requires_setup`); it must NOT+ /// silently start one — setup belongs to [`Self::prepare_endpoint`].+ async fn discover_owned_endpoint(+ &self,+ pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal>;++ /// Current identity fingerprint for `pid`. Used to detect pid reuse+ /// between binding and mutation.+ async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal>;++ /// Explicitly prepare an owned endpoint for `pid`. Only ever called+ /// from the `browser_prepare` tool. Adapters gate disruptive or+ /// consent-requiring paths on the request's explicit fields and+ /// refuse with `browser_consent_required` otherwise.+ async fn prepare_endpoint(+ &self,+ request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal>;+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rsnew file mode 100644index 0000000000..57fb619bc2--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs@@ -0,0 +1,603 @@+//! Acting `browser_prepare` implementation for driver-owned Chromium profiles.++use std::fs::{self, OpenOptions};+use std::io::Write;+use std::path::{Path, PathBuf};+use std::process::{Child, Command, Stdio};+use std::sync::Mutex;+use std::time::{Duration, Instant};++use serde::{Deserialize, Serialize};++use super::approval::{consume_prepare_approval, validate_profile};+use super::platform::{+ PrepareAction, PrepareAuthorization, PrepareOutcome, PrepareProfile, PrepareProfileMode,+ PrepareRequest, PrepareSideEffects,+};+use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::types::{+ BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof, OwnedEndpoint,+};+use super::BrowserEngine;++const PROFILE_MARKER: &str = ".cua-driver-owned-profile.json";+const PROFILE_SCHEMA: &str = "cua-driver-browser-profile-v1";++#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]+struct ProfileMarker {+ schema: String,+ mode: PrepareProfileMode,+ #[serde(skip_serializing_if = "Option::is_none")]+ name: Option<String>,+}++struct PreparedProfile {+ path: PathBuf,+ created: bool,+ delete_on_cleanup: bool,+ marker: ProfileMarker,+}++pub(crate) struct ManagedBrowser {+ child: Child,+ profile: PathBuf,+ delete_profile: bool,+ marker: ProfileMarker,+ owner_sessions: Vec<String>,+}++impl Drop for ManagedBrowser {+ fn drop(&mut self) {+ #[cfg(unix)]+ unsafe {+ // The isolated browser is spawned as its own process group. Chrome+ // fans out into renderer/utility descendants, so killing only the+ // root Child can leave profile writers alive after cleanup.+ libc::kill(-(self.child.id() as i32), libc::SIGKILL);+ }+ let _ = self.child.kill();+ let _ = self.child.wait();+ if self.delete_profile && profile_matches_marker(&self.profile, &self.marker) {+ let _ = fs::remove_dir_all(&self.profile);+ }+ }+}++pub(crate) type ManagedBrowsers = Mutex<Vec<ManagedBrowser>>;++fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(code, message)+}++fn profile_root() -> Result<PathBuf, BrowserRefusal> {+ if let Some(root) = std::env::var_os("CUA_DRIVER_BROWSER_PROFILE_ROOT") {+ return Ok(PathBuf::from(root));+ }+ #[cfg(target_os = "windows")]+ let root = std::env::var_os("LOCALAPPDATA")+ .map(PathBuf::from)+ .map(|path| path.join("CuaDriver").join("BrowserProfiles"));+ #[cfg(target_os = "macos")]+ let root = std::env::var_os("HOME").map(PathBuf::from).map(|path| {+ path.join("Library")+ .join("Application Support")+ .join("CuaDriver")+ .join("BrowserProfiles")+ });+ #[cfg(all(unix, not(target_os = "macos")))]+ let root = std::env::var_os("XDG_STATE_HOME")+ .map(PathBuf::from)+ .or_else(|| {+ std::env::var_os("HOME")+ .map(PathBuf::from)+ .map(|path| path.join(".local").join("state"))+ })+ .map(|path| path.join("cua-driver").join("browser-profiles"));+ root.ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "could not resolve the current user's driver-owned profile directory",+ )+ })+}++fn read_profile_marker(path: &Path) -> Option<ProfileMarker> {+ let Ok(metadata) = fs::symlink_metadata(path) else {+ return None;+ };+ if metadata.file_type().is_symlink() || !metadata.is_dir() {+ return None;+ }+ let Ok(bytes) = fs::read(path.join(PROFILE_MARKER)) else {+ return None;+ };+ serde_json::from_slice::<ProfileMarker>(&bytes)+ .ok()+ .filter(|marker| marker.schema == PROFILE_SCHEMA)+}++fn profile_matches_marker(path: &Path, expected: &ProfileMarker) -> bool {+ read_profile_marker(path).is_some_and(|marker| marker == *expected)+}++fn cleanup_created_profile(profile: &PreparedProfile) {+ if profile.delete_on_cleanup && profile_matches_marker(&profile.path, &profile.marker) {+ let _ = fs::remove_dir_all(&profile.path);+ }+}++#[cfg(target_os = "linux")]+fn configure_linux_isolated_browser_command(+ command: &mut Command,+ native_wayland: bool,+ no_sandbox: bool,+) {+ command.arg("--password-store=basic");+ if native_wayland {+ command.arg("--ozone-platform=wayland");+ }+ if no_sandbox {+ command.arg("--no-sandbox");+ }+}++fn isolated_browser_command(executable: &str, profile: &Path) -> Command {+ let mut command = Command::new(executable);+ #[cfg(unix)]+ {+ use std::os::unix::process::CommandExt;+ command.process_group(0);+ }+ command+ .arg("--remote-debugging-port=0")+ .arg(format!("--user-data-dir={}", profile.display()))+ .arg("--no-first-run")+ .arg("--no-default-browser-check")+ .arg("--disable-background-networking")+ .arg("--disable-component-update")+ .arg("--disable-default-apps")+ .arg("--disable-extensions");+ #[cfg(target_os = "windows")]+ command+ .arg("--window-position=40,40")+ .arg("--window-size=900,640");+ #[cfg(target_os = "linux")]+ {+ let native_wayland = std::env::var("XDG_SESSION_TYPE")+ .is_ok_and(|session| session.eq_ignore_ascii_case("wayland"))+ && std::env::var_os("WAYLAND_DISPLAY").is_some()+ && std::env::var_os("DISPLAY").is_none();+ let no_sandbox = std::env::var("CUA_E2E_BROWSER_NO_SANDBOX").as_deref() == Ok("1");+ configure_linux_isolated_browser_command(&mut command, native_wayland, no_sandbox);+ }+ let stderr = if std::env::var_os("CUA_E2E_BROWSER_STDERR").is_some() {+ Stdio::inherit()+ } else {+ Stdio::null()+ };+ command+ .arg("about:blank")+ .stdin(Stdio::null())+ .stdout(Stdio::null())+ .stderr(stderr);+ command+}++fn write_profile_marker(path: &Path, marker: &ProfileMarker) -> Result<(), BrowserRefusal> {+ let marker_path = path.join(PROFILE_MARKER);+ let mut options = OpenOptions::new();+ options.write(true).create_new(true);+ #[cfg(unix)]+ {+ use std::os::unix::fs::OpenOptionsExt;+ options.mode(0o600);+ }+ let mut file = options.open(&marker_path).map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not create the isolated profile ownership marker: {error}"),+ )+ })?;+ let bytes = serde_json::to_vec(marker).expect("serialize profile marker");+ file.write_all(&bytes)+ .and_then(|_| file.sync_all())+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not persist the isolated profile ownership marker: {error}"),+ )+ })+}++fn prepare_profile(profile: &PrepareProfile) -> Result<PreparedProfile, BrowserRefusal> {+ validate_profile(profile)?;+ let root = profile_root()?;+ fs::create_dir_all(&root).map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not create the driver-owned profile root: {error}"),+ )+ })?;+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ fs::set_permissions(&root, fs::Permissions::from_mode(0o700)).map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not restrict the driver-owned profile root: {error}"),+ )+ })?;+ }+ let root_metadata = fs::symlink_metadata(&root).map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not inspect the driver-owned profile root: {error}"),+ )+ })?;+ if root_metadata.file_type().is_symlink() || !root_metadata.is_dir() {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "the driver-owned profile root is not a real directory",+ ));+ }+ let leaf = match profile.mode {+ PrepareProfileMode::IsolatedNew => format!("isolated-{}", uuid::Uuid::new_v4()),+ PrepareProfileMode::IsolatedNamed => profile.name.clone().expect("validated profile name"),+ };+ let path = root.join(leaf);+ let marker = ProfileMarker {+ schema: PROFILE_SCHEMA.to_owned(),+ mode: profile.mode,+ name: profile.name.clone(),+ };+ let created = if path.exists() {+ if profile.mode != PrepareProfileMode::IsolatedNamed+ || !profile_matches_marker(&path, &marker)+ {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "the requested profile directory exists but is not proven driver-owned",+ ));+ }+ false+ } else {+ fs::create_dir(&path).map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not create an isolated browser profile: {error}"),+ )+ })?;+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ if let Err(error) = fs::set_permissions(&path, fs::Permissions::from_mode(0o700)) {+ let _ = fs::remove_dir(&path);+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not restrict the isolated browser profile: {error}"),+ ));+ }+ }+ let is_empty = fs::read_dir(&path)+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not verify the isolated browser profile: {error}"),+ )+ })?+ .next()+ .is_none();+ if !is_empty {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "new isolated browser profile was not empty",+ ));+ }+ if let Err(error) = write_profile_marker(&path, &marker) {+ let _ = fs::remove_dir(&path);+ return Err(error);+ }+ true+ };+ Ok(PreparedProfile {+ path,+ created,+ delete_on_cleanup: profile.mode == PrepareProfileMode::IsolatedNew,+ marker,+ })+}++async fn wait_for_spawned_endpoint(+ child: &mut Child,+ profile: &Path,+) -> Result<OwnedEndpoint, BrowserRefusal> {+ let deadline = Instant::now() + Duration::from_secs(20);+ let port_file = profile.join("DevToolsActivePort");+ loop {+ if let Some(status) = child.try_wait().map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not inspect the isolated browser process: {error}"),+ )+ })? {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("isolated browser exited before exposing DevTools ({status})"),+ ));+ }+ if let Ok(text) = fs::read_to_string(&port_file) {+ let mut lines = text.lines();+ if let (Some(port), Some(path)) = (lines.next(), lines.next()) {+ if let Ok(port) = port.parse::<u16>() {+ if path.starts_with("/devtools/browser/")+ && tokio::net::TcpStream::connect(("127.0.0.1", port))+ .await+ .is_ok()+ {+ return Ok(OwnedEndpoint {+ ws_url: format!("ws://127.0.0.1:{port}{path}"),+ http_port: Some(port),+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::SpawnedByDriver,+ owner_pid: i64::from(child.id()),+ detail: Some(+ "driver-spawned process and private profile port file"+ .to_owned(),+ ),+ },+ });+ }+ }+ }+ }+ if Instant::now() >= deadline {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "isolated browser did not expose a loopback DevTools endpoint before timeout",+ ));+ }+ tokio::time::sleep(Duration::from_millis(100)).await;+ }+}++async fn attest_spawned_endpoint(+ engine: &BrowserEngine,+ child_pid: i64,+ profile_endpoint: OwnedEndpoint,+) -> Result<OwnedEndpoint, BrowserRefusal> {+ let deadline = Instant::now() + Duration::from_secs(5);+ loop {+ if let Some(live) = engine.platform.discover_owned_endpoint(child_pid).await? {+ if live.http_port == profile_endpoint.http_port+ && live.ws_url == profile_endpoint.ws_url+ {+ return Ok(OwnedEndpoint {+ ws_url: live.ws_url,+ http_port: live.http_port,+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::SpawnedByDriver,+ owner_pid: child_pid,+ detail: Some(+ "driver-owned profile port file plus live loopback socket owner"+ .to_owned(),+ ),+ },+ });+ }+ }+ if Instant::now() >= deadline {+ return Err(refusal(+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,+ "the isolated browser profile endpoint did not match live loopback socket ownership",+ ));+ }+ tokio::time::sleep(Duration::from_millis(100)).await;+ }+}++impl BrowserEngine {+ pub(crate) fn cleanup_prepared_session(&self, session: &str) {+ self.managed_browsers+ .lock()+ .unwrap()+ .retain(|browser| !browser.owner_sessions.iter().any(|owner| owner == session));+ }++ pub(crate) async fn prepare_browser(+ &self,+ request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ match self.platform.prepare_endpoint(request.clone()).await {+ Ok(mut outcome) => {+ if outcome.prepared_pid.is_none() {+ outcome.prepared_pid = outcome+ .endpoint+ .as_ref()+ .map(|endpoint| endpoint.ownership.owner_pid);+ }+ return Ok(outcome);+ }+ Err(error) if error.code != BrowserRefusalCode::BrowserRequiresSetup => {+ return Err(error)+ }+ Err(_) => {}+ }++ if !request.allow_launch {+ return Err(refusal(+ BrowserRefusalCode::BrowserRequiresSetup,+ "no owned endpoint is available; pass allow_launch=true with an isolated profile and verified approval",+ ));+ }+ let profile_request = request.profile.as_ref().ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserConsentRequired,+ "acting setup requires profile.mode=isolated_new or isolated_named",+ )+ })?;+ validate_profile(profile_request)?;+ match request.authorization.as_ref() {+ Some(PrepareAuthorization::McpHost) => {}+ Some(PrepareAuthorization::ApprovalArtifact(token)) => {+ consume_prepare_approval(token, request.pid, profile_request)?;+ }+ None => {+ return Err(refusal(+ BrowserRefusalCode::BrowserConsentRequired,+ "browser preparation needs MCP host approval or a fresh browser-approve token",+ ))+ }+ }++ let classification = self.platform.classify_browser(request.pid).await?;+ if !classification.supports_cdp || classification.engine != BrowserEngineFamily::Chromium {+ return Err(refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "isolated automatic setup is currently supported only for Chromium browsers",+ ));+ }+ let fingerprint = self.platform.process_fingerprint(request.pid).await?;+ let executable = fingerprint.executable.ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "could not prove the requested browser executable for isolated launch",+ )+ })?;+ let prepared_profile = prepare_profile(profile_request)?;+ let mut command = isolated_browser_command(&executable, &prepared_profile.path);+ let mut child = command.spawn().map_err(|error| {+ cleanup_created_profile(&prepared_profile);+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not launch an isolated browser process: {error}"),+ )+ })?;+ let endpoint = match wait_for_spawned_endpoint(&mut child, &prepared_profile.path).await {+ Ok(endpoint) => {+ match attest_spawned_endpoint(self, i64::from(child.id()), endpoint).await {+ Ok(endpoint) => endpoint,+ Err(error) => {+ let _ = child.kill();+ let _ = child.wait();+ cleanup_created_profile(&prepared_profile);+ return Err(error);+ }+ }+ }+ Err(error) => {+ let _ = child.kill();+ let _ = child.wait();+ cleanup_created_profile(&prepared_profile);+ return Err(error);+ }+ };+ let prepared_pid = endpoint.ownership.owner_pid;+ let mut owner_sessions = vec![request.session];+ if let Some(transport_session) = request.transport_session {+ if !owner_sessions.contains(&transport_session) {+ owner_sessions.push(transport_session);+ }+ }+ self.managed_browsers.lock().unwrap().push(ManagedBrowser {+ child,+ profile: prepared_profile.path,+ delete_profile: prepared_profile.delete_on_cleanup,+ marker: prepared_profile.marker,+ owner_sessions,+ });+ Ok(PrepareOutcome {+ action: PrepareAction::LaunchedIsolatedBrowser,+ endpoint: Some(endpoint),+ message: "Launched a separate driver-owned isolated Chromium process; the requested browser process was not modified or terminated.".to_owned(),+ prepared_pid: Some(prepared_pid),+ side_effects: PrepareSideEffects {+ launched_browser: true,+ created_profile: prepared_profile.created,+ reused_driver_profile: !prepared_profile.created,+ ..PrepareSideEffects::default()+ },+ })+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn profile_marker_must_match_mode_and_name_exactly() {+ let path = std::env::temp_dir().join(format!(+ "cua-driver-profile-marker-test-{}",+ uuid::Uuid::new_v4()+ ));+ fs::create_dir(&path).unwrap();+ let expected = ProfileMarker {+ schema: PROFILE_SCHEMA.to_owned(),+ mode: PrepareProfileMode::IsolatedNamed,+ name: Some("research".to_owned()),+ };+ write_profile_marker(&path, &expected).unwrap();+ assert!(profile_matches_marker(&path, &expected));+ assert!(!profile_matches_marker(+ &path,+ &ProfileMarker {+ name: Some("other".to_owned()),+ ..expected.clone()+ }+ ));+ assert!(!profile_matches_marker(+ &path,+ &ProfileMarker {+ mode: PrepareProfileMode::IsolatedNew,+ name: None,+ ..expected.clone()+ }+ ));+ assert!(write_profile_marker(&path, &expected).is_err());+ fs::remove_dir_all(path).unwrap();+ }++ #[test]+ fn isolated_launch_uses_a_deterministic_clean_profile() {+ let profile = Path::new("profile-under-test");+ let command = isolated_browser_command("chromium-under-test", profile);+ let args = command+ .get_args()+ .map(|arg| arg.to_string_lossy().into_owned())+ .collect::<Vec<_>>();++ for required in [+ "--remote-debugging-port=0",+ "--user-data-dir=profile-under-test",+ "--no-first-run",+ "--no-default-browser-check",+ "--disable-background-networking",+ "--disable-component-update",+ "--disable-default-apps",+ "--disable-extensions",+ "about:blank",+ ] {+ assert!(args.iter().any(|arg| arg == required), "missing {required}");+ }+ #[cfg(target_os = "windows")]+ for required in ["--window-position=40,40", "--window-size=900,640"] {+ assert!(args.iter().any(|arg| arg == required), "missing {required}");+ }+ #[cfg(target_os = "linux")]+ assert!(args.iter().any(|arg| arg == "--password-store=basic"));+ }++ #[cfg(target_os = "linux")]+ #[test]+ fn isolated_launch_can_select_native_wayland_and_test_vm_sandbox_mode() {+ let mut command = Command::new("chromium-under-test");+ configure_linux_isolated_browser_command(&mut command, true, true);+ let args = command+ .get_args()+ .map(|arg| arg.to_string_lossy().into_owned())+ .collect::<Vec<_>>();+ assert!(args.iter().any(|arg| arg == "--password-store=basic"));+ assert!(args.iter().any(|arg| arg == "--ozone-platform=wayland"));+ assert!(args.iter().any(|arg| arg == "--no-sandbox"));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rsnew file mode 100644index 0000000000..5ab2a31ec9--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs@@ -0,0 +1,209 @@+//! Structured refusals for the browser-tool surface.+//!+//! The exact-or-refused contract means most failure paths are not+//! protocol errors — they are deliberate, machine-readable refusals the+//! calling agent is expected to branch on. A refusal serializes into+//! `structuredContent` as `{"status":"refused","refusal":{code,...}}`+//! with a stable snake_case `code` from the closed set below.++use serde::Serialize;+use serde_json::Value;++use crate::protocol::ToolResult;++/// Closed vocabulary of browser refusal codes. Additive-only: renaming+/// or removing a code is a breaking change for consumers that branch on+/// it.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]+#[serde(rename_all = "snake_case")]+pub enum BrowserRefusalCode {+ /// No CDP route exists for this process (not a browser, or an+ /// engine family without CDP support in v1).+ BrowserRouteUnavailable,+ /// The browser supports CDP but no owned endpoint is available —+ /// run `browser_prepare` explicitly.+ BrowserRequiresSetup,+ /// More than one CDP candidate matched the native window and the+ /// title tie-break could not pick a unique one.+ BrowserBindingAmbiguous,+ /// A previously minted binding no longer identifies the same+ /// process/endpoint (fingerprint drift, endpoint change, unknown or+ /// foreign-session target id).+ BrowserBindingStale,+ /// Revalidation could not prove the CDP target still corresponds to+ /// the bound native window, or mutation was attempted on a+ /// non-exact binding.+ BrowserWrongTargetRefused,+ /// The operation needs an explicit `tab_id` and none was given.+ BrowserTabRequired,+ /// The given `tab_id` is unknown in this session or its CDP target+ /// is gone.+ BrowserTabNotFound,+ /// The given page ref does not resolve in the tab's live snapshot+ /// namespace (malformed, foreign namespace, or invalidated by+ /// navigation).+ BrowserRefStale,+ /// The trusted Input-domain route is unavailable and the caller did+ /// not explicitly request the `dom_event` route.+ BrowserInputTrustUnavailable,+ /// The discovered endpoint's ownership proof does not attribute it+ /// to the target process.+ BrowserEndpointOwnerMismatch,+ /// The platform adapter requires explicit user/caller consent+ /// before it will prepare an endpoint.+ BrowserConsentRequired,+}++impl BrowserRefusalCode {+ /// The stable wire string for this code.+ pub fn as_str(&self) -> &'static str {+ match self {+ Self::BrowserRouteUnavailable => "browser_route_unavailable",+ Self::BrowserRequiresSetup => "browser_requires_setup",+ Self::BrowserBindingAmbiguous => "browser_binding_ambiguous",+ Self::BrowserBindingStale => "browser_binding_stale",+ Self::BrowserWrongTargetRefused => "browser_wrong_target_refused",+ Self::BrowserTabRequired => "browser_tab_required",+ Self::BrowserTabNotFound => "browser_tab_not_found",+ Self::BrowserRefStale => "browser_ref_stale",+ Self::BrowserInputTrustUnavailable => "browser_input_trust_unavailable",+ Self::BrowserEndpointOwnerMismatch => "browser_endpoint_owner_mismatch",+ Self::BrowserConsentRequired => "browser_consent_required",+ }+ }+}++/// A structured refusal: stable code + human-readable message ++/// optional machine detail (candidate lists, hints).+#[derive(Debug, Clone, Serialize)]+pub struct BrowserRefusal {+ pub code: BrowserRefusalCode,+ pub message: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub detail: Option<Value>,+}++impl BrowserRefusal {+ pub fn new(code: BrowserRefusalCode, message: impl Into<String>) -> Self {+ Self {+ code,+ message: message.into(),+ detail: None,+ }+ }++ pub fn with_detail(mut self, detail: Value) -> Self {+ self.detail = Some(detail);+ self+ }++ /// Render as a tool result. NOT an MCP protocol error: the call+ /// executed correctly and its outcome is the refusal, so `isError`+ /// stays unset and agents branch on `structuredContent.status`.+ pub fn to_tool_result(&self) -> ToolResult {+ let text = format!("refused ({}): {}", self.code.as_str(), self.message);+ ToolResult::text(text).with_structured(serde_json::json!({+ "status": "refused",+ "refusal": self,+ }))+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn every_code_serializes_to_the_documented_snake_case_string() {+ let all = [+ (+ BrowserRefusalCode::BrowserRouteUnavailable,+ "browser_route_unavailable",+ ),+ (+ BrowserRefusalCode::BrowserRequiresSetup,+ "browser_requires_setup",+ ),+ (+ BrowserRefusalCode::BrowserBindingAmbiguous,+ "browser_binding_ambiguous",+ ),+ (+ BrowserRefusalCode::BrowserBindingStale,+ "browser_binding_stale",+ ),+ (+ BrowserRefusalCode::BrowserWrongTargetRefused,+ "browser_wrong_target_refused",+ ),+ (+ BrowserRefusalCode::BrowserTabRequired,+ "browser_tab_required",+ ),+ (+ BrowserRefusalCode::BrowserTabNotFound,+ "browser_tab_not_found",+ ),+ (BrowserRefusalCode::BrowserRefStale, "browser_ref_stale"),+ (+ BrowserRefusalCode::BrowserInputTrustUnavailable,+ "browser_input_trust_unavailable",+ ),+ (+ BrowserRefusalCode::BrowserEndpointOwnerMismatch,+ "browser_endpoint_owner_mismatch",+ ),+ (+ BrowserRefusalCode::BrowserConsentRequired,+ "browser_consent_required",+ ),+ ];+ for (code, wire) in all {+ assert_eq!(code.as_str(), wire);+ // serde and as_str must agree — consumers see the serde form.+ assert_eq!(serde_json::to_value(code).unwrap(), serde_json::json!(wire));+ }+ }++ #[test]+ fn refusal_tool_result_shape_is_stable() {+ let refusal = BrowserRefusal::new(+ BrowserRefusalCode::BrowserRequiresSetup,+ "no owned DevTools endpoint",+ )+ .with_detail(serde_json::json!({"hint": "run browser_prepare"}));+ let result = refusal.to_tool_result();++ // Refusals are outcomes, not protocol errors.+ assert!(result.is_error.is_none());++ let structured = result.structured_content.expect("structured refusal");+ assert_eq!(structured["status"], "refused");+ assert_eq!(structured["refusal"]["code"], "browser_requires_setup");+ assert_eq!(+ structured["refusal"]["message"],+ "no owned DevTools endpoint"+ );+ assert_eq!(+ structured["refusal"]["detail"]["hint"],+ "run browser_prepare"+ );++ // The human-readable line carries the code for text-only clients.+ let text = match &result.content[0] {+ crate::protocol::Content::Text { text, .. } => text.clone(),+ other => panic!("expected text content, got {other:?}"),+ };+ assert!(text.contains("browser_requires_setup"), "{text}");+ }++ #[test]+ fn detail_is_omitted_when_absent() {+ let refusal = BrowserRefusal::new(BrowserRefusalCode::BrowserRefStale, "ref p1:2 not live");+ let v = serde_json::to_value(&refusal).unwrap();+ assert!(+ v.get("detail").is_none(),+ "absent detail must not serialize: {v}"+ );+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rsnew file mode 100644index 0000000000..b82eb75d2f--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/store.rs@@ -0,0 +1,483 @@+//! Session-scoped target / tab / page-ref capability store.+//!+//! Browser target ids (`bt-<uuid>`), tab ids (`tab-<uuid>`) and page refs+//! (`p<snapshot>:<index>`) are opaque, session-scoped capabilities:+//! they only resolve in the session that minted them, and the whole+//! namespace is dropped when that session ends. Ids are minted from a+//! process-global counter so they never collide across sessions — a+//! capability leaked into another session simply fails to resolve.+//!+//! Refs map internally to CDP `backendNodeId`s plus a [`FrameRef`]+//! recording which frame (main, same-process iframe, or OOPIF child+//! target) minted the node and that frame's document identity+//! (`frame_id` + `loader_id`) at snapshot time. Navigation invalidates+//! every snapshot of the navigated tab; stale refs refuse with+//! `browser_ref_stale`, and frame identity is re-proven against the+//! live frame tree before any mutation.++use std::collections::HashMap;+use std::sync::atomic::{AtomicU64, Ordering};+use std::sync::Mutex;++use serde::Serialize;+use uuid::Uuid;++use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::types::{BindingQuality, ProcessFingerprint, Rect};++/// Which frame kind a ref was minted in. Exposed on the wire as a+/// stable string via [`FrameKind::as_str`]; everything else about the+/// frame stays internal.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum FrameKind {+ /// The tab's main frame (including composed shadow DOM inside it).+ Main,+ /// A same-process iframe walked via `contentDocument`.+ Iframe,+ /// An out-of-process iframe reached through a capability-tested+ /// child session beneath the tab's target.+ Oopif,+}++impl FrameKind {+ pub fn as_str(&self) -> &'static str {+ match self {+ Self::Main => "main",+ Self::Iframe => "iframe",+ Self::Oopif => "oopif",+ }+ }+}++/// CDP frame/document identity captured at snapshot time. The+/// `loader_id` changes on every document load, so equality against the+/// live frame tree proves the ref's document is still the one that was+/// snapshotted.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct FrameIdentity {+ pub frame_id: String,+ pub loader_id: String,+}++/// The frame a ref belongs to, with everything needed to re-prove that+/// frame before mutation. Invariants enforced at mint time:+/// - `kind != Main` ⇒ `identity` is `Some` (unprovable frames are+/// omitted from snapshots, never guessed).+/// - `kind == Oopif` ⇔ `oopif_target_id` is `Some`.+#[derive(Debug, Clone)]+pub struct FrameRef {+ pub kind: FrameKind,+ /// CDP target id of the OOPIF child target (contained beneath the+ /// bound tab), present only for `Oopif` refs.+ pub oopif_target_id: Option<String>,+ /// Document identity at snapshot time. `None` only on the+ /// v1-compat main-frame path where the endpoint cannot report a+ /// frame tree; node liveness checks remain the backstop there.+ pub identity: Option<FrameIdentity>,+}++impl FrameRef {+ /// The v1-compat main-frame ref: no frame tree available, identity+ /// unproven, mutation falls back to node-liveness checks only.+ pub fn main_unproven() -> Self {+ Self {+ kind: FrameKind::Main,+ oopif_target_id: None,+ identity: None,+ }+ }+}++/// One interactive element captured in a page snapshot.+#[derive(Debug, Clone, Serialize)]+pub struct RefEntry {+ /// CDP backendNodeId — internal only, never exposed to callers.+ /// Valid in the tab's own session, or in the OOPIF child session+ /// named by `frame.oopif_target_id`.+ #[serde(skip_serializing)]+ pub backend_node_id: i64,+ pub node_name: String,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub label: Option<String>,+ /// Frame identity — internal; only the kind string is surfaced.+ #[serde(skip_serializing)]+ pub frame: FrameRef,+}++#[derive(Debug, Clone)]+pub struct SnapshotRecord {+ pub id: u64,+ pub url: String,+ /// index → entry; the external ref is `p<id>:<index>`.+ pub refs: HashMap<u32, RefEntry>,+}++#[derive(Debug, Clone)]+pub struct TabRecord {+ pub tab_id: String,+ pub cdp_target_id: String,+ pub snapshots: HashMap<u64, SnapshotRecord>,+}++/// One bound browser target: the full evidence set captured at bind+/// time, revalidated before every mutation.+#[derive(Debug, Clone)]+pub struct TargetRecord {+ pub target_id: String,+ pub pid: i64,+ pub window_id: u64,+ pub ws_url: String,+ pub endpoint_owner_pid: i64,+ pub fingerprint: ProcessFingerprint,+ pub native_title: String,+ pub native_bounds: Rect,+ pub cdp_target_id: String,+ /// CDP browser window id, or None for the exact single-page embedded route.+ pub cdp_window_id: Option<i64>,+ pub quality: BindingQuality,+ pub tabs: HashMap<String, TabRecord>,+}++#[derive(Default)]+struct SessionTargets {+ targets: HashMap<String, TargetRecord>,+}++/// Parse an external page ref of the form `p<snapshot>:<index>`.+/// Anything else — including refs from other namespaces such as the+/// accessibility `element_index` / element-token space — is rejected.+pub fn parse_ref(external: &str) -> Option<(u64, u32)> {+ let rest = external.strip_prefix('p')?;+ let (snap, idx) = rest.split_once(':')?;+ // Reject leading '+', whitespace, empty parts: only plain digits.+ if snap.is_empty()+ || idx.is_empty()+ || !snap.bytes().all(|b| b.is_ascii_digit())+ || !idx.bytes().all(|b| b.is_ascii_digit())+ {+ return None;+ }+ Some((snap.parse().ok()?, idx.parse().ok()?))+}++/// Format the external ref for a snapshot/index pair.+pub fn format_ref(snapshot_id: u64, index: u32) -> String {+ format!("p{snapshot_id}:{index}")+}++pub struct BrowserStore {+ inner: Mutex<HashMap<String, SessionTargets>>,+ next_id: AtomicU64,+}++impl BrowserStore {+ pub fn new() -> Self {+ Self {+ inner: Mutex::new(HashMap::new()),+ next_id: AtomicU64::new(1),+ }+ }++ fn next(&self) -> u64 {+ self.next_id.fetch_add(1, Ordering::Relaxed)+ }++ /// Mint a target id and insert the record under `session`.+ /// Panics never; the caller has already enforced that `session` is+ /// an explicit (non-default) session.+ pub fn mint_target(&self, session: &str, mut record: TargetRecord) -> String {+ let id = format!("bt-{}", Uuid::new_v4());+ record.target_id = id.clone();+ self.inner+ .lock()+ .unwrap()+ .entry(session.to_owned())+ .or_default()+ .targets+ .insert(id.clone(), record);+ id+ }++ /// Mint a fresh tab id (caller stores it via [`Self::update_target`]).+ pub fn mint_tab_id(&self) -> String {+ format!("tab-{}", Uuid::new_v4())+ }++ /// Mint a fresh snapshot id.+ pub fn mint_snapshot_id(&self) -> u64 {+ self.next()+ }++ /// Look up a target capability. Unknown ids — including ids minted+ /// by a *different* session — refuse with `browser_binding_stale`:+ /// the capability is simply not valid here.+ pub fn get_target(+ &self,+ session: &str,+ target_id: &str,+ ) -> Result<TargetRecord, BrowserRefusal> {+ self.inner+ .lock()+ .unwrap()+ .get(session)+ .and_then(|s| s.targets.get(target_id))+ .cloned()+ .ok_or_else(|| {+ BrowserRefusal::new(+ BrowserRefusalCode::BrowserBindingStale,+ format!(+ "target {target_id} is not a live binding in this session — \+ re-run get_browser_state with pid + window_id"+ ),+ )+ })+ }++ /// Mutate a stored target in place. No-op if it disappeared.+ pub fn update_target(&self, session: &str, target_id: &str, f: impl FnOnce(&mut TargetRecord)) {+ if let Some(rec) = self+ .inner+ .lock()+ .unwrap()+ .get_mut(session)+ .and_then(|s| s.targets.get_mut(target_id))+ {+ f(rec);+ }+ }++ /// Resolve an external page ref to a backendNodeId within one tab's+ /// live snapshot namespace.+ pub fn resolve_ref(+ &self,+ session: &str,+ target_id: &str,+ tab_id: &str,+ external: &str,+ ) -> Result<RefEntry, BrowserRefusal> {+ let (snap, idx) = parse_ref(external).ok_or_else(|| {+ BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ format!(+ "ref {external:?} is not a browser page ref — expected the \+ p<snapshot>:<index> namespace from get_browser_state"+ ),+ )+ })?;+ let target = self.get_target(session, target_id)?;+ let tab = target.tabs.get(tab_id).ok_or_else(|| {+ BrowserRefusal::new(+ BrowserRefusalCode::BrowserTabNotFound,+ format!("tab {tab_id} is not known for target {target_id}"),+ )+ })?;+ tab.snapshots+ .get(&snap)+ .and_then(|s| s.refs.get(&idx))+ .cloned()+ .ok_or_else(|| {+ BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ format!(+ "ref {external} is stale — the page navigated or the snapshot \+ was superseded; re-run get_browser_state to re-snapshot"+ ),+ )+ })+ }++ /// Drop every snapshot of one tab (navigation invalidates refs).+ pub fn invalidate_tab_snapshots(&self, session: &str, target_id: &str, tab_id: &str) {+ self.update_target(session, target_id, |rec| {+ if let Some(tab) = rec.tabs.get_mut(tab_id) {+ tab.snapshots.clear();+ }+ });+ }++ /// Drop the whole namespace for an ended session. Wired to+ /// `session::register_session_end_hook` by the engine.+ pub fn remove_session(&self, session: &str) {+ self.inner.lock().unwrap().remove(session);+ }++ /// Number of live targets in a session (diagnostics/tests).+ pub fn target_count(&self, session: &str) -> usize {+ self.inner+ .lock()+ .unwrap()+ .get(session)+ .map_or(0, |s| s.targets.len())+ }+}++impl Default for BrowserStore {+ fn default() -> Self {+ Self::new()+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::browser::types::BindingQuality;++ fn record() -> TargetRecord {+ TargetRecord {+ target_id: String::new(),+ pid: 42,+ window_id: 7,+ ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),+ endpoint_owner_pid: 42,+ fingerprint: ProcessFingerprint {+ pid: 42,+ start_time: Some(1),+ executable: None,+ },+ native_title: "Docs - Chrome".into(),+ native_bounds: Rect::new(0.0, 0.0, 800.0, 600.0),+ cdp_target_id: "CDP1".into(),+ cdp_window_id: Some(11),+ quality: BindingQuality::Exact,+ tabs: HashMap::new(),+ }+ }++ fn store_with_ref() -> (BrowserStore, String, String, String) {+ let store = BrowserStore::new();+ let tid = store.mint_target("sess-a", record());+ let tab_id = store.mint_tab_id();+ let snap_id = store.mint_snapshot_id();+ let ext = format_ref(snap_id, 0);+ store.update_target("sess-a", &tid, |rec| {+ let mut refs = HashMap::new();+ refs.insert(+ 0,+ RefEntry {+ backend_node_id: 555,+ node_name: "button".into(),+ label: Some("Submit".into()),+ frame: FrameRef {+ kind: FrameKind::Main,+ oopif_target_id: None,+ identity: Some(FrameIdentity {+ frame_id: "F_MAIN".into(),+ loader_id: "L1".into(),+ }),+ },+ },+ );+ rec.tabs.insert(+ tab_id.clone(),+ TabRecord {+ tab_id: tab_id.clone(),+ cdp_target_id: "CDP1".into(),+ snapshots: HashMap::from([(+ snap_id,+ SnapshotRecord {+ id: snap_id,+ url: "https://example.test".into(),+ refs,+ },+ )]),+ },+ );+ });+ (store, tid, tab_id, ext)+ }++ #[test]+ fn ref_parsing_accepts_only_the_p_namespace() {+ assert_eq!(parse_ref("p12:5"), Some((12, 5)));+ assert_eq!(parse_ref("p0:0"), Some((0, 0)));+ for bad in [+ "e12", "12:5", "p:5", "p12:", "p-1:2", "p 1:2", "p1:+2", "p1", "",+ ] {+ assert_eq!(parse_ref(bad), None, "must reject {bad:?}");+ }+ }++ #[test]+ fn resolve_ref_happy_path() {+ let (store, tid, tab, ext) = store_with_ref();+ let entry = store.resolve_ref("sess-a", &tid, &tab, &ext).unwrap();+ assert_eq!(entry.backend_node_id, 555);+ assert_eq!(entry.node_name, "button");+ assert_eq!(entry.frame.kind, FrameKind::Main);+ assert_eq!(+ entry.frame.identity.as_ref().map(|i| i.loader_id.as_str()),+ Some("L1")+ );+ }++ #[test]+ fn ref_entry_serialization_hides_internal_identifiers() {+ let (store, tid, tab, ext) = store_with_ref();+ let entry = store.resolve_ref("sess-a", &tid, &tab, &ext).unwrap();+ let v = serde_json::to_value(&entry).unwrap();+ assert!(v.get("backend_node_id").is_none(), "{v}");+ assert!(v.get("frame").is_none(), "frame identity is internal: {v}");+ }++ #[test]+ fn target_ids_do_not_resolve_in_a_foreign_session() {+ let (store, tid, tab, ext) = store_with_ref();+ let err = store.resolve_ref("sess-b", &tid, &tab, &ext).unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserBindingStale);+ let err = store.get_target("sess-b", &tid).unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserBindingStale);+ }++ #[test]+ fn foreign_namespace_refs_are_refused_as_stale() {+ let (store, tid, tab, _) = store_with_ref();+ // An accessibility element_index-style ref must not resolve.+ let err = store.resolve_ref("sess-a", &tid, &tab, "e42").unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserRefStale);+ }++ #[test]+ fn unknown_snapshot_or_index_is_stale() {+ let (store, tid, tab, _) = store_with_ref();+ let err = store+ .resolve_ref("sess-a", &tid, &tab, "p999999:0")+ .unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserRefStale);+ }++ #[test]+ fn unknown_tab_is_tab_not_found() {+ let (store, tid, _, ext) = store_with_ref();+ let err = store+ .resolve_ref("sess-a", &tid, "tab999", &ext)+ .unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserTabNotFound);+ }++ #[test]+ fn navigation_invalidates_tab_refs() {+ let (store, tid, tab, ext) = store_with_ref();+ assert!(store.resolve_ref("sess-a", &tid, &tab, &ext).is_ok());+ store.invalidate_tab_snapshots("sess-a", &tid, &tab);+ let err = store.resolve_ref("sess-a", &tid, &tab, &ext).unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserRefStale);+ }++ #[test]+ fn remove_session_drops_the_whole_namespace() {+ let (store, tid, tab, ext) = store_with_ref();+ assert_eq!(store.target_count("sess-a"), 1);+ store.remove_session("sess-a");+ assert_eq!(store.target_count("sess-a"), 0);+ let err = store.resolve_ref("sess-a", &tid, &tab, &ext).unwrap_err();+ assert_eq!(err.code, BrowserRefusalCode::BrowserBindingStale);+ }++ #[test]+ fn minted_ids_are_unique_across_sessions() {+ let store = BrowserStore::new();+ let a = store.mint_target("s1", record());+ let b = store.mint_target("s2", record());+ assert_ne!(a, b, "capability ids must never collide across sessions");+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rsnew file mode 100644index 0000000000..e6140bf878--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs@@ -0,0 +1,1477 @@+//! The five browser tools: get_browser_state, browser_prepare,+//! browser_navigate, browser_click, browser_type.+//!+//! Schemas, annotations, and exact-or-refused semantics live here; OS+//! identity comes from the [`BrowserPlatform`] adapter; CDP mechanics+//! from [`super::engine`]. All structured outputs share the shape+//! `{"status": "ok" | "refused", ...}`.++use std::sync::Arc;++use async_trait::async_trait;+use serde_json::{json, Value};++use crate::protocol::ToolResult;+use crate::tool::{Tool, ToolDef, ToolRegistry};+use crate::tool_args::ArgsExt;++use super::approval::MCP_HOST_APPROVAL_ARG;+use super::engine::BrowserEngine;+use super::platform::{PrepareAuthorization, PrepareProfile, PrepareRequest};+use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::types::BindingQuality;++/// Register all five browser tools against one shared engine. Platform+/// crates call this from their `register_all` after constructing the+/// engine with their adapter.+pub fn register_browser_tools(engine: &Arc<BrowserEngine>, registry: &mut ToolRegistry) {+ registry.register(Box::new(GetBrowserStateTool::new(engine.clone())));+ registry.register(Box::new(BrowserPrepareTool::new(engine.clone())));+ registry.register(Box::new(BrowserNavigateTool::new(engine.clone())));+ registry.register(Box::new(BrowserClickTool::new(engine.clone())));+ registry.register(Box::new(BrowserTypeTool::new(engine.clone())));+}++// ── Shared helpers ───────────────────────────────────────────────────────────++/// The public caller session id, falling back to the daemon's internal mirror.+fn session_of(args: &Value) -> String {+ args.opt_str("session")+ .or_else(|| args.opt_str("_session_id"))+ .unwrap_or_else(|| "default".into())+}++/// Target/ref minting requires an explicit (non-default) session so the+/// capability namespace has a real owner whose end event cleans it up.+fn require_explicit_session(args: &Value) -> Result<String, ToolResult> {+ let sid = session_of(args);+ if sid.is_empty() || sid == "default" {+ return Err(ToolResult::error(+ "Browser targets and page refs are session-scoped capabilities — declare an \+ explicit session (start_session) and pass its id on this call.",+ ));+ }+ Ok(sid)+}++fn schema_target_id() -> Value {+ json!({+ "type": "string",+ "description": "Opaque browser target id minted by get_browser_state \+ (session-scoped; never a CDP id)."+ })+}++fn schema_tab_id() -> Value {+ json!({+ "type": "string",+ "description": "Opaque tab id from get_browser_state (session-scoped)."+ })+}++fn schema_ref() -> Value {+ json!({+ "type": "string",+ "description": "Page element ref in the p<snapshot>:<index> namespace from \+ get_browser_state. Refs are invalidated by navigation and by newer \+ snapshots of the same tab."+ })+}++fn schema_session() -> Value {+ json!({+ "type": "string",+ "description": "Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session."+ })+}++// ── get_browser_state ────────────────────────────────────────────────────────++pub struct GetBrowserStateTool {+ def: ToolDef,+ engine: Arc<BrowserEngine>,+}++impl GetBrowserStateTool {+ pub fn new(engine: Arc<BrowserEngine>) -> Self {+ let def = ToolDef {+ name: "get_browser_state".into(),+ description: "Read-only browser inspection. Mode 1 (bind): pass pid + \+ window_id of a native browser window to classify it, correlate it to \+ a CDP target (exact-or-refuse), and mint a session-scoped target id \+ plus tab ids. Mode 2 (snapshot): pass target_id + tab_id to snapshot \+ the tab's composed DOM (main frame, shadow DOM, same-process iframes, \+ and capability-tested out-of-process iframes) and mint \+ p<snapshot>:<index> element refs for browser_click / browser_type; \+ each ref reports its frame kind. Never performs setup — a missing \+ endpoint is a structured browser_requires_setup refusal pointing at \+ browser_prepare."+ .into(),+ input_schema: json!({+ "type": "object",+ "properties": {+ "pid": { "type": "integer", "description": "Native browser process id (bind mode)." },+ "window_id": { "type": "integer", "description": "Native window id owned by pid (bind mode)." },+ "target_id": schema_target_id(),+ "tab_id": schema_tab_id(),+ "session": schema_session(),+ },+ "additionalProperties": true+ }),+ read_only: true,+ destructive: false,+ idempotent: true,+ open_world: false,+ };+ Self { def, engine }+ }+}++#[async_trait]+impl Tool for GetBrowserStateTool {+ fn def(&self) -> &ToolDef {+ &self.def+ }++ async fn invoke(&self, args: Value) -> ToolResult {+ // Snapshot mode: target_id (+ tab_id) — uses existing capabilities.+ if let Some(target_id) = args.opt_str("target_id") {+ let session = match require_explicit_session(&args) {+ Ok(s) => s,+ Err(e) => return e,+ };+ let tab_id = match args.opt_str("tab_id") {+ Some(t) => t,+ None => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserTabRequired,+ "snapshot mode requires a tab_id from a prior bind",+ )+ .to_tool_result()+ }+ };+ return match self+ .engine+ .snapshot_tab(&session, &target_id, &tab_id)+ .await+ {+ Ok(outcome) => {+ let ref_list: Vec<Value> = outcome+ .refs+ .iter()+ .map(|(ext, entry)| {+ json!({+ "ref": ext,+ "node": entry.node_name,+ "label": entry.label,+ "frame": entry.frame.kind.as_str(),+ })+ })+ .collect();+ ToolResult::text(format!(+ "snapshot p{} of {}: {} interactive element(s)",+ outcome.snapshot_id,+ outcome.url,+ ref_list.len()+ ))+ .with_structured(json!({+ "status": "ok",+ "mode": "snapshot",+ "target_id": target_id,+ "tab_id": tab_id,+ "snapshot_id": format!("p{}", outcome.snapshot_id),+ "url": outcome.url,+ "refs": ref_list,+ "truncated": outcome.truncated,+ "oopif": {+ "status": outcome.oopif.as_str(),+ "frames": outcome.oopif.frames(),+ },+ }))+ }+ Err(refusal) => refusal.to_tool_result(),+ };+ }++ // Bind mode: pid + window_id.+ let pid = match args.require_i64("pid") {+ Ok(v) => v,+ Err(e) => return e,+ };+ let window_id = match args.require_u64("window_id") {+ Ok(v) => v,+ Err(e) => return e,+ };+ let session = match require_explicit_session(&args) {+ Ok(s) => s,+ Err(e) => return e,+ };++ match self.engine.bind_native(&session, pid, window_id).await {+ Ok((target_id, record)) => {+ let tabs: Vec<Value> = record+ .tabs+ .values()+ .map(|t| {+ json!({+ "tab_id": t.tab_id,+ "active": t.cdp_target_id == record.cdp_target_id,+ })+ })+ .collect();+ let quality = match record.quality {+ BindingQuality::Exact => "exact",+ BindingQuality::Heuristic => "heuristic",+ };+ let binding_route = if record.cdp_window_id.is_some() {+ "native_cdp_window"+ } else {+ "embedded_single_page"+ };+ ToolResult::text(format!(+ "bound target {target_id} ({quality}) with {} tab(s)",+ tabs.len()+ ))+ .with_structured(json!({+ "status": "ok",+ "mode": "bind",+ "target_id": target_id,+ "binding_quality": quality,+ "binding_route": binding_route,+ "mutation_allowed": record.quality == BindingQuality::Exact,+ "native_title": record.native_title,+ "tabs": tabs,+ }))+ }+ Err(refusal) => refusal.to_tool_result(),+ }+ }+}++// ── browser_prepare ──────────────────────────────────────────────────────────++pub struct BrowserPrepareTool {+ def: ToolDef,+ engine: Arc<BrowserEngine>,+}++impl BrowserPrepareTool {+ pub fn new(engine: Arc<BrowserEngine>) -> Self {+ let def = ToolDef {+ name: "browser_prepare".into(),+ description: "Explicitly prepare an owned DevTools endpoint for a browser \+ pid. Existing endpoints are detected without side effects. Acting setup \+ requires MCP-host approval or a short-lived token from the interactive \+ browser-approve command, allow_launch=true, and a driver-owned isolated \+ profile. It launches a separate browser and never copies, modifies, or \+ terminates the requested user profile."+ .into(),+ input_schema: json!({+ "type": "object",+ "properties": {+ "pid": { "type": "integer", "description": "Browser process id to prepare." },+ "approval_token": {+ "type": "string",+ "description": "Single-use token minted by `cua-driver browser-approve` for direct CLI/raw use. Omit for an MCP-host-approved call."+ },+ "allow_launch": {+ "type": "boolean",+ "description": "Allow a separate driver-owned isolated Chromium process to be launched (default false)."+ },+ "profile": {+ "type": "object",+ "properties": {+ "mode": { "type": "string", "enum": ["isolated_new", "isolated_named"] },+ "name": { "type": "string", "description": "Required only for isolated_named; 1-64 path-safe ASCII characters." }+ },+ "required": ["mode"],+ "additionalProperties": false+ },+ "session": schema_session(),+ },+ "required": ["pid"],+ "additionalProperties": true+ }),+ read_only: false,+ destructive: true,+ idempotent: false,+ open_world: false,+ };+ Self { def, engine }+ }+}++#[async_trait]+impl Tool for BrowserPrepareTool {+ fn def(&self) -> &ToolDef {+ &self.def+ }++ async fn invoke(&self, args: Value) -> ToolResult {+ let pid = match args.require_i64("pid") {+ Ok(v) => v,+ Err(e) => return e,+ };+ let session = match require_explicit_session(&args) {+ Ok(session) => session,+ Err(error) => return error,+ };+ let profile = match args.get("profile") {+ None | Some(Value::Null) => None,+ Some(value) => match serde_json::from_value::<PrepareProfile>(value.clone()) {+ Ok(profile) => Some(profile),+ Err(error) => {+ return ToolResult::error(format!("invalid browser profile request: {error}"))+ }+ },+ };+ let authorization = if args+ .get(MCP_HOST_APPROVAL_ARG)+ .and_then(Value::as_bool)+ .unwrap_or(false)+ {+ Some(PrepareAuthorization::McpHost)+ } else {+ args.opt_str("approval_token")+ .map(PrepareAuthorization::ApprovalArtifact)+ };+ let request = PrepareRequest {+ pid,+ session,+ transport_session: args.opt_str("_transport_session_id"),+ authorization,+ profile,+ allow_launch: args.opt_bool("allow_launch").unwrap_or(false),+ };+ match self.engine.prepare_browser(request).await {+ Ok(outcome) => {+ let prepared = outcome.endpoint.is_some();+ ToolResult::text(format!(+ "browser_prepare: {} — {}",+ if prepared {+ "endpoint available"+ } else {+ "no endpoint"+ },+ outcome.message+ ))+ .with_structured(json!({+ "status": "ok",+ "prepared": prepared,+ "action": outcome.action,+ "message": outcome.message,+ // The ws_url itself stays internal; expose only proof metadata.+ "endpoint_ownership": outcome.endpoint.map(|e| e.ownership),+ "prepared_pid": outcome.prepared_pid,+ "side_effects": outcome.side_effects,+ }))+ }+ Err(refusal) => refusal.to_tool_result(),+ }+ }+}++// ── browser_navigate ─────────────────────────────────────────────────────────++pub struct BrowserNavigateTool {+ def: ToolDef,+ engine: Arc<BrowserEngine>,+}++impl BrowserNavigateTool {+ pub fn new(engine: Arc<BrowserEngine>) -> Self {+ let def = ToolDef {+ name: "browser_navigate".into(),+ description: "Navigate one tab of an exactly-bound browser target to a \+ new URL (http/https/about only). Refused for heuristic bindings. \+ Navigation invalidates all p<snapshot>:<index> refs for the tab."+ .into(),+ input_schema: json!({+ "type": "object",+ "properties": {+ "target_id": schema_target_id(),+ "tab_id": schema_tab_id(),+ "url": { "type": "string", "description": "Destination URL (http:, https:, or about:)." },+ "session": schema_session(),+ },+ "required": ["target_id", "tab_id", "url"],+ "additionalProperties": true+ }),+ read_only: false,+ destructive: false,+ idempotent: false,+ open_world: true,+ };+ Self { def, engine }+ }+}++#[async_trait]+impl Tool for BrowserNavigateTool {+ fn def(&self) -> &ToolDef {+ &self.def+ }++ async fn invoke(&self, args: Value) -> ToolResult {+ let (target_id, tab_id, url) = match (+ args.require_str("target_id"),+ args.require_str("tab_id"),+ args.require_str("url"),+ ) {+ (Ok(t), Ok(tab), Ok(u)) => (t, tab, u),+ (Err(e), _, _) | (_, Err(e), _) | (_, _, Err(e)) => return e,+ };+ let session = match require_explicit_session(&args) {+ Ok(s) => s,+ Err(e) => return e,+ };+ let lower = url.to_ascii_lowercase();+ if !(lower.starts_with("http://")+ || lower.starts_with("https://")+ || lower.starts_with("about:"))+ {+ return ToolResult::error(format!(+ "browser_navigate only accepts http/https/about URLs, got: {url}"+ ));+ }++ let validated = match self+ .engine+ .revalidate_for_mutation(&session, &target_id, Some(&tab_id))+ .await+ {+ Ok(v) => v,+ Err(refusal) => return refusal.to_tool_result(),+ };++ match validated+ .conn+ .call(+ Some(&validated.cdp_session),+ "Page.navigate",+ json!({ "url": url }),+ )+ .await+ {+ Ok(result) => {+ if let Some(err_text) = result.get("errorText").and_then(Value::as_str) {+ return ToolResult::error(format!("navigation failed: {err_text}"));+ }+ // Refs die with the old document.+ self.engine+ .store+ .invalidate_tab_snapshots(&session, &target_id, &tab_id);+ ToolResult::text(format!("navigated {tab_id} to {url}")).with_structured(json!({+ "status": "ok",+ "target_id": target_id,+ "tab_id": tab_id,+ "url": url,+ "refs_invalidated": true,+ }))+ }+ Err(e) => ToolResult::error(format!("Page.navigate failed: {e}")),+ }+ }+}++// ── browser_click ────────────────────────────────────────────────────────────++pub struct BrowserClickTool {+ def: ToolDef,+ engine: Arc<BrowserEngine>,+}++impl BrowserClickTool {+ pub fn new(engine: Arc<BrowserEngine>) -> Self {+ let def = ToolDef {+ name: "browser_click".into(),+ description: "Click a page element (by ref) or viewport coordinates in an \+ exactly-bound tab. Default route is trusted hardware-like input \+ (Input.dispatchMouseEvent), and refuses where that route cannot \+ preserve standalone-browser background posture. \+ input_route=\"dom_event\" (synthetic \+ el.click(), ref required) is used only when explicitly requested. \+ Refused for heuristic bindings."+ .into(),+ input_schema: json!({+ "type": "object",+ "properties": {+ "target_id": schema_target_id(),+ "tab_id": schema_tab_id(),+ "session": schema_session(),+ "ref": schema_ref(),+ "x": { "type": "number", "description": "Viewport x (CSS px) — alternative to ref." },+ "y": { "type": "number", "description": "Viewport y (CSS px) — alternative to ref." },+ "input_route": {+ "type": "string",+ "enum": ["trusted", "dom_event"],+ "description": "\"trusted\" (default): Input.dispatchMouseEvent. \+ It refuses rather than foregrounding a standalone browser. \+ \"dom_event\": synthetic full-background DOM click, only \+ when explicitly requested."+ },+ },+ "required": ["target_id", "tab_id"],+ "additionalProperties": true+ }),+ read_only: false,+ destructive: false,+ idempotent: false,+ open_world: false,+ };+ Self { def, engine }+ }+}++#[async_trait]+impl Tool for BrowserClickTool {+ fn def(&self) -> &ToolDef {+ &self.def+ }++ async fn invoke(&self, args: Value) -> ToolResult {+ let (target_id, tab_id) = match (args.require_str("target_id"), args.require_str("tab_id"))+ {+ (Ok(t), Ok(tab)) => (t, tab),+ (Err(e), _) | (_, Err(e)) => return e,+ };+ let session = match require_explicit_session(&args) {+ Ok(s) => s,+ Err(e) => return e,+ };+ let route = args+ .opt_str("input_route")+ .unwrap_or_else(|| "trusted".into());+ if route != "trusted" && route != "dom_event" {+ return ToolResult::error(format!(+ "input_route must be \"trusted\" or \"dom_event\", got {route:?}"+ ));+ }+ let ext_ref = args.opt_str("ref");+ let coords = match (args.opt_f64("x"), args.opt_f64("y")) {+ (Some(x), Some(y)) => Some((x, y)),+ (None, None) => None,+ _ => return ToolResult::error("pass both x and y, or neither"),+ };+ if ext_ref.is_none() && coords.is_none() {+ return ToolResult::error("browser_click needs a ref or x/y coordinates");+ }+ if route == "dom_event" && ext_ref.is_none() {+ return ToolResult::error("input_route=dom_event requires a ref");+ }++ // Resolve the ref BEFORE revalidation? No — revalidate first so a+ // stale binding refuses before we touch the page at all.+ let validated = match self+ .engine+ .revalidate_for_mutation(&session, &target_id, Some(&tab_id))+ .await+ {+ Ok(v) => v,+ Err(refusal) => return refusal.to_tool_result(),+ };+ if route == "trusted" && validated.record.cdp_window_id.is_some() {+ if let Some(limitation) = self+ .engine+ .platform+ .standalone_trusted_input_background_limitation()+ {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserInputTrustUnavailable,+ format!(+ "{limitation}; use input_route=\"dom_event\" with a ref for a synthetic full-background click"+ ),+ )+ .to_tool_result();+ }+ }++ // Ref path: re-prove the ref's frame/document identity and get+ // the session (tab or contained OOPIF child) its node lives in.+ let (backend_node_id, frame_kind, cdp_session) = match &ext_ref {+ Some(r) => {+ let entry = match self+ .engine+ .store+ .resolve_ref(&session, &target_id, &tab_id, r)+ {+ Ok(entry) => entry,+ Err(refusal) => return refusal.to_tool_result(),+ };+ let frame_session = match self+ .engine+ .frame_session_for_mutation(+ &session,+ &target_id,+ &tab_id,+ &validated,+ &entry.frame,+ )+ .await+ {+ Ok(s) => s,+ Err(refusal) => return refusal.to_tool_result(),+ };+ (+ Some(entry.backend_node_id),+ Some(entry.frame.kind.as_str()),+ frame_session,+ )+ }+ None => (None, None, validated.cdp_session.clone()),+ };++ let conn = &validated.conn;+ let cdp = cdp_session.as_str();++ // dom_event route: explicit opt-in only.+ if route == "dom_event" {+ let backend = backend_node_id.expect("checked above");+ let resolved = match conn+ .call(+ Some(cdp),+ "DOM.resolveNode",+ json!({ "backendNodeId": backend }),+ )+ .await+ {+ Ok(v) => v,+ Err(_) => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node no longer resolves in the live page",+ )+ .to_tool_result()+ }+ };+ let object_id = match resolved+ .get("object")+ .and_then(|o| o.get("objectId"))+ .and_then(Value::as_str)+ {+ Some(o) => o.to_owned(),+ None => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node has no live object in the page",+ )+ .to_tool_result()+ }+ };+ return match conn+ .call(+ Some(cdp),+ "Runtime.callFunctionOn",+ json!({+ "objectId": object_id,+ "functionDeclaration": "function() { this.click(); }",+ }),+ )+ .await+ {+ Ok(_) => ToolResult::text(format!(+ "dispatched DOM click on {} in {tab_id}",+ ext_ref.as_deref().unwrap_or("?")+ ))+ .with_structured(json!({+ "status": "ok",+ "route": "dom_event",+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": ext_ref,+ "frame": frame_kind,+ })),+ Err(e) => ToolResult::error(format!("DOM click failed: {e}")),+ };+ }++ // Trusted route: resolve a click point, then Input.dispatchMouseEvent.+ let (x, y) = match (backend_node_id, coords) {+ (Some(backend), _) => {+ // Best effort scroll-into-view; ignore failure (older Chromium).+ let _ = conn+ .call(+ Some(cdp),+ "DOM.scrollIntoViewIfNeeded",+ json!({ "backendNodeId": backend }),+ )+ .await;+ let box_model = match conn+ .call(+ Some(cdp),+ "DOM.getBoxModel",+ json!({ "backendNodeId": backend }),+ )+ .await+ {+ Ok(v) => v,+ Err(_) => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node has no layout box — it left the DOM or is hidden",+ )+ .to_tool_result()+ }+ };+ match quad_center(&box_model) {+ Some(pt) => pt,+ None => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node returned an unusable layout box",+ )+ .to_tool_result()+ }+ }+ }+ (None, Some(pt)) => pt,+ (None, None) => unreachable!("validated above"),+ };++ for (event_type, click_count) in [("mousePressed", 1), ("mouseReleased", 1)] {+ if let Err(e) = conn+ .call(+ Some(cdp),+ "Input.dispatchMouseEvent",+ json!({+ "type": event_type,+ "x": x,+ "y": y,+ "button": "left",+ "clickCount": click_count,+ }),+ )+ .await+ {+ // Trusted input is the contract; we never silently fall+ // back to synthetic events.+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserInputTrustUnavailable,+ format!(+ "trusted Input route failed ({e}) — re-run with \+ input_route=\"dom_event\" to explicitly request a synthetic click"+ ),+ )+ .to_tool_result();+ }+ }+ ToolResult::text(format!("clicked ({x:.0}, {y:.0}) in {tab_id}")).with_structured(json!({+ "status": "ok",+ "route": "trusted",+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": ext_ref,+ "frame": frame_kind,+ "x": x,+ "y": y,+ }))+ }+}++/// Center of the content quad from a `DOM.getBoxModel` result.+fn quad_center(box_model: &Value) -> Option<(f64, f64)> {+ let quad = box_model.get("model")?.get("content")?.as_array()?;+ if quad.len() < 8 {+ return None;+ }+ let nums: Vec<f64> = quad.iter().filter_map(Value::as_f64).collect();+ if nums.len() < 8 {+ return None;+ }+ let xs = [nums[0], nums[2], nums[4], nums[6]];+ let ys = [nums[1], nums[3], nums[5], nums[7]];+ Some((xs.iter().sum::<f64>() / 4.0, ys.iter().sum::<f64>() / 4.0))+}++// ── browser_type ─────────────────────────────────────────────────────────────++/// Editability check evaluated ON the ref's node (`this`), so focus is+/// verified against the node's own root — Document or ShadowRoot — and+/// behaves the same in the main frame, composed shadow DOM,+/// same-process iframes, and OOPIF child documents.+const EDITABLE_AND_FOCUSED_CHECK: &str = "function() { \+ const root = this.getRootNode(); \+ const active = ('activeElement' in root) ? root.activeElement : null; \+ if (active !== this) return false; \+ if (this.isContentEditable) return true; \+ if (this.tagName === 'TEXTAREA') return !this.disabled && !this.readOnly; \+ if (this.tagName !== 'INPUT') return false; \+ return !this.disabled && !this.readOnly && \+ !['button','checkbox','color','file','hidden','image','radio','range','reset','submit']\+ .includes((this.type || 'text').toLowerCase()); \+}";++pub struct BrowserTypeTool {+ def: ToolDef,+ engine: Arc<BrowserEngine>,+}++impl BrowserTypeTool {+ pub fn new(engine: Arc<BrowserEngine>) -> Self {+ let def = ToolDef {+ name: "browser_type".into(),+ description: "Type text into an exactly-bound tab via the Input domain. \+ mode=\"insert_text\" (default) uses Input.insertText; \+ mode=\"keystrokes\" dispatches per-character key events. Pass a ref \+ to an editable element from the latest snapshot. A ref is required; \+ heuristic bindings are refused."+ .into(),+ input_schema: json!({+ "type": "object",+ "properties": {+ "target_id": schema_target_id(),+ "tab_id": schema_tab_id(),+ "session": schema_session(),+ "text": { "type": "string", "description": "Text to type." },+ "ref": schema_ref(),+ "mode": {+ "type": "string",+ "enum": ["insert_text", "keystrokes"],+ "description": "insert_text (default): bulk Input.insertText. \+ keystrokes: per-character Input.dispatchKeyEvent."+ },+ },+ "required": ["target_id", "tab_id", "ref", "text"],+ "additionalProperties": true+ }),+ read_only: false,+ destructive: false,+ idempotent: false,+ open_world: false,+ };+ Self { def, engine }+ }+}++#[async_trait]+impl Tool for BrowserTypeTool {+ fn def(&self) -> &ToolDef {+ &self.def+ }++ async fn invoke(&self, args: Value) -> ToolResult {+ let (target_id, tab_id, text) = match (+ args.require_str("target_id"),+ args.require_str("tab_id"),+ args.require_str("text"),+ ) {+ (Ok(t), Ok(tab), Ok(x)) => (t, tab, x),+ (Err(e), _, _) | (_, Err(e), _) | (_, _, Err(e)) => return e,+ };+ let session = match require_explicit_session(&args) {+ Ok(s) => s,+ Err(e) => return e,+ };+ let mode = args.opt_str("mode").unwrap_or_else(|| "insert_text".into());+ if mode != "insert_text" && mode != "keystrokes" {+ return ToolResult::error(format!(+ "mode must be \"insert_text\" or \"keystrokes\", got {mode:?}"+ ));+ }++ let validated = match self+ .engine+ .revalidate_for_mutation(&session, &target_id, Some(&tab_id))+ .await+ {+ Ok(v) => v,+ Err(refusal) => return refusal.to_tool_result(),+ };++ let ext_ref = match args.require_str("ref") {+ Ok(value) => value,+ Err(error) => return error,+ };+ let entry = match self+ .engine+ .store+ .resolve_ref(&session, &target_id, &tab_id, &ext_ref)+ {+ Ok(e) => e,+ Err(refusal) => return refusal.to_tool_result(),+ };+ // Re-prove the ref's frame identity; typing routes to the frame's+ // own session (tab, or the contained OOPIF child session).+ let cdp_session = match self+ .engine+ .frame_session_for_mutation(&session, &target_id, &tab_id, &validated, &entry.frame)+ .await+ {+ Ok(s) => s,+ Err(refusal) => return refusal.to_tool_result(),+ };+ let conn = &validated.conn;+ let cdp = cdp_session.as_str();++ if let Err(_e) = conn+ .call(+ Some(cdp),+ "DOM.focus",+ json!({ "backendNodeId": entry.backend_node_id }),+ )+ .await+ {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node can no longer be focused — re-snapshot the tab",+ )+ .to_tool_result();+ }+ // Frame- and shadow-aware editability check: evaluated on the+ // ref's own node so it works identically for the main document,+ // shadow roots (getRootNode().activeElement), same-process+ // iframes, and OOPIF child documents.+ let object_id = match conn+ .call(+ Some(cdp),+ "DOM.resolveNode",+ json!({ "backendNodeId": entry.backend_node_id }),+ )+ .await+ .ok()+ .and_then(|resolved| {+ resolved+ .get("object")+ .and_then(|o| o.get("objectId"))+ .and_then(Value::as_str)+ .map(str::to_owned)+ }) {+ Some(o) => o,+ None => {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserRefStale,+ "the ref's node no longer resolves in the live page",+ )+ .to_tool_result()+ }+ };+ let editable = conn+ .call(+ Some(cdp),+ "Runtime.callFunctionOn",+ json!({+ "objectId": object_id,+ "functionDeclaration": EDITABLE_AND_FOCUSED_CHECK,+ "returnByValue": true,+ }),+ )+ .await;+ if !matches!(+ editable,+ Ok(ref value) if value["result"]["value"].as_bool() == Some(true)+ ) {+ return BrowserRefusal::new(+ BrowserRefusalCode::BrowserInputTrustUnavailable,+ "the requested ref is not a focused editable element",+ )+ .to_tool_result();+ }++ let typed = if mode == "insert_text" {+ conn.call(Some(cdp), "Input.insertText", json!({ "text": text }))+ .await+ .map(|_| ())+ } else {+ let mut result = Ok(());+ for ch in text.chars() {+ let (key, key_text) = if ch == '\n' {+ ("Enter".to_string(), "\r".to_string())+ } else {+ (ch.to_string(), ch.to_string())+ };+ let down = conn+ .call(+ Some(cdp),+ "Input.dispatchKeyEvent",+ json!({ "type": "keyDown", "key": key, "text": key_text }),+ )+ .await;+ let up = conn+ .call(+ Some(cdp),+ "Input.dispatchKeyEvent",+ json!({ "type": "keyUp", "key": key }),+ )+ .await;+ if let Err(e) = down.and(up) {+ result = Err(e);+ break;+ }+ }+ result+ };++ match typed {+ Ok(()) => ToolResult::text(format!(+ "typed {} char(s) into {tab_id}",+ text.chars().count()+ ))+ .with_structured(json!({+ "status": "ok",+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": ext_ref,+ "frame": entry.frame.kind.as_str(),+ "mode": mode,+ "chars": text.chars().count(),+ })),+ Err(e) => BrowserRefusal::new(+ BrowserRefusalCode::BrowserInputTrustUnavailable,+ format!("trusted Input typing route failed: {e}"),+ )+ .to_tool_result(),+ }+ }+}++#[cfg(test)]+mod tests {+ use super::*;+ use crate::browser::platform::{BrowserPlatform, PrepareOutcome, PrepareRequest};+ use crate::browser::types::{+ BrowserClassification, BrowserEngineFamily, NativeWindowInfo, OwnedEndpoint,+ ProcessFingerprint,+ };++ /// Minimal adapter: pid 1 is a CDP-capable browser with no endpoint+ /// (setup required); pid 2 is not a browser; pid 3 is Safari-like+ /// (browser, no CDP). Prepare requires consent.+ struct MockPlatform;++ #[async_trait]+ impl BrowserPlatform for MockPlatform {+ async fn classify_browser(+ &self,+ pid: i64,+ ) -> Result<BrowserClassification, BrowserRefusal> {+ Ok(match pid {+ 1 => BrowserClassification {+ is_browser: true,+ engine: BrowserEngineFamily::Chromium,+ product: Some("MockChrome".into()),+ channel: Some("stable".into()),+ supports_cdp: true,+ },+ 3 => BrowserClassification {+ is_browser: true,+ engine: BrowserEngineFamily::Webkit,+ product: Some("MockSafari".into()),+ channel: None,+ supports_cdp: false,+ },+ _ => BrowserClassification {+ is_browser: false,+ engine: BrowserEngineFamily::Unknown,+ product: None,+ channel: None,+ supports_cdp: false,+ },+ })+ }++ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ use crate::browser::types::{NativeOwnershipMethod, NativeOwnershipProof, Rect};+ Ok(NativeWindowInfo {+ pid,+ window_id,+ title: "Mock - Chrome".into(),+ bounds: Rect::new(0.0, 0.0, 800.0, 600.0),+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: pid,+ detail: None,+ },+ })+ }++ async fn is_only_exact_native_window(+ &self,+ _pid: i64,+ _window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal> {+ Ok(Some(true))+ }++ async fn discover_owned_endpoint(+ &self,+ _pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {+ Ok(None)+ }++ async fn process_fingerprint(+ &self,+ pid: i64,+ ) -> Result<ProcessFingerprint, BrowserRefusal> {+ Ok(ProcessFingerprint {+ pid,+ start_time: Some(1),+ executable: None,+ })+ }++ async fn prepare_endpoint(+ &self,+ _request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ Err(BrowserRefusal::new(+ BrowserRefusalCode::BrowserRequiresSetup,+ "mock endpoint needs acting setup",+ ))+ }+ }++ fn engine() -> Arc<BrowserEngine> {+ BrowserEngine::new(Arc::new(MockPlatform))+ }++ fn structured(result: &ToolResult) -> &Value {+ result+ .structured_content+ .as_ref()+ .expect("structured content")+ }++ #[test]+ fn tool_annotations_and_schemas() {+ let e = engine();+ let state = GetBrowserStateTool::new(e.clone());+ assert!(+ state.def().read_only,+ "get_browser_state must be strictly read-only"+ );+ assert!(state.def().idempotent);++ let prepare = BrowserPrepareTool::new(e.clone());+ assert!(prepare.def().destructive);+ assert!(!prepare.def().idempotent);+ let prepare_properties = prepare.def().input_schema["properties"]+ .as_object()+ .expect("browser_prepare properties");+ assert!(!prepare_properties.contains_key("consent"));+ assert!(!prepare_properties.contains_key("allow_restart"));+ assert!(!prepare_properties.contains_key(MCP_HOST_APPROVAL_ARG));++ for (def, name) in [+ (+ BrowserPrepareTool::new(e.clone()).def().clone(),+ "browser_prepare",+ ),+ (+ BrowserNavigateTool::new(e.clone()).def().clone(),+ "browser_navigate",+ ),+ (+ BrowserClickTool::new(e.clone()).def().clone(),+ "browser_click",+ ),+ (+ BrowserTypeTool::new(e.clone()).def().clone(),+ "browser_type",+ ),+ ] {+ assert_eq!(def.name, name);+ assert!(!def.read_only, "{name} is a mutation");+ assert!(def.input_schema["properties"].is_object(), "{name} schema");+ }+ // Navigate reaches the open web; the input tools do not.+ assert!(BrowserNavigateTool::new(e.clone()).def().open_world);+ assert!(!BrowserClickTool::new(e).def().open_world);+ }++ #[test]+ fn registration_registers_all_five() {+ let e = engine();+ let mut registry = ToolRegistry::new();+ register_browser_tools(&e, &mut registry);+ let names: Vec<&str> = registry.tool_names().collect();+ assert_eq!(+ names,+ vec![+ "get_browser_state",+ "browser_prepare",+ "browser_navigate",+ "browser_click",+ "browser_type"+ ]+ );+ }++ #[tokio::test]+ async fn bind_requires_an_explicit_session() {+ let e = engine();+ let tool = GetBrowserStateTool::new(e);+ for args in [+ json!({ "pid": 1, "window_id": 7 }),+ json!({ "pid": 1, "window_id": 7, "_session_id": "default" }),+ ] {+ let result = tool.invoke(args).await;+ assert_eq!(result.is_error, Some(true));+ }+ }++ #[tokio::test]+ async fn public_session_field_is_the_primary_capability_namespace() {+ let tool = GetBrowserStateTool::new(engine());+ let result = tool+ .invoke(json!({ "pid": 2, "window_id": 7, "session": "public-run" }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_route_unavailable"+ );+ assert_ne!(+ result.is_error,+ Some(true),+ "public session must pass capability-namespace validation"+ );+ }++ #[tokio::test]+ async fn non_browser_pid_refuses_route_unavailable() {+ let tool = GetBrowserStateTool::new(engine());+ let result = tool+ .invoke(json!({ "pid": 2, "window_id": 7, "_session_id": "run-1" }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_route_unavailable"+ );+ }++ #[tokio::test]+ async fn cdp_less_browser_refuses_route_unavailable() {+ let tool = GetBrowserStateTool::new(engine());+ let result = tool+ .invoke(json!({ "pid": 3, "window_id": 7, "_session_id": "run-1" }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_route_unavailable"+ );+ }++ #[tokio::test]+ async fn missing_endpoint_refuses_requires_setup_without_preparing() {+ let tool = GetBrowserStateTool::new(engine());+ let result = tool+ .invoke(json!({ "pid": 1, "window_id": 7, "_session_id": "run-1" }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "refused");+ assert_eq!(s["refusal"]["code"], "browser_requires_setup");+ }++ #[tokio::test]+ async fn prepare_requires_non_forgeable_approval_for_acting_setup() {+ let tool = BrowserPrepareTool::new(engine());+ let result = tool+ .invoke(json!({+ "pid": 1,+ "allow_launch": true,+ "profile": { "mode": "isolated_new" },+ "session": "run-1"+ }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_consent_required"+ );+ }++ #[tokio::test]+ async fn mutations_on_unknown_targets_refuse_binding_stale() {+ let e = engine();+ for result in [+ BrowserNavigateTool::new(e.clone())+ .invoke(json!({+ "target_id": "bt999", "tab_id": "tab1",+ "url": "https://example.test", "_session_id": "run-1"+ }))+ .await,+ BrowserClickTool::new(e.clone())+ .invoke(json!({+ "target_id": "bt999", "tab_id": "tab1", "ref": "p1:0",+ "_session_id": "run-1"+ }))+ .await,+ BrowserTypeTool::new(e)+ .invoke(json!({+ "target_id": "bt999", "tab_id": "tab1", "text": "hi",+ "_session_id": "run-1"+ }))+ .await,+ ] {+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_binding_stale",+ "unknown capability must refuse, not error"+ );+ }+ }++ #[tokio::test]+ async fn mutations_reject_bad_url_and_bad_route_before_binding() {+ let e = engine();+ let nav = BrowserNavigateTool::new(e.clone())+ .invoke(json!({+ "target_id": "bt1", "tab_id": "tab1", "url": "file:///etc/passwd",+ "_session_id": "run-1"+ }))+ .await;+ assert_eq!(nav.is_error, Some(true));++ let click = BrowserClickTool::new(e)+ .invoke(json!({+ "target_id": "bt1", "tab_id": "tab1", "ref": "p1:0",+ "input_route": "sneaky", "_session_id": "run-1"+ }))+ .await;+ assert_eq!(click.is_error, Some(true));+ }++ #[tokio::test]+ async fn heuristic_bindings_refuse_mutation() {+ use crate::browser::types::{BindingQuality, Rect};+ use std::collections::HashMap;++ let e = engine();+ // Seed a heuristic binding directly into the store.+ let mut tabs = HashMap::new();+ let tab_id = e.store.mint_tab_id();+ tabs.insert(+ tab_id.clone(),+ crate::browser::store::TabRecord {+ tab_id: tab_id.clone(),+ cdp_target_id: "CDPX".into(),+ snapshots: HashMap::new(),+ },+ );+ let target_id = e.store.mint_target(+ "run-1",+ crate::browser::store::TargetRecord {+ target_id: String::new(),+ pid: 1,+ window_id: 7,+ ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),+ endpoint_owner_pid: 1,+ fingerprint: ProcessFingerprint {+ pid: 1,+ start_time: Some(1),+ executable: None,+ },+ native_title: "Mock - Chrome".into(),+ native_bounds: Rect::new(0.0, 0.0, 800.0, 600.0),+ cdp_target_id: "CDPX".into(),+ cdp_window_id: Some(5),+ quality: BindingQuality::Heuristic,+ tabs,+ },+ );++ let result = BrowserTypeTool::new(e)+ .invoke(json!({+ "target_id": target_id, "tab_id": tab_id, "text": "hi",+ "_session_id": "run-1"+ }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_wrong_target_refused",+ "heuristic bindings are read-only"+ );+ }++ #[tokio::test]+ async fn stale_fingerprint_refuses_before_any_cdp_traffic() {+ use crate::browser::types::{BindingQuality, Rect};+ use std::collections::HashMap;++ let e = engine();+ let mut tabs = HashMap::new();+ let tab_id = e.store.mint_tab_id();+ tabs.insert(+ tab_id.clone(),+ crate::browser::store::TabRecord {+ tab_id: tab_id.clone(),+ cdp_target_id: "CDPX".into(),+ snapshots: HashMap::new(),+ },+ );+ // Bound fingerprint has start_time 999; MockPlatform now reports 1.+ let target_id = e.store.mint_target(+ "run-1",+ crate::browser::store::TargetRecord {+ target_id: String::new(),+ pid: 1,+ window_id: 7,+ ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),+ endpoint_owner_pid: 1,+ fingerprint: ProcessFingerprint {+ pid: 1,+ start_time: Some(999),+ executable: None,+ },+ native_title: "Mock - Chrome".into(),+ native_bounds: Rect::new(0.0, 0.0, 800.0, 600.0),+ cdp_target_id: "CDPX".into(),+ cdp_window_id: Some(5),+ quality: BindingQuality::Exact,+ tabs,+ },+ );++ let result = BrowserNavigateTool::new(e)+ .invoke(json!({+ "target_id": target_id, "tab_id": tab_id,+ "url": "https://example.test", "_session_id": "run-1"+ }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_binding_stale"+ );+ }++ #[tokio::test]+ async fn session_end_hook_drops_the_capability_namespace() {+ use crate::browser::types::{BindingQuality, Rect};+ use std::collections::HashMap;++ let e = engine();+ let sid = "browser-store-cleanup-session-771";+ e.store.mint_target(+ sid,+ crate::browser::store::TargetRecord {+ target_id: String::new(),+ pid: 1,+ window_id: 7,+ ws_url: "ws://127.0.0.1:9222/devtools/browser/x".into(),+ endpoint_owner_pid: 1,+ fingerprint: ProcessFingerprint {+ pid: 1,+ start_time: Some(1),+ executable: None,+ },+ native_title: "T".into(),+ native_bounds: Rect::new(0.0, 0.0, 1.0, 1.0),+ cdp_target_id: "C".into(),+ cdp_window_id: Some(1),+ quality: BindingQuality::Exact,+ tabs: HashMap::new(),+ },+ );+ assert_eq!(e.store.target_count(sid), 1);+ crate::session::fire_session_end(sid);+ assert_eq!(+ e.store.target_count(sid),+ 0,+ "session end must clean the store"+ );+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rsnew file mode 100644index 0000000000..0156188657--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/types.rs@@ -0,0 +1,254 @@+//! Shared, serde-friendly value types for the browser-tool surface.+//!+//! These types cross the core ↔ platform-adapter boundary, so they are+//! deliberately conservative: plain data, explicit proof fields (never+//! implicit booleans buried in strings), and `serde` derives throughout+//! so adapters and structured tool output share one shape.++use serde::{Deserialize, Serialize};++/// A rectangle in screen coordinates. Platform adapters MUST normalize+/// native window bounds into the same coordinate space CDP's+/// `Browser.getWindowBounds` reports (device-independent pixels, origin+/// at the top-left of the primary display) before handing them to core —+/// correlation compares the two spaces directly.+#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize, Default)]+pub struct Rect {+ pub x: f64,+ pub y: f64,+ pub width: f64,+ pub height: f64,+}++impl Rect {+ pub fn new(x: f64, y: f64, width: f64, height: f64) -> Self {+ Self {+ x,+ y,+ width,+ height,+ }+ }++ /// Whether every edge of `self` is within `tolerance` device pixels of+ /// `other`. Tolerance absorbs shadow/inset differences between the+ /// native window server rect and CDP's outer window rect.+ pub fn approx_eq(&self, other: &Rect, tolerance: f64) -> bool {+ (self.x - other.x).abs() <= tolerance+ && (self.y - other.y).abs() <= tolerance+ && (self.width - other.width).abs() <= tolerance+ && (self.height - other.height).abs() <= tolerance+ }+}++/// Rendering-engine family of a classified browser process.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum BrowserEngineFamily {+ Chromium,+ Gecko,+ Webkit,+ Unknown,+}++/// Platform adapter's verdict on whether a pid is a browser and which+/// engine family it belongs to. `supports_cdp` is the gate for the whole+/// browser-tool route in v1 (Chromium-family only).+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct BrowserClassification {+ pub is_browser: bool,+ pub engine: BrowserEngineFamily,+ /// Human-readable product name, e.g. "Google Chrome", "Microsoft Edge".+ pub product: Option<String>,+ /// Release channel when known, e.g. "stable", "canary".+ pub channel: Option<String>,+ /// Whether this browser can expose a DevTools (CDP) endpoint at all.+ pub supports_cdp: bool,+}++/// How a platform adapter proved that a native window belongs to a pid.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum NativeOwnershipMethod {+ /// The OS window server reports the window's owning pid directly.+ WindowServerOwner,+ /// The accessibility tree ties the window element to the pid.+ AccessibilityOwner,+ /// Some other platform-attested mechanism (documented in `detail`).+ PlatformAttested,+}++/// Explicit proof that a native window is owned by a specific process.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct NativeOwnershipProof {+ pub method: NativeOwnershipMethod,+ /// Pid the OS attributes the window to. Core refuses when this does+ /// not equal the caller-supplied pid.+ pub owner_pid: i64,+ pub detail: Option<String>,+}++/// Native window metadata used for exact CDP-window correlation.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct NativeWindowInfo {+ pub pid: i64,+ pub window_id: u64,+ pub title: String,+ /// Bounds normalized to CDP's coordinate space — see [`Rect`].+ pub bounds: Rect,+ /// Whether the platform can attest that `bounds` are complete and in+ /// the normalized coordinate space. False forces title-only,+ /// read-only correlation even if the numeric values happen to match.+ pub geometry_exact: bool,+ pub ownership: NativeOwnershipProof,+}++/// How a platform adapter proved that a loopback DevTools endpoint is+/// owned by the target browser process (and not an unrelated listener).+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum EndpointOwnershipMethod {+ /// The listening loopback socket's owning pid was resolved via the+ /// OS socket table and matches the browser pid (or a child of it).+ ListeningSocketPid,+ /// The port was read from the profile's `DevToolsActivePorts` file+ /// belonging to the browser's own user-data dir.+ DevtoolsActivePortsFile,+ /// The driver itself launched the browser with the debugging port,+ /// so ownership is known by construction.+ SpawnedByDriver,+ /// Some other platform-attested mechanism (documented in `detail`).+ PlatformAttested,+}++/// Explicit proof of DevTools-endpoint ownership.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct EndpointOwnershipProof {+ pub method: EndpointOwnershipMethod,+ /// Pid the endpoint was attributed to. Core refuses with+ /// `browser_endpoint_owner_mismatch` when this does not equal the+ /// target pid.+ pub owner_pid: i64,+ pub detail: Option<String>,+}++/// A discovered, owned DevTools browser endpoint. `ws_url` must be a+/// loopback `ws://` URL — core validates this before connecting.+#[derive(Debug, Clone, Serialize, Deserialize)]+pub struct OwnedEndpoint {+ /// Browser-level WebSocket URL, e.g.+ /// `ws://127.0.0.1:9222/devtools/browser/<uuid>`.+ pub ws_url: String,+ pub http_port: Option<u16>,+ pub ownership: EndpointOwnershipProof,+}++/// A point-in-time identity fingerprint for a process. Used to detect+/// pid reuse between binding and mutation.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct ProcessFingerprint {+ pub pid: i64,+ /// OS process start time in platform-native ticks/units. The unit is+ /// opaque to core — only equality matters.+ pub start_time: Option<u64>,+ /// Executable path when the platform can resolve it.+ pub executable: Option<String>,+}++impl ProcessFingerprint {+ /// Whether `other` plausibly identifies the same process instance.+ /// Any field known on both sides must match exactly; a field unknown+ /// on either side is not treated as a match signal, so two+ /// fingerprints that share only the pid still match ONLY if neither+ /// side ever learned a start time / executable. This is the+ /// conservative reading: a platform that can report start times will+ /// always report them, so a disagreement or a newly-missing value+ /// means the process identity can no longer be proven.+ pub fn matches(&self, other: &ProcessFingerprint) -> bool {+ if self.pid != other.pid {+ return false;+ }+ match (&self.start_time, &other.start_time) {+ (Some(a), Some(b)) if a != b => return false,+ (Some(_), None) | (None, Some(_)) => return false,+ _ => {}+ }+ match (&self.executable, &other.executable) {+ (Some(a), Some(b)) if a != b => return false,+ _ => {}+ }+ true+ }+}++/// How well a native window was correlated to a CDP target.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum BindingQuality {+ /// Unique bounds correlation or an independently attested one-native /+ /// one-CDP-window cardinality proof. The only quality that permits mutation.+ Exact,+ /// Title-only correlation. Read-only: mutations are refused.+ Heuristic,+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn rect_tolerance_is_inclusive() {+ let a = Rect::new(0.0, 0.0, 800.0, 600.0);+ let b = Rect::new(8.0, 0.0, 800.0, 600.0);+ assert!(a.approx_eq(&b, 8.0), "diff exactly at tolerance matches");+ assert!(!a.approx_eq(&b, 7.9), "diff beyond tolerance refuses");+ }++ #[test]+ fn fingerprint_pid_reuse_is_detected() {+ let bound = ProcessFingerprint {+ pid: 100,+ start_time: Some(11111),+ executable: Some("/opt/chrome".into()),+ };+ let same = bound.clone();+ assert!(bound.matches(&same));++ // Same pid, different start time — classic pid reuse.+ let reused = ProcessFingerprint {+ start_time: Some(22222),+ ..bound.clone()+ };+ assert!(!bound.matches(&reused));++ // Start time became unknowable — identity can't be proven anymore.+ let degraded = ProcessFingerprint {+ start_time: None,+ ..bound.clone()+ };+ assert!(!bound.matches(°raded));++ let other_pid = ProcessFingerprint {+ pid: 101,+ ..bound.clone()+ };+ assert!(!bound.matches(&other_pid));++ let other_exe = ProcessFingerprint {+ executable: Some("/opt/other".into()),+ ..bound+ };+ assert!(!bound.matches(&other_exe));+ }++ #[test]+ fn fingerprint_with_no_known_fields_matches_only_on_pid() {+ let a = ProcessFingerprint {+ pid: 5,+ start_time: None,+ executable: None,+ };+ let b = a.clone();+ assert!(a.matches(&b));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rsnew file mode 100644index 0000000000..609c4dc828--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/v2_tests.rs@@ -0,0 +1,859 @@+//! End-to-end tests for the v2 DOM-ref slice against a deterministic+//! mock CDP endpoint: composed shadow DOM, same-process iframes,+//! capability-tested OOPIFs with containment, frame/document identity+//! revalidation, navigation invalidation, and unproven-capability+//! omission/refusal.++use std::sync::{Arc, Mutex as StdMutex};++use async_trait::async_trait;+use serde_json::{json, Value};++use crate::protocol::ToolResult;+use crate::tool::Tool;++use super::engine::BrowserEngine;+use super::mock_cdp::{MockCdpServer, MockEvent, MockHandler, MockReply};+use super::platform::{BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest};+use super::refusal::BrowserRefusal;+use super::tools::{BrowserClickTool, BrowserTypeTool, GetBrowserStateTool};+use super::types::{+ BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,+ NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,+ ProcessFingerprint, Rect,+};++// ── Scripted Chromium fixture ────────────────────────────────────────────────++/// Mutable knobs + a call log, shared between the mock handler and the+/// test body. Tests flip loaders/capabilities mid-run to simulate+/// navigations, frame removal, and capability regression.+#[derive(Debug)]+struct FixtureState {+ oopif_supported: bool,+ oopif_present: bool,+ emit_rogue_attach: bool,+ main_loader: String,+ iframe_loader: String,+ oopif_loader: String,+ tab_sessions: u64,+ oopif_sessions: u64,+ /// Every incoming CDP call: (sessionId, method, params).+ calls: Vec<(Option<String>, String, Value)>,+}++impl Default for FixtureState {+ fn default() -> Self {+ Self {+ oopif_supported: true,+ oopif_present: true,+ emit_rogue_attach: false,+ main_loader: "L_MAIN_1".into(),+ iframe_loader: "L_IFRAME_1".into(),+ oopif_loader: "L_OOPIF_1".into(),+ tab_sessions: 0,+ oopif_sessions: 0,+ calls: Vec::new(),+ }+ }+}++type SharedState = Arc<StdMutex<FixtureState>>;++/// Main-frame document: a plain button, an open shadow root with an+/// input, a user-agent shadow root (must be skipped), a same-process+/// iframe with a button, and an OOPIF placeholder (no contentDocument).+fn main_document() -> Value {+ json!({+ "root": {+ "nodeType": 9,+ "nodeName": "#document",+ "documentURL": "https://fixture.test/",+ "frameId": "F_MAIN",+ "children": [{+ "nodeType": 1,+ "nodeName": "HTML",+ "backendNodeId": 1,+ "children": [+ {+ "nodeType": 1,+ "nodeName": "BUTTON",+ "backendNodeId": 10,+ "attributes": ["id", "main-btn"],+ },+ {+ "nodeType": 1,+ "nodeName": "DIV",+ "backendNodeId": 11,+ "shadowRoots": [{+ "nodeType": 11,+ "nodeName": "#document-fragment",+ "shadowRootType": "open",+ "backendNodeId": 12,+ "children": [{+ "nodeType": 1,+ "nodeName": "INPUT",+ "backendNodeId": 20,+ "attributes": ["aria-label", "Shadow Input", "type", "text"],+ }]+ }]+ },+ {+ "nodeType": 1,+ "nodeName": "INPUT",+ "backendNodeId": 21,+ "attributes": ["type", "text"],+ "shadowRoots": [{+ "nodeType": 11,+ "nodeName": "#document-fragment",+ "shadowRootType": "user-agent",+ "backendNodeId": 23,+ "children": [{+ "nodeType": 1,+ "nodeName": "DIV",+ "backendNodeId": 22,+ "attributes": ["role", "button"],+ }]+ }]+ },+ {+ "nodeType": 1,+ "nodeName": "IFRAME",+ "backendNodeId": 13,+ "frameId": "F_IFRAME",+ "contentDocument": {+ "nodeType": 9,+ "nodeName": "#document",+ "frameId": "F_IFRAME",+ "children": [{+ "nodeType": 1,+ "nodeName": "BUTTON",+ "backendNodeId": 30,+ "attributes": ["id", "inner-btn"],+ }]+ }+ },+ {+ "nodeType": 1,+ "nodeName": "IFRAME",+ "backendNodeId": 14,+ "frameId": "F_OOPIF",+ }+ ]+ }]+ }+ })+}++fn oopif_document() -> Value {+ json!({+ "root": {+ "nodeType": 9,+ "nodeName": "#document",+ "documentURL": "https://ads.example/frame",+ "frameId": "F_OOPIF",+ "children": [{+ "nodeType": 1,+ "nodeName": "HTML",+ "backendNodeId": 90,+ "children": [{+ "nodeType": 1,+ "nodeName": "INPUT",+ "backendNodeId": 100,+ "attributes": ["id", "ad-input", "type", "text"],+ }]+ }]+ }+ })+}++fn fixture_handler(state: SharedState) -> MockHandler {+ Arc::new(move |call| {+ let mut st = state.lock().unwrap();+ st.calls.push((+ call.session_id.clone(),+ call.method.clone(),+ call.params.clone(),+ ));+ let sess = call.session_id.clone().unwrap_or_default();+ let is_tab = sess.starts_with("tab-sess-");+ let is_oopif = sess.starts_with("oopif-sess-");++ match call.method.as_str() {+ "Target.getTargets" => MockReply::ok(json!({+ "targetInfos": [{+ "targetId": "T1",+ "type": "page",+ "title": "Fixture",+ "url": "https://fixture.test/",+ "attached": false,+ }]+ })),+ "Browser.getWindowForTarget" => MockReply::ok(json!({ "windowId": 11 })),+ "Browser.getWindowBounds" => MockReply::ok(json!({+ "bounds": { "left": 0.0, "top": 0.0, "width": 800.0, "height": 600.0 }+ })),+ "Target.attachToTarget" => {+ st.tab_sessions += 1;+ MockReply::ok(json!({ "sessionId": format!("tab-sess-{}", st.tab_sessions) }))+ }+ "Page.getFrameTree" if is_tab => MockReply::ok(json!({+ "frameTree": {+ "frame": {+ "id": "F_MAIN",+ "loaderId": st.main_loader.clone(),+ "url": "https://fixture.test/",+ },+ "childFrames": [{+ "frame": {+ "id": "F_IFRAME",+ "parentId": "F_MAIN",+ "loaderId": st.iframe_loader.clone(),+ "url": "https://fixture.test/inner",+ }+ }]+ }+ })),+ "Page.getFrameTree" if is_oopif => MockReply::ok(json!({+ "frameTree": {+ "frame": {+ "id": "F_OOPIF",+ "loaderId": st.oopif_loader.clone(),+ "url": "https://ads.example/frame",+ }+ }+ })),+ "DOM.getDocument" if is_tab => MockReply::ok(main_document()),+ "DOM.getDocument" if is_oopif => MockReply::ok(oopif_document()),+ "Target.setAutoAttach" if is_tab => {+ if call.params["autoAttach"].as_bool() == Some(false) {+ return MockReply::ok(json!({}));+ }+ if !st.oopif_supported {+ return MockReply::method_not_found("Target.setAutoAttach");+ }+ let mut events = Vec::new();+ if st.oopif_present {+ st.oopif_sessions += 1;+ events.push(MockEvent {+ method: "Target.attachedToTarget".into(),+ session_id: Some(sess.clone()),+ params: json!({+ "sessionId": format!("oopif-sess-{}", st.oopif_sessions),+ "targetInfo": {+ "targetId": "T_OOPIF",+ "type": "iframe",+ "url": "https://ads.example/frame",+ "attached": true,+ },+ "waitingForDebugger": false,+ }),+ });+ }+ if st.emit_rogue_attach {+ // A child announced on a session we never proved.+ events.push(MockEvent {+ method: "Target.attachedToTarget".into(),+ session_id: Some("unproven-sess".into()),+ params: json!({+ "sessionId": "rogue-sess",+ "targetInfo": {+ "targetId": "T_ROGUE",+ "type": "iframe",+ "url": "https://evil.example/",+ "attached": true,+ },+ "waitingForDebugger": false,+ }),+ });+ // A popup page target beneath the tab — wrong type.+ events.push(MockEvent {+ method: "Target.attachedToTarget".into(),+ session_id: Some(sess.clone()),+ params: json!({+ "sessionId": "popup-sess",+ "targetInfo": {+ "targetId": "T_POPUP",+ "type": "page",+ "url": "https://fixture.test/popup",+ "attached": true,+ },+ "waitingForDebugger": false,+ }),+ });+ }+ MockReply::ok(json!({})).with_events(events)+ }+ "DOM.scrollIntoViewIfNeeded" => MockReply::ok(json!({})),+ "DOM.getBoxModel" => {+ let backend = call.params["backendNodeId"].as_i64().unwrap_or(0);+ let known = if is_oopif {+ backend == 100+ } else {+ [10, 20, 21, 30].contains(&backend)+ };+ if known {+ let (x, y) = ((backend * 10) as f64, (backend * 10) as f64);+ MockReply::ok(json!({+ "model": {+ "content": [x, y, x + 20.0, y, x + 20.0, y + 10.0, x, y + 10.0]+ }+ }))+ } else {+ MockReply::err(-32000, "No node with given id")+ }+ }+ "DOM.focus"+ | "Input.dispatchMouseEvent"+ | "Input.insertText"+ | "Input.dispatchKeyEvent" => MockReply::ok(json!({})),+ "DOM.resolveNode" => MockReply::ok(json!({+ "object": { "objectId": format!("obj-{}", call.params["backendNodeId"]) }+ })),+ "Runtime.callFunctionOn" => MockReply::ok(json!({ "result": { "value": true } })),+ other => MockReply::method_not_found(other),+ }+ })+}++/// Platform adapter pointing at the fixture endpoint: pid 1 is a+/// Chromium browser owning native window 7 at (0,0,800,600).+struct FixturePlatform {+ ws_url: String,+ trusted_input_limited: bool,+}++#[async_trait]+impl BrowserPlatform for FixturePlatform {+ fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {+ self.trusted_input_limited+ .then_some("fixture trusted input raises the standalone window")+ }++ async fn classify_browser(&self, _pid: i64) -> Result<BrowserClassification, BrowserRefusal> {+ Ok(BrowserClassification {+ is_browser: true,+ engine: BrowserEngineFamily::Chromium,+ product: Some("MockChrome".into()),+ channel: Some("stable".into()),+ supports_cdp: true,+ })+ }++ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ Ok(NativeWindowInfo {+ pid,+ window_id,+ title: "Fixture - Chrome".into(),+ bounds: Rect::new(0.0, 0.0, 800.0, 600.0),+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: pid,+ detail: None,+ },+ })+ }++ async fn is_only_exact_native_window(+ &self,+ _pid: i64,+ _window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal> {+ Ok(Some(true))+ }++ async fn discover_owned_endpoint(+ &self,+ pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {+ Ok(Some(OwnedEndpoint {+ ws_url: self.ws_url.clone(),+ http_port: None,+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::ListeningSocketPid,+ owner_pid: pid,+ detail: None,+ },+ }))+ }++ async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {+ Ok(ProcessFingerprint {+ pid,+ start_time: Some(1),+ executable: None,+ })+ }++ async fn prepare_endpoint(+ &self,+ _request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ Ok(PrepareOutcome {+ action: PrepareAction::NoOp,+ endpoint: None,+ message: "fixture: nothing to do".into(),+ prepared_pid: None,+ side_effects: Default::default(),+ })+ }+}++// ── Scaffolding ──────────────────────────────────────────────────────────────++struct Fixture {+ state: SharedState,+ // Kept alive for the test's duration; dropping it kills the endpoint.+ _server: MockCdpServer,+ engine: Arc<BrowserEngine>,+}++async fn fixture_with(configure: impl FnOnce(&mut FixtureState)) -> Fixture {+ fixture_with_platform(configure, false).await+}++async fn fixture_with_platform(+ configure: impl FnOnce(&mut FixtureState),+ trusted_input_limited: bool,+) -> Fixture {+ let mut initial = FixtureState::default();+ configure(&mut initial);+ let state = Arc::new(StdMutex::new(initial));+ let server = MockCdpServer::start(fixture_handler(state.clone())).await;+ let engine = BrowserEngine::new(Arc::new(FixturePlatform {+ ws_url: server.ws_url(),+ trusted_input_limited,+ }));+ Fixture {+ state,+ _server: server,+ engine,+ }+}++async fn fixture() -> Fixture {+ fixture_with(|_| {}).await+}++fn structured(result: &ToolResult) -> &Value {+ result+ .structured_content+ .as_ref()+ .expect("structured content")+}++const SESSION: &str = "run-v2";++async fn bind(f: &Fixture) -> (String, String) {+ let tool = GetBrowserStateTool::new(f.engine.clone());+ let result = tool+ .invoke(json!({ "pid": 1, "window_id": 7, "session": SESSION }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "ok", "bind must succeed: {s}");+ assert_eq!(s["binding_quality"], "exact");+ let target_id = s["target_id"].as_str().unwrap().to_owned();+ let tab_id = s["tabs"][0]["tab_id"].as_str().unwrap().to_owned();+ (target_id, tab_id)+}++async fn snapshot(f: &Fixture, target_id: &str, tab_id: &str) -> Value {+ let tool = GetBrowserStateTool::new(f.engine.clone());+ let result = tool+ .invoke(json!({ "target_id": target_id, "tab_id": tab_id, "session": SESSION }))+ .await;+ structured(&result).clone()+}++/// The `ref` string of the first snapshot entry in the given frame kind+/// with the given backing label fragment (or any, if empty).+fn ref_of(snapshot: &Value, frame: &str, label_fragment: &str) -> String {+ snapshot["refs"]+ .as_array()+ .unwrap()+ .iter()+ .find(|r| {+ r["frame"] == frame+ && (label_fragment.is_empty()+ || r["label"].as_str().unwrap_or("").contains(label_fragment))+ })+ .unwrap_or_else(|| panic!("no {frame} ref with label ~{label_fragment:?}: {snapshot}"))+ ["ref"]+ .as_str()+ .unwrap()+ .to_owned()+}++fn recorded_calls(f: &Fixture, method: &str) -> Vec<(Option<String>, Value)> {+ f.state+ .lock()+ .unwrap()+ .calls+ .iter()+ .filter(|(_, m, _)| m == method)+ .map(|(s, _, p)| (s.clone(), p.clone()))+ .collect()+}++// ── Snapshot composition ─────────────────────────────────────────────────────++#[tokio::test]+async fn snapshot_composes_shadow_iframe_and_oopif_refs() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;++ assert_eq!(snap["status"], "ok", "{snap}");+ let frames: Vec<&str> = snap["refs"]+ .as_array()+ .unwrap()+ .iter()+ .map(|r| r["frame"].as_str().unwrap())+ .collect();+ assert_eq!(+ frames,+ vec!["main", "main", "main", "iframe", "oopif"],+ "main button + shadow input + plain input, iframe button, oopif input: {snap}"+ );+ assert_eq!(snap["oopif"]["status"], "attached");+ assert_eq!(snap["oopif"]["frames"], 1);+ assert_eq!(snap["truncated"], false);++ // Composed shadow content keeps its labels; user-agent shadow+ // internals (backend 22, role=button) must not have been minted.+ let labels: Vec<&str> = snap["refs"]+ .as_array()+ .unwrap()+ .iter()+ .map(|r| r["label"].as_str().unwrap_or(""))+ .collect();+ assert!(labels.iter().any(|l| l.contains("Shadow Input")), "{snap}");+ assert!(+ !labels.iter().any(|l| l.contains("role=button")),+ "user-agent shadow content leaked: {snap}"+ );+}++#[tokio::test]+async fn unproven_oopif_capability_is_omitted_not_guessed() {+ let f = fixture_with(|st| st.oopif_supported = false).await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;++ assert_eq!(+ snap["status"], "ok",+ "capability gap is not an error: {snap}"+ );+ assert_eq!(snap["oopif"]["status"], "unsupported");+ assert_eq!(snap["oopif"]["frames"], 0);+ let frames: Vec<&str> = snap["refs"]+ .as_array()+ .unwrap()+ .iter()+ .map(|r| r["frame"].as_str().unwrap())+ .collect();+ assert_eq!(+ frames,+ vec!["main", "main", "main", "iframe"],+ "OOPIF content omitted, everything provable kept: {snap}"+ );+}++#[tokio::test]+async fn rogue_attach_announcements_are_contained() {+ let f = fixture_with(|st| st.emit_rogue_attach = true).await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;++ let oopif_refs: Vec<&Value> = snap["refs"]+ .as_array()+ .unwrap()+ .iter()+ .filter(|r| r["frame"] == "oopif")+ .collect();+ assert_eq!(+ oopif_refs.len(),+ 1,+ "only the child attached beneath the proven tab session mints refs: {snap}"+ );+ assert_eq!(snap["oopif"]["frames"], 1);++ // The rogue/popup sessions must never have been spoken to.+ let touched: Vec<String> = f+ .state+ .lock()+ .unwrap()+ .calls+ .iter()+ .filter_map(|(s, _, _)| s.clone())+ .collect();+ assert!(+ !touched+ .iter()+ .any(|s| s == "rogue-sess" || s == "popup-sess"),+ "core issued commands to an unproven session: {touched:?}"+ );+}++// ── Mutation routing + frame identity revalidation ──────────────────────────++#[tokio::test]+async fn click_routes_oopif_refs_through_the_contained_child_session() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let oopif_ref = ref_of(&snap, "oopif", "ad-input");++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": oopif_ref, "session": SESSION+ }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "ok", "{s}");+ assert_eq!(s["frame"], "oopif");+ // Box-model center of backend 100 in the child session's space.+ assert_eq!(s["x"], 1010.0);+ assert_eq!(s["y"], 1005.0);++ let mouse = recorded_calls(&f, "Input.dispatchMouseEvent");+ assert!(!mouse.is_empty());+ assert!(+ mouse+ .iter()+ .all(|(sess, _)| sess.as_deref().unwrap_or("").starts_with("oopif-sess-")),+ "OOPIF input must dispatch on the child session: {mouse:?}"+ );+}++#[tokio::test]+async fn click_validates_same_process_iframe_loader_and_uses_the_tab_session() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let iframe_ref = ref_of(&snap, "iframe", "inner-btn");++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": iframe_ref, "session": SESSION+ }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "ok", "{s}");+ assert_eq!(s["frame"], "iframe");++ let mouse = recorded_calls(&f, "Input.dispatchMouseEvent");+ assert!(+ mouse+ .iter()+ .all(|(sess, _)| sess.as_deref().unwrap_or("").starts_with("tab-sess-")),+ "same-process iframe input stays on the tab session: {mouse:?}"+ );+ assert!(+ !recorded_calls(&f, "Page.getFrameTree").is_empty(),+ "frame identity must have been re-proven"+ );+}++#[tokio::test]+async fn trusted_click_refuses_when_standalone_background_posture_is_unavailable() {+ let f = fixture_with_platform(|_| {}, true).await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let main_ref = ref_of(&snap, "main", "main-btn");++ let trusted = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": main_ref,+ "input_route": "trusted", "session": SESSION+ }))+ .await;+ assert_eq!(+ structured(&trusted)["refusal"]["code"],+ "browser_input_trust_unavailable"+ );+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());++ let synthetic = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": main_ref,+ "input_route": "dom_event", "session": SESSION+ }))+ .await;+ assert_eq!(structured(&synthetic)["status"], "ok");+ assert!(!recorded_calls(&f, "Runtime.callFunctionOn").is_empty());+}++#[tokio::test]+async fn main_frame_navigation_invalidates_refs_via_loader_identity() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let main_ref = ref_of(&snap, "main", "main-btn");++ f.state.lock().unwrap().main_loader = "L_MAIN_2".into();++ let click = BrowserClickTool::new(f.engine.clone());+ let result = click+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": main_ref, "session": SESSION+ }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_ref_stale",+ "loader change means a new document"+ );+ assert!(+ recorded_calls(&f, "Input.dispatchMouseEvent").is_empty(),+ "no input may reach a document that cannot be re-proven"+ );++ // The whole snapshot namespace was invalidated, so a retry refuses+ // at resolution already.+ let retry = click+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": main_ref, "session": SESSION+ }))+ .await;+ assert_eq!(structured(&retry)["refusal"]["code"], "browser_ref_stale");+}++#[tokio::test]+async fn same_process_iframe_navigation_invalidates_its_refs() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let iframe_ref = ref_of(&snap, "iframe", "inner-btn");++ f.state.lock().unwrap().iframe_loader = "L_IFRAME_2".into();++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": iframe_ref, "session": SESSION+ }))+ .await;+ assert_eq!(structured(&result)["refusal"]["code"], "browser_ref_stale");+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());+}++#[tokio::test]+async fn oopif_navigation_invalidates_its_refs() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let oopif_ref = ref_of(&snap, "oopif", "ad-input");++ f.state.lock().unwrap().oopif_loader = "L_OOPIF_2".into();++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": oopif_ref, "session": SESSION+ }))+ .await;+ assert_eq!(structured(&result)["refusal"]["code"], "browser_ref_stale");+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());+}++#[tokio::test]+async fn removed_oopif_frame_is_stale_not_guessed() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let oopif_ref = ref_of(&snap, "oopif", "ad-input");++ f.state.lock().unwrap().oopif_present = false;++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": oopif_ref, "session": SESSION+ }))+ .await;+ assert_eq!(structured(&result)["refusal"]["code"], "browser_ref_stale");+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());+}++#[tokio::test]+async fn oopif_capability_regression_refuses_rather_than_reroutes() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let oopif_ref = ref_of(&snap, "oopif", "ad-input");++ f.state.lock().unwrap().oopif_supported = false;++ let result = BrowserClickTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": oopif_ref, "session": SESSION+ }))+ .await;+ assert_eq!(+ structured(&result)["refusal"]["code"],+ "browser_route_unavailable",+ "a lost capability is a refusal, never a fallback to the wrong session"+ );+ assert!(recorded_calls(&f, "Input.dispatchMouseEvent").is_empty());+}++// ── Typing routes ────────────────────────────────────────────────────────────++#[tokio::test]+async fn typing_into_composed_shadow_input_uses_the_tab_session() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let shadow_ref = ref_of(&snap, "main", "Shadow Input");++ let result = BrowserTypeTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": shadow_ref,+ "text": "hi", "session": SESSION+ }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "ok", "{s}");+ assert_eq!(s["frame"], "main");++ let inserts = recorded_calls(&f, "Input.insertText");+ assert_eq!(inserts.len(), 1);+ assert!(inserts[0].0.as_deref().unwrap().starts_with("tab-sess-"));+ assert_eq!(inserts[0].1["text"], "hi");+ assert!(+ !recorded_calls(&f, "Runtime.callFunctionOn").is_empty(),+ "editability must be checked on the node itself"+ );+}++#[tokio::test]+async fn typing_into_an_oopif_input_routes_to_the_child_session() {+ let f = fixture().await;+ let (target, tab) = bind(&f).await;+ let snap = snapshot(&f, &target, &tab).await;+ let oopif_ref = ref_of(&snap, "oopif", "ad-input");++ let result = BrowserTypeTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target, "tab_id": tab, "ref": oopif_ref,+ "text": "q", "session": SESSION+ }))+ .await;+ let s = structured(&result);+ assert_eq!(s["status"], "ok", "{s}");+ assert_eq!(s["frame"], "oopif");++ let inserts = recorded_calls(&f, "Input.insertText");+ assert_eq!(inserts.len(), 1);+ assert!(+ inserts[0].0.as_deref().unwrap().starts_with("oopif-sess-"),+ "typing must land in the contained child session: {inserts:?}"+ );+ let focuses = recorded_calls(&f, "DOM.focus");+ assert!(focuses+ .iter()+ .all(|(sess, _)| sess.as_deref().unwrap().starts_with("oopif-sess-")));+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/cdp.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/cdp.rsindex b463d8f95a..269438e224 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/cdp.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/cdp.rs@@ -1,18 +1,26 @@//! Cross-platform CDP (Chrome DevTools Protocol) helper.//!-//! A self-contained `Runtime.evaluate` client that speaks raw TCP — no-//! external HTTP/WS crates. Used by the cross-platform `page` tool's-//! `execute_javascript` action on Windows/Linux (and by the macOS Electron-//! backend, which retains its own copy under `platform-macos/src/browser/`-//! that predates this helper).+//! Legacy-compatible `Runtime.evaluate` support for the cross-platform+//! `page` tool. HTTP target discovery and first-page/URL-hint selection retain+//! the published legacy behavior, while WebSocket calls use the same pooled,+//! event-aware [`crate::browser::cdp_ws::CdpConnection`] transport as the+//! first-class browser tools.//!//! Flow://! 1. HTTP GET http://127.0.0.1:{cdp_port}/json → discover page WS URLs.-//! 2. WebSocket connect to the first page URL.+//! 2. Reuse or connect the selected page WebSocket through `CdpPool`.//! 3. Send Runtime.evaluate with userGesture=true.-//! 4. Read frames until we receive the response with id=1.+//! 4. Let the shared demultiplexer match the response without losing events.use serde_json::Value;+use std::sync::OnceLock;++use crate::browser::cdp_ws::CdpPool;++fn legacy_pool() -> &'static CdpPool {+ static POOL: OnceLock<CdpPool> = OnceLock::new();+ POOL.get_or_init(CdpPool::new)+}/// Evaluate `expression` in the first page tab exposed by a Chromium-family/// browser listening on `port` (the value passed to `--remote-debugging-port`).@@ -71,22 +79,22 @@ async fn cdp_evaluate(.ok_or_else(|| anyhow::anyhow!("Page has no webSocketDebuggerUrl"))?.to_string();- let cmd = serde_json::json!({- "id": 1,- "method": "Runtime.evaluate",- "params": {- "expression": expression,- "userGesture": true,- "awaitPromise": await_promise- }- });-- tokio::time::timeout(+ let connection = legacy_pool().get(&ws_url).await?;+ let result = tokio::time::timeout(std::time::Duration::from_secs(30),- cdp_ws_call(port, &ws_url, &cmd.to_string()),+ connection.call(+ None,+ "Runtime.evaluate",+ serde_json::json!({+ "expression": expression,+ "userGesture": true,+ "awaitPromise": await_promise+ }),+ ),).await- .map_err(|_| anyhow::anyhow!("CDP evaluate timed out after 30 s"))?+ .map_err(|_| anyhow::anyhow!("CDP evaluate timed out after 30 s"))??;+ Ok(serde_json::json!({ "result": result }))}fn pick_page<'a>(pages: &'a [Value], hint: Option<&str>) -> Option<&'a Value> {@@ -231,196 +239,13 @@ async fn cdp_list_pages(port: u16) -> anyhow::Result<Vec<Value>> {Ok(pages)}-// ── WebSocket CDP call ────────────────────────────────────────────────────--async fn cdp_ws_call(port: u16, ws_url: &str, message: &str) -> anyhow::Result<Value> {- use tokio::io::{AsyncReadExt, AsyncWriteExt};-- let path: String = if let Some(rest) = ws_url.strip_prefix("ws://") {- rest.split_once('/')- .map(|(_, path)| path)- .map(|p| format!("/{p}"))- .unwrap_or_else(|| "/".into())- } else {- ws_url.to_string()- };-- let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))- .await- .map_err(|e| anyhow::anyhow!("Cannot connect to CDP WebSocket on port {port}: {e}"))?;-- let handshake = format!(- "GET {path} HTTP/1.1\r\n\- Host: 127.0.0.1:{port}\r\n\- Upgrade: websocket\r\n\- Connection: Upgrade\r\n\- Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\- Sec-WebSocket-Version: 13\r\n\- \r\n"- );- stream.write_all(handshake.as_bytes()).await?;-- let mut hdr = Vec::with_capacity(512);- loop {- let mut b = [0u8; 1];- stream.read_exact(&mut b).await?;- hdr.push(b[0]);- if hdr.ends_with(b"\r\n\r\n") {- break;- }- if hdr.len() > 8192 {- anyhow::bail!("WebSocket upgrade response headers too large");- }- }- if !String::from_utf8_lossy(&hdr).contains("101") {- anyhow::bail!(- "WebSocket upgrade failed: {}",- String::from_utf8_lossy(&hdr[..hdr.len().min(200)])- );- }-- ws_write_text(&mut stream, message.as_bytes()).await?;-- loop {- match ws_read_frame(&mut stream).await? {- WsFrame::Text(text) => {- if let Ok(val) = serde_json::from_str::<Value>(&text) {- if val.get("id").and_then(|id| id.as_u64()) == Some(1) {- return Ok(val);- }- } else {- anyhow::bail!(- "CDP returned non-JSON frame: {}",- &text[..text.len().min(120)]- );- }- }- WsFrame::Ping(data) => {- ws_write_pong(&mut stream, &data).await?;- }- WsFrame::Close => {- anyhow::bail!("CDP WebSocket closed by server before response");- }- WsFrame::Other => { /* binary / continuation / pong — skip */ }- }- }-}--// ── WebSocket frame I/O ───────────────────────────────────────────────────--enum WsFrame {- Text(String),- Ping(Vec<u8>),- Close,- Other,-}--async fn ws_read_frame(stream: &mut tokio::net::TcpStream) -> anyhow::Result<WsFrame> {- use tokio::io::AsyncReadExt;-- let mut hdr = [0u8; 2];- stream.read_exact(&mut hdr).await?;-- let opcode = hdr[0] & 0x0F;- let masked = (hdr[1] & 0x80) != 0;- let len_byte = (hdr[1] & 0x7F) as usize;-- let payload_len: usize = match len_byte {- 0..=125 => len_byte,- 126 => {- let mut b = [0u8; 2];- stream.read_exact(&mut b).await?;- u16::from_be_bytes(b) as usize- }- _ => {- let mut b = [0u8; 8];- stream.read_exact(&mut b).await?;- let n = u64::from_be_bytes(b) as usize;- if n > 16 * 1024 * 1024 {- anyhow::bail!("CDP WebSocket frame too large ({n} bytes)");- }- n- }- };-- let mask_key: Option<[u8; 4]> = if masked {- let mut m = [0u8; 4];- stream.read_exact(&mut m).await?;- Some(m)- } else {- None- };-- let mut payload = vec![0u8; payload_len];- stream.read_exact(&mut payload).await?;- if let Some(mk) = mask_key {- for (i, b) in payload.iter_mut().enumerate() {- *b ^= mk[i % 4];- }- }-- match opcode {- 1 => Ok(WsFrame::Text(String::from_utf8(payload).map_err(|_| {- anyhow::anyhow!("CDP returned non-UTF-8 text frame")- })?)),- 2 => Ok(WsFrame::Other),- 8 => Ok(WsFrame::Close),- 9 => Ok(WsFrame::Ping(payload)),- _ => Ok(WsFrame::Other),- }-}--async fn ws_write_text(stream: &mut tokio::net::TcpStream, payload: &[u8]) -> anyhow::Result<()> {- use tokio::io::AsyncWriteExt;- const MASK: [u8; 4] = [0xDE, 0xAD, 0xBE, 0xEF];- let len = payload.len();-- let mut frame = Vec::with_capacity(len + 10);- frame.push(0x81u8);- encode_len_masked(&mut frame, len);- frame.extend_from_slice(&MASK);- for (i, &b) in payload.iter().enumerate() {- frame.push(b ^ MASK[i % 4]);- }- stream.write_all(&frame).await?;- Ok(())-}--async fn ws_write_pong(stream: &mut tokio::net::TcpStream, payload: &[u8]) -> anyhow::Result<()> {- use tokio::io::AsyncWriteExt;- const MASK: [u8; 4] = [0xCA, 0xFE, 0xBA, 0xBE];- let len = payload.len().min(125);-- let mut frame = Vec::with_capacity(len + 6);- frame.push(0x8Au8);- frame.push(0x80 | len as u8);- frame.extend_from_slice(&MASK);- for (i, &b) in payload[..len].iter().enumerate() {- frame.push(b ^ MASK[i % 4]);- }- stream.write_all(&frame).await?;- Ok(())-}--fn encode_len_masked(buf: &mut Vec<u8>, len: usize) {- if len < 126 {- buf.push(0x80 | len as u8);- } else if len <= 65535 {- buf.push(0x80 | 126);- buf.push((len >> 8) as u8);- buf.push(len as u8);- } else {- buf.push(0x80 | 127);- for i in (0..8).rev() {- buf.push((len >> (i * 8)) as u8);- }- }-}-#[cfg(test)]mod tests {- use super::pick_page;+ use super::{evaluate, format_cdp_result, pick_page};+ use futures_util::{SinkExt, StreamExt};use serde_json::json;+ use tokio::io::{AsyncReadExt, AsyncWriteExt};+ use tokio_tungstenite::{accept_async, tungstenite::Message};fn pages() -> Vec<serde_json::Value> {vec![@@ -450,4 +275,82 @@ mod tests {Some("ws://a"));}++ #[test]+ fn legacy_result_format_is_unchanged() {+ assert_eq!(+ format_cdp_result(&json!({ "result": { "result": { "value": "text" } } })),+ "\"text\""+ );+ assert_eq!(+ format_cdp_result(&json!({+ "result": {+ "exceptionDetails": {+ "exception": { "description": "ReferenceError: missing" }+ }+ }+ })),+ "exception: ReferenceError: missing"+ );+ }++ #[tokio::test]+ async fn evaluate_uses_event_aware_transport_without_changing_output() {+ let listener = tokio::net::TcpListener::bind(("127.0.0.1", 0))+ .await+ .unwrap();+ let port = listener.local_addr().unwrap().port();+ let server = tokio::spawn(async move {+ let (mut http, _) = listener.accept().await.unwrap();+ let mut request = [0u8; 1024];+ let _ = http.read(&mut request).await.unwrap();+ let body = json!([{+ "type": "page",+ "url": "app://fixture/",+ "webSocketDebuggerUrl": format!("ws://127.0.0.1:{port}/devtools/page/compat")+ }])+ .to_string();+ http.write_all(+ format!(+ "HTTP/1.1 200 OK\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{}",+ body.len(),+ body+ )+ .as_bytes(),+ )+ .await+ .unwrap();++ let (socket, _) = listener.accept().await.unwrap();+ let mut websocket = accept_async(socket).await.unwrap();+ let Message::Text(text) = websocket.next().await.unwrap().unwrap() else {+ panic!("expected Runtime.evaluate request")+ };+ let call: serde_json::Value = serde_json::from_str(&text).unwrap();+ assert_eq!(call["method"], "Runtime.evaluate");+ let id = call["id"].as_u64().unwrap();+ websocket+ .send(Message::Text(+ json!({ "method": "Runtime.consoleAPICalled", "params": {} })+ .to_string()+ .into(),+ ))+ .await+ .unwrap();+ websocket+ .send(Message::Text(+ json!({+ "id": id,+ "result": { "result": { "value": "compat" } }+ })+ .to_string()+ .into(),+ ))+ .await+ .unwrap();+ });++ assert_eq!(evaluate(port, "1 + 1", true).await.unwrap(), "\"compat\"");+ server.await.unwrap();+ }}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rsindex 21ffab2168..52bd0bd6e6 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs@@ -32,6 +32,7 @@ pub fn embedded_mode() -> bool {std::env::var_os(EMBEDDED_ENV).is_some_and(|v| v == "1")}+pub mod browser;pub mod capture_mode;pub mod cdp;pub mod element_cache;diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rsindex fa96486074..9017c238c5 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/policy.rs@@ -86,16 +86,9 @@ impl PolicyEngine {pub fn evaluate(&self, tool: &str, args: &Value) -> PolicyDecision {let tool = canonical_tool_name(tool);- let mut sanitized_args;- let args = if args.get("_session_id").is_some() {- sanitized_args = args.clone();- if let Some(object) = sanitized_args.as_object_mut() {- object.remove("_session_id");- }- &sanitized_args- } else {- args- };+ let mut sanitized_args = args.clone();+ crate::tool_args::sanitize_reserved_args(&mut sanitized_args);+ let args = &sanitized_args;#[cfg(not(any(feature = "yaml", feature = "rego")))]let _ = (tool, args);@@ -735,7 +728,7 @@ allow if {#[cfg(feature = "rego")]#[test]- fn rego_does_not_receive_internal_session_arguments() {+ fn rego_does_not_receive_internal_transport_arguments() {let dir = tempdir().unwrap();let path = dir.path().join("policy.rego");fs::write(@@ -756,7 +749,12 @@ allow if {assert_eq!(policy.evaluate("click",- &serde_json::json!({"x": 10, "_session_id": "internal"})+ &serde_json::json!({+ "x": 10,+ "_session_id": "public-session",+ "_transport_session_id": "transport-session",+ "_cua_browser_prepare_mcp_host_approved": true,+ })),PolicyDecision::Allow);diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/server.rsindex b16736f281..32dfc63e3f 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs@@ -445,10 +445,8 @@ fn classify_tool_completion(.and_then(|value| value.get("isError")).and_then(serde_json::Value::as_bool).unwrap_or(false);- let success = timer.valid_params- && timer.known_tool- && rpc_error_code.is_none()- && !tool_reported_error;+ let success =+ timer.valid_params && timer.known_tool && rpc_error_code.is_none() && !tool_reported_error;let error_class = if success {ToolErrorClass::None@@ -456,9 +454,7 @@ fn classify_tool_completion(ToolErrorClass::InvalidParams} else if !timer.known_tool {ToolErrorClass::UnknownTool- } else if rpc_error_code == Some(-32603)- && timer.path == StdioExecutionPath::DaemonProxy- {+ } else if rpc_error_code == Some(-32603) && timer.path == StdioExecutionPath::DaemonProxy {ToolErrorClass::TransportError} else if rpc_error_code.is_some() {ToolErrorClass::InternalError@@ -564,7 +560,11 @@ fn size_bucket(size: usize) -> OutputSizeBucket {/// tools/list / tools/call). Shared by the stdio loop above and the/// daemon's HTTP transport (`cua-driver`'s `mcp_http`) so both speak the/// exact same MCP semantics.-pub async fn handle_request(req: Request, id: serde_json::Value, registry: &Arc<ToolRegistry>) -> Response {+pub async fn handle_request(+ req: Request,+ id: serde_json::Value,+ registry: &Arc<ToolRegistry>,+) -> Response {match req.method.as_str() {"initialize" => Response::ok(id, initialize_result()),@@ -572,7 +572,8 @@ pub async fn handle_request(req: Request, id: serde_json::Value, registry: &Arc<"tools/call" => match req.tool_call() {Err(e) => Response::error(id, -32602, format!("Invalid params: {e}")),- Ok(call) => {+ Ok(mut call) => {+ crate::tool_args::sanitize_reserved_args(&mut call.args);match configured_policy() {Ok(Some(policy)) => match policy.evaluate(&call.name, &call.args) {PolicyDecision::Allow => {}@@ -600,6 +601,35 @@ pub async fn handle_request(req: Request, id: serde_json::Value, registry: &Arc<);}}++ let public_session = call+ .args+ .get("session")+ .and_then(serde_json::Value::as_str)+ .filter(|session| !session.is_empty())+ .map(str::to_owned);+ if let (Some(arguments), Some(session)) =+ (call.args.as_object_mut(), public_session)+ {+ arguments.insert(+ "_session_id".to_owned(),+ serde_json::Value::String(session.clone()),+ );+ arguments.insert(+ "_transport_session_id".to_owned(),+ serde_json::Value::String(session.clone()),+ );+ crate::session::touch_session(&session);+ }+ if call.name == "browser_prepare" {+ if let Some(arguments) = call.args.as_object_mut() {+ arguments.insert(+ crate::browser::approval::MCP_HOST_APPROVAL_ARG.to_owned(),+ serde_json::Value::Bool(true),+ );+ }+ }+let result = registry.invoke(&call.name, call.args).await;match serde_json::to_value(result) {Ok(v) => Response::ok(id, v),@@ -644,7 +674,10 @@ mod observation_tests {let debug = format!("{observation:?}");for forbidden in ["private task text", "private-base64", "result body"] {- assert!(!debug.contains(forbidden), "observer leaked content: {debug}");+ assert!(+ !debug.contains(forbidden),+ "observer leaked content: {debug}"+ );}}@@ -688,7 +721,10 @@ mod observation_tests {let invalid_observation =timer(false, false, StdioExecutionPath::InProcess).finish(&invalid);assert!(!invalid_observation.success);- assert_eq!(invalid_observation.error_class, ToolErrorClass::InvalidParams);+ assert_eq!(+ invalid_observation.error_class,+ ToolErrorClass::InvalidParams+ );assert_eq!(invalid_observation.output_type, OutputType::Empty);let unknown = Response::ok(@@ -717,7 +753,10 @@ mod observation_tests {#[test]fn structured_codes_map_without_error_text() {for (code, expected) in [- ("background_unavailable", ToolErrorClass::BackgroundUnavailable),+ (+ "background_unavailable",+ ToolErrorClass::BackgroundUnavailable,+ ),("permission_denied", ToolErrorClass::PermissionDenied),("private_custom_error", ToolErrorClass::InternalError),] {@@ -729,8 +768,7 @@ mod observation_tests {"structuredContent": {"code": code, "detail": "private detail"}}),);- let observation =- timer(true, true, StdioExecutionPath::InProcess).finish(&response);+ let observation = timer(true, true, StdioExecutionPath::InProcess).finish(&response);assert_eq!(observation.error_class, expected, "code={code}");let debug = format!("{observation:?}");assert!(!debug.contains("private prose"));diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rsindex b31c7fae17..4404091ea0 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs@@ -11,9 +11,8 @@ use crate::{protocol::{Content, ToolResult},recording::{now_ms, screenshot_for, RecordingSession},recording_tools::{- GetRecordingStateTool, ReplayTrajectoryTool, StartRecordingTool,+ init_replay_registry, GetRecordingStateTool, ReplayTrajectoryTool, StartRecordingTool,StopRecordingTool,- init_replay_registry,},tool_args::ArgsExt,};@@ -103,6 +102,8 @@ impl ToolDef {/// - `recording.start`, `recording.stop`, `recording.state`,/// `recording.replay`, `recording.install_dependency`/// - `page.action`+/// - `browser.state`, `browser.prepare`, `browser.navigate`,+/// `browser.input.click`, `browser.input.type`/// - `driver.update_check`, `driver.probe`////// Tools with no entry get `[]` — that's fine, it just means@@ -137,10 +138,7 @@ pub fn default_capabilities_for(tool_name: &str) -> Vec<String> {"parallel_mouse_drag" => &["input.pointer.drag"],"mouse_button_down" => &["input.pointer.button"],"mouse_button_up" => &["input.pointer.button"],- "scroll" => &[- "input.pointer.scroll",- "accessibility.element_tokens",- ],+ "scroll" => &["input.pointer.scroll", "accessibility.element_tokens"],"move_cursor" => &[// Visual overlay move, not a real OS pointer move on// macOS/Windows — see SKILL.md. Surfaced as@@ -173,14 +171,8 @@ pub fn default_capabilities_for(tool_name: &str) -> Vec<String> {// so we deliberately do NOT claim `terminal_safe` here — the// contract is intentionally narrower than `type_text`'s. It// still accepts `element_token`, hence the tokens claim.- "type_text_chars" => &[- "input.keyboard.type",- "accessibility.element_tokens",- ],- "press_key" => &[- "input.keyboard.press",- "accessibility.element_tokens",- ],+ "type_text_chars" => &["input.keyboard.type", "accessibility.element_tokens"],+ "press_key" => &["input.keyboard.press", "accessibility.element_tokens"],"hotkey" => &["input.keyboard.hotkey"],"set_value" => &[// Bulk-set an editable field's value — semantically a@@ -205,10 +197,7 @@ pub fn default_capabilities_for(tool_name: &str) -> Vec<String> {"get_cursor_position" => &["screen.cursor.position"],// ── accessibility / window state ─────────────────────────────- "get_accessibility_tree" => &[- "accessibility.tree",- "accessibility.tree.structured",- ],+ "get_accessibility_tree" => &["accessibility.tree", "accessibility.tree.structured"],"get_window_state" => &["accessibility.window_state","accessibility.tree",@@ -266,6 +255,17 @@ pub fn default_capabilities_for(tool_name: &str) -> Vec<String> {// ── cross-platform page ──────────────────────────────────────"page" => &["page.action"],+ // ── browser-tool v1 (exact-or-refused CDP surface) ───────────+ // Additive tokens; see `crate::browser` for semantics. The+ // input tools claim distinct browser.* tokens (not the+ // input.pointer/keyboard families) because they act inside a+ // page via CDP, not on the OS input layer.+ "get_browser_state" => &["browser.state"],+ "browser_prepare" => &["browser.prepare"],+ "browser_navigate" => &["browser.navigate"],+ "browser_click" => &["browser.input.click"],+ "browser_type" => &["browser.input.type"],+// ── driver self-service ──────────────────────────────────────"check_for_update" => &["driver.update_check"],"probe" => &["driver.probe"],@@ -334,8 +334,12 @@ impl ToolRegistry {}pub fn tools_list(&self) -> Value {- let list: Vec<Value> =- self.order.iter().filter_map(|n| self.tools.get(n)).map(|t| t.def().to_list_entry()).collect();+ let list: Vec<Value> = self+ .order+ .iter()+ .filter_map(|n| self.tools.get(n))+ .map(|t| t.def().to_list_entry())+ .collect();// `capability_version` is the contract version for the// capability tokens claimed by each tool entry. Bumped on// BREAKING vocabulary changes only; additive changes (new@@ -359,9 +363,9 @@ impl ToolRegistry {/// Iterate over (name, &ToolDef) in registration order.pub fn iter_defs(&self) -> impl Iterator<Item = (&str, &ToolDef)> {- self.order.iter().filter_map(move |n| {- self.tools.get(n).map(|t| (n.as_str(), t.def()))- })+ self.order+ .iter()+ .filter_map(move |n| self.tools.get(n).map(|t| (n.as_str(), t.def())))}/// Get a tool's ToolDef by name, or None if unknown.@@ -394,15 +398,36 @@ impl ToolRegistry {// Reserve and capture the turn before dispatch so recorded evidence// shows the application immediately before the action changed it.- let should_record = self.tools.get(resolved_name)+ let should_record = self+ .tools+ .get(resolved_name).map(|tool| !tool.def().read_only).unwrap_or(false)&& !matches!(resolved_name,"start_recording" | "stop_recording" | "get_recording_state" | "replay_trajectory");+ let recording_args = if resolved_name == "browser_prepare" {+ let mut redacted = args.clone();+ if let Some(arguments) = redacted.as_object_mut() {+ if arguments.contains_key("approval_token") {+ arguments.insert(+ "approval_token".to_owned(),+ Value::String("[redacted]".to_owned()),+ );+ }+ arguments.remove("_cua_browser_prepare_mcp_host_approved");+ arguments.remove("_transport_session_id");+ }+ redacted+ } else {+ args.clone()+ };let pending_turn = should_record- .then(|| self.recording.begin_turn(resolved_name, &args, start_ms))+ .then(|| {+ self.recording+ .begin_turn(resolved_name, &recording_args, start_ms)+ }).flatten();let result = match self.tools.get(resolved_name) {@@ -419,10 +444,15 @@ impl ToolRegistry {// stream stays the actual user-action sequence (not the meta// start/stop frames).if let Some(pending_turn) = pending_turn {- let result_text = result.content.iter()+ let result_text = result+ .content+ .iter().find_map(|c| {- if let Content::Text { text, .. } = c { Some(text.as_str()) }- else { None }+ if let Content::Text { text, .. } = c {+ Some(text.as_str())+ } else {+ None+ }}).unwrap_or("");self.recording.finish_turn(pending_turn, result_text);@@ -520,31 +550,65 @@ mod capability_tests {/// suite.const TOOLS_REQUIRING_CAPABILITIES: &[&str] = &[// pointer- "click", "double_click", "right_click", "drag", "scroll",- "move_cursor", "mouse_button_down", "mouse_button_up",- "mouse_drag", "parallel_mouse_drag",+ "click",+ "double_click",+ "right_click",+ "drag",+ "scroll",+ "move_cursor",+ "mouse_button_down",+ "mouse_button_up",+ "mouse_drag",+ "parallel_mouse_drag",// keyboard- "type_text", "type_text_chars", "press_key", "hotkey", "set_value",+ "type_text",+ "type_text_chars",+ "press_key",+ "hotkey",+ "set_value",// screen- "zoom", "get_screen_size", "get_desktop_state",+ "zoom",+ "get_screen_size",+ "get_desktop_state","get_cursor_position",// accessibility- "get_accessibility_tree", "get_window_state",+ "get_accessibility_tree",+ "get_window_state",// app / window- "launch_app", "list_apps", "kill_app", "list_windows",- "bring_to_front", "debug_window_info",+ "launch_app",+ "list_apps",+ "kill_app",+ "list_windows",+ "bring_to_front",+ "debug_window_info",// permissions / config- "check_permissions", "get_config", "set_config",+ "check_permissions",+ "get_config",+ "set_config",// sessions- "start_session", "end_session",+ "start_session",+ "end_session",// agent cursor- "set_agent_cursor_enabled", "set_agent_cursor_motion",- "set_agent_cursor_style", "get_agent_cursor_state",+ "set_agent_cursor_enabled",+ "set_agent_cursor_motion",+ "set_agent_cursor_style",+ "get_agent_cursor_state",// recording / replay- "start_recording", "stop_recording", "get_recording_state",- "replay_trajectory", "install_ffmpeg",+ "start_recording",+ "stop_recording",+ "get_recording_state",+ "replay_trajectory",+ "install_ffmpeg",// misc- "page", "check_for_update", "probe",+ "page",+ "check_for_update",+ "probe",+ // browser-tool v1+ "get_browser_state",+ "browser_prepare",+ "browser_navigate",+ "browser_click",+ "browser_type",];/// All capability tokens in the canonical vocabulary. Any token@@ -611,6 +675,12 @@ mod capability_tests {"recording.install_dependency",// page"page.action",+ // browser-tool v1+ "browser.state",+ "browser.prepare",+ "browser.navigate",+ "browser.input.click",+ "browser.input.type",// driver self"driver.update_check","driver.probe",@@ -631,8 +701,7 @@ mod capability_tests {#[test]fn every_claimed_capability_is_in_the_canonical_vocabulary() {- let vocab: std::collections::HashSet<&str> =- CANONICAL_VOCABULARY.iter().copied().collect();+ let vocab: std::collections::HashSet<&str> = CANONICAL_VOCABULARY.iter().copied().collect();for name in TOOLS_REQUIRING_CAPABILITIES {for cap in default_capabilities_for(name) {assert!(@@ -711,20 +780,26 @@ mod capability_tests {fn to_list_entry_includes_capabilities_array_for_a_known_tool() {let def = dummy_def("click");let entry = def.to_list_entry();- let caps = entry.get("capabilities")+ let caps = entry+ .get("capabilities").and_then(|v| v.as_array()).expect("capabilities must be an array");- assert!(!caps.is_empty(),- "click must claim at least one capability via default_capabilities_for");+ assert!(+ !caps.is_empty(),+ "click must claim at least one capability via default_capabilities_for"+ );// Specifically: click claims the `input.pointer.click.left`// family — that's the contract Hermes' cua_backend.py is// expected to dispatch on once this surface is wired up.- let cap_strs: Vec<&str> =- caps.iter().filter_map(|v| v.as_str()).collect();- assert!(cap_strs.contains(&"input.pointer.click"),- "click missing input.pointer.click: {cap_strs:?}");- assert!(cap_strs.contains(&"input.pointer.click.left"),- "click missing input.pointer.click.left: {cap_strs:?}");+ let cap_strs: Vec<&str> = caps.iter().filter_map(|v| v.as_str()).collect();+ assert!(+ cap_strs.contains(&"input.pointer.click"),+ "click missing input.pointer.click: {cap_strs:?}"+ );+ assert!(+ cap_strs.contains(&"input.pointer.click.left"),+ "click missing input.pointer.click.left: {cap_strs:?}"+ );}#[test]@@ -733,7 +808,8 @@ mod capability_tests {// present — consumers can rely on the key existing.let def = dummy_def("totally_made_up_tool");let entry = def.to_list_entry();- let caps = entry.get("capabilities")+ let caps = entry+ .get("capabilities").and_then(|v| v.as_array()).expect("capabilities must be present even if empty");assert!(caps.is_empty());diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rsindex cbf411cd7b..b357fcf568 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs@@ -30,6 +30,39 @@ use serde_json::Value;use crate::protocol::ToolResult;+/// Remove transport-reserved arguments supplied by a public caller. Trusted+/// ingress code calls this before injecting session or approval context, so a+/// tool request cannot forge underscore-prefixed transport evidence.+pub fn sanitize_reserved_args(args: &mut Value) {+ if let Some(object) = args.as_object_mut() {+ object.retain(|key, _| !key.starts_with('_'));+ }+}++#[cfg(test)]+mod reserved_args_tests {+ use super::sanitize_reserved_args;+ use serde_json::json;++ #[test]+ fn removes_all_top_level_reserved_arguments_only() {+ let mut args = json!({+ "pid": 42,+ "_session_id": "forged",+ "_cua_browser_prepare_mcp_host_approved": true,+ "profile": {"mode": "isolated_new", "_future_public_field": "retained"}+ });+ sanitize_reserved_args(&mut args);+ assert_eq!(+ args,+ json!({+ "pid": 42,+ "profile": {"mode": "isolated_new", "_future_public_field": "retained"}+ })+ );+ }+}+/// Format the canonical "missing required field" error.#[inline]fn missing(kind: &str, name: &str) -> ToolResult {@@ -40,17 +73,13 @@ fn missing(kind: &str, name: &str) -> ToolResult {/// present but a different JSON type than the caller asked for.#[inline]fn wrong_type(kind: &str, name: &str) -> ToolResult {- ToolResult::error(format!(- "Field {name} has wrong type — expected {kind}"- ))+ ToolResult::error(format!("Field {name} has wrong type — expected {kind}"))}/// Format the canonical out-of-range error for narrowing casts.#[inline]fn out_of_range(kind: &str, name: &str, raw: i128) -> ToolResult {- ToolResult::error(format!(- "Field {name} is out of range for {kind}: {raw}"- ))+ ToolResult::error(format!("Field {name} is out of range for {kind}: {raw}"))}/// Extension trait on `&serde_json::Value` (the MCP `arguments` blob)@@ -177,9 +206,7 @@ impl ArgsExt for Value {}fn opt_str(&self, name: &str) -> Option<String> {- self.get(name)- .and_then(|v| v.as_str())- .map(str::to_owned)+ self.get(name).and_then(|v| v.as_str()).map(str::to_owned)}fn opt_bool(&self, name: &str) -> Option<bool> {diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver-testkit/Cargo.tomlindex c5264661c9..fbc3719abf 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/Cargo.toml+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/Cargo.toml@@ -13,6 +13,9 @@ serde = { workspace = true }serde_json = { workspace = true }tempfile = "3"+[target.'cfg(unix)'.dependencies]+libc = "0.2"+[target.'cfg(target_os = "linux")'.dependencies]x11rb = "0.13"diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/bin/cua-e2e-report.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/bin/cua-e2e-report.rsindex f2654872d5..84a2ff411d 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/bin/cua-e2e-report.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/bin/cua-e2e-report.rs@@ -28,6 +28,18 @@ Options:\n --artifact-root <dir> Resolve and validate linked evidence artifact);}+fn canonical_environment(records: Vec<EnvironmentRecord>) -> EnvironmentRecord {+ let mut records = records.into_iter();+ let first = records.next().expect("expected an environment record");+ for record in records {+ assert_eq!(+ record, first,+ "conflicting environment records in one E2E report"+ );+ }+ first+}+fn main() {let args: Vec<String> = std::env::args().skip(1).collect();if args.iter().any(|arg| arg == "--help" || arg == "-h") {@@ -64,25 +76,27 @@ fn main() {if let Some(path) = environment {let records: Vec<EnvironmentRecord> = read_json_lines(&path).unwrap_or_else(|errors| panic!("invalid environment:\n{}", errors.join("\n")));- assert_eq!(records.len(), 1, "expected one environment record");- assert!(- environment_schema_supported(&records[0].schema),- "unsupported environment schema: {}",- records[0].schema,- );- source_sha = records[0].source_sha.clone();- if records[0].status == EnvironmentStatus::Error {+ for record in &records {+ assert!(+ environment_schema_supported(&record.schema),+ "unsupported environment schema: {}",+ record.schema,+ );+ }+ let record = canonical_environment(records);+ source_sha = record.source_sha.clone();+ if record.status == EnvironmentStatus::Error {emit(format!("# CUA Driver E2E\n\n**Environment:** ERROR\n\n{}\n",- records[0].message+ record.message),output.as_ref(),);- eprintln!("E2E environment is not ready: {}", records[0].message);+ eprintln!("E2E environment is not ready: {}", record.message);std::process::exit(2);}- environment_record = records.into_iter().next();+ environment_record = Some(record);}let summary = validate_catalog(&declarations,@@ -99,3 +113,27 @@ fn main() {);emit(markdown, output.as_ref());}++#[cfg(test)]+mod tests {+ use super::canonical_environment;+ use cua_driver_testkit::e2e::EnvironmentRecord;+ use std::time::Duration;++ #[test]+ fn identical_environment_records_collapse_to_one() {+ let record = EnvironmentRecord::ready(Duration::ZERO);+ assert_eq!(+ canonical_environment(vec![record.clone(), record.clone()]),+ record+ );+ }++ #[test]+ #[should_panic(expected = "conflicting environment records")]+ fn conflicting_environment_records_are_rejected() {+ let ready = EnvironmentRecord::ready(Duration::ZERO);+ let error = EnvironmentRecord::error(Duration::ZERO, "desktop unavailable");+ let _ = canonical_environment(vec![ready, error]);+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/browser_fixture.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/browser_fixture.rsnew file mode 100644index 0000000000..e597dc09d3--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/browser_fixture.rs@@ -0,0 +1,337 @@+use std::io::{Read, Write};+use std::net::{TcpListener, TcpStream};+use std::sync::atomic::{AtomicBool, Ordering};+use std::sync::{Arc, Mutex};+use std::thread;+use std::time::Duration;++/// Loopback HTTP host for the repo-owned browser fixture and its state oracle.+///+/// The page is served over HTTP so standalone browsers exercise an ordinary web+/// origin. Fixture state is POSTed back to `/state` and remains independent of+/// cua-driver responses.+pub struct BrowserFixtureServer {+ page_url: String,+ journal_url: String,+ latest: Arc<Mutex<serde_json::Value>>,+ observed: Arc<Mutex<Vec<serde_json::Value>>>,+ stop: Arc<AtomicBool>,+ worker: Option<thread::JoinHandle<()>>,+}++impl BrowserFixtureServer {+ pub fn start(html: &str) -> Self {+ let listener = TcpListener::bind(("127.0.0.1", 0)).expect("bind browser fixture server");+ listener+ .set_nonblocking(true)+ .expect("make browser fixture server nonblocking");+ let address = listener+ .local_addr()+ .expect("read browser fixture server address");+ let page_url = format!("http://{address}/fixture");+ let journal_url = format!("http://{address}/state");+ let journal_script = format!(+ "<script>window.__CUA_E2E_FIXTURE_JOURNAL_URL={};</script>",+ serde_json::to_string(&journal_url).expect("serialize fixture journal URL")+ );+ let page = if let Some(head) = html.find("<head>") {+ let insertion = head + "<head>".len();+ format!(+ "{}{}{}",+ &html[..insertion],+ journal_script,+ &html[insertion..]+ )+ } else {+ format!("{journal_script}{html}")+ }+ .into_bytes();+ let page = Arc::new(page);+ let latest = Arc::new(Mutex::new(serde_json::json!({})));+ let observed = Arc::new(Mutex::new(Vec::new()));+ let stop = Arc::new(AtomicBool::new(false));+ let latest_for_worker = Arc::clone(&latest);+ let observed_for_worker = Arc::clone(&observed);+ let stop_for_worker = Arc::clone(&stop);+ let worker = thread::spawn(move || {+ while !stop_for_worker.load(Ordering::Relaxed) {+ match listener.accept() {+ Ok((stream, _)) => {+ let page = Arc::clone(&page);+ let latest = Arc::clone(&latest_for_worker);+ let observed = Arc::clone(&observed_for_worker);+ thread::spawn(move || handle_connection(stream, &page, &latest, &observed));+ }+ Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {+ thread::sleep(Duration::from_millis(10));+ }+ Err(_) => break,+ }+ }+ });++ Self {+ page_url,+ journal_url,+ latest,+ observed,+ stop,+ worker: Some(worker),+ }+ }++ pub fn page_url(&self) -> &str {+ &self.page_url+ }++ /// Return the fixture URL through another loopback hostname.+ ///+ /// This is used by browser E2E rows that require Chromium to place an+ /// iframe in a distinct site while retaining a repo-owned loopback oracle.+ pub fn page_url_on_host(&self, host: &str) -> String {+ assert!(+ matches!(host, "localhost" | "127.0.0.1"),+ "fixture host must remain on loopback"+ );+ self.page_url.replacen("127.0.0.1", host, 1)+ }++ pub fn journal_url(&self) -> &str {+ &self.journal_url+ }++ pub fn contains(&self, marker: &str) -> bool {+ self.latest+ .lock()+ .expect("lock browser fixture")+ .to_string()+ .contains(marker)+ }++ pub fn text(&self, id: &str) -> Option<String> {+ self.latest+ .lock()+ .expect("lock browser fixture")+ .get(id)+ .and_then(|entry| entry.get("text"))+ .and_then(serde_json::Value::as_str)+ .map(str::to_owned)+ }++ pub fn value(&self, id: &str) -> Option<String> {+ self.latest+ .lock()+ .expect("lock browser fixture")+ .get(id)+ .and_then(|entry| entry.get("value"))+ .and_then(serde_json::Value::as_str)+ .map(str::to_owned)+ }++ pub fn snapshot(&self) -> serde_json::Value {+ self.latest.lock().expect("lock browser fixture").clone()+ }++ pub fn has_observed(&self, marker: &str) -> bool {+ self.observed+ .lock()+ .expect("lock browser fixture history")+ .iter()+ .any(|state| state.to_string().contains(marker))+ }+}++fn handle_connection(+ mut stream: TcpStream,+ page: &[u8],+ latest: &Arc<Mutex<serde_json::Value>>,+ observed: &Arc<Mutex<Vec<serde_json::Value>>>,+) {+ // BSD accept can preserve the listener's nonblocking flag. The fixture+ // handler needs a bounded blocking read so it does not close before the+ // browser has written its request bytes.+ if stream.set_nonblocking(false).is_err() {+ return;+ }+ let _ = stream.set_read_timeout(Some(Duration::from_secs(1)));+ let mut request = Vec::new();+ let mut chunk = [0u8; 8192];+ let mut body_range = None;+ loop {+ match stream.read(&mut chunk) {+ Ok(0) => break,+ Ok(n) => request.extend_from_slice(&chunk[..n]),+ Err(error)+ if matches!(+ error.kind(),+ std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut+ ) =>+ {+ break;+ }+ Err(_) => break,+ }+ if body_range.is_none() {+ body_range = request+ .windows(4)+ .position(|window| window == b"\r\n\r\n")+ .map(|header_end| {+ let headers = String::from_utf8_lossy(&request[..header_end]);+ let content_len = headers+ .lines()+ .find_map(|line| {+ line.split_once(':').and_then(|(name, value)| {+ name.eq_ignore_ascii_case("content-length").then_some(value)+ })+ })+ .and_then(|value| value.trim().parse::<usize>().ok())+ .unwrap_or(0);+ (header_end + 4, content_len)+ });+ }+ if let Some((body_start, content_len)) = body_range {+ if request.len() >= body_start + content_len {+ break;+ }+ }+ }++ let request_line = request+ .split(|byte| *byte == b'\n')+ .next()+ .map(String::from_utf8_lossy)+ .unwrap_or_default();+ if std::env::var_os("CUA_E2E_BROWSER_SERVER_LOG").is_some() {+ eprintln!("[browser-fixture] {request_line}");+ }+ if request_line.starts_with("GET /fixture ")+ || request_line.starts_with("GET /fixture?")+ || request_line.starts_with("GET / ")+ {+ let headers = format!(+ "HTTP/1.1 200 OK\r\nContent-Type: text/html; charset=utf-8\r\nContent-Length: {}\r\nCache-Control: no-store\r\nConnection: close\r\n\r\n",+ page.len()+ );+ let _ = stream.write_all(headers.as_bytes());+ let _ = stream.write_all(page);+ } else if request_line.starts_with("POST /state ") {+ if let Some((body_start, content_len)) = body_range {+ if let Some(body) = request.get(body_start..body_start + content_len) {+ if let Ok(state) = serde_json::from_slice::<serde_json::Value>(body) {+ *latest.lock().expect("lock browser fixture") = state.clone();+ observed+ .lock()+ .expect("lock browser fixture history")+ .push(state);+ }+ }+ }+ let _ = stream.write_all(+ b"HTTP/1.1 204 No Content\r\nAccess-Control-Allow-Origin: *\r\nConnection: close\r\n\r\n",+ );+ } else {+ let _ = stream+ .write_all(b"HTTP/1.1 404 Not Found\r\nContent-Length: 0\r\nConnection: close\r\n\r\n");+ }+}++impl Drop for BrowserFixtureServer {+ fn drop(&mut self) {+ self.stop.store(true, Ordering::Relaxed);+ if let Some(worker) = self.worker.take() {+ let _ = worker.join();+ }+ }+}++#[cfg(test)]+mod tests {+ use super::BrowserFixtureServer;+ use std::io::{Read, Write};+ use std::net::TcpStream;+ use std::time::{Duration, Instant};++ fn address(url: &str, suffix: &str) -> String {+ url.strip_prefix("http://")+ .and_then(|url| url.strip_suffix(suffix))+ .expect("fixture URL shape")+ .to_owned()+ }++ #[test]+ fn serves_fixture_and_receives_external_state() {+ let server = BrowserFixtureServer::start("<html><head></head><body>marker</body></html>");+ let address = address(server.page_url(), "/fixture");+ let mut stream = TcpStream::connect(&address).expect("connect browser fixture");+ stream+ .write_all(format!("GET /fixture HTTP/1.1\r\nHost: {address}\r\n\r\n").as_bytes())+ .expect("request browser fixture");+ let mut response = String::new();+ stream+ .read_to_string(&mut response)+ .expect("read browser fixture");+ assert!(response.contains("200 OK"));+ assert!(response.contains("marker"));+ assert!(response.contains(server.journal_url()));++ let body = r#"{"status":{"text":"last_action=left_click"}}"#;+ let mut stream = TcpStream::connect(&address).expect("connect browser journal");+ stream+ .write_all(+ format!(+ "POST /state HTTP/1.1\r\nHost: {address}\r\nContent-Length: {}\r\n\r\n{body}",+ body.len()+ )+ .as_bytes(),+ )+ .expect("post browser fixture state");+ drop(stream);++ let deadline = Instant::now() + Duration::from_secs(1);+ while !server.contains("last_action=left_click") && Instant::now() < deadline {+ std::thread::sleep(Duration::from_millis(10));+ }+ assert!(server.contains("last_action=left_click"));+ }++ #[test]+ fn idle_preconnection_does_not_block_fixture_requests() {+ let server = BrowserFixtureServer::start("<html><body>concurrent-marker</body></html>");+ let address = address(server.page_url(), "/fixture");+ let _idle = TcpStream::connect(&address).expect("open idle browser preconnection");++ let mut stream = TcpStream::connect(&address).expect("connect active browser request");+ stream+ .set_read_timeout(Some(Duration::from_millis(500)))+ .expect("bound active response wait");+ stream+ .write_all(format!("GET /fixture HTTP/1.1\r\nHost: {address}\r\n\r\n").as_bytes())+ .expect("request fixture behind idle connection");+ let mut response = String::new();+ stream+ .read_to_string(&mut response)+ .expect("active request must not wait for idle preconnection");++ assert!(response.contains("200 OK"));+ assert!(response.contains("concurrent-marker"));+ }++ #[test]+ fn accepts_request_bytes_after_a_short_client_delay() {+ let server = BrowserFixtureServer::start("<html><body>delayed-marker</body></html>");+ let address = address(server.page_url(), "/fixture");+ let mut stream = TcpStream::connect(&address).expect("connect delayed browser request");++ std::thread::sleep(Duration::from_millis(50));+ stream+ .write_all(format!("GET /fixture HTTP/1.1\r\nHost: {address}\r\n\r\n").as_bytes())+ .expect("send delayed browser request");+ let mut response = String::new();+ stream+ .read_to_string(&mut response)+ .expect("read delayed browser response");++ assert!(response.contains("200 OK"));+ assert!(response.contains("delayed-marker"));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rsindex 3785e2eac5..f5574bddf7 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/e2e.rs@@ -301,6 +301,14 @@ pub enum RefusalCode {BackgroundUnavailable,BackgroundOccluded,BackgroundUipiBlocked,+ BrowserRouteUnavailable,+ BrowserRequiresSetup,+ BrowserBindingAmbiguous,+ BrowserBindingStale,+ BrowserWrongTargetRefused,+ BrowserTabNotFound,+ BrowserRefStale,+ BrowserInputTrustUnavailable,}impl RefusalCode {@@ -309,6 +317,14 @@ impl RefusalCode {"background_unavailable" => Some(Self::BackgroundUnavailable),"background_occluded" => Some(Self::BackgroundOccluded),"background_uipi_blocked" => Some(Self::BackgroundUipiBlocked),+ "browser_route_unavailable" => Some(Self::BrowserRouteUnavailable),+ "browser_requires_setup" => Some(Self::BrowserRequiresSetup),+ "browser_binding_ambiguous" => Some(Self::BrowserBindingAmbiguous),+ "browser_binding_stale" => Some(Self::BrowserBindingStale),+ "browser_wrong_target_refused" => Some(Self::BrowserWrongTargetRefused),+ "browser_tab_not_found" => Some(Self::BrowserTabNotFound),+ "browser_ref_stale" => Some(Self::BrowserRefStale),+ "browser_input_trust_unavailable" => Some(Self::BrowserInputTrustUnavailable),_ => None,}}diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rsindex 547133d985..fa1d415e71 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/lib.rs@@ -34,6 +34,7 @@//! tests only; they are never read by the shipped driver.pub mod ax;+mod browser_fixture;mod driver;pub mod e2e;mod journal;@@ -48,6 +49,7 @@ pub mod sentinel;mod windows_setup;pub use driver::{BehaviorRecording, Driver};+pub use browser_fixture::BrowserFixtureServer;pub use journal::FixtureJournal;pub use mcp::McpDriver;pub use raw::RawDriver;diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/mcp.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/mcp.rsindex adfec45c69..0a779a16cd 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/mcp.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/mcp.rs@@ -37,25 +37,29 @@ impl McpDriver {/// Returns `None` (with a skip message) if the binary isn't built — the/// caller's test should early-return so an un-built binary skips, not fails.pub fn spawn() -> Option<Self> {- Self::spawn_internal(&[], None)+ Self::spawn_internal(&[], &[], None)}/// Spawn the driver with a stable recording label for artifact naming.pub fn spawn_named(recording_label: &str) -> Option<Self> {- Self::spawn_internal(&[], Some(recording_label))+ Self::spawn_internal(&[], &[], Some(recording_label))}/// Spawn a named driver with environment variables scoped to this child.pub fn spawn_named_with_env(recording_label: &str, env: &[(&str, &str)]) -> Option<Self> {- Self::spawn_internal(env, Some(recording_label))+ Self::spawn_internal(env, &[], Some(recording_label))}/// Spawn the driver with extra environment variables set on the child.pub fn spawn_with_env(env: &[(&str, &str)]) -> Option<Self> {- Self::spawn_internal(env, None)+ Self::spawn_internal(env, &[], None)}- fn spawn_internal(env: &[(&str, &str)], recording_label: Option<&str>) -> Option<Self> {+ fn spawn_internal(+ env: &[(&str, &str)],+ args: &[&str],+ recording_label: Option<&str>,+ ) -> Option<Self> {let bin = driver_binary();if !bin.exists() {eprintln!("[testkit] driver binary not built at {bin:?} — skipping");@@ -77,6 +81,9 @@ impl McpDriver {// A test that exercises telemetry can explicitly override this// through `spawn_with_env` / `spawn_named_with_env` below..env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "false");+ cmd.args(args);+ #[cfg(not(target_os = "macos"))]+ cmd.env("CUA_DRIVER_RS_MCP_NO_RELAUNCH", "1");for (key, value) in env {cmd.env(key, value);}@@ -138,7 +145,8 @@ impl McpDriver {#[cfg(target_os = "macos")]fn spawn_macos_daemon_proxy_internal(recording_label: Option<&str>) -> Option<Self> {let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());- let socket = format!("{home}/Library/Caches/cua-driver/cua-driver.sock");+ let socket = std::env::var("CUA_E2E_MACOS_DAEMON_SOCKET")+ .unwrap_or_else(|_| format!("{home}/Library/Caches/cua-driver/cua-driver.sock"));if std::os::unix::net::UnixStream::connect(&socket).is_err() {eprintln!("[testkit] CuaDriver daemon not listening at {socket} — \@@ -146,7 +154,11 @@ impl McpDriver {);return None;}- Self::spawn_internal(&[("CUA_DRIVER_RS_MCP_FORCE_PROXY", "1")], recording_label)+ Self::spawn_internal(+ &[("CUA_DRIVER_RS_MCP_FORCE_PROXY", "1")],+ &["mcp", "--socket", &socket],+ recording_label,+ )}fn initialize(&mut self) {diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/reaper.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/reaper.rsindex ac38d186c7..30d8b688ed 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/reaper.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/reaper.rs@@ -1,6 +1,6 @@-//! Cross-platform child reaping. Kills every spawned child on drop; on Windows-//! also assigns them to a kill-on-close Job Object so the OS reaps the whole-//! tree even on panic / SIGKILL / Ctrl-C.+//! Cross-platform child reaping. Kills every spawned child tree on drop:+//! Windows uses a kill-on-close Job Object, while Unix gives each test-owned+//! child its own process group and terminates that group explicitly.use std::process::{Child, Command};use std::time::Duration;@@ -58,6 +58,8 @@ impl Drop for ChildReaper {tree_kill(pid);}for c in &mut self.children {+ #[cfg(unix)]+ process_group_kill(c.id());tree_kill(c.id());let _ = c.kill();let _ = c.wait();@@ -70,12 +72,36 @@ impl Drop for ChildReaper {/// never outlive the test process. On other platforms a plain spawn (the/// [`ChildReaper`] still kills it on drop).pub fn spawn_in_job(cmd: &mut Command) -> std::io::Result<Child> {+ #[cfg(unix)]+ {+ use std::os::unix::process::CommandExt;+ cmd.process_group(0);+ }let child = cmd.spawn()?;#[cfg(target_os = "windows")]win::assign_child(&child);Ok(child)}+#[cfg(unix)]+fn process_group_kill(pid: u32) {+ let Some(group) = process_group_target(pid) else {+ return;+ };+ // A negative pid targets one process group. Do this directly: some `kill`+ // utilities parse `kill -9 -<pgid>` as `kill(-1, SIGKILL)` unless the+ // negative operand is protected with an implementation-specific `--`.+ unsafe {+ libc::kill(group, libc::SIGKILL);+ }+}++#[cfg(unix)]+fn process_group_target(pid: u32) -> Option<i32> {+ let pid = i32::try_from(pid).ok()?;+ (pid > 1).then_some(-pid)+}+#[cfg(target_os = "windows")]fn tree_kill(pid: u32) {use std::process::Stdio;@@ -158,3 +184,16 @@ mod win {}}}++#[cfg(all(test, unix))]+mod tests {+ use super::process_group_target;++ #[test]+ fn process_group_target_is_exact_and_never_all_processes() {+ assert_eq!(process_group_target(42), Some(-42));+ assert_eq!(process_group_target(0), None);+ assert_eq!(process_group_target(1), None);+ assert_eq!(process_group_target(u32::MAX), None);+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs b/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rsindex 3d707f30df..f9ce5491d7 100644--- a/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs+++ b/libs/cua-driver/rust/crates/cua-driver-testkit/src/sentinel.rs@@ -209,6 +209,8 @@ impl ForegroundSentinel {}reset_journal(&self.journal_path)?;+ #[cfg(target_os = "linux")]+ set_sway_fullscreen(driver, self.target, false)?;let raised = driver.call("bring_to_front",serde_json::json!({@@ -240,6 +242,8 @@ impl ForegroundSentinel {}activate_native_foreground(driver, self.target);+ #[cfg(target_os = "linux")]+ set_sway_fullscreen(driver, self.target, true)?;wait_for_native_focus_stable(self.target);std::thread::sleep(Duration::from_millis(150));reset_journal(&self.journal_path)?;@@ -255,15 +259,23 @@ impl ForegroundSentinel {/// Confirm the target is fully behind the ready foreground sentinel before/// the behavioral video boundary is crossed.pub fn assert_background_posture(&self, target: TargetWindow) -> Result<(), String> {- let observer = DesktopObserver::new(NativeObserver::new(), target);- let before = observer.snapshot().map_err(|error| error.to_string())?;- if before.target_z == crate::observer::TargetZ::BackgroundOccluded {- Ok(())- } else {- Err(format!(- "background target was not fully occluded before recording: {:?}",- before.target_z- ))+ let deadline = Instant::now() + Duration::from_secs(2);+ loop {+ let observer = DesktopObserver::new(NativeObserver::new(), target);+ let before = observer.snapshot().map_err(|error| error.to_string())?;+ if before.target_z == crate::observer::TargetZ::BackgroundOccluded {+ return Ok(());+ }+ if Instant::now() >= deadline {+ return Err(format!(+ "background target was not fully occluded before recording: {:?}",+ before.target_z+ ));+ }+ // Native maximize/fullscreen transitions can report focus before+ // their final geometry. This wait is outside the action boundary;+ // dispatch-time occlusion remains an immediate strict assertion.+ std::thread::sleep(Duration::from_millis(50));}}@@ -441,18 +453,42 @@ fn focus_sway_target(driver: &mut impl Driver, target: TargetWindow) -> Result<(return Ok(());}- let tree_output = Command::new("swaymsg")- .args(["-r", "-t", "get_tree"])- .output()- .map_err(|error| format!("read Sway tree for focus canary: {error}"))?;- if !tree_output.status.success() {- return Err(format!(- "read Sway tree for focus canary: {}",- String::from_utf8_lossy(&tree_output.stderr).trim()- ));+ let (_, con_id) = sway_tree_and_container_for_target(driver, target)?;+ run_sway_container_command(con_id, &["focus"], "focus canary")+}++#[cfg(target_os = "linux")]+fn set_sway_fullscreen(+ driver: &mut impl Driver,+ target: TargetWindow,+ enabled: bool,+) -> Result<(), String> {+ let is_sway = is_wayland_session()+ && std::env::var("CUA_E2E_WAYLAND_SESSION").is_ok_and(|session| session == "sway");+ if !is_sway {+ return Ok(());}- let tree: serde_json::Value = serde_json::from_slice(&tree_output.stdout)- .map_err(|error| format!("parse Sway tree for focus canary: {error}"))?;++ let (tree, view_id) = sway_tree_and_container_for_target(driver, target)?;+ let con_id = if enabled {+ view_id+ } else {+ sway_fullscreen_holder_id(&tree, view_id).unwrap_or(view_id)+ };+ let state = if enabled { "enable" } else { "disable" };+ run_sway_container_command(con_id, &["fullscreen", state], "fullscreen canary")?;+ if !enabled {+ wait_for_sway_fullscreen_cleared(view_id)?;+ }+ Ok(())+}++#[cfg(target_os = "linux")]+fn sway_tree_and_container_for_target(+ driver: &mut impl Driver,+ target: TargetWindow,+) -> Result<(serde_json::Value, i64), String> {+ let tree = read_sway_tree()?;let windows = driver.call("list_windows", serde_json::json!({}));if windows.is_error() {@@ -471,26 +507,143 @@ fn focus_sway_target(driver: &mut impl Driver, target: TargetWindow) -> Result<(target.pid, target.native_id)})?;+ Ok((tree, con_id))+}++#[cfg(target_os = "linux")]+fn read_sway_tree() -> Result<serde_json::Value, String> {+ let tree_output = Command::new("swaymsg")+ .args(["-r", "-t", "get_tree"])+ .output()+ .map_err(|error| format!("read Sway tree for focus canary: {error}"))?;+ if !tree_output.status.success() {+ return Err(format!(+ "read Sway tree for focus canary: {}",+ String::from_utf8_lossy(&tree_output.stderr).trim()+ ));+ }+ serde_json::from_slice(&tree_output.stdout)+ .map_err(|error| format!("parse Sway tree for focus canary: {error}"))+}++#[cfg(target_os = "linux")]+fn sway_path_to_container<'a>(+ node: &'a serde_json::Value,+ con_id: i64,+ path: &mut Vec<&'a serde_json::Value>,+) -> bool {+ path.push(node);+ if node["id"].as_i64() == Some(con_id) {+ return true;+ }+ for key in ["nodes", "floating_nodes"] {+ if let Some(children) = node[key].as_array() {+ for child in children {+ if sway_path_to_container(child, con_id, path) {+ return true;+ }+ }+ }+ }+ path.pop();+ false+}++#[cfg(target_os = "linux")]+fn sway_fullscreen_holder_id(tree: &serde_json::Value, view_id: i64) -> Option<i64> {+ let mut path = Vec::new();+ sway_path_to_container(tree, view_id, &mut path).then_some(())?;+ path.into_iter()+ .rev()+ .find(|node| node["fullscreen_mode"].as_i64().unwrap_or(0) != 0)+ .and_then(|node| node["id"].as_i64())+}++#[cfg(target_os = "linux")]+fn sway_container_fullscreen_mode(tree: &serde_json::Value, con_id: i64) -> Option<i64> {+ if tree["id"].as_i64() == Some(con_id) {+ return Some(tree["fullscreen_mode"].as_i64().unwrap_or(0));+ }+ ["nodes", "floating_nodes"].into_iter().find_map(|key| {+ tree[key].as_array().and_then(|children| {+ children+ .iter()+ .find_map(|child| sway_container_fullscreen_mode(child, con_id))+ })+ })+}++#[cfg(target_os = "linux")]+fn wait_for_sway_fullscreen_cleared(view_id: i64) -> Result<(), String> {+ let deadline = Instant::now() + Duration::from_secs(1);+ loop {+ let tree = read_sway_tree()?;+ let fullscreen_mode = sway_container_fullscreen_mode(&tree, view_id)+ .ok_or_else(|| format!("Sway fullscreen canary lost view {view_id}"))?;+ if fullscreen_mode == 0 {+ return Ok(());+ }+ if Instant::now() >= deadline {+ return Err(format!(+ "Sway fullscreen canary did not clear fullscreen mode {fullscreen_mode} for view {view_id}"+ ));+ }+ std::thread::sleep(Duration::from_millis(25));+ }+}+#[cfg(target_os = "linux")]+fn run_sway_container_command(con_id: i64, command: &[&str], purpose: &str) -> Result<(), String> {let criterion = format!("[con_id={con_id}]");let output = Command::new("swaymsg")- .args(["-r", criterion.as_str(), "focus"])+ .arg("-r")+ .arg(criterion.as_str())+ .args(command).output()- .map_err(|error| format!("run Sway focus canary for con_id {con_id}: {error}"))?;+ .map_err(|error| format!("run Sway {purpose} for con_id {con_id}: {error}"))?;let result: serde_json::Value = serde_json::from_slice(&output.stdout)- .map_err(|error| format!("parse Sway focus result for con_id {con_id}: {error}"))?;- let focused = output.status.success()+ .map_err(|error| format!("parse Sway {purpose} result for con_id {con_id}: {error}"))?;+ let succeeded = output.status.success()&& result.as_array().is_some_and(|results| {!results.is_empty() && results.iter().all(|item| item["success"] == true)});- if focused {- Ok(())- } else {+ if !succeeded {Err(format!(- "Sway focus canary for con_id {con_id} failed: stdout={} stderr={}",+ "Sway {purpose} for con_id {con_id} failed: stdout={} stderr={}",String::from_utf8_lossy(&output.stdout).trim(),String::from_utf8_lossy(&output.stderr).trim(),))+ } else {+ if std::env::var_os("CUA_E2E_DEBUG_SWAY").is_some() {+ let tree = read_sway_tree()?;+ let mut rows = Vec::new();+ collect_sway_debug_rows(&tree, &mut rows);+ eprintln!(+ "[testkit] Sway {purpose}: con_id={con_id} command={command:?} tree={rows:?}"+ );+ }+ Ok(())+ }+}++#[cfg(target_os = "linux")]+fn collect_sway_debug_rows(node: &serde_json::Value, rows: &mut Vec<String>) {+ let focused = node["focused"].as_bool().unwrap_or(false);+ let fullscreen = node["fullscreen_mode"].as_i64().unwrap_or(0);+ if focused || fullscreen != 0 || node["pid"].as_u64().is_some() {+ rows.push(format!(+ "id={} pid={} name={:?} focused={focused} fullscreen={fullscreen}",+ node["id"].as_i64().unwrap_or_default(),+ node["pid"].as_u64().unwrap_or_default(),+ node["name"].as_str().unwrap_or("")+ ));+ }+ for key in ["nodes", "floating_nodes"] {+ if let Some(children) = node[key].as_array() {+ for child in children {+ collect_sway_debug_rows(child, rows);+ }+ }}}@@ -563,6 +716,65 @@ fn sway_container_id(node: &serde_json::Value, title: &str) -> Option<i64> {mod sway_tests {use super::*;+ #[test]+ fn fullscreen_command_targets_the_holder_ancestor() {+ let tree = serde_json::json!({+ "id": 1,+ "nodes": [{+ "id": 30,+ "fullscreen_mode": 1,+ "nodes": [{+ "id": 31,+ "pid": 1234,+ "name": "CuaTestHarness Sentinel",+ "focused": true,+ "fullscreen_mode": 0+ }]+ }]+ });+ assert_eq!(sway_fullscreen_holder_id(&tree, 31), Some(30));+ }++ #[test]+ fn fullscreen_command_prefers_the_actionable_view() {+ let tree = serde_json::json!({+ "id": 1,+ "fullscreen_mode": 1,+ "nodes": [{+ "id": 30,+ "fullscreen_mode": 1,+ "nodes": [{+ "id": 31,+ "pid": 1234,+ "name": "CuaTestHarness Sentinel",+ "focused": true,+ "fullscreen_mode": 1+ }]+ }]+ });+ assert_eq!(sway_fullscreen_holder_id(&tree, 31), Some(31));+ }++ #[test]+ fn fullscreen_clear_checks_the_view_not_inherited_workspace_state() {+ let tree = serde_json::json!({+ "id": 1,+ "fullscreen_mode": 1,+ "nodes": [{+ "id": 30,+ "fullscreen_mode": 1,+ "nodes": [{+ "id": 31,+ "pid": 1234,+ "name": "CuaTestHarness Sentinel",+ "focused": true,+ "fullscreen_mode": 0+ }]+ }]+ });+ assert_eq!(sway_container_fullscreen_mode(&tree, 31), Some(0));+ }+#[test]fn focus_target_uses_unique_sway_pid_when_title_is_unavailable() {let tree = serde_json::json!({@@ -699,15 +911,17 @@ fn wait_for_native_focus_lost(target: TargetWindow) -> Result<(), String> {let backend = NativeObserver::new();let deadline = Instant::now() + Duration::from_secs(3);loop {- let lost = backend- .snapshot(target)- .map(|snapshot| snapshot.target_z != TargetZ::Foreground)- .unwrap_or(false);+ let snapshot = backend.snapshot(target).ok();+ let lost = snapshot+ .as_ref()+ .is_some_and(|snapshot| snapshot.target_z != TargetZ::Foreground);if lost {return Ok(());}if Instant::now() >= deadline {- return Err("native Wayland focus-loss canary was not detected".to_owned());+ return Err(format!(+ "native Wayland focus-loss canary was not detected; last snapshot: {snapshot:?}"+ ));}std::thread::sleep(Duration::from_millis(25));}diff --git a/libs/cua-driver/rust/crates/cua-driver/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver/Cargo.tomlindex f915a83249..658102d1c2 100644--- a/libs/cua-driver/rust/crates/cua-driver/Cargo.toml+++ b/libs/cua-driver/rust/crates/cua-driver/Cargo.toml@@ -83,6 +83,8 @@ base64 = { workspace = true }# Isolated HOME / cache directories for `version_check` unit tests so they# never touch the developer's real `~/.cua-driver-rs/version_check.json`.tempfile = "3"+futures-util = "0.3"+tokio-tungstenite = "0.24"[target.'cfg(target_os = "windows")'.dev-dependencies]platform-windows = { path = "../platform-windows" }diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex 97241774c3..15de58fed0 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -12,8 +12,8 @@//! Cursor-overlay flags (--cursor-id, --no-overlay, etc.) are consumed by//! `CursorConfig::from_args()` and are ignored here.-use std::process;use cua_driver_core::{protocol::Content, tool::ToolRegistry};+use std::process;/// Which CLI command was requested.pub enum Command {@@ -51,7 +51,9 @@ pub enum Command {/// through it.socket: Option<String>,},- McpConfig { client: Option<String> },+ McpConfig {+ client: Option<String>,+ },Serve {socket: Option<String>,/// True when `--no-permissions-gate` is on argv. The env-var@@ -67,23 +69,45 @@ pub enum Command {/// which always routes through the proxy on an installed bundle.claude_code_compat: bool,},- Stop { socket: Option<String> },- Status { socket: Option<String> },- Recording { subcommand: String, args: Vec<String>, socket: Option<String> },- DumpDocs { pretty: bool, doc_type: String },- Update { apply: bool, json: bool },+ Stop {+ socket: Option<String>,+ },+ Status {+ socket: Option<String>,+ },+ Recording {+ subcommand: String,+ args: Vec<String>,+ socket: Option<String>,+ },+ DumpDocs {+ pretty: bool,+ doc_type: String,+ },+ Update {+ apply: bool,+ json: bool,+ },/// `cua-driver check-update [--json] [--no-cache]` — pure check verb./// Never installs; the apply path stays on `update --apply` so the/// "did anything change on disk?" question is unambiguous from argv./// Mirror of the `check_for_update` MCP tool — both routes share/// `crate::version_check::check_update_state`.- CheckUpdate { json: bool, no_cache: bool },- Doctor { json: bool },+ CheckUpdate {+ json: bool,+ no_cache: bool,+ },+ Doctor {+ json: bool,+ },Diagnose,/// `cua-driver permissions status|grant [--json]` — report TCC status/// (with source attribution + a live capture probe) or raise the/// correctly-attributed grant by launching CuaDriver via LaunchServices.- Permissions { subcommand: String, json: bool },+ Permissions {+ subcommand: String,+ json: bool,+ },Config {/// `show` | `get` | `set` | `reset` (None → show)subcommand: Option<String>,@@ -101,7 +125,9 @@ pub enum Command {/// (lands in Session 1+). macOS / Linux: not yet implemented; the/// stub returns a helpful "use install-local.sh --autostart"/// message. See `crates/cua-driver/src/autostart.rs`.- Autostart { subcommand: String },+ Autostart {+ subcommand: String,+ },/// `cua-driver manifest` — emit a stable JSON description of the CLI/// surface (subcommands, args, MCP invocation, version).///@@ -114,7 +140,9 @@ pub enum Command {/// Mirrors the existing `dump-docs` shape (read-only inspection/// subcommand) and is purely additive: never removes a field,/// never renames an existing one.- Manifest { pretty: bool },+ Manifest {+ pretty: bool,+ },/// `cua-driver skills {install|update|uninstall|status|path}` —/// agent skill-pack management. The verb is the ONLY way a user/// installs or updates the cua-driver skill pack into their agent@@ -126,7 +154,17 @@ pub enum Command {/// GitHub, places it under `<HomeDir>/skills/cua-driver/`, and/// symlinks into each detected agent's `skills/` dir. See/// `crates/cua-driver/src/skills.rs`.- Skills { subcommand: String, flags: Vec<String> },+ Skills {+ subcommand: String,+ flags: Vec<String>,+ },+ /// Mint a short-lived, single-use approval token for a direct/raw+ /// `browser_prepare` call. This command requires an interactive terminal.+ BrowserApprove {+ pid: i64,+ profile_mode: String,+ profile_name: Option<String>,+ },}pub enum TelemetryCommand {@@ -141,10 +179,22 @@ pub enum TelemetryCommand {/// Flags whose next token is a value (not a subcommand)./// We skip both the flag and its value when scanning for the subcommand.const VALUE_FLAGS: &[&str] = &[- "--cursor-icon", "--cursor-id", "--cursor-palette", "--cursor-shape",- "--glide-ms", "--dwell-ms", "--idle-hide-ms",- "--screenshot-out-file", "--client", "--socket", "--pid-file", "--type",+ "--cursor-icon",+ "--cursor-id",+ "--cursor-palette",+ "--cursor-shape",+ "--glide-ms",+ "--dwell-ms",+ "--idle-hide-ms",+ "--screenshot-out-file",+ "--client",+ "--socket",+ "--pid-file",+ "--type","--host-bundle-id",+ "--pid",+ "--profile-mode",+ "--profile-name",// Experimental PiP preview — value flag for the optional geometry// override (--experimental-pip itself is a bare flag and doesn't// need to be listed here).@@ -199,6 +249,7 @@ fn finite_command_name_from_args(args: &[String]) -> Option<&'static str> {Some("permissions") => Some("permissions"),Some("autostart") => Some("autostart"),Some("skills") => Some("skills"),+ Some("browser-approve") => Some("browser_approve"),Some("config") => Some("config"),Some(_) => Some("call"),}@@ -323,9 +374,12 @@ pub fn parse_command() -> Command {std::process::exit(0);}if args.iter().any(|a| a == "--help" || a == "-h") {- println!("cua-driver {} — cross-platform computer-use automation driver", env!("CARGO_PKG_VERSION"));+ println!(+ "cua-driver {} — cross-platform computer-use automation driver",+ env!("CARGO_PKG_VERSION")+ );println!("Usage: cua-driver [SUBCOMMAND] [OPTIONS]");- println!("Subcommands: mcp, list-tools, describe, call, serve, stop, status, config, telemetry, recording, update, check-update, doctor, diagnose, permissions, autostart, skills, manifest");+ println!("Subcommands: mcp, list-tools, describe, call, serve, stop, status, config, telemetry, recording, update, check-update, doctor, diagnose, permissions, autostart, skills, browser-approve, manifest");println!();println!("permissions options (macOS):");println!(" cua-driver permissions status Report Accessibility + Screen Recording status. Read-only (no prompt).");@@ -362,36 +416,67 @@ pub fn parse_command() -> Command {println!(" cua-driver skills path Print where the local skill pack lives.");println!(" --from main (install only) Fetch latest from main branch instead of the tagged release.");println!();+ println!("browser preparation approval:");+ println!(" cua-driver browser-approve --pid <pid> --profile-mode isolated_new");+ println!(" cua-driver browser-approve --pid <pid> --profile-mode isolated_named --profile-name <name>");+ println!(" Interactively mint a five-minute, single-use token for a");+ println!(" direct CLI/raw browser_prepare call. MCP hosts use their");+ println!(" destructive-tool approval flow instead.");+ println!();println!("mcp options (macOS):");- println!(" --no-daemon-relaunch Stay in-process; skip auto-launching the CuaDriver daemon.");+ println!(+ " --no-daemon-relaunch Stay in-process; skip auto-launching the CuaDriver daemon."+ );println!(" Also: CUA_DRIVER_RS_MCP_NO_RELAUNCH=1");println!(" --embedded Run embedded inside a host app (also: CUA_DRIVER_EMBEDDED=1).");println!(" Inherits the host's TCC grants; never prompts or relaunches.");println!(" See Skills/cua-driver/EMBEDDING.md.");- println!(" --host-bundle-id <id> Advisory host bundle id label for check_permissions output.");- println!(" --socket <path> Override the daemon UDS path used by the proxy fallback.");+ println!(+ " --host-bundle-id <id> Advisory host bundle id label for check_permissions output."+ );+ println!(+ " --socket <path> Override the daemon UDS path used by the proxy fallback."+ );println!(" --claude-code-computer-use-compat");println!(" Select the Claude Code computer-use compat surface.");- println!(" Now forwarded to the proxy-launched daemon (was a no-op");- println!(" on the proxy path — the path you actually run — because");+ println!(+ " Now forwarded to the proxy-launched daemon (was a no-op"+ );+ println!(+ " on the proxy path — the path you actually run — because"+ );println!(" the daemon hardcoded compat=false). Note: the compat");- println!(" screenshot tool itself was removed in #1692, so the flag");- println!(" has no tool-surface effect today; the wiring is in place");+ println!(+ " screenshot tool itself was removed in #1692, so the flag"+ );+ println!(+ " has no tool-surface effect today; the wiring is in place"+ );println!(" for any future compat-gated tool.");println!();println!("agent cursor overlay (serve / mcp only — needs the daemon UI runloop):");println!(" The overlay is ON by default: every MCP session automatically gets its own");- println!(" cursor (keyed by session id) that shows where the agent acts without moving the");+ println!(+ " cursor (keyed by session id) that shows where the agent acts without moving the"+ );println!(" real pointer. It is removed when the session ends. A pure accessibility (AX)");- println!(" action snaps the cursor with a brief pulse on its first action instead of a long");+ println!(+ " action snaps the cursor with a brief pulse on its first action instead of a long"+ );println!(" glide, so it can be easy to miss — do a pixel click or move_cursor first");println!(" for a visibly gliding demo. These flags tune the overlay on `serve`/`mcp`:");println!(" --no-overlay Disable the cursor overlay entirely for this daemon.");- println!(" --cursor-id <id> Name the default cursor instance (default: 'default').");+ println!(+ " --cursor-id <id> Name the default cursor instance (default: 'default')."+ );println!(" --cursor-icon <path> Use a custom PNG / JPEG / SVG / ICO cursor asset.");- println!(" --cursor-shape <name> Built-in silhouette: {} ('teardrop' is the default —",- cursor_overlay::BuiltinShape::names_help());- println!(" embedded cursor-up SVG; 'arrow' is the procedural gradient");+ println!(+ " --cursor-shape <name> Built-in silhouette: {} ('teardrop' is the default —",+ cursor_overlay::BuiltinShape::names_help()+ );+ println!(+ " embedded cursor-up SVG; 'arrow' is the procedural gradient"+ );println!(" diamond). Same vocabulary as MCP `cursor_icon`.");println!(" --cursor-palette <name> Pick a built-in colour palette for the cursor.");println!(" (These are no-ops for one-shot CLI calls like `cua-driver call` — the overlay");@@ -400,7 +485,9 @@ pub fn parse_command() -> Command {println!("manifest options:");println!(" cua-driver manifest Emit a stable JSON description of this CLI's surface");println!(" (subcommands, args, MCP invocation, version). Read-only.");- println!(" Consumers (Hermes, Claude Code, …) read it to drop");+ println!(+ " Consumers (Hermes, Claude Code, …) read it to drop"+ );println!(" hardcoded launch argv like _CUA_DRIVER_ARGS = [\"mcp\"].");println!(" --pretty / -p Pretty-print the JSON.");println!();@@ -409,9 +496,15 @@ pub fn parse_command() -> Command {println!();println!("experimental options (default: off):");println!(" --experimental-pip Show a small always-on-top window with the latest");- println!(" post-action screenshot + a 1-line label. macOS only");- println!(" today; Win/Linux print a not-yet-implemented notice.");- println!(" --experimental-pip-geometry WxH[+X+Y] Override window size (and optional top-left");+ println!(+ " post-action screenshot + a 1-line label. macOS only"+ );+ println!(+ " today; Win/Linux print a not-yet-implemented notice."+ );+ println!(+ " --experimental-pip-geometry WxH[+X+Y] Override window size (and optional top-left"+ );println!(" origin). Defaults to 480x360 in the top-right");println!(" corner of the main display.");std::process::exit(0);@@ -421,6 +514,9 @@ pub fn parse_command() -> Command {let screenshot_out_file = flag_value(&args, "--screenshot-out-file");let mcp_client = flag_value(&args, "--client");let socket = flag_value(&args, "--socket");+ let approval_pid = flag_value(&args, "--pid");+ let approval_profile_mode = flag_value(&args, "--profile-mode");+ let approval_profile_name = flag_value(&args, "--profile-name");// `--embedded` / `--host-bundle-id` export to the environment rather// than threading through `Command`: all consumers read@@ -448,7 +544,9 @@ pub fn parse_command() -> Command {}let no_daemon_relaunch = args.iter().any(|a| a == "--no-daemon-relaunch");- let claude_code_compat = args.iter().any(|a| a == "--claude-code-computer-use-compat");+ let claude_code_compat = args+ .iter()+ .any(|a| a == "--claude-code-computer-use-compat");let mut pos = positionals.into_iter();match pos.next() {@@ -498,7 +596,11 @@ pub fn parse_command() -> Command {Some("recording") => {let subcommand = pos.next().unwrap_or("status").to_string();let rest: Vec<String> = pos.map(str::to_owned).collect();- Command::Recording { subcommand, args: rest, socket }+ Command::Recording {+ subcommand,+ args: rest,+ socket,+ }}Some("dump-docs") => {let pretty = args.iter().any(|a| a == "--pretty" || a == "-p");@@ -538,7 +640,12 @@ pub fn parse_command() -> Command {let subcommand = pos.next().map(str::to_owned);let key = pos.next().map(str::to_owned);let value = pos.next().map(str::to_owned);- Command::Config { subcommand, key, value, socket }+ Command::Config {+ subcommand,+ key,+ value,+ socket,+ }}Some("describe") => {let name = pos.next().unwrap_or("").to_string();@@ -561,12 +668,17 @@ pub fn parse_command() -> Command {Some(s) => match serde_json::from_str(s) {Ok(v) => Some(v),Err(e) => {- eprintln!("error: positional JSON arg to 'cua-driver call' did not parse: {e}");+ eprintln!(+ "error: positional JSON arg to 'cua-driver call' did not parse: {e}"+ );eprintln!(" received: {s}");eprintln!();eprintln!("hint: PowerShell 5.1 strips quotes around JSON field names in");eprintln!(" multi-field args. Pipe the JSON via stdin instead:");- eprintln!(" '{{\"pid\":1234,\"window_id\":5678}}' | cua-driver call {}", tool);+ eprintln!(+ " '{{\"pid\":1234,\"window_id\":5678}}' | cua-driver call {}",+ tool+ );eprintln!();eprintln!(" Or use PowerShell 7+ (pwsh) which preserves the quotes.");process::exit(2);@@ -574,31 +686,34 @@ pub fn parse_command() -> Command {},None => read_stdin_json(),};- Command::Call { tool, json_args, screenshot_out_file, socket: socket.clone() }- }- Some("telemetry") => {- match pos.next() {- Some("install-event") => Command::Telemetry(TelemetryCommand::InstallEvent),- Some("enable") => Command::Telemetry(TelemetryCommand::Enable),- Some("disable") => Command::Telemetry(TelemetryCommand::Disable),- Some("status") => Command::Telemetry(TelemetryCommand::Status {- json: args.iter().any(|arg| arg == "--json"),- }),- Some("reset-id") => Command::Telemetry(TelemetryCommand::ResetId),- Some("inspect") => {- let event = pos.next().unwrap_or("").to_owned();- if event.is_empty() {- eprintln!("Usage: cua-driver telemetry inspect <event> --json");- process::exit(64);- }- Command::Telemetry(TelemetryCommand::Inspect { event })- }- _ => {- eprintln!("Usage: cua-driver telemetry {{enable|disable|status [--json]|reset-id|inspect <event> --json}}");+ Command::Call {+ tool,+ json_args,+ screenshot_out_file,+ socket: socket.clone(),+ }+ }+ Some("telemetry") => match pos.next() {+ Some("install-event") => Command::Telemetry(TelemetryCommand::InstallEvent),+ Some("enable") => Command::Telemetry(TelemetryCommand::Enable),+ Some("disable") => Command::Telemetry(TelemetryCommand::Disable),+ Some("status") => Command::Telemetry(TelemetryCommand::Status {+ json: args.iter().any(|arg| arg == "--json"),+ }),+ Some("reset-id") => Command::Telemetry(TelemetryCommand::ResetId),+ Some("inspect") => {+ let event = pos.next().unwrap_or("").to_owned();+ if event.is_empty() {+ eprintln!("Usage: cua-driver telemetry inspect <event> --json");process::exit(64);}+ Command::Telemetry(TelemetryCommand::Inspect { event })}- }+ _ => {+ eprintln!("Usage: cua-driver telemetry {{enable|disable|status [--json]|reset-id|inspect <event> --json}}");+ process::exit(64);+ }+ },Some("autostart") => {// No `cua-driver autostart` (no subcommand) shortcut today —// every operation is destructive enough that we want the@@ -626,6 +741,25 @@ pub fn parse_command() -> Command {}Command::Skills { subcommand, flags }}+ Some("browser-approve") => {+ let pid = approval_pid+ .as_deref()+ .and_then(|value| value.parse::<i64>().ok())+ .filter(|pid| *pid > 0)+ .unwrap_or_else(|| {+ eprintln!("browser-approve requires --pid <positive integer>");+ process::exit(64);+ });+ let profile_mode = approval_profile_mode.unwrap_or_else(|| {+ eprintln!("browser-approve requires --profile-mode isolated_new|isolated_named");+ process::exit(64);+ });+ Command::BrowserApprove {+ pid,+ profile_mode,+ profile_name: approval_profile_name,+ }+ }Some(first) => {// Implicit call: unrecognised first positional → treat as tool name.// Same parse-error handling as the explicit `call` branch above. See #1637.@@ -634,12 +768,17 @@ pub fn parse_command() -> Command {Some(s) => match serde_json::from_str(s) {Ok(v) => Some(v),Err(e) => {- eprintln!("error: positional JSON arg to 'cua-driver {tool}' did not parse: {e}");+ eprintln!(+ "error: positional JSON arg to 'cua-driver {tool}' did not parse: {e}"+ );eprintln!(" received: {s}");eprintln!();eprintln!("hint: PowerShell 5.1 strips quotes around JSON field names in");eprintln!(" multi-field args. Pipe the JSON via stdin instead:");- eprintln!(" '{{\"pid\":1234,\"window_id\":5678}}' | cua-driver {}", tool);+ eprintln!(+ " '{{\"pid\":1234,\"window_id\":5678}}' | cua-driver {}",+ tool+ );eprintln!();eprintln!(" Or use PowerShell 7+ (pwsh) which preserves the quotes.");process::exit(2);@@ -647,7 +786,58 @@ pub fn parse_command() -> Command {},None => read_stdin_json(),};- Command::Call { tool, json_args, screenshot_out_file, socket: socket.clone() }+ Command::Call {+ tool,+ json_args,+ screenshot_out_file,+ socket: socket.clone(),+ }+ }+ }+}++pub fn run_browser_approve(pid: i64, profile_mode: &str, profile_name: Option<&str>) {+ use std::io::{IsTerminal as _, Write as _};++ if !std::io::stdin().is_terminal() || !std::io::stderr().is_terminal() {+ eprintln!("browser-approve requires an interactive terminal; approval cannot be piped or scripted");+ process::exit(1);+ }+ let mode = match profile_mode {+ "isolated_new" => cua_driver_core::browser::PrepareProfileMode::IsolatedNew,+ "isolated_named" => cua_driver_core::browser::PrepareProfileMode::IsolatedNamed,+ other => {+ eprintln!("unsupported profile mode {other:?}; use isolated_new or isolated_named");+ process::exit(64);+ }+ };+ let profile = cua_driver_core::browser::PrepareProfile {+ mode,+ name: profile_name.map(str::to_owned),+ };+ if let Err(error) = cua_driver_core::browser::approval::validate_profile(&profile) {+ eprintln!("{}", error.message);+ process::exit(64);+ }+ eprintln!("Approve CUA Driver to launch a separate driver-owned Chromium profile?");+ eprintln!(" source pid: {pid}");+ eprintln!(" profile mode: {profile_mode}");+ if let Some(name) = profile_name {+ eprintln!(" profile name: {name}");+ }+ eprintln!("The existing browser process and its profile will not be modified or terminated.");+ eprint!("Type APPROVE to continue: ");+ let _ = std::io::stderr().flush();+ let mut confirmation = String::new();+ if std::io::stdin().read_line(&mut confirmation).is_err() || confirmation.trim() != "APPROVE" {+ eprintln!("browser preparation approval declined; no artifact was created");+ process::exit(1);+ }+ match cua_driver_core::browser::approval::mint_prepare_approval(pid, profile) {+ Ok(token) => println!("{token}"),+ Err(error) => {+ eprintln!("{}", error.message);+ process::exit(1);}}}@@ -705,7 +895,9 @@ pub fn run_describe(registry: &ToolRegistry, name: &str) {print!("name: {}\n", def.name);if !def.description.is_empty() {print!("\ndescription:\n{}", def.description);- if !def.description.ends_with('\n') { println!(); }+ if !def.description.ends_with('\n') {+ println!();+ }}print!("\ninput_schema:\n");let pretty = serde_json::to_string_pretty(&def.input_schema)@@ -909,8 +1101,12 @@ pub fn launch_daemon_and_wait("`open -n -g -a CuaDriver --args serve{}` exited {:?}. \Check that `/Applications/CuaDriver.app` is installed, or \pass --no-daemon-relaunch to bypass.",- if pass_socket { format!(" --socket {socket_path}") } else { String::new() },- status.code()+ if pass_socket {+ format!(" --socket {socket_path}")+ } else {+ String::new()+ },+ status.code()),});}@@ -1243,14 +1439,16 @@ pub fn run_mcp_config(client: Option<&str>) {match client {None | Some("") => {- println!(r#"{{+ println!(+ r#"{{"mcpServers": {{"cua-driver": {{"command": "{binary}","args": ["mcp"]}}}}-}}"#);+}}"#+ );}Some("claude") | Some("claude-code") => {// Claude Code wants the MCP server registered as@@ -1296,13 +1494,17 @@ pub fn run_mcp_config(client: Option<&str>) {let json = cfg.to_string();#[cfg(windows)]let json = json.replace('"', "\\\"");- println!("claude mcp add-json --scope user cua-computer-use '{}'", json);+ println!(+ "claude mcp add-json --scope user cua-computer-use '{}'",+ json+ );}Some("codex") => {println!("codex mcp add cua-driver -- {binary} mcp");}Some("cursor") => {- println!(r#"{{+ println!(+ r#"{{"mcpServers": {{"cua-driver": {{"command": "{binary}",@@ -1310,13 +1512,17 @@ pub fn run_mcp_config(client: Option<&str>) {"type": "stdio"}}}}-}}"#);+}}"#+ );}Some("openclaw") => {- println!("openclaw mcp set cua-driver '{{\"command\":\"{binary}\",\"args\":[\"mcp\"]}}'");+ println!(+ "openclaw mcp set cua-driver '{{\"command\":\"{binary}\",\"args\":[\"mcp\"]}}'"+ );}Some("opencode") => {- println!(r#"// paste under "mcp" in opencode.json:+ println!(+ r#"// paste under "mcp" in opencode.json:{{"$schema": "https://opencode.ai/config.json","mcp": {{@@ -1326,7 +1532,8 @@ pub fn run_mcp_config(client: Option<&str>) {"enabled": true}}}}-}}"#);+}}"#+ );}Some("hermes") => {println!("# paste under mcp_servers in ~/.hermes/config.yaml,");@@ -1373,8 +1580,7 @@ pub fn run_mcp_config(client: Option<&str>) {}}});- let pretty = serde_json::to_string_pretty(&full)- .unwrap_or_else(|_| full.to_string());+ let pretty = serde_json::to_string_pretty(&full).unwrap_or_else(|_| full.to_string());println!("# Antigravity CLI (the `agy` binary) reads MCP server configs from:\n\# ~/.gemini/config/mcp_config.json (Unix)\n\@@ -1429,8 +1635,7 @@ pub fn run_mcp_config(client: Option<&str>) {}}});- let pretty = serde_json::to_string_pretty(&full)- .unwrap_or_else(|_| full.to_string());+ let pretty = serde_json::to_string_pretty(&full).unwrap_or_else(|_| full.to_string());println!("# ZCode (Z.ai) is a GUI app — add via Settings -> MCP Servers ->\n\# New MCP Server (type: stdio), or paste this under \"Full\n\@@ -1525,8 +1730,10 @@ pub fn run_call(effective};if crate::serve::is_daemon_listening(&socket_path) {- let args_for_daemon = json_args.clone()+ let mut args_for_daemon = json_args+ .clone().unwrap_or(serde_json::Value::Object(serde_json::Map::new()));+ cua_driver_core::tool_args::sanitize_reserved_args(&mut args_for_daemon);let req = crate::serve::DaemonRequest {method: "call".into(),name: Some(tool.to_owned()),@@ -1547,13 +1754,21 @@ pub fn run_call(if let Some(content) = result.get("content").and_then(|v| v.as_array()) {for item in content {if item.get("type").and_then(|v| v.as_str()) == Some("image") {- let b64 = item.get("data").and_then(|v| v.as_str()).map(str::to_owned);- let mime = item.get("mimeType").and_then(|v| v.as_str())- .unwrap_or("image/png").to_owned();+ let b64 = item+ .get("data")+ .and_then(|v| v.as_str())+ .map(str::to_owned);+ let mime = item+ .get("mimeType")+ .and_then(|v| v.as_str())+ .unwrap_or("image/png")+ .to_owned();if let Some(b64) = b64 {if let Some(ref path) = screenshot_out_file {use base64::Engine as _;- match base64::engine::general_purpose::STANDARD.decode(&b64) {+ match base64::engine::general_purpose::STANDARD+ .decode(&b64)+ {Ok(bytes) => {if let Err(e) = std::fs::write(path, &bytes) {eprintln!("--screenshot-out-file: failed to write {path}: {e}");@@ -1582,8 +1797,14 @@ pub fn run_call(let mut obj = sc.clone();if let Some((b64, mime)) = image_b64 {if let serde_json::Value::Object(ref mut map) = obj {- map.insert("screenshot_png_b64".into(), serde_json::Value::String(b64));- map.insert("screenshot_mime_type".into(), serde_json::Value::String(mime));+ map.insert(+ "screenshot_png_b64".into(),+ serde_json::Value::String(b64),+ );+ map.insert(+ "screenshot_mime_type".into(),+ serde_json::Value::String(mime),+ );}}let pretty = serde_json::to_string_pretty(&obj)@@ -1592,10 +1813,13 @@ pub fn run_call(printed = true;}if !printed {- if let Some(content) = result.get("content").and_then(|v| v.as_array()) {+ if let Some(content) = result.get("content").and_then(|v| v.as_array())+ {for item in content {if item.get("type").and_then(|v| v.as_str()) == Some("text") {- if let Some(text) = item.get("text").and_then(|v| v.as_str()) {+ if let Some(text) =+ item.get("text").and_then(|v| v.as_str())+ {println!("{text}");}}@@ -1639,7 +1863,8 @@ pub fn run_call(.build().expect("tokio runtime");- let args = json_args.unwrap_or(serde_json::Value::Object(serde_json::Map::new()));+ let mut args = json_args.unwrap_or(serde_json::Value::Object(serde_json::Map::new()));+ cua_driver_core::tool_args::sanitize_reserved_args(&mut args);let session_context = cua_driver_core::session::begin_tool_call(tool,&args,@@ -1685,7 +1910,9 @@ pub fn run_call(}}}- Content::Image { data, mime_type, .. } => {+ Content::Image {+ data, mime_type, ..+ } => {image_b64 = Some((data.clone(), mime_type.clone()));}}@@ -1707,7 +1934,9 @@ pub fn run_call(}}} else {- eprintln!("--screenshot-out-file: no image content in tool response; file not written");+ eprintln!(+ "--screenshot-out-file: no image content in tool response; file not written"+ );}}@@ -1719,12 +1948,14 @@ pub fn run_call(if let Some((b64, mime)) = image_b64 {if let serde_json::Value::Object(ref mut map) = obj {map.insert("screenshot_png_b64".into(), serde_json::Value::String(b64));- map.insert("screenshot_mime_type".into(), serde_json::Value::String(mime));+ map.insert(+ "screenshot_mime_type".into(),+ serde_json::Value::String(mime),+ );}}}- let pretty = serde_json::to_string_pretty(&obj)- .unwrap_or_else(|_| obj.to_string());+ let pretty = serde_json::to_string_pretty(&obj).unwrap_or_else(|_| obj.to_string());println!("{pretty}");has_printed = true;}@@ -1814,19 +2045,27 @@ pub fn run_recording_cmd(subcommand: &str, args: &[String], socket: Option<&str>};if let Ok(sr) = crate::serve::send_request(&socket_path, &state_req) {if let Some(result) = sr.result {- let sc = result.get("structuredContent")+ let sc = result+ .get("structuredContent").or_else(|| result.get("structured_content"));- if let Some(next_turn) = sc.and_then(|s| s.get("next_turn")).and_then(|v| v.as_u64()) {+ if let Some(next_turn) =+ sc.and_then(|s| s.get("next_turn")).and_then(|v| v.as_u64())+ {println!("Next turn: {next_turn:05}");}}}}Ok(resp) => {- if let Some(e) = resp.error { eprintln!("{e}"); }+ if let Some(e) = resp.error {+ eprintln!("{e}");+ }+ process::exit(1);+ }+ Err(e) => {+ eprintln!("recording start: {e}");process::exit(1);}- Err(e) => { eprintln!("recording start: {e}"); process::exit(1); }}}@@ -1841,10 +2080,15 @@ pub fn run_recording_cmd(subcommand: &str, args: &[String], socket: Option<&str>match crate::serve::send_request(&socket_path, &req) {Ok(resp) if resp.ok => println!("Recording stopped."),Ok(resp) => {- if let Some(e) = resp.error { eprintln!("{e}"); }+ if let Some(e) = resp.error {+ eprintln!("{e}");+ }+ process::exit(1);+ }+ Err(e) => {+ eprintln!("recording stop: {e}");process::exit(1);}- Err(e) => { eprintln!("recording stop: {e}"); process::exit(1); }}}@@ -1859,14 +2103,21 @@ pub fn run_recording_cmd(subcommand: &str, args: &[String], socket: Option<&str>match crate::serve::send_request(&socket_path, &req) {Ok(resp) if resp.ok => {if let Some(result) = resp.result {- let sc = result.get("structuredContent")+ let sc = result+ .get("structuredContent").or_else(|| result.get("structured_content")).cloned().unwrap_or(serde_json::json!({}));let enabled = sc.get("enabled").and_then(|v| v.as_bool()).unwrap_or(false);- let out_dir = sc.get("output_dir").and_then(|v| v.as_str()).unwrap_or("(none)");+ let out_dir = sc+ .get("output_dir")+ .and_then(|v| v.as_str())+ .unwrap_or("(none)");let next_turn = sc.get("next_turn").and_then(|v| v.as_u64()).unwrap_or(0);- println!("Recording: {}", if enabled { "enabled" } else { "disabled" });+ println!(+ "Recording: {}",+ if enabled { "enabled" } else { "disabled" }+ );if enabled {println!(" output_dir: {out_dir}");println!(" next_turn: {next_turn:05}");@@ -1874,10 +2125,15 @@ pub fn run_recording_cmd(subcommand: &str, args: &[String], socket: Option<&str>}}Ok(resp) => {- if let Some(e) = resp.error { eprintln!("{e}"); }+ if let Some(e) = resp.error {+ eprintln!("{e}");+ }+ process::exit(1);+ }+ Err(e) => {+ eprintln!("recording status: {e}");process::exit(1);}- Err(e) => { eprintln!("recording status: {e}"); process::exit(1); }}}@@ -1903,14 +2159,18 @@ fn run_recording_render(args: &[String]) {let input_dir = match positionals.get(0) {Some(s) if !s.is_empty() => std::path::PathBuf::from(s),_ => {- eprintln!("Usage: cua-driver recording render <input-dir> <out.mp4> [--no-zoom] [--scale N]");+ eprintln!(+ "Usage: cua-driver recording render <input-dir> <out.mp4> [--no-zoom] [--scale N]"+ );process::exit(64);}};let output_path = match positionals.get(1) {Some(s) if !s.is_empty() => std::path::PathBuf::from(s),_ => {- eprintln!("Usage: cua-driver recording render <input-dir> <out.mp4> [--no-zoom] [--scale N]");+ eprintln!(+ "Usage: cua-driver recording render <input-dir> <out.mp4> [--no-zoom] [--scale N]"+ );eprintln!("(second positional argument is the output path)");process::exit(64);}@@ -1923,7 +2183,9 @@ fn run_recording_render(args: &[String]) {"--no-zoom" => no_zoom = true,"--scale" => {if let Some(v) = iter.next() {- if let Ok(f) = v.parse::<f64>() { scale = f; }+ if let Ok(f) = v.parse::<f64>() {+ scale = f;+ }}}_ => {}@@ -1934,10 +2196,12 @@ fn run_recording_render(args: &[String]) {no_zoom,default_scale: scale,};- println!("Rendering {} -> {}{}",+ println!(+ "Rendering {} -> {}{}",input_dir.display(),output_path.display(),- if no_zoom { " (no-zoom baseline)" } else { "" });+ if no_zoom { " (no-zoom baseline)" } else { "" }+ );match cua_driver_core::recording_render::render(&input_dir, &output_path, &opts) {Ok(res) => {println!("✅ Wrote {}", res.output_path.display());@@ -1965,8 +2229,7 @@ pub fn run_update_cmd(apply: bool, json: bool) {// verb and the MCP tool use, so all three surfaces agree.if json {let state = crate::version_check::check_update_state(false);- let val = serde_json::to_value(&state)- .unwrap_or_else(|_| serde_json::json!({}));+ let val = serde_json::to_value(&state).unwrap_or_else(|_| serde_json::json!({}));let pretty = serde_json::to_string_pretty(&val).unwrap_or_else(|_| val.to_string());println!("{pretty}");// `--apply` still installs when JSON is on — the JSON is just the@@ -2057,11 +2320,7 @@ pub fn run_update_cmd(apply: bool, json: bool) {}/// `cua-driver permissions status|grant`.-pub fn run_permissions_cmd(- _registry: std::sync::Arc<ToolRegistry>,- subcommand: &str,- json: bool,-) {+pub fn run_permissions_cmd(_registry: std::sync::Arc<ToolRegistry>, subcommand: &str, json: bool) {match subcommand {"status" => run_permissions_status(json),"grant" => run_permissions_grant(),@@ -2169,8 +2428,14 @@ fn run_permissions_status(json: bool) {.and_then(|v| v.as_str()).unwrap_or("driver-daemon");- println!("Accessibility: {}", if ax { "✅ granted" } else { "❌ not granted" });- println!("Screen Recording: {}", if sr { "✅ granted" } else { "❌ not granted" });+ println!(+ "Accessibility: {}",+ if ax { "✅ granted" } else { "❌ not granted" }+ );+ println!(+ "Screen Recording: {}",+ if sr { "✅ granted" } else { "❌ not granted" }+ );if sr && !cap {println!(" ⚠️ preflight reports granted, but a live capture probe failed — the grant \@@ -2226,8 +2491,7 @@ fn run_permissions_grant() {session_id: None,observation_origin: Some(crate::serve::ToolObservationOrigin::Direct),};- let poll_deadline =- std::time::Instant::now() + std::time::Duration::from_secs(180);+ let poll_deadline = std::time::Instant::now() + std::time::Duration::from_secs(180);let mut ax = false;let mut sr = false;loop {@@ -2237,8 +2501,14 @@ fn run_permissions_grant() {.and_then(|r| r.result).and_then(|res| res.get("structuredContent").cloned()){- ax = structured.get("accessibility").and_then(|v| v.as_bool()).unwrap_or(false);- sr = structured.get("screen_recording").and_then(|v| v.as_bool()).unwrap_or(false);+ ax = structured+ .get("accessibility")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);+ sr = structured+ .get("screen_recording")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);if ax && sr {break;}@@ -2604,15 +2874,18 @@ pub fn run_dump_docs_with_type(registry: &ToolRegistry, pretty: bool, doc_type:// Each MCP tool: `{name, description, input_schema}` (Swift's MCPToolDoc// shape — Rust adds read_only/destructive/idempotent as intentional// extras).- let tools: Vec<serde_json::Value> = registry.iter_defs()- .map(|(_, def)| serde_json::json!({- "name": def.name,- "description": def.description,- "input_schema": def.input_schema,- "read_only": def.read_only,- "destructive": def.destructive,- "idempotent": def.idempotent,- }))+ let tools: Vec<serde_json::Value> = registry+ .iter_defs()+ .map(|(_, def)| {+ serde_json::json!({+ "name": def.name,+ "description": def.description,+ "input_schema": def.input_schema,+ "read_only": def.read_only,+ "destructive": def.destructive,+ "idempotent": def.idempotent,+ })+ }).collect();let mcp = serde_json::json!({"version": env!("CARGO_PKG_VERSION"),@@ -2624,7 +2897,7 @@ pub fn run_dump_docs_with_type(registry: &ToolRegistry, pretty: bool, doc_type:let doc = match doc_type {"cli" => cli_docs,"mcp" => mcp,- _ => serde_json::json!({ "cli": cli_docs, "mcp": mcp }),+ _ => serde_json::json!({ "cli": cli_docs, "mcp": mcp }),};let out = if pretty {serde_json::to_string_pretty(&doc)@@ -2660,7 +2933,9 @@ fn diagnose_runtime_section() -> String {.ok().and_then(|p| p.to_str().map(str::to_owned)).unwrap_or_else(|| "<unknown>".into());- let argv0 = std::env::args().next().unwrap_or_else(|| "<unknown>".into());+ let argv0 = std::env::args()+ .next()+ .unwrap_or_else(|| "<unknown>".into());let pid = std::process::id();let version = env!("CARGO_PKG_VERSION");format!(@@ -2719,13 +2994,19 @@ fn diagnose_tcc_section(registry: std::sync::Arc<ToolRegistry>) -> String {let (ax, sr) = if let Ok(rt) = rt {rt.block_on(async {- let result = registry.invoke("check_permissions",- serde_json::Value::Object(Default::default())).await;+ let result = registry+ .invoke(+ "check_permissions",+ serde_json::Value::Object(Default::default()),+ )+ .await;if let Some(sc) = &result.structured_content {- let ax = sc.get("accessibility")+ let ax = sc+ .get("accessibility").and_then(|v| v.as_bool()).unwrap_or(false);- let sr = sc.get("screen_recording")+ let sr = sc+ .get("screen_recording").and_then(|v| v.as_bool()).unwrap_or(false);(ax, sr)@@ -2804,14 +3085,14 @@ fn diagnose_install_layout_section() -> String {fn diagnose_tcc_db_section() -> String {let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());- let db = format!(- "{home}/Library/Application Support/com.apple.TCC/TCC.db"- );+ let db = format!("{home}/Library/Application Support/com.apple.TCC/TCC.db");let sql = "SELECT service, client, client_type, auth_value, auth_reason, \hex(csreq) AS csreq_hex FROM access WHERE client='com.trycua.driver';";let mut lines = vec!["## tcc database rows for com.trycua.driver".to_owned()];- lines.push(format!("(reading {db} — best-effort; system TCC DB requires FDA)"));+ lines.push(format!(+ "(reading {db} — best-effort; system TCC DB requires FDA)"+ ));lines.push(String::new());match std::process::Command::new("sqlite3")@@ -2845,11 +3126,17 @@ fn diagnose_tcc_db_section() -> String {fn diagnose_config_paths_section() -> String {let home = std::env::var("HOME").unwrap_or_else(|_| "/tmp".into());let paths: &[(&str, String)] = &[- ("user data dir", format!("{home}/.cua-driver")),- ("config cache", format!("{home}/Library/Caches/cua-driver")),- ("telemetry id", format!("{home}/.cua-driver/.telemetry_id")),- ("updater plist", format!("{home}/Library/LaunchAgents/com.trycua.cua_driver_updater.plist")),- ("daemon plist", format!("{home}/Library/LaunchAgents/com.trycua.cua_driver_daemon.plist")),+ ("user data dir", format!("{home}/.cua-driver")),+ ("config cache", format!("{home}/Library/Caches/cua-driver")),+ ("telemetry id", format!("{home}/.cua-driver/.telemetry_id")),+ (+ "updater plist",+ format!("{home}/Library/LaunchAgents/com.trycua.cua_driver_updater.plist"),+ ),+ (+ "daemon plist",+ format!("{home}/Library/LaunchAgents/com.trycua.cua_driver_daemon.plist"),+ ),];let mut lines = vec!["## config + state paths".to_owned()];for (label, path) in paths {@@ -2912,11 +3199,13 @@ pub fn run_config_cmd(match subcommand.unwrap_or("show") {"show" | "" => {// Print full config as pretty JSON.- let config = rt.block_on(async {- registry.invoke("get_config", serde_json::json!({})).await- });+ let config =+ rt.block_on(async { registry.invoke("get_config", serde_json::json!({})).await });if let Some(sc) = config.structured_content {- println!("{}", serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string()));+ println!(+ "{}",+ serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string())+ );} else {eprintln!("get_config: no structured content returned");process::exit(1);@@ -2956,9 +3245,8 @@ pub fn run_config_cmd(}}// In-process: merge persisted file config over in-memory defaults.- let config = rt.block_on(async {- registry.invoke("get_config", serde_json::json!({})).await- });+ let config =+ rt.block_on(async { registry.invoke("get_config", serde_json::json!({})).await });let mut sc = match config.structured_content {Some(v) => v,None => {@@ -2985,7 +3273,13 @@ pub fn run_config_cmd(sc.get(key).cloned()};if let Some(v) = v {- println!("{}", match &v { serde_json::Value::String(s) => s.clone(), other => other.to_string() });+ println!(+ "{}",+ match &v {+ serde_json::Value::String(s) => s.clone(),+ other => other.to_string(),+ }+ );} else {eprintln!("Unknown config key: {key}");eprintln!("Available keys: capture_mode, max_image_dimension, version, platform, agent_cursor.enabled");@@ -3009,8 +3303,8 @@ pub fn run_config_cmd(}};// Parse value: try JSON, fall back to string.- let parsed_value: serde_json::Value =- serde_json::from_str(value).unwrap_or_else(|_| serde_json::Value::String(value.to_owned()));+ let parsed_value: serde_json::Value = serde_json::from_str(value)+ .unwrap_or_else(|_| serde_json::Value::String(value.to_owned()));let args = serde_json::json!({ key: parsed_value });// Try daemon first.@@ -3038,7 +3332,10 @@ pub fn run_config_cmd(if let Ok(r2) = crate::serve::send_request(&socket_path, &req2) {if let Some(result) = r2.result {if let Some(sc) = result.get("structuredContent") {- println!("{}", serde_json::to_string_pretty(sc).unwrap_or_default());+ println!(+ "{}",+ serde_json::to_string_pretty(sc).unwrap_or_default()+ );}}}@@ -3050,9 +3347,7 @@ pub fn run_config_cmd(}}// In-process.- let result = rt.block_on(async {- registry.invoke("set_config", args).await- });+ let result = rt.block_on(async { registry.invoke("set_config", args).await });if result.is_error.unwrap_or(false) {for item in &result.content {if let cua_driver_core::protocol::Content::Text { text, .. } = item {@@ -3064,11 +3359,13 @@ pub fn run_config_cmd(// Persist the value to disk so future CLI invocations can read it.write_config_file(key, &parsed_value);// Print updated config.- let config = rt.block_on(async {- registry.invoke("get_config", serde_json::json!({})).await- });+ let config =+ rt.block_on(async { registry.invoke("get_config", serde_json::json!({})).await });if let Some(sc) = config.structured_content {- println!("{}", serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string()));+ println!(+ "{}",+ serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string())+ );}}@@ -3080,19 +3377,19 @@ pub fn run_config_cmd("capture_mode": "ax","max_image_dimension": 0});- let result = rt.block_on(async {- registry.invoke("set_config", defaults).await- });+ let result = rt.block_on(async { registry.invoke("set_config", defaults).await });if result.is_error.unwrap_or(false) {eprintln!("config reset failed");process::exit(1);}println!("Config reset to defaults.");- let config = rt.block_on(async {- registry.invoke("get_config", serde_json::json!({})).await- });+ let config =+ rt.block_on(async { registry.invoke("get_config", serde_json::json!({})).await });if let Some(sc) = config.structured_content {- println!("{}", serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string()));+ println!(+ "{}",+ serde_json::to_string_pretty(&sc).unwrap_or_else(|_| sc.to_string())+ );}}@@ -3312,31 +3609,54 @@ mod tests {let obj = m.as_object().expect("manifest is an object");// schema_version — stable string; consumers branch on this.- assert_eq!(obj.get("schema_version").and_then(|v| v.as_str()), Some("1"));+ assert_eq!(+ obj.get("schema_version").and_then(|v| v.as_str()),+ Some("1")+ );// binary_version — must equal CARGO_PKG_VERSION (current build).- let bv = obj.get("binary_version").and_then(|v| v.as_str())+ let bv = obj+ .get("binary_version")+ .and_then(|v| v.as_str()).expect("binary_version present and a string");assert_eq!(bv, env!("CARGO_PKG_VERSION"));// mcp_invocation — { command: <bin path>, args: ["mcp"] }- let inv = obj.get("mcp_invocation").and_then(|v| v.as_object())+ let inv = obj+ .get("mcp_invocation")+ .and_then(|v| v.as_object()).expect("mcp_invocation is an object");- assert!(inv.get("command").and_then(|v| v.as_str()).is_some(),- "mcp_invocation.command must be a string");- let args = inv.get("args").and_then(|v| v.as_array())+ assert!(+ inv.get("command").and_then(|v| v.as_str()).is_some(),+ "mcp_invocation.command must be a string"+ );+ let args = inv+ .get("args")+ .and_then(|v| v.as_array()).expect("mcp_invocation.args is an array");assert_eq!(args.len(), 1);assert_eq!(args[0].as_str(), Some("mcp"));// subcommands — non-empty array with the canonical entries.- let subs = obj.get("subcommands").and_then(|v| v.as_array())+ let subs = obj+ .get("subcommands")+ .and_then(|v| v.as_array()).expect("subcommands is an array");- let names: Vec<&str> = subs.iter()+ let names: Vec<&str> = subs+ .iter().filter_map(|s| s.get("name").and_then(|v| v.as_str())).collect();- for need in ["mcp", "list-tools", "describe", "call", "serve",- "stop", "status", "mcp-config", "manifest"] {+ for need in [+ "mcp",+ "list-tools",+ "describe",+ "call",+ "serve",+ "stop",+ "status",+ "mcp-config",+ "manifest",+ ] {assert!(names.contains(&need), "missing subcommand '{need}'");}}@@ -3347,15 +3667,24 @@ mod tests {#[test]fn manifest_subcommands_have_uniform_shape() {let m = build_manifest();- let subs = m.get("subcommands").and_then(|v| v.as_array()).expect("subcommands");+ let subs = m+ .get("subcommands")+ .and_then(|v| v.as_array())+ .expect("subcommands");for entry in subs {let obj = entry.as_object().expect("each subcommand is an object");- assert!(obj.get("name").and_then(|v| v.as_str()).is_some(),- "subcommand missing name: {entry}");- assert!(obj.get("description").and_then(|v| v.as_str()).is_some(),- "subcommand missing description: {entry}");- assert!(obj.get("args").and_then(|v| v.as_array()).is_some(),- "subcommand missing args[]: {entry}");+ assert!(+ obj.get("name").and_then(|v| v.as_str()).is_some(),+ "subcommand missing name: {entry}"+ );+ assert!(+ obj.get("description").and_then(|v| v.as_str()).is_some(),+ "subcommand missing description: {entry}"+ );+ assert!(+ obj.get("args").and_then(|v| v.as_array()).is_some(),+ "subcommand missing args[]: {entry}"+ );}}@@ -3367,7 +3696,9 @@ mod tests {fn manifest_mcp_invocation_is_stable() {let m = build_manifest();let inv = m.get("mcp_invocation").expect("mcp_invocation");- let args: Vec<&str> = inv.get("args").and_then(|v| v.as_array())+ let args: Vec<&str> = inv+ .get("args")+ .and_then(|v| v.as_array()).expect("args[] array").iter().filter_map(|v| v.as_str())@@ -3378,7 +3709,9 @@ mod tests {fn first_sentence(text: &str) -> String {let trimmed = text.trim();- if trimmed.is_empty() { return String::new(); }+ if trimmed.is_empty() {+ return String::new();+ }let flat: String = trimmed.splitn(3, "\n\n").next()@@ -3396,6 +3729,8 @@ fn first_sentence(text: &str) -> String {prev = ch;}let mut s = sentence.trim().to_string();- if s.ends_with('.') { s.pop(); }+ if s.ends_with('.') {+ s.pop();+ }s}diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rsindex de4333b081..fc329440e0 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs@@ -26,6 +26,7 @@mod autostart;mod bundle;+mod check_update_tool;mod cli;mod doctor;mod mcp_http;@@ -34,12 +35,11 @@ mod responsibility;mod serve;mod skills;mod telemetry;-mod check_update_tool;mod updater;mod version_check;-use std::sync::Arc;use std::sync::atomic::{AtomicBool, Ordering};+use std::sync::Arc;/// Set by the `Command::Mcp` arm when `--claude-code-computer-use-compat`/// is on argv. Read by `build_registry` / `build_registry_no_cursor` to@@ -53,10 +53,7 @@ fn init_logging() {use tracing_subscriber::EnvFilter;tracing_subscriber::fmt().with_writer(std::io::stderr)- .with_env_filter(- EnvFilter::from_env("CUA_LOG")- .add_directive(tracing::Level::WARN.into()),- )+ .with_env_filter(EnvFilter::from_env("CUA_LOG").add_directive(tracing::Level::WARN.into())).init();telemetry::register_stdio_observer();}@@ -69,18 +66,24 @@ fn maybe_wrap_finite_command() {if telemetry::is_wrapped_cli_child() {return;}- let Some(command_name) = cli::finite_command_name_from_argv() else { return; };+ let Some(command_name) = cli::finite_command_name_from_argv() else {+ return;+ };let tool_name = cli::finite_tool_name_from_argv();let operation = cli::finite_operation_from_argv();let client_kind = cli::finite_client_kind_from_argv();telemetry::spawn_first_run_registration_worker();- let Ok(executable) = std::env::current_exe() else { return; };+ let Ok(executable) = std::env::current_exe() else {+ return;+ };let started_at = std::time::Instant::now();let status = std::process::Command::new(executable).args(std::env::args_os().skip(1)).env(telemetry::cli_wrapped_child_env(), "1").status();- let Ok(status) = status else { return; };+ let Ok(status) = status else {+ return;+ };let exit_code = status.code().unwrap_or(1);telemetry::spawn_cli_completion_worker(command_name,@@ -160,17 +163,11 @@ fn maybe_init_pip() {// Register the platform factory. The set is idempotent so multiple// entry points calling this in the same process is safe.#[cfg(target_os = "macos")]- pip_preview::set_pip_backend_factory(- Box::new(platform_macos::pip::MacosPipBackendFactory),- );+ pip_preview::set_pip_backend_factory(Box::new(platform_macos::pip::MacosPipBackendFactory));#[cfg(target_os = "windows")]- pip_preview::set_pip_backend_factory(- Box::new(platform_windows::pip::WindowsPipBackendFactory),- );+ pip_preview::set_pip_backend_factory(Box::new(platform_windows::pip::WindowsPipBackendFactory));#[cfg(target_os = "linux")]- pip_preview::set_pip_backend_factory(- Box::new(platform_linux::pip::LinuxPipBackendFactory),- );+ pip_preview::set_pip_backend_factory(Box::new(platform_linux::pip::LinuxPipBackendFactory));match pip_preview::start_pip(&cfg) {Ok(backend) => {@@ -180,8 +177,9 @@ fn maybe_init_pip() {// closure can re-borrow on every call without taking// ownership of the trait object.use std::sync::Mutex as StdMutex;- static BACKEND: std::sync::OnceLock<StdMutex<Option<Box<dyn pip_preview::PipBackend>>>> =- std::sync::OnceLock::new();+ static BACKEND: std::sync::OnceLock<+ StdMutex<Option<Box<dyn pip_preview::PipBackend>>>,+ > = std::sync::OnceLock::new();let _ = BACKEND.set(StdMutex::new(Some(backend)));cua_driver_core::pip_hook::set_pip_push_fn(|frame| {if let Some(slot) = BACKEND.get() {@@ -270,13 +268,19 @@ fn main() {cli::run_manifest(pretty);return;}- cli::Command::Call { tool, json_args, screenshot_out_file, socket } => {+ cli::Command::Call {+ tool,+ json_args,+ screenshot_out_file,+ socket,+ } => {// Register callbacks (needed if the tool does screenshots/recording).cua_driver_core::recording::set_screenshot_fn(|window_id, pid| {if let Some(wid) = window_id {platform_macos::capture::screenshot_window_bytes(wid as u32).ok()} else if let Some(p) = pid {- platform_macos::windows::resolve_main_window_id(p as i32).ok()+ platform_macos::windows::resolve_main_window_id(p as i32)+ .ok().and_then(|wid| platform_macos::capture::screenshot_window_bytes(wid).ok())} else {platform_macos::capture::screenshot_display_bytes().ok()@@ -291,15 +295,19 @@ fn main() {cua_driver_core::recording::set_element_bounds_fn(|wid, pid, idx| {platform_macos::recording_hooks::element_window_local_xy(wid, pid, idx)});- cua_driver_core::video::set_video_backend_factory(- Box::new(platform_macos::video_sckit::SckitVideoBackendFactory),- );+ cua_driver_core::video::set_video_backend_factory(Box::new(+ platform_macos::video_sckit::SckitVideoBackendFactory,+ ));let reg = Arc::new(build_macos_registry());reg.init_self_weak();cli::run_call(reg, &tool, json_args, screenshot_out_file, socket);return;}- cli::Command::Serve { socket, no_permissions_gate, claude_code_compat } => {+ cli::Command::Serve {+ socket,+ no_permissions_gate,+ claude_code_compat,+ } => {responsibility::reexec_disclaimed_if_needed();let gate_opts = platform_macos::permissions::GateOpts::from_env_and_flag(no_permissions_gate,@@ -328,7 +336,8 @@ fn main() {if let Some(wid) = window_id {platform_macos::capture::screenshot_window_bytes(wid as u32).ok()} else if let Some(p) = pid {- platform_macos::windows::resolve_main_window_id(p as i32).ok()+ platform_macos::windows::resolve_main_window_id(p as i32)+ .ok().and_then(|wid| platform_macos::capture::screenshot_window_bytes(wid).ok())} else {platform_macos::capture::screenshot_display_bytes().ok()@@ -343,9 +352,9 @@ fn main() {cua_driver_core::recording::set_element_bounds_fn(|wid, pid, idx| {platform_macos::recording_hooks::element_window_local_xy(wid, pid, idx)});- cua_driver_core::video::set_video_backend_factory(- Box::new(platform_macos::video_sckit::SckitVideoBackendFactory),- );+ cua_driver_core::video::set_video_backend_factory(Box::new(+ platform_macos::video_sckit::SckitVideoBackendFactory,+ ));let pip_cfg = match pip_preview::default_config_path() {Some(p) => pip_preview::PipConfig::from_args_and_file(&p),None => pip_preview::PipConfig::from_args(),@@ -450,9 +459,11 @@ fn main() {}if let Err(e) = gate_result {eprintln!("[cua-driver] permissions gate: {e}");- eprintln!("[cua-driver] continuing — tool calls touching AX or \+ eprintln!(+ "[cua-driver] continuing — tool calls touching AX or \Screen Recording fail until you grant the missing TCC \- permissions.");+ permissions."+ );}// Keep the main thread alive for the daemon.@@ -489,7 +500,11 @@ fn main() {serve::run_status_cmd(&sp, &pid_path);return;}- cli::Command::Recording { subcommand, args, socket } => {+ cli::Command::Recording {+ subcommand,+ args,+ socket,+ } => {cli::run_recording_cmd(&subcommand, &args, socket.as_deref());return;}@@ -535,13 +550,36 @@ fn main() {skills::run(&subcommand, &flags);return;}- cli::Command::Config { subcommand, key, value, socket } => {+ cli::Command::BrowserApprove {+ pid,+ profile_mode,+ profile_name,+ } => {+ cli::run_browser_approve(pid, &profile_mode, profile_name.as_deref());+ return;+ }+ cli::Command::Config {+ subcommand,+ key,+ value,+ socket,+ } => {let reg = Arc::new(build_macos_registry());reg.init_self_weak();- cli::run_config_cmd(reg, subcommand.as_deref(), key.as_deref(), value.as_deref(), socket.as_deref());+ cli::run_config_cmd(+ reg,+ subcommand.as_deref(),+ key.as_deref(),+ value.as_deref(),+ socket.as_deref(),+ );return;}- cli::Command::Mcp { no_daemon_relaunch, socket, claude_code_compat } => {+ cli::Command::Mcp {+ no_daemon_relaunch,+ socket,+ claude_code_compat,+ } => {let startup_started = std::time::Instant::now();CLAUDE_CODE_COMPAT.store(claude_code_compat, Ordering::SeqCst);// Long-running MCP server — kick off the background update@@ -611,7 +649,8 @@ fn main() {if let Some(wid) = window_id {platform_macos::capture::screenshot_window_bytes(wid as u32).ok()} else if let Some(p) = pid {- platform_macos::windows::resolve_main_window_id(p as i32).ok()+ platform_macos::windows::resolve_main_window_id(p as i32)+ .ok().and_then(|wid| platform_macos::capture::screenshot_window_bytes(wid).ok())} else {platform_macos::capture::screenshot_display_bytes().ok()@@ -628,9 +667,9 @@ fn main() {cua_driver_core::recording::set_element_bounds_fn(|wid, pid, idx| {platform_macos::recording_hooks::element_window_local_xy(wid, pid, idx)});- cua_driver_core::video::set_video_backend_factory(- Box::new(platform_macos::video_sckit::SckitVideoBackendFactory),- );+ cua_driver_core::video::set_video_backend_factory(Box::new(+ platform_macos::video_sckit::SckitVideoBackendFactory,+ ));maybe_init_pip();std::thread::Builder::new()@@ -664,7 +703,9 @@ fn main() {}// Overlay disabled: park the main thread while the MCP background thread// keeps running.- loop { std::thread::park(); }+ loop {+ std::thread::park();+ }}// ── Non-macOS entry-point ─────────────────────────────────────────────────@@ -713,16 +754,27 @@ fn main() -> anyhow::Result<()> {cli::run_manifest(pretty);return Ok(());}- cli::Command::Call { tool, json_args, screenshot_out_file, socket } => {+ cli::Command::Call {+ tool,+ json_args,+ screenshot_out_file,+ socket,+ } => {let reg = Arc::new(build_registry_no_cursor());reg.init_self_weak();// run_call builds its own tokio runtime; must run on a fresh thread.std::thread::spawn(move || {cli::run_call(reg, &tool, json_args, screenshot_out_file, socket);- }).join().ok();+ })+ .join()+ .ok();return Ok(());}- cli::Command::Serve { socket, no_permissions_gate, claude_code_compat } => {+ cli::Command::Serve {+ socket,+ no_permissions_gate,+ claude_code_compat,+ } => {responsibility::reexec_disclaimed_if_needed();telemetry::capture_start(telemetry::event::SERVE_START_LEGACY,@@ -748,7 +800,9 @@ fn main() -> anyhow::Result<()> {// run_serve_cmd builds its own runtime; must run on a fresh thread.std::thread::spawn(move || {serve::run_serve_cmd(reg, &sp, Some(&pid_path));- }).join().ok();+ })+ .join()+ .ok();return Ok(());}cli::Command::Stop { socket } => {@@ -762,7 +816,11 @@ fn main() -> anyhow::Result<()> {serve::run_status_cmd(&sp, &pid_path);return Ok(());}- cli::Command::Recording { subcommand, args, socket } => {+ cli::Command::Recording {+ subcommand,+ args,+ socket,+ } => {cli::run_recording_cmd(&subcommand, &args, socket.as_deref());return Ok(());}@@ -807,15 +865,40 @@ fn main() -> anyhow::Result<()> {skills::run(&subcommand, &flags);return Ok(());}- cli::Command::Config { subcommand, key, value, socket } => {+ cli::Command::BrowserApprove {+ pid,+ profile_mode,+ profile_name,+ } => {+ cli::run_browser_approve(pid, &profile_mode, profile_name.as_deref());+ return Ok(());+ }+ cli::Command::Config {+ subcommand,+ key,+ value,+ socket,+ } => {let reg = Arc::new(build_registry_no_cursor());reg.init_self_weak();std::thread::spawn(move || {- cli::run_config_cmd(reg, subcommand.as_deref(), key.as_deref(), value.as_deref(), socket.as_deref());- }).join().ok();+ cli::run_config_cmd(+ reg,+ subcommand.as_deref(),+ key.as_deref(),+ value.as_deref(),+ socket.as_deref(),+ );+ })+ .join()+ .ok();return Ok(());}- cli::Command::Mcp { no_daemon_relaunch, socket, claude_code_compat } => {+ cli::Command::Mcp {+ no_daemon_relaunch,+ socket,+ claude_code_compat,+ } => {let startup_started = std::time::Instant::now();CLAUDE_CODE_COMPAT.store(claude_code_compat, Ordering::SeqCst);// Long-running MCP server — kick off the background update@@ -874,7 +957,6 @@ fn main() -> anyhow::Result<()> {#[cfg(not(target_os = "macos"))]async fn async_main() -> anyhow::Result<()> {-let cursor_cfg = cursor_overlay::CursorConfig::from_args();tracing::info!(@@ -926,10 +1008,14 @@ fn build_registry(cursor_cfg: cursor_overlay::CursorConfig) -> cua_driver_core::cua_driver_core::recording::set_element_bounds_fn(|wid, pid, idx| {platform_windows::recording_hooks::element_window_local_xy(wid, pid, idx)});- cua_driver_core::video::set_video_backend_factory(- Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),- );- { let mut r = platform_windows::register_tools_with_cursor(cursor_cfg, compat); check_update_tool::register_into(&mut r); r }+ cua_driver_core::video::set_video_backend_factory(Box::new(+ cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory,+ ));+ {+ let mut r = platform_windows::register_tools_with_cursor(cursor_cfg, compat);+ check_update_tool::register_into(&mut r);+ r+ }}#[cfg(target_os = "linux")]{@@ -938,9 +1024,8 @@ fn build_registry(cursor_cfg: cursor_overlay::CursorConfig) -> cua_driver_core::platform_linux::wayland::screenshot_dispatch(xid).ok()} else if let Some(p) = pid {let wins = platform_linux::wayland::list_windows_dispatch(Some(p as u32));- wins.first().and_then(|w| {- platform_linux::wayland::screenshot_dispatch(w.xid).ok()- })+ wins.first()+ .and_then(|w| platform_linux::wayland::screenshot_dispatch(w.xid).ok())} else {platform_linux::capture::screenshot_display_bytes().ok()}@@ -982,7 +1067,11 @@ fn build_registry(cursor_cfg: cursor_overlay::CursorConfig) -> cua_driver_core::if let Err(error) = platform_linux::atspi::ensure_listener_active() {tracing::warn!("could not activate the persistent AT-SPI listener: {error}");}- { let mut r = platform_linux::register_tools_with_cursor(cursor_cfg, compat); check_update_tool::register_into(&mut r); r }+ {+ let mut r = platform_linux::register_tools_with_cursor(cursor_cfg, compat);+ check_update_tool::register_into(&mut r);+ r+ }}#[cfg(not(any(target_os = "windows", target_os = "linux")))]{@@ -1013,12 +1102,15 @@ fn build_registry_no_cursor() -> cua_driver_core::tool::ToolRegistry {cua_driver_core::recording::set_element_bounds_fn(|wid, pid, idx| {platform_windows::recording_hooks::element_window_local_xy(wid, pid, idx)});- cua_driver_core::video::set_video_backend_factory(- Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),- );+ cua_driver_core::video::set_video_backend_factory(Box::new(+ cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory,+ ));{let mut r = platform_windows::register_tools_with_cursor(- cursor_overlay::CursorConfig { enabled: false, ..Default::default() },+ cursor_overlay::CursorConfig {+ enabled: false,+ ..Default::default()+ },compat,);check_update_tool::register_into(&mut r);@@ -1038,9 +1130,8 @@ fn build_registry_no_cursor() -> cua_driver_core::tool::ToolRegistry {platform_linux::wayland::screenshot_dispatch(xid).ok()} else if let Some(p) = pid {let wins = platform_linux::wayland::list_windows_dispatch(Some(p as u32));- wins.first().and_then(|w| {- platform_linux::wayland::screenshot_dispatch(w.xid).ok()- })+ wins.first()+ .and_then(|w| platform_linux::wayland::screenshot_dispatch(w.xid).ok())} else {platform_linux::capture::screenshot_display_bytes().ok()}@@ -1065,7 +1156,10 @@ fn build_registry_no_cursor() -> cua_driver_core::tool::ToolRegistry {}{let mut r = platform_linux::register_tools_with_cursor(- cursor_overlay::CursorConfig { enabled: false, ..Default::default() },+ cursor_overlay::CursorConfig {+ enabled: false,+ ..Default::default()+ },compat,);check_update_tool::register_into(&mut r);diff --git a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rsindex b11a771692..0573100283 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/proxy.rs@@ -84,18 +84,21 @@ pub async fn run_proxy(socket_path: String) -> anyhow::Result<()> {// alive-but-idle session — one issuing zero tool calls — is never reaped:// its control connection stays parked open.//- // Detached + fire-and-forget. If the connect races daemon startup and- // fails, we log and continue — the per-call `send_request` has its own- // retry/timeout, and a restarted daemon loses session state anyway, so a- // missing control connection only degrades to no-reaper (the recording- // idle-TTL still backstops a leaked recording). It must NOT bail the proxy.+ // The daemon must acknowledge `session_begin` before the proxy accepts tool+ // calls. Besides lifecycle cleanup, that registered control channel is the+ // trust boundary used by destructive `browser_prepare` calls.+ let (control_ready_tx, control_ready_rx) = tokio::sync::oneshot::channel();{let socket = socket_path.clone();let sid = session_id.clone();tokio::spawn(async move {- run_control_connection(socket, sid).await;+ run_control_connection(socket, sid, control_ready_tx).await;});}+ tokio::time::timeout(std::time::Duration::from_secs(4), control_ready_rx)+ .await+ .map_err(|_| anyhow::anyhow!("daemon did not acknowledge the MCP control session"))?+ .map_err(|_| anyhow::anyhow!("daemon control session closed before acknowledgement"))?;// Cache the tool list once at startup. The daemon's registry is// static for the lifetime of the daemon, so polling on every@@ -215,9 +218,9 @@ fn proxy_knows_tool(cached_tools_list: &serde_json::Value, name: &str) -> bool {.get("tools").and_then(serde_json::Value::as_array).is_some_and(|tools| {- tools.iter().any(|tool| {- tool.get("name").and_then(serde_json::Value::as_str) == Some(name)- })+ tools+ .iter()+ .any(|tool| tool.get("name").and_then(serde_json::Value::as_str) == Some(name))})}@@ -233,7 +236,11 @@ fn proxy_knows_tool(cached_tools_list: &serde_json::Value, name: &str) -> bool {/// and the task ends; the proxy keeps running on its per-call connections. A/// connect failure (racing daemon startup) is logged and swallowed — it must/// not bail the proxy.-async fn run_control_connection(socket_path: String, session_id: String) {+async fn run_control_connection(+ socket_path: String,+ session_id: String,+ control_ready: tokio::sync::oneshot::Sender<()>,+) {let begin = DaemonRequest {method: "session_begin".into(),name: None,@@ -281,6 +288,12 @@ async fn run_control_connection(socket_path: String, session_id: String) {// death, when the kernel closes it and the daemon reaps the session.let mut reader = BufReader::new(stream);let mut buf = String::new();+ match reader.read_line(&mut buf).await {+ Ok(0) | Err(_) => return,+ Ok(_) => {+ let _ = control_ready.send(());+ }+ }loop {buf.clear();match reader.read_line(&mut buf).await {@@ -322,6 +335,12 @@ async fn run_control_connection(socket_path: String, session_id: String) {let mut reader = BufReader::new(client);let mut buf = String::new();+ match reader.read_line(&mut buf).await {+ Ok(0) | Err(_) => return,+ Ok(_) => {+ let _ = control_ready.send(());+ }+ }loop {buf.clear();match reader.read_line(&mut buf).await {@@ -334,7 +353,7 @@ async fn run_control_connection(socket_path: String, session_id: String) {#[cfg(all(not(unix), not(target_os = "windows")))]{- let _ = (line, session_id, socket_path);+ let _ = (line, session_id, socket_path, control_ready);}}@@ -374,15 +393,13 @@ fn fetch_tools_list_from_daemon(resp.error.unwrap_or_else(|| "(no error message)".into()));}- let result = resp.result.ok_or_else(|| {- anyhow::anyhow!("daemon list response missing `result` field")- })?;+ let result = resp+ .result+ .ok_or_else(|| anyhow::anyhow!("daemon list response missing `result` field"))?;let tools_array = result.get("tools").and_then(|v| v.as_array())- .ok_or_else(|| {- anyhow::anyhow!("daemon list response missing `tools` array")- })?;+ .ok_or_else(|| anyhow::anyhow!("daemon list response missing `tools` array"))?;// Reshape the daemon's `{name, description, input_schema, read_only,// ..., capabilities}` envelope into MCP's `{name, description,@@ -402,17 +419,28 @@ fn fetch_tools_list_from_daemon(.get("description").cloned().unwrap_or(serde_json::Value::String(String::new()));- let input_schema = t.get("input_schema").cloned().unwrap_or_else(- || serde_json::json!({"type": "object", "properties": {}}),- );- let read_only = t.get("read_only").and_then(|v| v.as_bool()).unwrap_or(false);- let destructive =- t.get("destructive").and_then(|v| v.as_bool()).unwrap_or(false);- let idempotent =- t.get("idempotent").and_then(|v| v.as_bool()).unwrap_or(false);- let open_world =- t.get("open_world").and_then(|v| v.as_bool()).unwrap_or(false);- let capabilities = t.get("capabilities")+ let input_schema = t+ .get("input_schema")+ .cloned()+ .unwrap_or_else(|| serde_json::json!({"type": "object", "properties": {}}));+ let read_only = t+ .get("read_only")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);+ let destructive = t+ .get("destructive")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);+ let idempotent = t+ .get("idempotent")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);+ let open_world = t+ .get("open_world")+ .and_then(|v| v.as_bool())+ .unwrap_or(false);+ let capabilities = t+ .get("capabilities").and_then(|v| v.as_array()).cloned().unwrap_or_else(|| {@@ -448,9 +476,9 @@ fn fetch_tools_list_from_daemon(let capability_version = result.get("capability_version").cloned()- .unwrap_or_else(|| serde_json::Value::String(- cua_driver_core::tool::CAPABILITY_VERSION.to_owned()- ));+ .unwrap_or_else(|| {+ serde_json::Value::String(cua_driver_core::tool::CAPABILITY_VERSION.to_owned())+ });let schema_version = result.get("schema_version").cloned()@@ -562,11 +590,12 @@ async fn handle_proxy_request(async fn forward_tool_call(id: serde_json::Value,name: String,- args: serde_json::Value,+ mut args: serde_json::Value,socket_path: &str,session_id: &str,daemon_observes_tool_calls: bool,) -> Response {+ cua_driver_core::tool_args::sanitize_reserved_args(&mut args);let req = DaemonRequest {method: "call".into(),name: Some(name.clone()),@@ -618,7 +647,9 @@ async fn forward_tool_call(// it as `Response::ok` with `isError: true`. Mirror that// shape here so MCP clients see identical envelopes either// way — CodeRabbit #2.- let msg = resp.error.unwrap_or_else(|| "daemon reported failure".into());+ let msg = resp+ .error+ .unwrap_or_else(|| "daemon reported failure".into());let exit_code = resp.exit_code.unwrap_or(1);let result = serde_json::json!({"content": [{ "type": "text", "text": msg }],@@ -654,11 +685,10 @@ mod tests {/// Reconstruct the `!resp.ok` branch in isolation so we can assert/// on the serialized shape without spinning up a real daemon //// tokio runtime. Keep this in sync with `forward_tool_call`.- fn build_tool_error_response(- id: serde_json::Value,- resp: DaemonResponse,- ) -> Response {- let msg = resp.error.unwrap_or_else(|| "daemon reported failure".into());+ fn build_tool_error_response(id: serde_json::Value, resp: DaemonResponse) -> Response {+ let msg = resp+ .error+ .unwrap_or_else(|| "daemon reported failure".into());let exit_code = resp.exit_code.unwrap_or(1);let result = serde_json::json!({"content": [{ "type": "text", "text": msg }],@@ -682,10 +712,14 @@ mod tests {// Top-level JSON-RPC envelope: success (`result`), not error.assert_eq!(value["jsonrpc"], "2.0");assert_eq!(value["id"], serde_json::json!(7));- assert!(value.get("error").is_none(),- "tool-level failure must NOT surface as JSON-RPC error: got {value}");- assert!(value.get("result").is_some(),- "tool-level failure must carry a `result` payload: got {value}");+ assert!(+ value.get("error").is_none(),+ "tool-level failure must NOT surface as JSON-RPC error: got {value}"+ );+ assert!(+ value.get("result").is_some(),+ "tool-level failure must carry a `result` payload: got {value}"+ );// CallTool.Result inside `result`: isError + content text.let result = &value["result"];@@ -706,7 +740,10 @@ mod tests {let resp = build_tool_error_response(serde_json::json!("abc"), daemon_resp);let value = serde_json::to_value(&resp).expect("serialize");assert_eq!(value["result"]["isError"], serde_json::json!(true));- assert_eq!(value["result"]["content"][0]["text"], "daemon reported failure");+ assert_eq!(+ value["result"]["content"][0]["text"],+ "daemon reported failure"+ );assert_eq!(value["result"]["structuredContent"]["exit_code"], 1);}@@ -719,7 +756,10 @@ mod tests {]});assert!(proxy_knows_tool(&cached, "click"));- assert!(proxy_knows_tool(&cached, "type_text_chars"), "deprecated alias stays bounded/known");+ assert!(+ proxy_knows_tool(&cached, "type_text_chars"),+ "deprecated alias stays bounded/known"+ );assert!(!proxy_knows_tool(&cached, "click/private-user-value"));assert!(!proxy_knows_tool(&cached, ""));}diff --git a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs b/libs/cua-driver/rust/crates/cua-driver/src/serve.rsindex fa8f7b93ba..ae90ee210f 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/serve.rs@@ -18,6 +18,33 @@//! Windows — \\.\pipe\cua-driver (TODO: use named pipe; stubs only for now)use serde::{Deserialize, Serialize};+use std::collections::HashSet;+use std::sync::{Mutex, OnceLock};++static ACTIVE_PROXY_SESSIONS: OnceLock<Mutex<HashSet<String>>> = OnceLock::new();++fn active_proxy_sessions() -> &'static Mutex<HashSet<String>> {+ ACTIVE_PROXY_SESSIONS.get_or_init(|| Mutex::new(HashSet::new()))+}++fn is_active_proxy_session(session: Option<&str>) -> bool {+ session.is_some_and(|session| active_proxy_sessions().lock().unwrap().contains(session))+}++fn inject_browser_prepare_approval(+ tool_name: &str,+ args: &mut serde_json::Value,+ session: Option<&str>,+) {+ if tool_name == "browser_prepare" && is_active_proxy_session(session) {+ if let Some(arguments) = args.as_object_mut() {+ arguments.insert(+ cua_driver_core::browser::approval::MCP_HOST_APPROVAL_ARG.to_owned(),+ serde_json::Value::Bool(true),+ );+ }+ }+}// ── Recording idle-TTL backstop (#1764) ─────────────────────────────────────────@@ -62,10 +89,16 @@ fn apply_session_identity(.filter(|s| !s.is_empty()).map(|s| s.to_owned());if let Some(obj) = args.as_object_mut() {- if !obj.contains_key("_session_id") {- if let Some(id) = explicit.clone().or_else(|| minted.clone()) {- obj.insert("_session_id".to_owned(), serde_json::Value::String(id));- }+ obj.remove("_session_id");+ obj.remove("_transport_session_id");+ if let Some(id) = explicit.clone().or_else(|| minted.clone()) {+ obj.insert("_session_id".to_owned(), serde_json::Value::String(id));+ }+ if let Some(id) = minted.clone() {+ obj.insert(+ "_transport_session_id".to_owned(),+ serde_json::Value::String(id),+ );}}if let Some(sess) = &explicit {@@ -392,6 +425,7 @@ async fn invoke_daemon_tool(let mut args = req.args.unwrap_or_else(|| serde_json::Value::Object(serde_json::Map::new()));+ cua_driver_core::tool_args::sanitize_reserved_args(&mut args);let effective_session = apply_session_identity(&mut args, &req.session_id);let operation = cua_driver_core::server::tool_operation(&tool_name, Some(&args));let observation = observation_transport.map(|transport| {@@ -448,6 +482,8 @@ async fn invoke_daemon_tool(}}+ inject_browser_prepare_approval(&tool_name, &mut args, req.session_id.as_deref());+let session_context = observation_transport.and_then(|transport| {let transport = match transport {crate::telemetry::Transport::McpStdio => {@@ -860,6 +896,10 @@ pub async fn run_serve(// per-call connections never send this. ACK ok.if let Some(sid) = req.session_id.as_deref() {control_session_id = Some(sid.to_owned());+ active_proxy_sessions()+ .lock()+ .unwrap()+ .insert(sid.to_owned());}let resp = DaemonResponse::ok(serde_json::json!({"session_begin": true})@@ -925,6 +965,7 @@ pub async fn run_serve(// idempotent, so racing a legacy explicit session_end is// benign.if let Some(sid) = control_session_id {+ active_proxy_sessions().lock().unwrap().remove(&sid);// stop_owner can SYNCHRONOUSLY finalize the recording's// mp4 — on macOS it hits SCStream::stop_capture(), which// blocks on disk I/O (video_sckit.rs). Run it on a@@ -1323,6 +1364,10 @@ pub async fn run_serve(// session in the post-loop block below. ACK ok.if let Some(sid) = req.session_id.as_deref() {control_session_id = Some(sid.to_owned());+ active_proxy_sessions()+ .lock()+ .unwrap()+ .insert(sid.to_owned());}let resp = DaemonResponse::ok(serde_json::json!({"session_begin": true})@@ -1377,6 +1422,7 @@ pub async fn run_serve(// the full rationale). Per-call connections leave// control_session_id None.if let Some(sid) = control_session_id {+ active_proxy_sessions().lock().unwrap().remove(&sid);// Run stop_owner off the reactor (see the unix branch):// recording finalize can be a synchronous blocking call.// fire_session_end stays inline (non-blocking hooks).@@ -1797,7 +1843,8 @@ mod telemetry_routing_tests {#[cfg(test)]mod session_boundary_tests {- use super::apply_session_identity;+ use super::{active_proxy_sessions, apply_session_identity, inject_browser_prepare_approval};+ use cua_driver_core::browser::approval::MCP_HOST_APPROVAL_ARG;use serde_json::json;#[test]@@ -1806,6 +1853,16 @@ mod session_boundary_tests {let eff = apply_session_identity(&mut args, &None);assert_eq!(eff.as_deref(), Some("research-1"));assert_eq!(args["_session_id"], "research-1");+ assert!(args.get("_transport_session_id").is_none());+ }++ #[test]+ fn public_and_transport_sessions_remain_independent() {+ let mut args = json!({ "session": "capability-session" });+ let eff = apply_session_identity(&mut args, &Some("proxy-session".to_owned()));+ assert_eq!(eff.as_deref(), Some("capability-session"));+ assert_eq!(args["_session_id"], "capability-session");+ assert_eq!(args["_transport_session_id"], "proxy-session");}#[test]@@ -1817,6 +1874,7 @@ mod session_boundary_tests {let eff = apply_session_identity(&mut args, &Some("mcp-123".to_owned()));assert_eq!(args["_session_id"], "mcp-123");assert_eq!(eff.as_deref(), Some("mcp-123"));+ assert_eq!(args["_transport_session_id"], "mcp-123");assert!(args.get("session").is_none());}@@ -1829,10 +1887,37 @@ mod session_boundary_tests {}#[test]- fn caller_set_session_id_is_not_overwritten_by_minted() {+ fn caller_set_session_id_is_replaced_by_minted() {let mut args = json!({ "_session_id": "caller-set" });let eff = apply_session_identity(&mut args, &Some("mcp-999".to_owned()));- assert_eq!(args["_session_id"], "caller-set");- assert_eq!(eff.as_deref(), Some("caller-set"));+ assert_eq!(args["_session_id"], "mcp-999");+ assert_eq!(args["_transport_session_id"], "mcp-999");+ assert_eq!(eff.as_deref(), Some("mcp-999"));+ }++ #[test]+ fn browser_prepare_approval_requires_a_live_proxy_session() {+ let session = "approval-boundary-test";+ let mut raw_args = json!({"pid": 42});+ inject_browser_prepare_approval("browser_prepare", &mut raw_args, Some(session));+ assert!(raw_args.get(MCP_HOST_APPROVAL_ARG).is_none());++ active_proxy_sessions()+ .lock()+ .unwrap()+ .insert(session.to_owned());+ let mut proxy_args = json!({"pid": 42});+ inject_browser_prepare_approval("browser_prepare", &mut proxy_args, Some(session));+ active_proxy_sessions().lock().unwrap().remove(session);+ assert_eq!(proxy_args[MCP_HOST_APPROVAL_ARG], true);++ let mut other_tool = json!({"pid": 42});+ active_proxy_sessions()+ .lock()+ .unwrap()+ .insert(session.to_owned());+ inject_browser_prepare_approval("get_browser_state", &mut other_tool, Some(session));+ active_proxy_sessions().lock().unwrap().remove(session);+ assert!(other_tool.get(MCP_HOST_APPROVAL_ARG).is_none());}}diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/README.md b/libs/cua-driver/rust/crates/cua-driver/tests/README.mdindex f83f842cdd..672b0ef54d 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/README.md+++ b/libs/cua-driver/rust/crates/cua-driver/tests/README.md@@ -84,6 +84,12 @@ clone of the private maintainer seed, requires a logged-in user session, andverifies the installed driver's Accessibility and Screen Recording grantsbefore delegating to `scripts/ci/macos/run-rust-e2e.sh`.+For focused macOS runs on a workstation shared with other driver clients,+start a TCC-authorized daemon on a dedicated socket and set+`CUA_E2E_MACOS_DAEMON_SOCKET` to that socket. This prevents an unrelated MCP+client from changing the shared daemon's session or recording state while a+row is asserting focus preservation.+Legacy Windows Sandbox runs use`../../../../tests/runners/windows-sandbox/run-tests-in-sandbox.ps1`, whichbuilds selected Windows harness apps and maps them into the sandbox. The current@@ -129,3 +135,12 @@ desktop state outside the repo-local fixtures:checks. Requires a logged-in GUI session and usable System Events scripting.- `installed_app_textedit_macos_test.rs`: real TextEdit background AX write andverification. Requires a logged-in GUI session and Accessibility permission.+- `standalone_browser_behavior_test.rs`: installed Chrome and Edge browser-tool+ targeting, mutation, frame, tab, ambiguity, and isolated-profile rows. The+ harness owns a fresh browser profile and creates adversarial tabs and windows+ through the browser endpoint instead of relying on browser command-line+ handoff behavior. Run it through the cross-platform+ `scripts/ci/run-rust-standalone-browser-e2e.sh`, which stages the Electron+ foreground sentinel when needed and opts pure Wayland runs into the native+ backend. macOS Lume maintainers can add it to the VM acceptance run with+ `run-all.sh --standalone-browser`.diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rsindex ec7e1f539a..918ac8a545 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/cross_platform_behavior_test.rs@@ -2,10 +2,12 @@//!//! These are source-owned Rust tests, not a copy of a partner test runner. The//! shared web fixture is loaded by Electron and Tauri on every supported OS;-//! Windows also has WebView2 coverage in `harness_web_test.rs`. Assertions read-//! mutated application state from a fixture-owned loopback journal, independently-//! of the driver's accessibility snapshot. A successful response alone is never-//! sufficient.+//! Windows also has WebView2 coverage. The embedded-browser rows require an+//! exact CDP round trip for Electron and a structured, side-effect-free refusal+//! for hosts whose engine-to-native-window relationship cannot be proven.+//! Assertions read mutated application state from a fixture-owned loopback+//! journal, independently of the driver's accessibility snapshot. A successful+//! response alone is never sufficient.//!//! Run after building the shared fixtures://!@@ -116,6 +118,11 @@ fn host_specs() -> Vec<HostSpec> {});}+ retain_selected_hosts(&mut hosts);+ hosts+}++fn retain_selected_hosts(hosts: &mut Vec<HostSpec>) {if let Ok(filter) = std::env::var("CUA_E2E_HARNESS_FILTER") {let selected = filter.split(',')@@ -126,7 +133,18 @@ fn host_specs() -> Vec<HostSpec> {hosts.retain(|host| selected.contains(host.name));}}+}+fn embedded_browser_specs() -> Vec<HostSpec> {+ let mut hosts = host_specs();+ #[cfg(target_os = "windows")]+ hosts.push(HostSpec {+ name: "webview2",+ path: harness_app("harness-webview", "CuaTestHarness.WebView.exe"),+ args: Vec::new(),+ title: "CuaTestHarness WebView",+ });+ retain_selected_hosts(&mut hosts);hosts}@@ -229,14 +247,22 @@ fn resume_first_failure(failure: Option<Box<dyn Any + Send>>) {}}-fn spawn_driver(recording_label: &str) -> Option<McpDriver> {+fn spawn_driver(recording_label: &str, cdp_port: Option<u16>) -> Option<McpDriver> {#[cfg(target_os = "macos")]{+ let _ = cdp_port;McpDriver::spawn_macos_daemon_proxy_named(recording_label)}#[cfg(not(target_os = "macos"))]{- McpDriver::spawn_named(recording_label)+ let port = cdp_port.map(|value| value.to_string());+ match port.as_deref() {+ Some(port) => McpDriver::spawn_named_with_env(+ recording_label,+ &[("CUA_DRIVER_CDP_PORT", port)],+ ),+ None => McpDriver::spawn_named(recording_label),+ }}}@@ -269,7 +295,9 @@ fn launch_host_with_evidence(spec: &HostSpec, scenario: &str, evidence: &mut Evi}let recording_label = scenario.to_owned();- let mut driver = spawn_driver(&recording_label).unwrap_or_else(|| {+ let cdp_port = matches!(spec.name, "electron" | "webview2")+ .then(allocate_loopback_port);+ let mut driver = spawn_driver(&recording_label, cdp_port).unwrap_or_else(|| {panic!("cua-driver could not be started for the required {} fixture",spec.name@@ -283,11 +311,20 @@ fn launch_host_with_evidence(spec: &HostSpec, scenario: &str, evidence: &mut Evi.env("CUA_E2E_FIXTURE_JOURNAL_URL", journal.url()).stdout(Stdio::inherit()).stderr(Stdio::inherit());- if spec.name == "electron" {- command.env(- "CUA_ELECTRON_CDP_PORT",- allocate_loopback_port().to_string(),- );+ match spec.name {+ "electron" => {+ command.env(+ "CUA_ELECTRON_CDP_PORT",+ cdp_port.expect("Electron CDP port").to_string(),+ );+ }+ "webview2" => {+ command.env(+ "CUA_WEBVIEW_CDP_PORT",+ cdp_port.expect("WebView2 CDP port").to_string(),+ );+ }+ _ => {}}let before_windows = driver.call("list_windows", serde_json::json!({}))@@ -653,6 +690,26 @@ fn delivered_observation() -> Observation {Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())}+fn browser_ref_by_label(snapshot: &ToolResponse, label_fragment: &str) -> String {+ snapshot.structured()["refs"]+ .as_array()+ .and_then(|refs| {+ refs.iter().find(|entry| {+ entry["label"]+ .as_str()+ .is_some_and(|label| label.contains(label_fragment))+ })+ })+ .and_then(|entry| entry["ref"].as_str())+ .map(str::to_owned)+ .unwrap_or_else(|| {+ panic!(+ "browser snapshot is missing ref label {label_fragment:?}: {}",+ snapshot.raw+ )+ })+}+fn refused_without_fixture_mutation(fixture: &Fixture,before: &serde_json::Value,@@ -1155,6 +1212,341 @@ fn cell_selected(case: &CaseSpec) -> bool {parts.peek().is_none() || parts.any(|part| case.cell_id == part || case.cell_id.contains(part))}+fn run_browser_tool_roundtrip(fixture: &mut Fixture) -> Observation {+ let legacy = fixture.driver.call(+ "page",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "window_id": fixture.wid,+ "action": "execute_javascript",+ "javascript": "document.querySelector('[data-cua-id=page-marker]').textContent",+ }),+ );+ assert!(+ !legacy.is_error() && legacy.text().contains("WEB_HARNESS_MARKER_v1"),+ "legacy page transport did not read the Electron fixture marker: {}",+ legacy.raw+ );+ let session = format!("browser-v1-e2e-{}", fixture.pid);+ let started = fixture+ .driver+ .call("start_session", serde_json::json!({ "session": session }));+ assert!(+ !started.is_error(),+ "browser E2E session did not start: {}",+ started.raw+ );+ let prepared = fixture.driver.call(+ "browser_prepare",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "session": session,+ }),+ );+ assert_eq!(+ prepared.structured()["prepared"].as_bool(),+ Some(true),+ "browser_prepare did not recognize the fixture's owned endpoint: {}",+ prepared.raw+ );+ let bind = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "window_id": fixture.wid,+ "session": session,+ }),+ );+ assert_eq!(+ bind.structured()["status"].as_str(),+ Some("ok"),+ "Electron browser binding failed: {}; raw={}",+ bind.text(),+ bind.raw+ );+ assert_eq!(+ bind.structured()["binding_quality"].as_str(),+ Some("exact"),+ "Electron browser binding must be exact: {}",+ bind.raw+ );+ assert_eq!(+ bind.structured()["binding_route"].as_str(),+ Some("embedded_single_page"),+ "Electron must exercise the bounded embedded-browser route: {}",+ bind.raw+ );+ let target_id = bind.structured()["target_id"]+ .as_str()+ .expect("bind target_id")+ .to_owned();+ let tab_id = bind.structured()["tabs"]+ .as_array()+ .and_then(|tabs| tabs.iter().find(|tab| tab["active"] == true))+ .and_then(|tab| tab["tab_id"].as_str())+ .expect("active tab_id")+ .to_owned();++ let first_snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "session": session,+ }),+ );+ assert_eq!(+ first_snapshot.structured()["status"].as_str(),+ Some("ok"),+ "Electron browser snapshot failed: {}",+ first_snapshot.raw+ );+ let increment_ref = browser_ref_by_label(&first_snapshot, "id=btn-increment");+ let click = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": increment_ref,+ "session": session,+ }),+ );+ assert_eq!(+ click.structured()["status"].as_str(),+ Some("ok"),+ "trusted browser click failed: {}",+ click.raw+ );+ assert_eq!(click.structured()["route"].as_str(), Some("trusted"));+ assert_fixture_text(fixture, "lbl-counter", "counter=1");++ let second_snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "session": session,+ }),+ );+ let input_ref = browser_ref_by_label(&second_snapshot, "id=txt-input");+ let typed = fixture.driver.call(+ "browser_type",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": input_ref,+ "text": "browser-v1",+ "session": session,+ }),+ );+ assert_eq!(+ typed.structured()["status"].as_str(),+ Some("ok"),+ "browser type failed: {}",+ typed.raw+ );+ assert_fixture_value(fixture, "txt-input", "browser-v1");+ assert_fixture_text(fixture, "lbl-input-mirror", "mirror=browser-v1");++ let stale = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": increment_ref,+ "session": session,+ }),+ );+ assert_eq!(+ stale.structured()["refusal"]["code"].as_str(),+ Some("browser_ref_stale"),+ "older snapshot ref should fail closed: {}",+ stale.raw+ );+ assert_fixture_text(fixture, "lbl-counter", "counter=1");++ let navigated = fixture.driver.call(+ "browser_navigate",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "url": "about:blank",+ "session": session,+ }),+ );+ assert_eq!(+ navigated.structured()["status"].as_str(),+ Some("ok"),+ "browser navigation failed: {}",+ navigated.raw+ );+ assert_eq!(+ navigated.structured()["refs_invalidated"].as_bool(),+ Some(true),+ "browser navigation must invalidate page refs: {}",+ navigated.raw+ );+ let blank_snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "session": session,+ }),+ );+ assert_eq!(+ blank_snapshot.structured()["url"].as_str(),+ Some("about:blank"),+ "browser did not reach the requested page: {}",+ blank_snapshot.raw+ );+ let stale_after_navigation = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target_id,+ "tab_id": tab_id,+ "ref": input_ref,+ "session": session,+ }),+ );+ assert_eq!(+ stale_after_navigation.structured()["refusal"]["code"].as_str(),+ Some("browser_ref_stale"),+ "navigation-invalidated ref should fail closed: {}",+ stale_after_navigation.raw+ );+ let ended = fixture+ .driver+ .call("end_session", serde_json::json!({ "session": session }));+ assert!(+ !ended.is_error(),+ "browser E2E session did not end: {}",+ ended.raw+ );+ delivered_observation()+}++fn run_browser_tool_refusal(fixture: &mut Fixture) -> Observation {+ let session = format!("browser-embedded-refusal-{}", fixture.pid);+ let started = fixture+ .driver+ .call("start_session", serde_json::json!({ "session": session }));+ assert!(+ !started.is_error(),+ "browser refusal session did not start: {}",+ started.raw+ );+ let journal_before = fixture.journal.snapshot();+ let response = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "window_id": fixture.wid,+ "session": session,+ }),+ );+ let code = response.structured()["refusal"]["code"]+ .as_str()+ .and_then(RefusalCode::from_driver_code)+ .unwrap_or_else(|| panic!("embedded browser did not refuse structurally: {}", response.raw));+ assert_eq!(+ code,+ RefusalCode::BrowserRouteUnavailable,+ "embedded browser returned the wrong refusal: {}",+ response.raw+ );+ assert_eq!(+ fixture.journal.snapshot(),+ journal_before,+ "browser refusal mutated the fixture journal"+ );+ let ended = fixture+ .driver+ .call("end_session", serde_json::json!({ "session": session }));+ assert!(+ !ended.is_error(),+ "browser refusal session did not end: {}",+ ended.raw+ );+ Observation::refused(+ code,+ vec![OracleKind::FixtureState],+ response.text(),+ Evidence::default(),+ )+}++fn embedded_browser_case(spec: &HostSpec) -> CaseSpec {+ let mut oracles = vec![+ OracleKind::FixtureState,+ OracleKind::Focus,+ OracleKind::ZOrder,+ OracleKind::NoLeakedInput,+ ];+ if cua_driver_testkit::e2e::DisplayServer::current()+ != cua_driver_testkit::e2e::DisplayServer::Wayland+ {+ oracles.push(OracleKind::Cursor);+ }+ let case = CaseSpec::delivered(+ format!(+ "{}-{}-browser-tool-roundtrip",+ std::env::consts::OS,+ spec.name+ ),+ spec.name,+ if spec.name == "electron" {+ "chromium"+ } else {+ "platform-webview"+ },+ "browser_tool_roundtrip",+ Targeting::Page,+ Delivery::Background,+ Scope::Window,+ cua_driver_testkit::e2e::DriverRoute::Cdp,+ oracles,+ );+ if spec.name == "electron" {+ case+ } else {+ case.expecting_refusal(vec![RefusalCode::BrowserRouteUnavailable])+ }+}++#[test]+#[ignore]+fn embedded_browser_routes_are_exact_or_refused() {+ let mut failure = None;+ let mut selected = 0usize;+ for spec in embedded_browser_specs() {+ let case = embedded_browser_case(&spec);+ if !cell_selected(&case) {+ continue;+ }+ selected += 1;+ let result = if spec.name == "electron" {+ run_host_case_with_outcome(case, &spec, run_browser_tool_roundtrip)+ } else {+ run_host_case_with_outcome(case, &spec, run_browser_tool_refusal)+ };+ if failure.is_none() {+ failure = result;+ }+ }+ if selected == 0+ && std::env::var("CUA_E2E_CELL_FILTER").is_ok_and(|filter| !filter.trim().is_empty())+ {+ eprintln!("no embedded-browser rows matched CUA_E2E_CELL_FILTER");+ return;+ }+ assert!(+ selected > 0,+ "no embedded-browser cells were selected; check CUA_E2E_HARNESS_FILTER"+ );+ resume_first_failure(failure);+}+#[test]#[ignore]fn shared_web_action_matrix_is_state_verified() {diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rsindex 9393387879..0e481992a5 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/e2e_environment_preflight_test.rs@@ -223,7 +223,7 @@ fn run_preflight() {assert_eq!(config.structured()["source_sha"].as_str(),Some(expected_sha),- "connected macOS daemon was not built from the requested source SHA"+ "connected driver was not built from the requested source SHA");}let recording_dir = driverdiff --git a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rsindex 84a54a3ab8..18533635bb 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_schema_test.rs@@ -47,6 +47,64 @@ fn tools_list_schema_shape() {"type_text_chars should be hidden from tools/list");+ // Browser v1 is a cross-platform source-owned surface. Keep its full+ // roster, capability inputs, and read-only boundary pinned at the spawned+ // driver layer so platform registration drift cannot pass core-only tests.+ for name in [+ "get_browser_state",+ "browser_prepare",+ "browser_navigate",+ "browser_click",+ "browser_type",+ ] {+ assert!(+ tools.iter().any(|tool| tool["name"] == name),+ "browser tool {name} missing from tools/list"+ );+ }+ let browser_state = tools+ .iter()+ .find(|tool| tool["name"] == "get_browser_state")+ .expect("get_browser_state not found in tools/list");+ assert_eq!(+ browser_state["annotations"]["readOnlyHint"], true,+ "get_browser_state must remain side-effect free"+ );+ for field in ["pid", "window_id", "target_id", "tab_id", "session"] {+ assert!(+ browser_state["inputSchema"]["properties"][field].is_object(),+ "get_browser_state schema missing {field}"+ );+ }+ for (name, required) in [+ ("browser_prepare", &["pid"][..]),+ ("browser_navigate", &["target_id", "tab_id", "url"][..]),+ ("browser_click", &["target_id", "tab_id"][..]),+ ("browser_type", &["target_id", "tab_id", "ref", "text"][..]),+ ] {+ let tool = tools+ .iter()+ .find(|tool| tool["name"] == name)+ .unwrap_or_else(|| panic!("{name} not found in tools/list"));+ assert_eq!(+ tool["annotations"]["readOnlyHint"], false,+ "{name} must remain a mutation"+ );+ assert!(+ tool["inputSchema"]["properties"]["session"].is_object(),+ "{name} schema must expose the public session field"+ );+ let advertised = tool["inputSchema"]["required"]+ .as_array()+ .unwrap_or_else(|| panic!("{name} required fields missing"));+ for field in required {+ assert!(+ advertised.iter().any(|value| value.as_str() == Some(field)),+ "{name} schema missing required field {field}: {advertised:?}"+ );+ }+ }+for tool in ["click","double_click",diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rsnew file mode 100644index 0000000000..3c354997b8--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/tests/standalone_browser_behavior_test.rs@@ -0,0 +1,1507 @@+//! Optional standalone Chrome/Edge browser-tool E2E coverage.+//!+//! These rows use real installed browsers with a fresh driver-owned profile.+//! They are intentionally outside canonical `all`: maintainers dispatch them+//! on interactive desktops where the requested browser is installed.++use std::collections::HashSet;+use std::io::{Read, Write};+use std::net::TcpStream;+use std::panic::{catch_unwind, AssertUnwindSafe};+use std::path::{Path, PathBuf};+use std::process::{Command, Stdio};+use std::sync::Mutex;+use std::thread;+use std::time::{Duration, Instant};++use cua_driver_testkit::e2e::{+ execute_case, recording_evidence, write_environment_from_env, CaseSpec, Delivery, DriverRoute,+ EnvironmentRecord, Evidence, Observation, OracleKind, RefusalCode, Scope, Targeting,+};+use cua_driver_testkit::observer::TargetWindow;+use cua_driver_testkit::sentinel::ForegroundSentinel;+use cua_driver_testkit::{spawn_in_job, BrowserFixtureServer, Driver, McpDriver, ToolResponse};+use futures_util::{SinkExt, StreamExt};+use tokio_tungstenite::tungstenite::Message;++const FIXTURE_HTML: &str = include_str!("../../../../tests/fixtures/shared/web/index.html");+static STANDALONE_BROWSER_TEST_LOCK: Mutex<()> = Mutex::new(());++fn standalone_fixture_html() -> String {+ FIXTURE_HTML.replace(+ "</body>",+ r#"<a id="standalone-new-tab" data-cua-id="standalone-new-tab" href="/fixture?tab=second" target="_blank" onclick="document.getElementById('standalone-tab-state').textContent='new_tab=open'">Open standalone tab</a>+<span id="standalone-tab-state" data-cua-id="standalone-tab-state">new_tab=closed</span>+<script>+ if (new URLSearchParams(window.location.search).get('tab') === 'second') {+ document.getElementById('standalone-tab-state').textContent = 'new_tab=open';+ }+</script>+</body>"#,+ )+}++fn standalone_frame_fixture_html(oopif_url: &str) -> String {+ let oopif_url = serde_json::to_string(oopif_url).expect("serialize OOPIF fixture URL");+ FIXTURE_HTML.replace(+ "</body>",+ &format!(+ r#"<fieldset>+ <legend>browser frame routes</legend>+ <div id="standalone-shadow-host"></div>+ <span id="standalone-shadow-state" data-cua-id="standalone-shadow-state">shadow=loading</span>+ <iframe id="standalone-same-frame" title="standalone same-process frame"></iframe>+ <span id="standalone-frame-state" data-cua-id="standalone-frame-state">iframe=loading</span>+ <iframe id="standalone-oopif" title="standalone out-of-process frame" src={oopif_url}></iframe>+</fieldset>+<script>+ const shadowState = document.getElementById('standalone-shadow-state');+ const shadow = document.getElementById('standalone-shadow-host').attachShadow({{ mode: 'open' }});+ shadow.innerHTML = `<button id="standalone-shadow-button" aria-label="standalone-shadow-button">Shadow button</button>+ <input id="standalone-shadow-input" aria-label="standalone-shadow-input">`;+ shadow.getElementById('standalone-shadow-button').addEventListener('click', () => {{+ shadowState.textContent = 'shadow=clicked';+ }});+ shadow.getElementById('standalone-shadow-input').addEventListener('input', event => {{+ shadowState.textContent = `shadow=typed:${{event.target.value}}`;+ }});++ const frameState = document.getElementById('standalone-frame-state');+ const sameFrame = document.getElementById('standalone-same-frame');+ sameFrame.addEventListener('load', () => {{ frameState.textContent = 'iframe=ready'; }});+ sameFrame.srcdoc = `<!doctype html><button id="standalone-frame-button" aria-label="standalone-frame-button">Frame button</button>+ <input id="standalone-frame-input" aria-label="standalone-frame-input">+ <script>+ document.getElementById('standalone-frame-button').addEventListener('click', () => {{+ parent.document.getElementById('standalone-frame-state').textContent = 'iframe=clicked';+ }});+ document.getElementById('standalone-frame-input').addEventListener('input', event => {{+ parent.document.getElementById('standalone-frame-state').textContent = 'iframe=typed:' + event.target.value;+ }});+ <\/script>`;+ shadowState.textContent = 'shadow=ready';+</script>+</body>"#+ ),+ )+}++#[derive(Clone, Debug)]+struct BrowserSpec {+ name: String,+ executable: PathBuf,+}++struct BrowserFixture {+ driver: McpDriver,+ server: BrowserFixtureServer,+ _profile: tempfile::TempDir,+ cdp_port: u16,+ pid: u32,+ window_id: u64,+}++fn browser_specs() -> Vec<BrowserSpec> {+ if let Some(path) = std::env::var_os("CUA_E2E_BROWSER_BIN") {+ let executable = PathBuf::from(path);+ assert!(+ executable.is_file(),+ "CUA_E2E_BROWSER_BIN is not a file: {}",+ executable.display()+ );+ let name = std::env::var("CUA_E2E_BROWSER_NAME").unwrap_or_else(|_| "chromium".to_owned());+ return vec![BrowserSpec { name, executable }];+ }++ #[cfg(target_os = "macos")]+ {+ let home = PathBuf::from(std::env::var_os("HOME").expect("HOME"));+ return [+ (+ "chrome",+ PathBuf::from("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),+ ),+ (+ "chrome",+ home.join("Applications/Google Chrome.app/Contents/MacOS/Google Chrome"),+ ),+ (+ "edge",+ PathBuf::from("/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),+ ),+ (+ "edge",+ home.join("Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"),+ ),+ ]+ .into_iter()+ .filter(|(_, executable)| executable.is_file())+ .map(|(name, executable)| BrowserSpec {+ name: name.to_owned(),+ executable,+ })+ .collect();+ }+ #[cfg(target_os = "linux")]+ {+ let mut candidates = vec![+ ("chrome", PathBuf::from("/usr/bin/google-chrome")),+ ("chromium", PathBuf::from("/usr/bin/chromium")),+ ("chromium", PathBuf::from("/usr/bin/chromium-browser")),+ ("edge", PathBuf::from("/usr/bin/microsoft-edge")),+ ];+ if let Some(path) = std::env::var_os("PATH") {+ for (name, executable_name) in [+ ("chrome", "google-chrome"),+ ("chromium", "chromium"),+ ("chromium", "chromium-browser"),+ ("edge", "microsoft-edge"),+ ] {+ if let Some(executable) = std::env::split_paths(&path)+ .map(|directory| directory.join(executable_name))+ .find(|candidate| candidate.is_file())+ {+ candidates.push((name, executable));+ }+ }+ }+ let mut browsers = candidates+ .into_iter()+ .filter(|(_, executable)| executable.is_file())+ .map(|(name, executable)| {+ let identity =+ std::fs::canonicalize(&executable).unwrap_or_else(|_| executable.clone());+ (name, executable, identity)+ })+ .fold(Vec::new(), |mut entries, (name, executable, identity)| {+ if !entries+ .iter()+ .any(|(_, existing_identity): &(BrowserSpec, PathBuf)| {+ *existing_identity == identity+ })+ {+ entries.push((+ BrowserSpec {+ name: name.to_owned(),+ executable,+ },+ identity,+ ));+ }+ entries+ })+ .into_iter()+ .map(|(spec, _)| spec)+ .collect::<Vec<_>>();+ // Chromium is the open-source fallback for environments without the+ // Chrome stable channel. Do not expand a Chrome/Edge acceptance lane+ // merely because the host image also exposes a Chromium package shim.+ if browsers.iter().any(|spec| spec.name == "chrome") {+ browsers.retain(|spec| spec.name != "chromium");+ }+ return browsers;+ }+ #[cfg(target_os = "windows")]+ let candidates = {+ let program_files = std::env::var_os("ProgramFiles")+ .map(PathBuf::from)+ .unwrap_or_else(|| PathBuf::from(r"C:\Program Files"));+ let program_files_x86 = std::env::var_os("ProgramFiles(x86)")+ .map(PathBuf::from)+ .unwrap_or_else(|| PathBuf::from(r"C:\Program Files (x86)"));+ let local_app_data = std::env::var_os("LOCALAPPDATA")+ .map(PathBuf::from)+ .unwrap_or_default();+ return [+ (+ "chrome",+ program_files.join(r"Google\Chrome\Application\chrome.exe"),+ ),+ (+ "chrome",+ program_files_x86.join(r"Google\Chrome\Application\chrome.exe"),+ ),+ (+ "chrome",+ local_app_data.join(r"Google\Chrome\Application\chrome.exe"),+ ),+ (+ "edge",+ program_files_x86.join(r"Microsoft\Edge\Application\msedge.exe"),+ ),+ (+ "edge",+ program_files.join(r"Microsoft\Edge\Application\msedge.exe"),+ ),+ ]+ .into_iter()+ .filter(|(_, executable)| executable.is_file())+ .map(|(name, executable)| BrowserSpec {+ name: name.to_owned(),+ executable,+ })+ .collect();+ };+}++fn allocate_loopback_port() -> u16 {+ std::net::TcpListener::bind(("127.0.0.1", 0))+ .and_then(|listener| listener.local_addr())+ .expect("allocate standalone browser CDP port")+ .port()+}++fn browser_http_json(port: u16, path: &str) -> Result<serde_json::Value, String> {+ let mut stream = TcpStream::connect(("127.0.0.1", port))+ .map_err(|error| format!("connect to harness CDP endpoint {port}: {error}"))?;+ stream+ .set_read_timeout(Some(Duration::from_secs(5)))+ .map_err(|error| format!("set CDP HTTP read timeout: {error}"))?;+ write!(+ stream,+ "GET {path} HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"+ )+ .map_err(|error| format!("request harness CDP endpoint {path}: {error}"))?;+ let mut response = Vec::new();+ if let Err(error) = stream.read_to_end(&mut response) {+ if !matches!(+ error.kind(),+ std::io::ErrorKind::WouldBlock | std::io::ErrorKind::TimedOut+ ) {+ return Err(format!("read harness CDP endpoint {path}: {error}"));+ }+ }+ let body_start = response+ .windows(4)+ .position(|window| window == b"\r\n\r\n")+ .map(|index| index + 4)+ .ok_or_else(|| format!("CDP endpoint {path} returned no HTTP headers"))?;+ serde_json::from_slice(&response[body_start..])+ .map_err(|error| format!("parse CDP endpoint {path}: {error}"))+}++fn browser_endpoint_url(port: u16) -> String {+ let body = browser_http_json(port, "/json/version")+ .unwrap_or_else(|error| panic!("read harness CDP version: {error}"));+ body["webSocketDebuggerUrl"]+ .as_str()+ .expect("browser websocket URL")+ .to_owned()+}++fn wait_for_browser_endpoint(port: u16) {+ let deadline = Instant::now() + Duration::from_secs(90);+ loop {+ let error = match browser_http_json(port, "/json/version") {+ Ok(body) if body["webSocketDebuggerUrl"].is_string() => return,+ Ok(body) => format!("missing browser websocket URL: {body}"),+ Err(error) => error,+ };+ assert!(+ Instant::now() < deadline,+ "standalone browser never exposed its harness CDP endpoint: {error}"+ );+ thread::sleep(Duration::from_millis(100));+ }+}++fn harness_cdp_call_at_url(+ ws_url: &str,+ method: &str,+ params: serde_json::Value,+) -> serde_json::Value {+ let ws_url = ws_url.to_owned();+ let method = method.to_owned();+ tokio::runtime::Runtime::new()+ .expect("create harness CDP runtime")+ .block_on(async move {+ let (mut socket, _) = tokio_tungstenite::connect_async(&ws_url)+ .await+ .expect("connect harness browser websocket");+ socket+ .send(Message::Text(+ serde_json::json!({"id": 1, "method": method, "params": params}).to_string(),+ ))+ .await+ .expect("send harness CDP command");+ while let Some(frame) = socket.next().await {+ let frame = frame.expect("read harness CDP frame");+ let Message::Text(text) = frame else {+ continue;+ };+ let value: serde_json::Value =+ serde_json::from_str(&text).expect("parse harness CDP response");+ if value["id"] == 1 {+ assert!(value.get("error").is_none(), "CDP {method}: {value}");+ return value["result"].clone();+ }+ }+ panic!("browser websocket closed before CDP {method} replied")+ })+}++fn harness_cdp_call(port: u16, method: &str, params: serde_json::Value) -> serde_json::Value {+ harness_cdp_call_at_url(&browser_endpoint_url(port), method, params)+}++fn navigate_initial_page(port: u16, server: &BrowserFixtureServer) {+ let url = server.page_url();+ wait_for_browser_endpoint(port);+ let deadline = Instant::now() + Duration::from_secs(30);+ let mut last_error = None;+ let mut last_navigate = None;+ loop {+ let targets = browser_http_json(port, "/json/list")+ .unwrap_or_else(|error| panic!("read harness CDP targets: {error}"));+ let pages = targets+ .as_array()+ .into_iter()+ .flatten()+ .filter(|target| target["type"] == "page")+ .collect::<Vec<_>>();+ assert!(+ pages.len() <= 1,+ "fresh standalone browser exposed multiple page targets before fixture setup: {targets}"+ );+ if pages.first().is_some_and(|target| target["url"] == url)+ && server.contains("WEB_HARNESS_MARKER_v1")+ {+ return;+ }+ if let Some(ws_url) = pages+ .first()+ .and_then(|target| target["webSocketDebuggerUrl"].as_str())+ .filter(|_| {+ last_navigate+ .is_none_or(|issued: Instant| issued.elapsed() >= Duration::from_secs(2))+ })+ {+ let navigated =+ harness_cdp_call_at_url(ws_url, "Page.navigate", serde_json::json!({"url": url}));+ last_navigate = Some(Instant::now());+ last_error = Some(if navigated.get("errorText").is_some() {+ navigated+ } else {+ serde_json::json!({"status": "acknowledged; waiting for target URL commit"})+ });+ }+ assert!(+ Instant::now() < deadline,+ "initial fixture navigation did not commit on the fresh page target: {}; targets={targets}",+ last_error+ .as_ref()+ .map_or_else(|| "no page target".to_owned(), serde_json::Value::to_string)+ );+ thread::sleep(Duration::from_millis(100));+ }+}++fn cdp_target_for_url(port: u16, url: &str) -> String {+ harness_cdp_call(port, "Target.getTargets", serde_json::json!({}))["targetInfos"]+ .as_array()+ .and_then(|targets| {+ targets+ .iter()+ .find(|target| target["type"] == "page" && target["url"] == url)+ })+ .and_then(|target| target["targetId"].as_str())+ .unwrap_or_else(|| panic!("no CDP page target for {url}"))+ .to_owned()+}++fn driver_profile_root() -> PathBuf {+ #[cfg(target_os = "windows")]+ {+ return PathBuf::from(std::env::var_os("LOCALAPPDATA").expect("LOCALAPPDATA"))+ .join("CuaDriver")+ .join("BrowserProfiles");+ }+ #[cfg(target_os = "macos")]+ {+ return PathBuf::from(std::env::var_os("HOME").expect("HOME"))+ .join("Library")+ .join("Application Support")+ .join("CuaDriver")+ .join("BrowserProfiles");+ }+ #[cfg(all(unix, not(target_os = "macos")))]+ {+ let state = std::env::var_os("XDG_STATE_HOME")+ .map(PathBuf::from)+ .unwrap_or_else(|| {+ PathBuf::from(std::env::var_os("HOME").expect("HOME"))+ .join(".local")+ .join("state")+ });+ state.join("cua-driver").join("browser-profiles")+ }+}++fn profile_entries(root: &Path) -> HashSet<std::ffi::OsString> {+ std::fs::read_dir(root)+ .ok()+ .into_iter()+ .flatten()+ .filter_map(Result::ok)+ .map(|entry| entry.file_name())+ .collect()+}++fn spawn_driver(label: &str) -> McpDriver {+ #[cfg(target_os = "macos")]+ let driver = McpDriver::spawn_macos_daemon_proxy_named(label);+ #[cfg(not(target_os = "macos"))]+ let driver = McpDriver::spawn_named(label);+ driver.expect("cua-driver binary/daemon is required for standalone browser E2E")+}++#[cfg(target_os = "linux")]+fn configure_linux_browser_command(command: &mut Command) {+ command.arg("--password-store=basic");+ let native_wayland = std::env::var("XDG_SESSION_TYPE")+ .is_ok_and(|session| session.eq_ignore_ascii_case("wayland"))+ && std::env::var_os("WAYLAND_DISPLAY").is_some()+ && std::env::var_os("DISPLAY").is_none();+ if native_wayland {+ command.arg("--ozone-platform=wayland");+ }+}++fn configure_test_browser_sandbox(command: &mut Command) {+ if std::env::var("CUA_E2E_BROWSER_NO_SANDBOX").as_deref() == Ok("1") {+ command.arg("--no-sandbox");+ }+}++#[cfg(target_os = "windows")]+const TEST_BROWSER_WINDOW_SIZE: &str = "900,640";+#[cfg(not(target_os = "windows"))]+const TEST_BROWSER_WINDOW_SIZE: &str = "980,760";++#[cfg(target_os = "windows")]+const TEST_BROWSER_INITIAL_POSITION: (i32, i32) = (40, 40);+#[cfg(not(target_os = "windows"))]+const TEST_BROWSER_INITIAL_POSITION: (i32, i32) = (80, 80);++fn command_for_browser(+ spec: &BrowserSpec,+ profile: &Path,+ cdp_port: u16,+ url: &str,+ position: (i32, i32),+) -> Command {+ let mut command = Command::new(&spec.executable);+ let output = if std::env::var_os("CUA_E2E_BROWSER_STDERR").is_some() {+ Stdio::inherit()+ } else {+ Stdio::null()+ };+ command+ .arg(format!("--remote-debugging-port={cdp_port}"))+ .arg(format!("--user-data-dir={}", profile.display()))+ .arg("--no-first-run")+ .arg("--no-default-browser-check")+ .arg("--disable-background-networking")+ .arg("--disable-component-update")+ .arg("--disable-extensions")+ .arg("--disable-default-apps")+ .arg("--site-per-process")+ .arg("--new-window")+ .arg(format!("--window-position={},{}", position.0, position.1))+ .arg(format!("--window-size={TEST_BROWSER_WINDOW_SIZE}"));+ configure_test_browser_sandbox(&mut command);+ #[cfg(target_os = "linux")]+ configure_linux_browser_command(&mut command);+ command.arg(url).stdout(Stdio::null()).stderr(output);+ command+}++fn command_for_unprepared_browser(+ spec: &BrowserSpec,+ profile: &Path,+ url: &str,+ position: (i32, i32),+) -> Command {+ let mut command = Command::new(&spec.executable);+ command+ .arg(format!("--user-data-dir={}", profile.display()))+ .arg("--no-first-run")+ .arg("--no-default-browser-check")+ .arg("--disable-background-networking")+ .arg("--disable-component-update")+ .arg("--disable-extensions")+ .arg("--disable-default-apps")+ .arg("--new-window")+ .arg(format!("--window-position={},{}", position.0, position.1))+ .arg(format!("--window-size={TEST_BROWSER_WINDOW_SIZE}"));+ configure_test_browser_sandbox(&mut command);+ #[cfg(target_os = "linux")]+ configure_linux_browser_command(&mut command);+ command+ .arg(url)+ .stdin(Stdio::null())+ .stdout(Stdio::null())+ .stderr(Stdio::null());+ command+}++fn window_ids(driver: &mut McpDriver) -> HashSet<u64> {+ driver+ .call("list_windows", serde_json::json!({}))+ .structured()["windows"]+ .as_array()+ .into_iter()+ .flatten()+ .filter_map(|window| window["window_id"].as_u64())+ .collect()+}++fn wait_for_fixture_window(+ driver: &mut McpDriver,+ before: &HashSet<u64>,+ server: &BrowserFixtureServer,+) -> Option<(u32, u64)> {+ // Fixture navigation is complete before this wait starts. Waiting is+ // topology-neutral; relaunching is not, since the first process may+ // eventually map and leave an extra CDP page.+ let deadline = Instant::now() + Duration::from_secs(40);+ loop {+ let windows = driver.call("list_windows", serde_json::json!({}));+ if let Some(window) = windows.structured()["windows"]+ .as_array()+ .and_then(|windows| {+ windows.iter().find(|window| {+ window["window_id"]+ .as_u64()+ .is_some_and(|id| !before.contains(&id))+ && window["title"]+ .as_str()+ .is_some_and(|title| title.contains("cua-driver Web Harness"))+ })+ })+ {+ if server.contains("WEB_HARNESS_MARKER_v1") {+ return Some((+ window["pid"].as_u64().expect("browser window pid") as u32,+ window["window_id"].as_u64().expect("browser window id"),+ ));+ }+ }+ if Instant::now() >= deadline {+ return None;+ }+ thread::sleep(Duration::from_millis(100));+ }+}++fn wait_for_exact_browser_binding(+ driver: &mut McpDriver,+ pid: u32,+ session: &str,+) -> Option<(u64, ToolResponse)> {+ let deadline = Instant::now() + Duration::from_secs(20);+ loop {+ let windows = driver.call("list_windows", serde_json::json!({ "pid": pid }));+ for window_id in windows.structured()["windows"]+ .as_array()+ .into_iter()+ .flatten()+ .filter_map(|window| window["window_id"].as_u64())+ {+ let state = driver.call(+ "get_browser_state",+ serde_json::json!({+ "pid": pid as i64,+ "window_id": window_id,+ "session": session,+ }),+ );+ if state.structured()["binding_quality"] == "exact" {+ return Some((window_id, state));+ }+ }+ if Instant::now() >= deadline {+ eprintln!(+ "no exact browser window binding for prepared pid {pid}; last windows={}",+ windows.raw+ );+ return None;+ }+ thread::sleep(Duration::from_millis(100));+ }+}++fn wait_for_pid_windows_to_close(driver: &mut McpDriver, pid: u32) {+ let deadline = Instant::now() + Duration::from_secs(10);+ loop {+ let windows = driver.call("list_windows", serde_json::json!({ "pid": pid }));+ let is_empty = windows.structured()["windows"]+ .as_array()+ .is_none_or(Vec::is_empty);+ if is_empty {+ return;+ }+ assert!(+ Instant::now() < deadline,+ "prepared browser windows remained after end_session: {}",+ windows.raw+ );+ thread::sleep(Duration::from_millis(100));+ }+}++fn spawn_browser_command(+ driver: &mut McpDriver,+ spec: &BrowserSpec,+ profile: &Path,+ cdp_port: u16,+ url: &str,+ position: (i32, i32),+) {+ let mut command = command_for_browser(spec, profile, cdp_port, url, position);+ let child = spawn_in_job(&mut command).expect("launch standalone browser");+ eprintln!(+ "[standalone-browser] spawned {} pid={} profile={} cdp_port={cdp_port}",+ spec.name,+ child.id(),+ profile.display()+ );+ driver.reaper().push(child);+}++fn launch_browser(spec: &BrowserSpec, label: &str) -> BrowserFixture {+ launch_browser_with_html(spec, label, standalone_fixture_html())+}++fn launch_browser_with_html(spec: &BrowserSpec, label: &str, html: String) -> BrowserFixture {+ let mut driver = spawn_driver(label);+ let server = BrowserFixtureServer::start(&html);+ let profile = tempfile::Builder::new()+ .prefix("cua-e2e-browser-")+ .tempdir()+ .expect("create isolated browser profile");+ let cdp_port = allocate_loopback_port();+ let before = window_ids(&mut driver);+ spawn_browser_command(+ &mut driver,+ spec,+ profile.path(),+ cdp_port,+ "about:blank",+ TEST_BROWSER_INITIAL_POSITION,+ );+ navigate_initial_page(cdp_port, &server);+ let window = wait_for_fixture_window(&mut driver, &before, &server);+ let (pid, window_id) = window.unwrap_or_else(|| {+ panic!(+ "standalone browser fixture did not become visible after bounded URL handoff; journal={}",+ server.snapshot()+ )+ });+ driver.reaper().track_pid(pid);+ BrowserFixture {+ driver,+ server,+ _profile: profile,+ cdp_port,+ pid,+ window_id,+ }+}++fn launch_additional_window(fixture: &mut BrowserFixture) -> (BrowserFixtureServer, u32, u64) {+ let html = standalone_fixture_html();+ let server = BrowserFixtureServer::start(&html);+ let before = window_ids(&mut fixture.driver);+ let first_target = cdp_target_for_url(fixture.cdp_port, fixture.server.page_url());+ let first_window = harness_cdp_call(+ fixture.cdp_port,+ "Browser.getWindowForTarget",+ serde_json::json!({"targetId": first_target}),+ );+ let bounds = &first_window["bounds"];+ let created = harness_cdp_call(+ fixture.cdp_port,+ "Target.createTarget",+ serde_json::json!({+ "url": server.page_url(),+ "newWindow": true,+ "left": bounds["left"],+ "top": bounds["top"],+ "width": bounds["width"],+ "height": bounds["height"],+ }),+ );+ assert!(created["targetId"].is_string(), "{created}");+ let window = wait_for_fixture_window(&mut fixture.driver, &before, &server);+ let (pid, window_id) = window.expect("additional standalone browser window did not appear");+ assert_eq!(pid, fixture.pid, "additional window must share browser pid");+ (server, pid, window_id)+}++fn wait_for_text(server: &BrowserFixtureServer, id: &str, expected: &str) {+ let deadline = Instant::now() + Duration::from_secs(3);+ while server.text(id).as_deref() != Some(expected) && Instant::now() < deadline {+ thread::sleep(Duration::from_millis(50));+ }+ assert_eq!(server.text(id).as_deref(), Some(expected));+}++fn wait_for_value(server: &BrowserFixtureServer, id: &str, expected: &str) {+ let deadline = Instant::now() + Duration::from_secs(3);+ while server.value(id).as_deref() != Some(expected) && Instant::now() < deadline {+ thread::sleep(Duration::from_millis(50));+ }+ assert_eq!(server.value(id).as_deref(), Some(expected));+}++fn wait_for_observed(server: &BrowserFixtureServer, marker: &str) {+ let deadline = Instant::now() + Duration::from_secs(15);+ while !server.has_observed(marker) && Instant::now() < deadline {+ thread::sleep(Duration::from_millis(50));+ }+ assert!(+ server.has_observed(marker),+ "fixture never observed {marker:?}: {}",+ server.snapshot()+ );+}++fn ref_by_label(snapshot: &ToolResponse, fragment: &str) -> String {+ snapshot.structured()["refs"]+ .as_array()+ .and_then(|refs| {+ refs.iter().find(|entry| {+ entry["label"]+ .as_str()+ .is_some_and(|label| label.contains(fragment))+ })+ })+ .and_then(|entry| entry["ref"].as_str())+ .unwrap_or_else(|| panic!("missing browser ref {fragment:?}: {}", snapshot.raw))+ .to_owned()+}++fn ref_by_frame_label(snapshot: &ToolResponse, frame: &str, fragment: &str) -> String {+ snapshot.structured()["refs"]+ .as_array()+ .and_then(|refs| {+ refs.iter().find(|entry| {+ entry["frame"] == frame+ && entry["label"]+ .as_str()+ .is_some_and(|label| label.contains(fragment))+ })+ })+ .and_then(|entry| entry["ref"].as_str())+ .unwrap_or_else(|| panic!("missing {frame} browser ref {fragment:?}: {}", snapshot.raw))+ .to_owned()+}++fn bind(fixture: &mut BrowserFixture, session: &str) -> (String, String, ToolResponse) {+ let started = fixture+ .driver+ .call("start_session", serde_json::json!({ "session": session }));+ assert!(!started.is_error(), "start_session failed: {}", started.raw);+ let prepared = fixture.driver.call(+ "browser_prepare",+ serde_json::json!({ "pid": fixture.pid as i64, "session": session }),+ );+ assert_eq!(prepared.structured()["prepared"], true, "{}", prepared.raw);+ // A newly mapped Wayland toplevel can briefly appear with a protocol-local+ // id before the compositor publishes its stable pid/geometry identity.+ // Model the real client preamble: re-list windows and bind only the id the+ // driver can prove exactly. Refusals remain strict; fixture setup merely+ // waits for the launched browser to finish registering with the desktop.+ let (window_id, state) =+ wait_for_exact_browser_binding(&mut fixture.driver, fixture.pid, session)+ .expect("standalone browser did not expose an exactly bindable window");+ fixture.window_id = window_id;+ let target = state.structured()["target_id"]+ .as_str()+ .expect("target_id")+ .to_owned();+ let tab = state.structured()["tabs"]+ .as_array()+ .and_then(|tabs| tabs.iter().find(|tab| tab["active"] == true))+ .and_then(|tab| tab["tab_id"].as_str())+ .expect("active tab")+ .to_owned();+ let snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "session": session,+ }),+ );+ assert_eq!(snapshot.structured()["status"], "ok", "{}", snapshot.raw);+ (target, tab, snapshot)+}++fn case(browser: &str, action: &str) -> CaseSpec {+ let mut oracles = vec![+ OracleKind::FixtureState,+ OracleKind::Focus,+ OracleKind::ZOrder,+ OracleKind::NoLeakedInput,+ ];+ if cua_driver_testkit::e2e::DisplayServer::current()+ != cua_driver_testkit::e2e::DisplayServer::Wayland+ {+ oracles.push(OracleKind::Cursor);+ }+ CaseSpec::delivered(+ format!("{}-{browser}-standalone-{action}", std::env::consts::OS),+ browser,+ "standalone-chromium",+ action,+ Targeting::Page,+ Delivery::Background,+ Scope::Window,+ DriverRoute::Cdp,+ oracles,+ )+}++fn refusal_case(browser: &str, action: &str, code: RefusalCode) -> CaseSpec {+ case(browser, action).expecting_refusal(vec![code])+}++fn run_with_background_oracles(+ fixture: &mut BrowserFixture,+ action: impl FnOnce(&mut BrowserFixture) -> Observation,+) -> Observation {+ let sentinel = ForegroundSentinel::launch(&mut fixture.driver);+ let target = TargetWindow {+ pid: fixture.pid,+ native_id: fixture.window_id,+ };+ sentinel+ .assert_background_posture(target)+ .expect("establish standalone browser background posture");+ fixture.driver.start_behavior_recording();+ sentinel+ .prepare_background_observation(&mut fixture.driver, target)+ .expect("restore standalone browser background posture");+ let (mut observation, passed) = sentinel+ .observe_background(target, || action(fixture))+ .expect("observe standalone browser desktop effects");+ observation.passed_oracles.extend(passed);+ observation+}++fn run_roundtrip(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-roundtrip",+ std::env::consts::OS,+ spec.name+ );+ execute_case(case(&spec.name, "browser_tool_roundtrip"), |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-roundtrip-{}", fixture.pid);+ let (target, tab, snapshot) = bind(fixture, &session);+ let click_ref = ref_by_label(&snapshot, "id=btn-increment");+ let click = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": click_ref,+ "input_route": "dom_event",+ "session": session,+ }),+ );+ assert_eq!(click.structured()["status"], "ok", "{}", click.raw);+ wait_for_text(&fixture.server, "lbl-counter", "counter=1");++ let snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "session": session,+ }),+ );+ let input_ref = ref_by_label(&snapshot, "id=txt-input");+ let typed = fixture.driver.call(+ "browser_type",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": input_ref,+ "text": "standalone-browser",+ "session": session,+ }),+ );+ assert_eq!(typed.structured()["status"], "ok", "{}", typed.raw);+ wait_for_value(&fixture.server, "txt-input", "standalone-browser");++ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ });+}++fn run_background_type(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-background-type",+ std::env::consts::OS,+ spec.name+ );+ execute_case(case(&spec.name, "background_type"), |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-background-type-{}", fixture.pid);+ let (target, tab, snapshot) = bind(fixture, &session);+ let input_ref = ref_by_label(&snapshot, "id=txt-input");+ let typed = fixture.driver.call(+ "browser_type",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": input_ref,+ "text": "standalone-browser",+ "session": session,+ }),+ );+ assert_eq!(typed.structured()["status"], "ok", "{}", typed.raw);+ wait_for_value(&fixture.server, "txt-input", "standalone-browser");+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ });+}++fn run_trusted_click(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-trusted-click",+ std::env::consts::OS,+ spec.name+ );+ let case = if cfg!(any(target_os = "linux", target_os = "macos")) {+ refusal_case(+ &spec.name,+ "trusted_click",+ RefusalCode::BrowserInputTrustUnavailable,+ )+ } else {+ case(&spec.name, "trusted_click")+ };+ execute_case(case, |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-trusted-click-{}", fixture.pid);+ let (target, tab, snapshot) = bind(fixture, &session);+ let click_ref = ref_by_label(&snapshot, "id=btn-increment");+ let click = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": click_ref,+ "input_route": "trusted",+ "session": session,+ }),+ );+ if cfg!(any(target_os = "linux", target_os = "macos")) {+ assert_eq!(+ click.structured()["refusal"]["code"],+ "browser_input_trust_unavailable",+ "{}",+ click.raw+ );+ wait_for_text(&fixture.server, "lbl-counter", "counter=0");+ Observation::refused(+ RefusalCode::BrowserInputTrustUnavailable,+ vec![OracleKind::FixtureState],+ click.text(),+ Evidence::default(),+ )+ } else {+ assert_eq!(click.structured()["status"], "ok", "{}", click.raw);+ wait_for_text(&fixture.server, "lbl-counter", "counter=1");+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ }+ })+ });+}++fn run_prepare_isolated_launch(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-prepare-isolated",+ std::env::consts::OS,+ spec.name+ );+ execute_case(+ case(&spec.name, "browser_prepare_isolated_launch"),+ |evidence| {+ let source_server = BrowserFixtureServer::start(&standalone_fixture_html());+ let target_server = BrowserFixtureServer::start(&standalone_fixture_html());+ let source_profile = tempfile::Builder::new()+ .prefix("cua-e2e-user-browser-")+ .tempdir()+ .expect("create ordinary browser profile");+ let driver_profiles = driver_profile_root();+ let profiles_before = profile_entries(&driver_profiles);+ let mut driver = spawn_driver(&scenario);+ *evidence = recording_evidence(driver.recording_dir());++ let before = window_ids(&mut driver);+ let mut source_command = command_for_unprepared_browser(+ spec,+ source_profile.path(),+ source_server.page_url(),+ TEST_BROWSER_INITIAL_POSITION,+ );+ let source_child = spawn_in_job(&mut source_command).expect("launch ordinary browser");+ driver.reaper().push(source_child);+ let (source_pid, source_window_id) =+ wait_for_fixture_window(&mut driver, &before, &source_server)+ .expect("ordinary browser fixture window");+ driver.reaper().track_pid(source_pid);++ let session = format!("standalone-prepare-{source_pid}");+ let started = driver.call("start_session", serde_json::json!({ "session": session }));+ assert!(!started.is_error(), "start_session failed: {}", started.raw);+ driver.start_behavior_recording();+ let prepared = driver.call(+ "browser_prepare",+ serde_json::json!({+ "pid": source_pid as i64,+ "session": session,+ "allow_launch": true,+ "profile": {"mode": "isolated_new"},+ }),+ );+ assert_eq!(prepared.structured()["status"], "ok", "{}", prepared.raw);+ assert_eq!(+ prepared.structured()["action"],+ "launched_isolated_browser",+ "{}",+ prepared.raw+ );+ assert_eq!(+ prepared.structured()["side_effects"]["launched_browser"],+ true+ );+ assert_eq!(+ prepared.structured()["side_effects"]["created_profile"],+ true+ );+ let prepared_json = prepared.raw.to_string();+ assert!(+ !prepared_json.contains(&driver_profiles.display().to_string()),+ "browser_prepare disclosed its private profile path: {}",+ prepared.raw+ );+ assert!(+ !prepared_json.contains("approval_token"),+ "{}",+ prepared.raw+ );++ let prepared_pid = prepared.structured()["prepared_pid"]+ .as_u64()+ .expect("prepared browser pid") as u32;+ assert_ne!(prepared_pid, source_pid);+ let (prepared_window_id, state) =+ wait_for_exact_browser_binding(&mut driver, prepared_pid, &session)+ .expect("isolated browser did not expose an exactly bindable window");+ let target = state.structured()["target_id"]+ .as_str()+ .expect("prepared target id")+ .to_owned();+ let tab = state.structured()["tabs"]+ .as_array()+ .and_then(|tabs| tabs.iter().find(|tab| tab["active"] == true))+ .and_then(|tab| tab["tab_id"].as_str())+ .expect("prepared active tab")+ .to_owned();+ let navigated = driver.call(+ "browser_navigate",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "url": target_server.page_url(),+ "session": session,+ }),+ );+ assert_eq!(navigated.structured()["status"], "ok", "{}", navigated.raw);+ wait_for_observed(&target_server, "WEB_HARNESS_MARKER_v1");++ let target_window = TargetWindow {+ pid: prepared_pid,+ native_id: prepared_window_id,+ };+ let sentinel = ForegroundSentinel::launch(&mut driver);+ sentinel+ .assert_background_posture(target_window)+ .expect("establish isolated browser background posture");+ sentinel+ .prepare_background_observation(&mut driver, target_window)+ .expect("restore isolated browser background posture");+ let (mut observation, passed) = sentinel+ .observe_background(target_window, || {+ let snapshot = driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "session": session,+ }),+ );+ let click_ref = ref_by_label(&snapshot, "id=btn-increment");+ let clicked = driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": click_ref,+ "input_route": "dom_event",+ "session": session,+ }),+ );+ assert_eq!(clicked.structured()["status"], "ok", "{}", clicked.raw);+ wait_for_text(&target_server, "lbl-counter", "counter=1");+ wait_for_text(&source_server, "lbl-counter", "counter=0");+ let source_windows =+ driver.call("list_windows", serde_json::json!({"pid": source_pid}));+ assert!(+ source_windows.structured()["windows"]+ .as_array()+ .is_some_and(|windows| windows.iter().any(|window| {+ window["window_id"].as_u64() == Some(source_window_id)+ })),+ "ordinary browser was modified or terminated: {}",+ source_windows.raw+ );+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ .expect("observe isolated browser desktop effects");+ observation.passed_oracles.extend(passed);++ let ended = driver.call("end_session", serde_json::json!({ "session": session }));+ assert!(!ended.is_error(), "end_session failed: {}", ended.raw);+ wait_for_pid_windows_to_close(&mut driver, prepared_pid);+ let profile_deadline = Instant::now() + Duration::from_secs(5);+ loop {+ if profile_entries(&driver_profiles) == profiles_before {+ break;+ }+ assert!(+ Instant::now() < profile_deadline,+ "isolated_new profile remained after end_session"+ );+ thread::sleep(Duration::from_millis(100));+ }+ observation+ },+ );+}++fn run_stale_ref(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-stale-ref",+ std::env::consts::OS,+ spec.name+ );+ execute_case(case(&spec.name, "browser_ref_stale"), |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-stale-ref-{}", fixture.pid);+ let (target, tab, first) = bind(fixture, &session);+ let stale_ref = ref_by_label(&first, "id=btn-increment");+ let newer = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "session": session,+ }),+ );+ assert_eq!(newer.structured()["status"], "ok", "{}", newer.raw);+ let refused = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": stale_ref,+ "input_route": "dom_event",+ "session": session,+ }),+ );+ assert_eq!(+ refused.structured()["refusal"]["code"],+ "browser_ref_stale",+ "{}",+ refused.raw+ );+ wait_for_text(&fixture.server, "lbl-counter", "counter=0");+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ });+}++fn run_frame_roundtrip(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-frame-roundtrip",+ std::env::consts::OS,+ spec.name+ );+ let child_server = BrowserFixtureServer::start(FIXTURE_HTML);+ let child_url = child_server.page_url_on_host("localhost");+ execute_case(case(&spec.name, "browser_frame_roundtrip"), |evidence| {+ let html = standalone_frame_fixture_html(&child_url);+ let mut fixture = launch_browser_with_html(spec, &scenario, html);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ wait_for_text(&fixture.server, "standalone-shadow-state", "shadow=ready");+ wait_for_text(&fixture.server, "standalone-frame-state", "iframe=ready");+ wait_for_observed(&child_server, "WEB_HARNESS_MARKER_v1");++ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-frame-roundtrip-{}", fixture.pid);+ let (target, tab, snapshot) = bind(fixture, &session);+ assert_eq!(+ snapshot.structured()["oopif"]["status"],+ "attached",+ "real Chromium did not expose a capability-tested OOPIF: {}",+ snapshot.raw+ );++ let shadow_button = ref_by_frame_label(&snapshot, "main", "standalone-shadow-button");+ let shadow_input = ref_by_frame_label(&snapshot, "main", "standalone-shadow-input");+ let frame_button = ref_by_frame_label(&snapshot, "iframe", "standalone-frame-button");+ let frame_input = ref_by_frame_label(&snapshot, "iframe", "standalone-frame-input");+ let oopif_button = ref_by_frame_label(&snapshot, "oopif", "id=btn-increment");+ let oopif_input = ref_by_frame_label(&snapshot, "oopif", "id=txt-input");++ for reference in [&shadow_button, &frame_button, &oopif_button] {+ let clicked = fixture.driver.call(+ "browser_click",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": reference,+ "input_route": "dom_event",+ "session": session,+ }),+ );+ assert_eq!(clicked.structured()["status"], "ok", "{}", clicked.raw);+ }+ wait_for_text(&fixture.server, "standalone-shadow-state", "shadow=clicked");+ wait_for_text(&fixture.server, "standalone-frame-state", "iframe=clicked");+ wait_for_text(&child_server, "lbl-counter", "counter=1");++ for (reference, text) in [+ (&shadow_input, "shadow-route"),+ (&frame_input, "iframe-route"),+ (&oopif_input, "oopif-route"),+ ] {+ let typed = fixture.driver.call(+ "browser_type",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": reference,+ "text": text,+ "session": session,+ }),+ );+ assert_eq!(typed.structured()["status"], "ok", "{}", typed.raw);+ }+ wait_for_text(+ &fixture.server,+ "standalone-shadow-state",+ "shadow=typed:shadow-route",+ );+ wait_for_text(+ &fixture.server,+ "standalone-frame-state",+ "iframe=typed:iframe-route",+ );+ wait_for_value(&child_server, "txt-input", "oopif-route");++ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ });+}++fn run_multi_tab(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-multi-tab",+ std::env::consts::OS,+ spec.name+ );+ execute_case(case(&spec.name, "multi_tab_exact_binding"), |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ let session = format!("standalone-multi-tab-{}", fixture.pid);+ let _ = bind(&mut fixture, &session);+ let created = harness_cdp_call(+ fixture.cdp_port,+ "Target.createTarget",+ serde_json::json!({+ "url": format!("{}?tab=second", fixture.server.page_url()),+ "newWindow": false,+ }),+ );+ assert!(created["targetId"].is_string(), "{created}");+ wait_for_observed(&fixture.server, "new_tab=open");++ run_with_background_oracles(&mut fixture, |fixture| {+ let deadline = Instant::now() + Duration::from_secs(5);+ let rebound = loop {+ let state = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "window_id": fixture.window_id,+ "session": session,+ }),+ );+ if state.structured()["status"] == "ok"+ && state.structured()["tabs"]+ .as_array()+ .is_some_and(|tabs| tabs.len() >= 2)+ {+ break state;+ }+ assert!(+ Instant::now() < deadline,+ "multi-tab bind did not enumerate both tabs: {}",+ state.raw+ );+ thread::sleep(Duration::from_millis(100));+ };+ assert_eq!(rebound.structured()["binding_quality"], "exact");+ Observation::delivered(vec![OracleKind::FixtureState], Evidence::default())+ })+ });+}++fn run_two_window_collision(spec: &BrowserSpec) {+ let scenario = format!(+ "{}-{}-standalone-two-window",+ std::env::consts::OS,+ spec.name+ );+ execute_case(+ refusal_case(+ &spec.name,+ "same_bounds_binding_ambiguous",+ RefusalCode::BrowserBindingAmbiguous,+ ),+ |evidence| {+ let mut fixture = launch_browser(spec, &scenario);+ *evidence = recording_evidence(fixture.driver.recording_dir());+ let (second_server, second_pid, second_window_id) =+ launch_additional_window(&mut fixture);+ assert_eq!(second_pid, fixture.pid);+ assert_ne!(second_window_id, fixture.window_id);+ run_with_background_oracles(&mut fixture, |fixture| {+ let session = format!("standalone-two-window-{}", fixture.pid);+ let started = fixture+ .driver+ .call("start_session", serde_json::json!({ "session": session }));+ assert!(!started.is_error(), "start_session failed: {}", started.raw);+ let prepared = fixture.driver.call(+ "browser_prepare",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "session": session,+ }),+ );+ assert_eq!(prepared.structured()["prepared"], true, "{}", prepared.raw);+ let refused = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "pid": fixture.pid as i64,+ "window_id": fixture.window_id,+ "session": session,+ }),+ );+ assert_eq!(+ refused.structured()["refusal"]["code"],+ "browser_binding_ambiguous",+ "{}",+ refused.raw+ );+ wait_for_text(&fixture.server, "lbl-counter", "counter=0");+ wait_for_text(&second_server, "lbl-counter", "counter=0");+ Observation::refused(+ RefusalCode::BrowserBindingAmbiguous,+ vec![OracleKind::FixtureState],+ refused.text(),+ Evidence::default(),+ )+ })+ },+ );+}++fn settle_between_browser_rows() {+ #[cfg(target_os = "macos")]+ thread::sleep(Duration::from_secs(2));+}++fn run_browser_scenario(run: fn(&BrowserSpec)) {+ let _guard = STANDALONE_BROWSER_TEST_LOCK+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner());+ write_environment_from_env(&EnvironmentRecord::ready(Duration::ZERO))+ .expect("write standalone-browser environment evidence");+ let specs = browser_specs();+ if specs.is_empty() {+ if std::env::var_os("CUA_TEST_REQUIRE_EXTERNAL_BROWSERS").is_some() {+ panic!("no standalone Chrome, Edge, or Chromium executable was found");+ }+ eprintln!("no standalone Chromium browser installed; optional suite skipped");+ return;+ }+ let mut failed_browsers = Vec::new();+ for spec in specs {+ eprintln!(+ "[standalone-browser] {} at {}",+ spec.name,+ spec.executable.display()+ );+ if catch_unwind(AssertUnwindSafe(|| run(&spec))).is_err() {+ failed_browsers.push(spec.name.clone());+ }+ settle_between_browser_rows();+ }+ assert!(+ failed_browsers.is_empty(),+ "standalone browser scenario failed for: {}",+ failed_browsers.join(", ")+ );+}++macro_rules! standalone_browser_test {+ ($name:ident, $run:ident) => {+ #[test]+ #[ignore = "requires an installed standalone Chromium browser and an interactive desktop"]+ fn $name() {+ run_browser_scenario($run);+ }+ };+}++standalone_browser_test!(standalone_browser_roundtrip, run_roundtrip);+standalone_browser_test!(standalone_browser_background_type, run_background_type);+standalone_browser_test!(standalone_browser_trusted_click, run_trusted_click);+standalone_browser_test!(+ standalone_browser_prepare_isolated,+ run_prepare_isolated_launch+);+standalone_browser_test!(standalone_browser_stale_ref, run_stale_ref);+standalone_browser_test!(standalone_browser_frames, run_frame_roundtrip);+standalone_browser_test!(standalone_browser_multi_tab, run_multi_tab);+standalone_browser_test!(+ standalone_browser_window_collision,+ run_two_window_collision+);diff --git a/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs b/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rsnew file mode 100644index 0000000000..6b4b32bef5--- /dev/null+++ b/libs/cua-driver/rust/crates/platform-linux/src/browser_platform.rs@@ -0,0 +1,494 @@+//! Linux identity and endpoint evidence for the first-class browser tools.++use std::collections::HashSet;+use std::time::Duration;++use async_trait::async_trait;+use cua_driver_core::browser::platform::{+ BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,+};+use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};+use cua_driver_core::browser::types::{+ BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,+ NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,+ ProcessFingerprint, Rect,+};+use tokio::io::{AsyncReadExt, AsyncWriteExt};++#[derive(Debug, Default)]+pub struct LinuxBrowserPlatform;++fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(code, message)+}++fn is_chromium(name: &str) -> bool {+ let name = name.to_ascii_lowercase();+ let products = [+ "chrome", "chromium", "electron", "brave", "edge", "msedge", "vivaldi", "opera", "arc",+ "thorium", "iridium", "yandex",+ ];+ name.split(|ch: char| !ch.is_ascii_alphanumeric())+ .any(|token| products.contains(&token))+}++fn is_firefox(name: &str) -> bool {+ name.to_ascii_lowercase().split_whitespace().any(|word| {+ word.rsplit(['/', '\\'])+ .next()+ .unwrap_or(word)+ .trim_end_matches(".exe")+ == "firefox"+ })+}++fn loopback_websocket_port(url: &str) -> Option<u16> {+ ["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]+ .iter()+ .find_map(|prefix| {+ url.strip_prefix(prefix)?+ .split('/')+ .next()?+ .parse::<u16>()+ .ok()+ })+}++fn parse_proc_net_loopback_listeners(text: &str) -> Vec<(u16, u64)> {+ text.lines()+ .skip(1)+ .filter_map(|line| {+ let fields = line.split_whitespace().collect::<Vec<_>>();+ if fields.len() < 10 || fields[3] != "0A" {+ return None;+ }+ let (address, port) = fields[1].split_once(':')?;+ let loopback = address == "0100007F" || address == "00000000000000000000000001000000";+ if !loopback {+ return None;+ }+ Some((+ u16::from_str_radix(port, 16).ok()?,+ fields[9].parse::<u64>().ok()?,+ ))+ })+ .collect()+}++fn socket_inodes_for_pid(pid: i64) -> Result<HashSet<u64>, BrowserRefusal> {+ let directory = std::fs::read_dir(format!("/proc/{pid}/fd")).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ )+ })?;+ Ok(directory+ .flatten()+ .filter_map(|entry| std::fs::read_link(entry.path()).ok())+ .filter_map(|target| {+ let target = target.to_string_lossy();+ target+ .strip_prefix("socket:[")+ .and_then(|value| value.strip_suffix(']'))+ .and_then(|value| value.parse::<u64>().ok())+ })+ .collect())+}++fn loopback_ports_for_pid(pid: i64) -> Result<Vec<u16>, BrowserRefusal> {+ let owned = socket_inodes_for_pid(pid)?;+ let mut listeners = Vec::new();+ for path in ["/proc/net/tcp", "/proc/net/tcp6"] {+ if let Ok(text) = std::fs::read_to_string(path) {+ listeners.extend(+ parse_proc_net_loopback_listeners(&text)+ .into_iter()+ .filter(|(_, inode)| owned.contains(inode))+ .map(|(port, _)| port),+ );+ }+ }+ listeners.sort_unstable();+ listeners.dedup();+ Ok(listeners)+}++fn process_identity(pid: i64) -> Result<(u64, Option<String>), BrowserRefusal> {+ let stat = std::fs::read_to_string(format!("/proc/{pid}/stat")).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ )+ })?;+ let tail = stat+ .rsplit_once(')')+ .map(|(_, tail)| tail.trim())+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not parse process identity for pid {pid}"),+ )+ })?;+ let started = tail+ .split_whitespace()+ .nth(19)+ .and_then(|value| value.parse::<u64>().ok())+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not parse process start time for pid {pid}"),+ )+ })?;+ let executable = std::fs::read_link(format!("/proc/{pid}/exe"))+ .ok()+ .map(|path| path.to_string_lossy().into_owned());+ Ok((started, executable))+}++async fn browser_websocket_url(port: u16) -> Option<String> {+ tokio::time::timeout(Duration::from_secs(2), async move {+ let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))+ .await+ .ok()?;+ let request = format!(+ "GET /json/version HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"+ );+ stream.write_all(request.as_bytes()).await.ok()?;+ let mut bytes = Vec::new();+ let mut chunk = [0u8; 4096];+ loop {+ let read = stream.read(&mut chunk).await.ok()?;+ if read == 0 {+ break;+ }+ bytes.extend_from_slice(&chunk[..read]);+ if bytes.len() > 256 * 1024 {+ return None;+ }+ if let Some(header_end) = bytes.windows(4).position(|part| part == b"\r\n\r\n") {+ let headers = String::from_utf8_lossy(&bytes[..header_end]);+ if let Some(length) = headers.lines().find_map(|line| {+ let (name, value) = line.split_once(':')?;+ name.eq_ignore_ascii_case("content-length")+ .then(|| value.trim().parse::<usize>().ok())+ .flatten()+ }) {+ if bytes.len() >= header_end + 4 + length {+ break;+ }+ }+ }+ }+ let body_start = bytes.windows(4).position(|part| part == b"\r\n\r\n")? + 4;+ let value: serde_json::Value = serde_json::from_slice(&bytes[body_start..]).ok()?;+ let url = value.get("webSocketDebuggerUrl")?.as_str()?.to_owned();+ (loopback_websocket_port(&url) == Some(port)).then_some(url)+ })+ .await+ .ok()+ .flatten()+}++#[async_trait]+impl BrowserPlatform for LinuxBrowserPlatform {+ fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {+ Some("Chromium's trusted CDP Input route activates its standalone browser window on Linux")+ }++ async fn classify_browser(&self, pid: i64) -> Result<BrowserClassification, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Linux process-id range"),+ )+ })?;+ let process = tokio::task::spawn_blocking(move || {+ crate::proc_fs::list_processes()+ .into_iter()+ .find(|process| process.pid == pid_u32)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ )+ })?;+ let identity = format!("{} {}", process.name, process.cmdline);+ let chromium = is_chromium(&identity);+ let gecko = is_firefox(&identity);+ Ok(BrowserClassification {+ is_browser: chromium || gecko,+ engine: if chromium {+ BrowserEngineFamily::Chromium+ } else if gecko {+ BrowserEngineFamily::Gecko+ } else {+ BrowserEngineFamily::Unknown+ },+ product: Some(process.name),+ channel: None,+ supports_cdp: chromium,+ })+ }++ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Linux process-id range"),+ )+ })?;+ if std::env::var_os("WAYLAND_DISPLAY").is_some() {+ if let Some(window) = crate::wayland::sway_ipc::window_for_id(window_id) {+ if window.pid != pid_u32 {+ return Err(refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("Sway window {window_id} is not owned by pid {pid}"),+ ));+ }+ return Ok(NativeWindowInfo {+ pid,+ window_id,+ title: window.title,+ bounds: Rect::new(+ f64::from(window.x),+ f64::from(window.y),+ f64::from(window.width),+ f64::from(window.height),+ ),+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: pid,+ detail: Some("Sway IPC pid and rect".to_owned()),+ },+ });+ }+ let window = tokio::task::spawn_blocking(move || {+ crate::wayland::list_windows_dispatch(Some(pid_u32))+ .into_iter()+ .find(|window| window.xid == window_id)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ "the active Wayland compositor cannot prove this window's pid and geometry",+ )+ })?;+ return Ok(NativeWindowInfo {+ pid,+ window_id,+ title: window.title,+ bounds: Rect::new(+ f64::from(window.x),+ f64::from(window.y),+ f64::from(window.width),+ f64::from(window.height),+ ),+ geometry_exact: false,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::PlatformAttested,+ owner_pid: pid,+ detail: Some(+ "Wayland shell/AT-SPI metadata; geometry may be unavailable, so core permits read-only heuristic binding only"+ .to_owned(),+ ),+ },+ });+ }++ let window = tokio::task::spawn_blocking(move || {+ crate::x11::list_windows(Some(pid_u32))+ .into_iter()+ .find(|window| window.xid == window_id)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("X11 window {window_id} is not owned by pid {pid}"),+ )+ })?;+ Ok(NativeWindowInfo {+ pid,+ window_id,+ title: window.title,+ bounds: Rect::new(+ f64::from(window.x),+ f64::from(window.y),+ f64::from(window.width),+ f64::from(window.height),+ ),+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::PlatformAttested,+ owner_pid: pid,+ detail: Some(+ "X11 _NET_WM_PID corroborated independently by the owned endpoint pid"+ .to_owned(),+ ),+ },+ })+ }++ async fn is_only_exact_native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Linux process-id range"),+ )+ })?;+ if std::env::var_os("WAYLAND_DISPLAY").is_some() {+ let Some(windows) = crate::wayland::sway_ipc::list_windows() else {+ return Ok(None);+ };+ let owned = windows+ .into_iter()+ .filter(|window| window.pid == pid_u32)+ .map(|window| window.id)+ .collect::<Vec<_>>();+ return Ok(Some(owned.len() == 1 && owned[0] == window_id));+ }+ let owned = tokio::task::spawn_blocking(move || {+ crate::x11::list_windows(Some(pid_u32))+ .into_iter()+ .map(|window| u64::from(window.xid))+ .collect::<Vec<_>>()+ })+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not enumerate X11 browser windows: {error}"),+ )+ })?;+ Ok(Some(owned.len() == 1 && owned[0] == window_id))+ }++ async fn discover_owned_endpoint(+ &self,+ pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {+ let ports = tokio::task::spawn_blocking(move || loopback_ports_for_pid(pid))+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("listener inspection task failed: {error}"),+ )+ })??;+ for port in ports {+ if let Some(ws_url) = browser_websocket_url(port).await {+ return Ok(Some(OwnedEndpoint {+ ws_url,+ http_port: Some(port),+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::ListeningSocketPid,+ owner_pid: pid,+ detail: Some("/proc socket inode owner".to_owned()),+ },+ }));+ }+ }+ Ok(None)+ }++ async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {+ let (start_time, executable) = tokio::task::spawn_blocking(move || process_identity(pid))+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("process fingerprint task failed: {error}"),+ )+ })??;+ Ok(ProcessFingerprint {+ pid,+ start_time: Some(start_time),+ executable,+ })+ }++ async fn prepare_endpoint(+ &self,+ request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ if let Some(endpoint) = self.discover_owned_endpoint(request.pid).await? {+ return Ok(PrepareOutcome {+ action: PrepareAction::AlreadyPrepared,+ prepared_pid: Some(endpoint.ownership.owner_pid),+ endpoint: Some(endpoint),+ message: "An owned loopback DevTools endpoint is already available.".to_owned(),+ side_effects: Default::default(),+ });+ }+ Err(refusal(+ BrowserRefusalCode::BrowserRequiresSetup,+ "No owned endpoint is available. Acting setup is handled by shared core only for a verified driver-owned isolated profile.",+ ))+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn proc_net_parser_returns_only_loopback_listeners() {+ let input = " sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode\n\+ 0: 0100007F:2406 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 12345\n\+ 1: 00000000:2475 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1000 0 67890\n";+ assert_eq!(+ parse_proc_net_loopback_listeners(input),+ vec![(9222, 12345)]+ );+ }++ #[test]+ fn classifier_covers_embedded_and_standalone_chromium() {+ assert!(is_chromium("CuaTestHarness.Electron"));+ assert!(is_chromium("chromium-browser"));+ assert!(is_chromium("msedge --remote-debugging-port=9222"));+ assert!(is_chromium("/opt/microsoft/msedge/msedge"));+ assert!(!is_chromium("firefox"));+ assert!(!is_chromium("search-worker"));+ assert!(!is_chromium("ledger-service"));+ }++ #[test]+ fn firefox_classifier_uses_product_tokens() {+ assert!(is_firefox("firefox --new-instance"));+ assert!(is_firefox("Mozilla Firefox"));+ assert!(!is_firefox("firefox-helper"));+ assert!(!is_firefox("waterfox"));+ }++ #[test]+ fn websocket_url_must_keep_the_attested_listener_port() {+ assert_eq!(+ loopback_websocket_port("ws://localhost:9222/devtools/browser/id"),+ Some(9222)+ );+ assert_ne!(+ loopback_websocket_port("ws://[::1]:9333/devtools/browser/foreign"),+ Some(9222)+ );+ assert_eq!(loopback_websocket_port("ws://0.0.0.0:9222/devtools"), None);+ }+}diff --git a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs b/libs/cua-driver/rust/crates/platform-linux/src/lib.rsindex c4ca6749b2..7482074e98 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs@@ -29,6 +29,9 @@ pub mod tty;#[cfg(target_os = "linux")]pub mod proc_fs;+#[cfg(target_os = "linux")]+pub mod browser_platform;+#[cfg(target_os = "linux")]pub mod installed_apps;diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex bb39c92c0f..e325f4f484 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs@@ -825,6 +825,11 @@ impl Tool for GetWindowStateTool {pub struct LaunchAppTool;static LAUNCH_DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();+fn contains_remote_debugging_flag(value: &str) -> bool {+ let lower = value.to_ascii_lowercase();+ lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")+}+#[async_trait]impl Tool for LaunchAppTool {fn def(&self) -> &ToolDef {@@ -838,7 +843,8 @@ impl Tool for LaunchAppTool {"launch_path":{"type":"string","description":"Round-trip the `launch_path` returned by `list_apps` — the Exec= command from the .desktop file with XDG field codes already stripped. Highest precedence on Linux; spawned directly via the system shell."},"name":{"type":"string","description":"App name or command to launch."},"bundle_id":{"type":"string","description":"Ignored on Linux (macOS/Windows concept)."},- "urls":{"type":"array","items":{"type":"string"},"description":"URLs to open via xdg-open."}+ "urls":{"type":"array","items":{"type":"string"},"description":"URLs to open via xdg-open."},+ "additional_arguments":{"type":"array","items":{"type":"string"},"description":"Extra command-line arguments passed to the launched process."}},"additionalProperties":false}),read_only: false, destructive: false, idempotent: false, open_world: true,})@@ -849,6 +855,23 @@ impl Tool for LaunchAppTool {let launch_path_opt = args.opt_str("launch_path");let name_opt = args.opt_str("name");let urls: Vec<String> = args.str_array("urls");+ let additional_arguments: Vec<String> = args.str_array("additional_arguments");+ if args.get("cdp_debugging_port").is_some() {+ return ToolResult::error(+ "cdp_debugging_port moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }+ if launch_path_opt+ .as_deref()+ .into_iter()+ .chain(name_opt.as_deref())+ .chain(additional_arguments.iter().map(String::as_str))+ .any(contains_remote_debugging_flag)+ {+ return ToolResult::error(+ "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }if launch_path_opt.is_none() && name_opt.is_none() && urls.is_empty() {return ToolResult::error("Provide at least one of: launch_path, name, or urls.");@@ -874,7 +897,8 @@ impl Tool for LaunchAppTool {if let Some(cmd) = command {let mut parts = cmd.split_whitespace();let prog = parts.next().unwrap_or(cmd);- let rest: Vec<&str> = parts.collect();+ let mut rest: Vec<String> = parts.map(str::to_owned).collect();+ rest.extend(additional_arguments);let mut launch = std::process::Command::new(prog);launch.args(&rest)@@ -885,7 +909,9 @@ impl Tool for LaunchAppTool {.env("ACCESSIBILITY_ENABLED", "1").env("NO_AT_BRIDGE", "0");if chromium_family_program(prog)- && !rest.iter().any(|arg| *arg == "--force-renderer-accessibility")+ && !rest+ .iter()+ .any(|arg| arg == "--force-renderer-accessibility"){launch.arg("--force-renderer-accessibility");}@@ -919,8 +945,8 @@ impl Tool for LaunchAppTool {Ok(Ok((message, pid_opt, name))) => {if let Some(pid) = pid_opt {let windows = tokio::task::spawn_blocking(move || {- let deadline = std::time::Instant::now()- + std::time::Duration::from_secs(3);+ let deadline =+ std::time::Instant::now() + std::time::Duration::from_secs(3);loop {let windows = crate::wayland::list_windows_dispatch(Some(pid));if !windows.is_empty() || std::time::Instant::now() >= deadline {@@ -1004,7 +1030,7 @@ fn resolve_element_local_coords(if crate::wayland::wayland_input_enabled() {let (window_x, window_y, window_width, window_height) =crate::wayland::window_geometry(xid)- .ok_or_else(|| anyhow::anyhow!("No Wayland geometry for window {xid}"))?;+ .ok_or_else(|| anyhow::anyhow!("No Wayland geometry for window {xid}"))?;if window_width == 0 || window_height == 0 {anyhow::bail!("Wayland window {xid} has no usable geometry");}@@ -1299,25 +1325,25 @@ fn unavailable_webkit_keyboard_background(pid: u32,delivery: crate::input::delivery::DeliveryMode,) -> Option<ToolResult> {- (!delivery.is_foreground()- && is_webkitgtk_embedder(pid)- && !crate::wayland::is_inject_mode())- .then(|| {- crate::input::delivery::background_unavailable_error(- crate::input::delivery::BackgroundUnavailable::FocusedInputOnly,- )- })+ (!delivery.is_foreground() && is_webkitgtk_embedder(pid) && !crate::wayland::is_inject_mode())+ .then(|| {+ crate::input::delivery::background_unavailable_error(+ crate::input::delivery::BackgroundUnavailable::FocusedInputOnly,+ )+ })}fn unavailable_gtk_keyboard_background(pid: u32,delivery: crate::input::delivery::DeliveryMode,) -> Option<ToolResult> {- (!delivery.is_foreground() && is_gtk_process(pid) && !crate::wayland::is_inject_mode()).then(|| {- crate::input::delivery::background_unavailable_error(- crate::input::delivery::BackgroundUnavailable::FocusedInputOnly,- )- })+ (!delivery.is_foreground() && is_gtk_process(pid) && !crate::wayland::is_inject_mode()).then(+ || {+ crate::input::delivery::background_unavailable_error(+ crate::input::delivery::BackgroundUnavailable::FocusedInputOnly,+ )+ },+ )}fn unavailable_gtk_pointer_background(@@ -2010,12 +2036,7 @@ impl Tool for ClickTool {// `get_window_state`. Miss → fall through to the injection paths.if !delivery.is_foreground() && button == 1 && count == 1 {if let Ok(Some(_)) =- crate::atspi::perform_action_at_screen_point(- pid,- xid,- output_x,- output_y,- )+ crate::atspi::perform_action_at_screen_point(pid, xid, output_x, output_y){return Ok("wayland_atspi");}@@ -2158,10 +2179,8 @@ async fn focus_nested_inject_target(pixel: Option<(f64, f64)>,) -> Result<(), ToolResult> {if let Some(index) = element_index {- return match tokio::task::spawn_blocking(move || {- crate::atspi::focus_element(pid, index)- })- .await+ return match tokio::task::spawn_blocking(move || crate::atspi::focus_element(pid, index))+ .await{Ok(Ok(true)) => Ok(()),Ok(Ok(false)) => Err(ToolResult::error(format!(@@ -2312,13 +2331,8 @@ impl Tool for TypeTextTool {// directly. Establish widget-local focus first, without changing the// compositor's focused toplevel, so keys reach the addressed control.if crate::wayland::is_inject_mode() {- if let Err(error) = focus_nested_inject_target(- pid,- xid,- resolved_elem_idx,- px.zip(py),- )- .await+ if let Err(error) =+ focus_nested_inject_target(pid, xid, resolved_elem_idx, px.zip(py)).await{return error;}@@ -2330,7 +2344,11 @@ impl Tool for TypeTextTool {Ok(Ok(())) => ToolResult::text(format!("Typed {text_len} character(s) (focus-free via cua-compositor)."))- .with_structured(type_text_structured("key_events", text_len, false)),+ .with_structured(type_text_structured(+ "key_events",+ text_len,+ false,+ )),Ok(Err(e)) => ToolResult::error(e.to_string()),Err(e) => ToolResult::error(format!("Task error: {e}")),};@@ -2380,10 +2398,9 @@ impl Tool for TypeTextTool {&& (is_chromium_embedder(pid) || is_webkitgtk_embedder(pid)){if let Some(idx) = resolved_elem_idx {- let focused = tokio::task::spawn_blocking(move || {- crate::atspi::focus_element(pid, idx)- })- .await;+ let focused =+ tokio::task::spawn_blocking(move || crate::atspi::focus_element(pid, idx))+ .await;match focused {Ok(Ok(true)) => {}Ok(Ok(false)) => {@@ -2396,10 +2413,9 @@ impl Tool for TypeTextTool {}let text_w = text.clone();- let result = tokio::task::spawn_blocking(move || {- crate::wayland::type_text(xid, &text_w)- })- .await;+ let result =+ tokio::task::spawn_blocking(move || crate::wayland::type_text(xid, &text_w))+ .await;return match result {Ok(Ok(())) => ToolResult::text(format!("Typed {text_len} character(s) (via Wayland virtual-keyboard)."@@ -2858,10 +2874,8 @@ impl Tool for PressKeyTool {}let result = if mods.is_empty() {let key_w = key.clone();- tokio::task::spawn_blocking(move || {- crate::wayland::inject_press_key(xid, &key_w)- })- .await+ tokio::task::spawn_blocking(move || crate::wayland::inject_press_key(xid, &key_w))+ .await} else {let mut chord = mods.clone();chord.push(key.clone());@@ -3045,10 +3059,9 @@ impl Tool for HotkeyTool {Err(error) => return error,};let resolved_element_index = match &resolved {- cua_driver_core::element_token::ResolvedElement::Element {- element_index,- ..- } => Some(*element_index),+ cua_driver_core::element_token::ResolvedElement::Element { element_index, .. } => {+ Some(*element_index)+ }cua_driver_core::element_token::ResolvedElement::None => None,};let xid_opt = match &resolved {@@ -3135,10 +3148,9 @@ impl Tool for HotkeyTool {}let mut chord = mods.clone();chord.push(key.clone());- let result = tokio::task::spawn_blocking(move || {- crate::wayland::inject_hotkey(xid, &chord)- })- .await;+ let result =+ tokio::task::spawn_blocking(move || crate::wayland::inject_hotkey(xid, &chord))+ .await;return match result {Ok(Ok(())) => ToolResult::text(format!("Pressed hotkey '{key_display}' (focus-free via cua-compositor)."@@ -3502,13 +3514,7 @@ impl Tool for ScrollTool {};let direction_for_inject = direction.clone();let result = tokio::task::spawn_blocking(move || {- crate::wayland::inject_scroll(- xid,- x,- y,- &direction_for_inject,- amount as u32,- )+ crate::wayland::inject_scroll(xid, x, y, &direction_for_inject, amount as u32)}).await;return match result {@@ -3535,8 +3541,7 @@ impl Tool for ScrollTool {(None,cua_driver_core::element_token::ResolvedElement::Element {- element_index,- ..+ element_index, ..},) => {let idx = *element_index;@@ -3564,12 +3569,7 @@ impl Tool for ScrollTool {crate::wayland::window_local_to_output(xid, x.round() as i32, y.round() as i32)});let result = tokio::task::spawn_blocking(move || {- crate::wayland::scroll_at(- xid,- output_point,- &direction_for_wayland,- amount as u32,- )+ crate::wayland::scroll_at(xid, output_point, &direction_for_wayland, amount as u32)}).await;return match result {@@ -3789,10 +3789,9 @@ impl Tool for DoubleClickTool {cua_driver_core::element_token::ResolvedElement::None => None,};let window_id_resolved: Option<u64> = match &resolved {- cua_driver_core::element_token::ResolvedElement::Element { window_id, .. } => {- args.opt_u64("window_id")- .or_else(|| window_id.map(|v| v as u64))- }+ cua_driver_core::element_token::ResolvedElement::Element { window_id, .. } => args+ .opt_u64("window_id")+ .or_else(|| window_id.map(|v| v as u64)),cua_driver_core::element_token::ResolvedElement::None => args.opt_u64("window_id"),};if let Some(idx) = elem_idx_resolved {@@ -4022,10 +4021,9 @@ impl Tool for RightClickTool {cua_driver_core::element_token::ResolvedElement::None => None,};let window_id_resolved: Option<u64> = match &resolved {- cua_driver_core::element_token::ResolvedElement::Element { window_id, .. } => {- args.opt_u64("window_id")- .or_else(|| window_id.map(|v| v as u64))- }+ cua_driver_core::element_token::ResolvedElement::Element { window_id, .. } => args+ .opt_u64("window_id")+ .or_else(|| window_id.map(|v| v as u64)),cua_driver_core::element_token::ResolvedElement::None => args.opt_u64("window_id"),};if let Some(idx) = elem_idx_resolved {@@ -6171,6 +6169,7 @@ impl Tool for GetConfigTool {let (pip_enabled, pip_geometry) = pip_preview::read_pip_keys_from_file();ToolResult::text("cua-driver-rs configuration").with_structured(json!({"version": env!("CARGO_PKG_VERSION"),+ "source_sha": option_env!("CUA_DRIVER_SOURCE_SHA"),"platform": "linux","capture_mode": cfg.capture_mode,"capture_scope": cfg.capture_scope,@@ -6723,14 +6722,14 @@ impl Tool for BringToFrontTool {}).await;return match result {- Ok(Ok(())) => ToolResult::text(format!(- "Brought Wayland window {window_id} to front."- ))- .with_structured(serde_json::json!({- "window_id": window_id,- "platform": "linux",- "session": "wayland",- })),+ Ok(Ok(())) => {+ ToolResult::text(format!("Brought Wayland window {window_id} to front."))+ .with_structured(serde_json::json!({+ "window_id": window_id,+ "platform": "linux",+ "session": "wayland",+ }))+ }Ok(Err(error)) => ToolResult::error(error.to_string()),Err(error) => ToolResult::error(format!("Task error: {error}")),};@@ -6920,6 +6919,10 @@ pub fn build_registry(compat: bool) -> ToolRegistry {r.register(Box::new(cua_driver_core::page::PageTool::new(Arc::new(super::page::LinuxPageBackend::new(),))));+ let browser_engine = cua_driver_core::browser::BrowserEngine::new(Arc::new(+ crate::browser_platform::LinuxBrowserPlatform,+ ));+ cua_driver_core::browser::register_browser_tools(&browser_engine, &mut r);r.register_recording_tools();r.register_session_tools();r@@ -6995,3 +6998,20 @@ mod driver_config_tests {assert_eq!(DriverConfig::default().capture_scope, "window");}}++#[cfg(test)]+mod browser_launch_guard_tests {+ use super::contains_remote_debugging_flag;++ #[test]+ fn rejects_all_chromium_remote_debugging_spellings() {+ assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));+ assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));+ assert!(contains_remote_debugging_flag(+ "/usr/bin/chrome --remote-debugging-port 9222"+ ));+ assert!(!contains_remote_debugging_flag(+ "--user-data-dir=/tmp/profile"+ ));+ }+}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/ax/bindings.rs b/libs/cua-driver/rust/crates/platform-macos/src/ax/bindings.rsindex 5391d26228..c7dd3a1118 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/ax/bindings.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/ax/bindings.rs@@ -72,6 +72,10 @@ extern "C" {attribute: CFStringRef,value: CFTypeRef,) -> AXError;+ pub fn AXUIElementSetMessagingTimeout(+ element: AXUIElementRef,+ timeout_in_seconds: f32,+ ) -> AXError;pub fn AXUIElementGetTypeID() -> CFTypeID;pub fn AXIsProcessTrusted() -> bool;/// `AXIsProcessTrustedWithOptions(options)` — when called withdiff --git a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rsindex 79fa8732c1..c49f15aa93 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/ax/tree.rs@@ -42,6 +42,16 @@ pub const DEFAULT_MAX_ELEMENTS: usize = 2_000;/// `enabled_pids`.const CHROMIUM_SETTLE_SECONDS: f64 = 0.5;+/// Bound each native AX request. Tokio cannot cancel a blocked+/// `AXUIElementCopyAttributeValue` after `spawn_blocking` starts, so the native+/// messaging timeout is what keeps an unresponsive app from retaining a worker+/// indefinitely.+const AX_MESSAGING_TIMEOUT_SECONDS: f32 = 2.0;++unsafe fn set_messaging_timeout(element: AXUIElementRef) {+ let _ = AXUIElementSetMessagingTimeout(element, AX_MESSAGING_TIMEOUT_SECONDS);+}+/// Pids for which we have already flipped on accessibility and paid the/// one-time settle delay. Repeat snapshots of the same app skip the settle:/// the tree is already built and stays built for the life of the process.@@ -135,6 +145,7 @@ pub fn walk_tree_bounded(if app_elem.is_null() {return TreeWalkResult { tree_markdown: String::new(), nodes, truncated: false };}+ set_messaging_timeout(app_elem);// Chromium/Electron apps (Arc, VS Code, Electron shells) ship their// web-content AX tree OFF and only build it once an assistive client@@ -173,6 +184,7 @@ pub fn walk_tree_bounded(// Filter: keep non-window children (menu bar) + the target window.let walk_these: Vec<AXUIElementRef> = if let Some(wid) = window_id {top_level.iter().copied().filter(|&child| {+ set_messaging_timeout(child);let role = copy_string_attr(child, "AXRole").unwrap_or_default();if role != "AXWindow" {return true; // always keep menu bar and other non-window items@@ -250,6 +262,10 @@ unsafe fn walk_element(}*visited_count += 1;+ // Messaging timeouts are per AX object, not inherited from the application+ // element, so every descendant must be bounded before any attribute read.+ set_messaging_timeout(element);+let role = copy_string_attr(element, "AXRole").unwrap_or_else(|| "AXUnknown".into());diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/cdp_client.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/cdp_client.rsindex 9b52b3cbf0..546a38e124 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/cdp_client.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/cdp_client.rs@@ -1,15 +1,13 @@-//! CDP (Chrome DevTools Protocol) client for Electron and other chromium-based apps.-//! Uses raw TCP for the HTTP /json endpoint and tokio-tungstenite for WebSocket.+//! Legacy-compatible CDP client for Electron and other Chromium apps.+//! HTTP discovery stays compatible with the page tool; WebSocket calls use+//! cua-driver-core's shared event-aware `CdpConnection` transport.+use cua_driver_core::browser::cdp_ws::CdpConnection;use std::collections::HashMap;use std::sync::Arc;use std::time::Duration;use tokio::io::{AsyncReadExt, AsyncWriteExt};use tokio::sync::Mutex as AsyncMutex;-use futures_util::{SinkExt, StreamExt};-use tokio_tungstenite::tungstenite::Message;--type WsStream = tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<tokio::net::TcpStream>>;pub struct CdpClient;@@ -232,16 +230,11 @@ async fn do_evaluate(session: &mut CdpSession, javascript: &str) -> anyhow::Resu}async fn do_insert_text(session: &mut CdpSession, text: &str) -> anyhow::Result<()> {- let obj = tokio::time::timeout(+ tokio::time::timeout(Duration::from_secs(10),session.call("Input.insertText", serde_json::json!({ "text": text })),).await.map_err(|_| anyhow::anyhow!("CDP insertText timed out after 10s"))??;-- if let Some(err) = obj.get("error") {- let msg = err.get("message").and_then(|v| v.as_str()).unwrap_or("unknown error");- anyhow::bail!("CDP Input.insertText error: {msg}");- }Ok(())}@@ -263,11 +256,7 @@ async fn do_dispatch_keystrokes(session: &mut CdpSession, text: &str) -> anyhow:params["text"] = serde_json::json!(key);params["unmodifiedText"] = serde_json::json!(key);}- let obj = session.call("Input.dispatchKeyEvent", params).await?;- if let Some(err) = obj.get("error") {- let msg = err.get("message").and_then(|v| v.as_str()).unwrap_or("unknown error");- anyhow::bail!("CDP Input.dispatchKeyEvent error: {msg}");- }+ session.call("Input.dispatchKeyEvent", params).await?;}// Small gap between characters — a real keyboard doesn't emit// 36 events in the same tick, and some editors' autosave /@@ -297,21 +286,20 @@ async fn do_dispatch_keystrokes(session: &mut CdpSession, text: &str) -> anyhow:/// on this same connection (via `ensure_target`) is what lets/// `CdpSessionCache` switch tabs without opening a new socket.struct CdpSession {- ws: WsStream,+ connection: Arc<CdpConnection>,session_id: Option<String>,/// URL of whichever target we're currently attached to/connected to —/// used by `ensure_target` to decide whether a re-attach is needed.current_target_url: Option<String>,- next_id: u64,}impl CdpSession {async fn connect(port: u16, target_url_contains: Option<&str>) -> anyhow::Result<Self> {match ws_url_for_page_target(port, target_url_contains).await {Ok((ws_url, target_url)) => {- let (ws, _) = tokio_tungstenite::connect_async(&ws_url).await- .map_err(|e| anyhow::anyhow!("WebSocket connect failed: {e}"))?;- Ok(Self { ws, session_id: None, current_target_url: Some(target_url), next_id: 1 })+ let connection = Arc::new(CdpConnection::connect(&ws_url).await+ .map_err(|e| anyhow::anyhow!("WebSocket connect failed: {e}"))?);+ Ok(Self { connection, session_id: None, current_target_url: Some(target_url) })}Err(page_discovery_err) => {Self::connect_via_browser_endpoint(port, target_url_contains, page_discovery_err).await@@ -325,13 +313,13 @@ impl CdpSession {page_discovery_err: anyhow::Error,) -> anyhow::Result<Self> {let browser_ws_url = format!("ws://127.0.0.1:{port}/devtools/browser");- let (ws, _) = tokio_tungstenite::connect_async(&browser_ws_url).await.map_err(|e| {+ let connection = Arc::new(CdpConnection::connect(&browser_ws_url).await.map_err(|e| {anyhow::anyhow!("No /json page discovery on port {port} ({page_discovery_err}), and \connecting to the browser-level endpoint also failed: {e}")- })?;- let mut session = Self { ws, session_id: None, current_target_url: None, next_id: 1 };+ })?);+ let mut session = Self { connection, session_id: None, current_target_url: None };session.attach_to_target(port, target_url_contains).await?;Ok(session)}@@ -369,7 +357,7 @@ impl CdpSession {async fn attach_to_target(&mut self, port: u16, target_url_contains: Option<&str>) -> anyhow::Result<()> {let targets = self.call("Target.getTargets", serde_json::json!({})).await?;- let infos = targets["result"]["targetInfos"].as_array().cloned().unwrap_or_default();+ let infos = targets["targetInfos"].as_array().cloned().unwrap_or_default();let pages: Vec<&serde_json::Value> = infos.iter().filter(|t| t.get("type").and_then(|v| v.as_str()) == Some("page")).collect();@@ -384,7 +372,7 @@ impl CdpSession {"Target.attachToTarget",serde_json::json!({ "targetId": target_id, "flatten": true }),).await?;- let session_id = attach["result"]["sessionId"].as_str()+ let session_id = attach["sessionId"].as_str().ok_or_else(|| anyhow::anyhow!("Target.attachToTarget did not return a sessionId"))?.to_owned();self.session_id = Some(session_id);@@ -392,36 +380,11 @@ impl CdpSession {Ok(())}- /// Send `method`/`params`, return the full response envelope once its- /// `id` comes back (event frames and other in-flight ids are skipped).+ /// Send one command through the shared event-aware CDP demultiplexer.async fn call(&mut self, method: &str, params: serde_json::Value) -> anyhow::Result<serde_json::Value> {- let id = self.next_id;- self.next_id += 1;-- let mut request = serde_json::json!({ "id": id, "method": method, "params": params });- if let Some(sid) = &self.session_id {- request["sessionId"] = serde_json::json!(sid);- }-- self.ws.send(Message::Text(request.to_string().into())).await- .map_err(|e| anyhow::anyhow!("WebSocket send failed: {e}"))?;-- loop {- let msg = self.ws.next().await- .ok_or_else(|| anyhow::anyhow!("WebSocket stream ended before response for id {id}"))??;- let text = match msg {- Message::Text(t) => t,- Message::Close(_) => anyhow::bail!("WebSocket closed before response for id {id}"),- _ => continue,- };- let obj: serde_json::Value = serde_json::from_str(&text)- .map_err(|e| anyhow::anyhow!("CDP response parse error: {e}"))?;- // Skip CDP event frames (they have "method" key but no "id").- if obj.get("method").is_some() { continue; }- if obj.get("id").and_then(|v| v.as_u64()) == Some(id) {- return Ok(obj);- }- }+ self.connection+ .call(self.session_id.as_deref(), method, params)+ .await}}@@ -672,7 +635,7 @@ fn parse_cdp_result(obj: &serde_json::Value) -> anyhow::Result<String> {let msg = err.get("message").and_then(|v| v.as_str()).unwrap_or("unknown error");anyhow::bail!("CDP error: {msg}");}- let result = &obj["result"]["result"];+ let result = &obj["result"];if let Some(v) = result.get("value") {return Ok(match v {serde_json::Value::String(s) => s.clone(),diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/electron_js.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/electron_js.rsindex c4683eebae..fd6bde6f85 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/electron_js.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/electron_js.rs@@ -1,12 +1,10 @@//! ElectronJS: detect Electron apps and evaluate JS via CDP inspector.-use std::time::Duration;use std::collections::HashSet;+use std::time::Duration;use super::cdp_client::{listening_ports, CdpClient};-const DEFAULT_PORTS: &[u16] = &[9222, 9223, 9224, 9225, 9230];-pub struct ElectronJs;impl ElectronJs {@@ -48,12 +46,8 @@ impl ElectronJs {/// Evaluate JavaScript in the Electron app at `pid` via CDP.pub async fn execute(javascript: &str, pid: i32) -> anyhow::Result<String> {- // 1. Check default ports for an existing CDP page target.- if let Some(port) = CdpClient::find_page_target(DEFAULT_PORTS).await {- return CdpClient::evaluate(javascript, port).await;- }-- // 2. Check listening ports of this process for a CDP endpoint.+ // Only inspect listeners owned by the requested process. Probing common+ // CDP ports globally can execute JavaScript in an unrelated browser.let existing_ports = listening_ports(pid).await;for &port in &existing_ports {if CdpClient::is_available(port).await {@@ -61,14 +55,14 @@ impl ElectronJs {}}- // 3. Snapshot current ports, then send SIGUSR1 to open the inspector.+ // Snapshot current ports, then send SIGUSR1 to open the inspector.let before_ports: HashSet<u16> = existing_ports.iter().cloned().collect();unsafe {libc::kill(pid, libc::SIGUSR1);}- // 4. Poll for new port.+ // Poll for a new process-owned port.let mut new_port: Option<u16> = None;for _ in 0..10 {tokio::time::sleep(Duration::from_millis(200)).await;@@ -79,12 +73,16 @@ impl ElectronJs {break;}}- if new_port.is_some() { break; }+ if new_port.is_some() {+ break;+ }}let port = new_port.ok_or_else(|| {- anyhow::anyhow!("Could not find Electron inspector port for pid {pid}. \- Try launching with --inspect or --remote-debugging-port.")+ anyhow::anyhow!(+ "Could not find Electron inspector port for pid {pid}. \+ Try launching with --inspect or --remote-debugging-port."+ )})?;CdpClient::evaluate(javascript, port).await@@ -125,4 +123,3 @@ fn find_bundle_path_for_app(name: &str) -> Option<String> {}None}-diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rsindex 43db1a243c..ece2a8c58f 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/mod.rs@@ -2,10 +2,12 @@ pub mod ax_page_reader;pub mod browser_js;pub mod cdp_client;pub mod electron_js;+pub mod platform;pub mod wk_web_view;pub use browser_js::BrowserJs;pub use cdp_client::{CdpClient, CdpSessionCache};pub use electron_js::ElectronJs;+pub use platform::MacOsBrowserPlatform;pub use wk_web_view::is_wk_web_view_app;pub use ax_page_reader::AXPageReader;diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rsnew file mode 100644index 0000000000..734fced17d--- /dev/null+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs@@ -0,0 +1,446 @@+//! macOS identity and endpoint evidence for the first-class browser tools.++use std::hash::{Hash, Hasher};+use std::process::Stdio;+use std::time::Duration;++use async_trait::async_trait;+use cua_driver_core::browser::platform::{+ BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,+};+use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};+use cua_driver_core::browser::types::{+ BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,+ NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,+ ProcessFingerprint, Rect,+};+use tokio::io::{AsyncReadExt, AsyncWriteExt};++#[derive(Debug, Default)]+pub struct MacOsBrowserPlatform;++fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(code, message)+}++fn is_chromium(name: &str, bundle_id: &str) -> bool {+ let value = format!("{name} {bundle_id}").to_ascii_lowercase();+ let products = [+ "chrome", "chromium", "electron", "brave", "edge", "vivaldi", "opera", "arc", "thorium",+ "iridium", "yandex",+ ];+ value+ .split(|ch: char| !ch.is_ascii_alphanumeric())+ .any(|token| products.contains(&token))+}++fn is_firefox(name: &str, bundle_id: &str) -> bool {+ format!("{name} {bundle_id}")+ .to_ascii_lowercase()+ .split(|ch: char| !ch.is_ascii_alphanumeric())+ .any(|token| token == "firefox")+}++fn loopback_websocket_port(url: &str) -> Option<u16> {+ ["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]+ .iter()+ .find_map(|prefix| {+ url.strip_prefix(prefix)?+ .split('/')+ .next()?+ .parse::<u16>()+ .ok()+ })+}++fn stable_hash(value: &str) -> u64 {+ let mut hasher = std::collections::hash_map::DefaultHasher::new();+ value.hash(&mut hasher);+ hasher.finish()+}++fn exact_browser_surface_ids(+ windows: impl IntoIterator<Item = crate::windows::WindowInfo>,+ pid: i64,+) -> Vec<u64> {+ windows+ .into_iter()+ .filter(|window| {+ i64::from(window.pid) == pid+ && !window.title.trim().is_empty()+ && window.bounds.width > 0.0+ && window.bounds.height > 0.0+ })+ .map(|window| u64::from(window.window_id))+ .collect()+}++async fn process_details(pid: i64) -> Result<(String, String), BrowserRefusal> {+ let output = tokio::process::Command::new("ps")+ .args(["-p", &pid.to_string(), "-o", "lstart=", "-o", "comm="])+ .stdin(Stdio::null())+ .stderr(Stdio::null())+ .output()+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not inspect browser process {pid}: {error}"),+ )+ })?;+ if !output.status.success() {+ return Err(refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ ));+ }+ let text = String::from_utf8_lossy(&output.stdout).trim().to_owned();+ if text.is_empty() {+ return Err(refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} has no process identity"),+ ));+ }+ let split = text+ .char_indices()+ .nth(24)+ .map(|(index, _)| index)+ .unwrap_or(text.len());+ let (started, executable) = text.split_at(split);+ Ok((started.trim().to_owned(), executable.trim().to_owned()))+}++fn parse_loopback_lsof_ports(text: &str) -> Vec<u16> {+ let mut ports = text+ .lines()+ .filter_map(|line| line.trim().strip_prefix('n'))+ .filter_map(|address| {+ let (host, port) = address.rsplit_once(':')?;+ let host = host.trim_matches(['[', ']']);+ matches!(host, "127.0.0.1" | "::1" | "localhost")+ .then(|| port.parse::<u16>().ok())+ .flatten()+ })+ .collect::<Vec<_>>();+ ports.sort_unstable();+ ports.dedup();+ ports+}++async fn loopback_ports_for_pid(pid: i64) -> Result<Vec<u16>, BrowserRefusal> {+ let output = tokio::process::Command::new("lsof")+ .args([+ "-a",+ "-p",+ &pid.to_string(),+ "-iTCP",+ "-sTCP:LISTEN",+ "-Fn",+ "-P",+ ])+ .stdin(Stdio::null())+ .stderr(Stdio::null())+ .output()+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not inspect browser listeners: {error}"),+ )+ })?;+ Ok(parse_loopback_lsof_ports(&String::from_utf8_lossy(+ &output.stdout,+ )))+}++async fn browser_websocket_url(port: u16) -> Option<String> {+ tokio::time::timeout(Duration::from_secs(2), async move {+ let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))+ .await+ .ok()?;+ let request = format!(+ "GET /json/version HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"+ );+ stream.write_all(request.as_bytes()).await.ok()?;+ let mut bytes = Vec::new();+ let mut chunk = [0u8; 4096];+ loop {+ let read = stream.read(&mut chunk).await.ok()?;+ if read == 0 {+ break;+ }+ bytes.extend_from_slice(&chunk[..read]);+ if bytes.len() > 256 * 1024 {+ return None;+ }+ if let Some(header_end) = bytes.windows(4).position(|part| part == b"\r\n\r\n") {+ let headers = String::from_utf8_lossy(&bytes[..header_end]);+ if let Some(length) = headers.lines().find_map(|line| {+ let (name, value) = line.split_once(':')?;+ name.eq_ignore_ascii_case("content-length")+ .then(|| value.trim().parse::<usize>().ok())+ .flatten()+ }) {+ if bytes.len() >= header_end + 4 + length {+ break;+ }+ }+ }+ }+ let body_start = bytes.windows(4).position(|part| part == b"\r\n\r\n")? + 4;+ let value: serde_json::Value = serde_json::from_slice(&bytes[body_start..]).ok()?;+ let url = value.get("webSocketDebuggerUrl")?.as_str()?.to_owned();+ (loopback_websocket_port(&url) == Some(port)).then_some(url)+ })+ .await+ .ok()+ .flatten()+}++#[async_trait]+impl BrowserPlatform for MacOsBrowserPlatform {+ fn standalone_trusted_input_background_limitation(&self) -> Option<&'static str> {+ Some("Chromium's trusted CDP Input route activates its standalone browser window on macOS")+ }++ async fn classify_browser(&self, pid: i64) -> Result<BrowserClassification, BrowserRefusal> {+ let (app, fallback_name, fallback_bundle_id) = tokio::task::spawn_blocking(move || {+ let app = crate::apps::list_running_apps()+ .into_iter()+ .find(|app| i64::from(app.pid) == pid);+ let fallback_name = crate::apps::get_app_name_for_pid(pid as i32);+ let fallback_bundle_id = crate::apps::bundle_id_for_pid(pid as i32);+ (app, fallback_name, fallback_bundle_id)+ })+ .await+ .unwrap_or((None, None, None));+ let name = app+ .as_ref()+ .map(|app| app.name.as_str())+ .or(fallback_name.as_deref())+ .unwrap_or("");+ let bundle_id = app+ .as_ref()+ .and_then(|app| app.bundle_id.as_deref())+ .or(fallback_bundle_id.as_deref())+ .unwrap_or("");+ let chromium = is_chromium(name, bundle_id);+ let webkit = bundle_id == "com.apple.Safari" || name.eq_ignore_ascii_case("Safari");+ let gecko = is_firefox(name, bundle_id);+ Ok(BrowserClassification {+ is_browser: chromium || webkit || gecko,+ engine: if chromium {+ BrowserEngineFamily::Chromium+ } else if webkit {+ BrowserEngineFamily::Webkit+ } else if gecko {+ BrowserEngineFamily::Gecko+ } else {+ BrowserEngineFamily::Unknown+ },+ product: (!name.is_empty()).then(|| name.to_owned()),+ channel: None,+ supports_cdp: chromium,+ })+ }++ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ let window_id_u32 = u32::try_from(window_id).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("window_id {window_id} is outside the macOS window-id range"),+ )+ })?;+ let window = tokio::task::spawn_blocking(move || {+ crate::windows::all_windows()+ .into_iter()+ .find(|window| window.window_id == window_id_u32)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("macOS window {window_id} is no longer available"),+ )+ })?;+ if i64::from(window.pid) != pid {+ return Err(refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("window {window_id} is not owned by pid {pid}"),+ ));+ }+ Ok(NativeWindowInfo {+ pid,+ window_id,+ title: window.title,+ bounds: Rect::new(+ window.bounds.x,+ window.bounds.y,+ window.bounds.width,+ window.bounds.height,+ ),+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: pid,+ detail: Some("CGWindow owner pid".to_owned()),+ },+ })+ }++ async fn is_only_exact_native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal> {+ let windows = tokio::task::spawn_blocking(move || {+ exact_browser_surface_ids(crate::windows::all_windows(), pid)+ })+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not enumerate macOS browser windows: {error}"),+ )+ })?;+ Ok(Some(windows.len() == 1 && windows[0] == window_id))+ }++ async fn discover_owned_endpoint(+ &self,+ pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {+ for port in loopback_ports_for_pid(pid).await? {+ if let Some(ws_url) = browser_websocket_url(port).await {+ return Ok(Some(OwnedEndpoint {+ ws_url,+ http_port: Some(port),+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::ListeningSocketPid,+ owner_pid: pid,+ detail: Some("lsof loopback listener owner".to_owned()),+ },+ }));+ }+ }+ Ok(None)+ }++ async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {+ let (started, executable) = process_details(pid).await?;+ Ok(ProcessFingerprint {+ pid,+ start_time: Some(stable_hash(&started)),+ executable: (!executable.is_empty()).then_some(executable),+ })+ }++ async fn prepare_endpoint(+ &self,+ request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ if let Some(endpoint) = self.discover_owned_endpoint(request.pid).await? {+ return Ok(PrepareOutcome {+ action: PrepareAction::AlreadyPrepared,+ prepared_pid: Some(endpoint.ownership.owner_pid),+ endpoint: Some(endpoint),+ message: "An owned loopback DevTools endpoint is already available.".to_owned(),+ side_effects: Default::default(),+ });+ }+ Err(refusal(+ BrowserRefusalCode::BrowserRequiresSetup,+ "No owned endpoint is available. Acting setup is handled by shared core only for a verified driver-owned isolated profile.",+ ))+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ fn window(window_id: u32, pid: i32, title: &str) -> crate::windows::WindowInfo {+ crate::windows::WindowInfo {+ window_id,+ pid,+ app_name: "Electron".to_owned(),+ title: title.to_owned(),+ bounds: crate::windows::WindowBounds {+ x: 120.0,+ y: 120.0,+ width: 940.0,+ height: 780.0,+ },+ layer: 0,+ z_index: 0,+ is_on_screen: true,+ on_current_space: Some(true),+ space_ids: None,+ }+ }++ #[test]+ fn lsof_parser_accepts_only_loopback_listeners() {+ let input = "n127.0.0.1:9222\nn*:9333\nn[::1]:9444\nn0.0.0.0:9555\n";+ assert_eq!(parse_loopback_lsof_ports(input), vec![9222, 9444]);+ }++ #[test]+ fn browser_classifier_covers_embedded_and_standalone_chromium() {+ assert!(is_chromium("Electron", "com.example.fixture"));+ assert!(is_chromium("Google Chrome", "com.google.Chrome"));+ assert!(!is_chromium("Safari", "com.apple.Safari"));+ assert!(!is_chromium("Search", "com.example.Search"));+ assert!(!is_chromium("Operator", "com.example.Operator"));+ }++ #[test]+ fn firefox_classifier_uses_product_tokens() {+ assert!(is_firefox("Firefox", "org.mozilla.firefox"));+ assert!(is_firefox("Mozilla Firefox", "org.mozilla.firefox"));+ assert!(!is_firefox("FirefoxHelper", "com.example.FirefoxHelper"));+ assert!(!is_firefox("Waterfox", "net.waterfox.current"));+ }++ #[test]+ fn websocket_url_must_keep_the_attested_listener_port() {+ assert_eq!(+ loopback_websocket_port("ws://127.0.0.1:9222/devtools/browser/id"),+ Some(9222)+ );+ assert_ne!(+ loopback_websocket_port("ws://localhost:9333/devtools/browser/foreign"),+ Some(9222)+ );+ assert_eq!(+ loopback_websocket_port("ws://192.0.2.1:9222/devtools"),+ None+ );+ }++ #[test]+ fn embedded_window_proof_ignores_untitled_window_server_helpers() {+ let mut helper = window(8, 42, "");+ helper.is_on_screen = false;+ let ids = exact_browser_surface_ids([window(7, 42, "CuaTestHarness Electron"), helper], 42);+ assert_eq!(ids, vec![7]);+ }++ #[test]+ fn embedded_window_proof_retains_multiple_titled_browser_surfaces() {+ let ids = exact_browser_surface_ids(+ [+ window(7, 42, "Primary browser window"),+ window(8, 42, "Secondary browser window"),+ ],+ 42,+ );+ assert_eq!(ids, vec![7, 8]);+ }+}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rsindex ddff5a15cd..c1f86a39db 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs@@ -144,10 +144,10 @@ impl Tool for GetWindowStateTool {// Always walk the AX tree (perception returns both tree + screenshot).let tree_result = {let q = query.clone();- // Wrap the blocking AX walk in a 30-second timeout. Heavy webview apps- // (Arc, Safari with many tabs, Electron) can block- // AXUIElementCopyAttributeValue indefinitely via XPC — without a- // deadline the MCP server hangs forever (issue #1537).+ // Keep the product deadline below the public client's 25-second+ // deadline so callers receive a structured driver error. The AX+ // walker also applies a native per-element messaging timeout because+ // dropping a spawn_blocking JoinHandle cannot cancel a blocked AX call.let walk_future = tokio::task::spawn_blocking(move || {crate::ax::tree::walk_tree_bounded(pid,@@ -157,12 +157,12 @@ impl Tool for GetWindowStateTool {max_depth,)});- match tokio::time::timeout(std::time::Duration::from_secs(30), walk_future).await {+ match tokio::time::timeout(std::time::Duration::from_secs(20), walk_future).await {Ok(Ok(r)) => Some(r),Ok(Err(e)) => return ToolResult::error(format!("AX tree walk failed: {e}")),Err(_elapsed) => {return ToolResult::error(format!(- "AX tree walk for pid={pid} timed out after 30 s. \+ "AX tree walk for pid={pid} timed out after 20 s. \The app (likely Arc, Electron, or Safari with many tabs) has a \pathologically large accessibility tree. \Workaround: re-call with a depth-limited scan \diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rsindex 98e0bbc844..30245570d2 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs@@ -1,5 +1,8 @@use async_trait::async_trait;-use cua_driver_core::{protocol::ToolResult, tool::{Tool, ToolDef}};+use cua_driver_core::{+ protocol::ToolResult,+ tool::{Tool, ToolDef},+};use serde_json::Value;use std::path::PathBuf;@@ -16,9 +19,8 @@ fn def() -> &'static ToolDef {or `name` (e.g. \"Calculator\"). If both are given, bundle_id wins.\n\n\Optional `urls` are handed to the app as open targets — for Finder, pass a folder \path to open a backgrounded Finder window there.\n\n\- Optional `cdp_debugging_port`: opens a Chrome DevTools Protocol (CDP) server \- on the specified port (appends --remote-debugging-port=N to the app's argv). \- Use this to automate Electron/VS Code/Cursor, or Chrome/Brave/Edge, via CDP.\n\n\+ Browser DevTools setup belongs to `browser_prepare`, which can prove that a \+ separate isolated profile is driver-owned before enabling CDP.\n\n\Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified \port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). \Use this for Tauri/WebKit-based apps.\n\n\@@ -52,10 +54,6 @@ fn def() -> &'static ToolDef {"items": { "type": "string" },"description": "Optional file paths or URLs to open with the app (e.g. a folder path for Finder)."},- "cdp_debugging_port": {- "type": "integer",- "description": "Open a Chrome DevTools Protocol server on this port (appends --remote-debugging-port=N)."- },"webkit_inspector_port": {"type": "integer","description": "Open a WebKit inspector server on this port (sets WEBKIT_INSPECTOR_SERVER env var)."@@ -81,21 +79,35 @@ fn def() -> &'static ToolDef {#[async_trait]impl Tool for LaunchAppTool {- fn def(&self) -> &ToolDef { def() }+ fn def(&self) -> &ToolDef {+ def()+ }async fn invoke(&self, args: Value) -> ToolResult {use cua_driver_core::tool_args::ArgsExt;let bundle_id = args.opt_str("bundle_id");- let name = args.opt_str("name");+ let name = args.opt_str("name");let urls: Vec<String> = args.str_array("urls");- let cdp_debugging_port = args.opt_u64("cdp_debugging_port").map(|v| v as u16);+ if args.get("cdp_debugging_port").is_some() {+ return ToolResult::error(+ "cdp_debugging_port moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }let webkit_inspector_port = args.opt_u64("webkit_inspector_port").map(|v| v as u16);let creates_new_instance = args.bool_or("creates_new_application_instance", false);- let mut additional_arguments: Vec<String> = args.str_array("additional_arguments");+ let additional_arguments: Vec<String> = args.str_array("additional_arguments");+ if additional_arguments+ .iter()+ .any(|argument| contains_remote_debugging_flag(argument))+ {+ return ToolResult::error(+ "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }if bundle_id.is_none() && name.is_none() {return ToolResult::error(- "Provide either bundle_id or name to identify the app to launch."+ "Provide either bundle_id or name to identify the app to launch.",);}if let Some(ref bid) = bundle_id {@@ -119,23 +131,18 @@ impl Tool for LaunchAppTool {return err;}- // Build additional arguments (e.g., CDP port).- if let Some(port) = cdp_debugging_port {- additional_arguments.push(format!("--remote-debugging-port={port}"));- }-// Build env dict for webkit inspector.let mut env: std::collections::HashMap<String, String> = std::collections::HashMap::new();if let Some(port) = webkit_inspector_port {- env.insert("WEBKIT_INSPECTOR_SERVER".to_string(), format!("127.0.0.1:{port}"));+ env.insert(+ "WEBKIT_INSPECTOR_SERVER".to_string(),+ format!("127.0.0.1:{port}"),+ );env.insert("TAURI_WEBVIEW_AUTOMATION".to_string(), "1".to_string());}let port_summary = {let mut s = String::new();- if let Some(port) = cdp_debugging_port {- s.push_str(&format!("\nCDP renderer available on port {port}."));- }if let Some(port) = webkit_inspector_port {s.push_str(&format!("\nWebKit inspector available on port {port}."));}@@ -229,7 +236,8 @@ impl Tool for LaunchAppTool {};Ok::<_, anyhow::Error>((pid, app_info, windows))- }).await;+ })+ .await;// Upgrade to targeted suppression now that we know the real pid.// Keep the wildcard lease alive until immediately AFTER we've@@ -247,12 +255,11 @@ impl Tool for LaunchAppTool {if let Ok(Ok((pid, _, _))) = &launch_result {if let Some(prior) = prior_frontmost {if *pid != prior {- let targeted_lease =- crate::focus_steal::FocusStealPreventer::begin_suppression(- Some(*pid),- prior,- "LaunchAppTool.post",- );+ let targeted_lease = crate::focus_steal::FocusStealPreventer::begin_suppression(+ Some(*pid),+ prior,+ "LaunchAppTool.post",+ );// Now safe to drop the wildcard — targeted is armed.drop(wildcard_lease);// Hold the targeted lease long enough to cover the@@ -298,8 +305,7 @@ impl Tool for LaunchAppTool {continue;}let activated = crate::apps::activate_pid(prior);- let still_frontmost =- crate::apps::frontmost_pid() == Some(*pid);+ let still_frontmost = crate::apps::frontmost_pid() == Some(*pid);if still_frontmost {tracing::warn!(target: "platform_macos::tools::launch_app",@@ -314,15 +320,12 @@ impl Tool for LaunchAppTool {} else {demotion_succeeded = true;}- tokio::time::sleep(- std::time::Duration::from_millis(200)- ).await;+ tokio::time::sleep(std::time::Duration::from_millis(200)).await;}// Final in-call state determines the structured response.let final_frontmost = crate::apps::frontmost_pid();- self_activation_suppressed = Some(- final_frontmost != Some(*pid) && demotion_succeeded- );+ self_activation_suppressed =+ Some(final_frontmost != Some(*pid) && demotion_succeeded);// Detached late-activation watchdog (slow path only).//@@ -374,10 +377,9 @@ impl Tool for LaunchAppTool {"LaunchAppTool.watchdog",);let mut late_activations = 0u32;- for _ in 0..32 { // 32 × 250ms = 8s- tokio::time::sleep(- std::time::Duration::from_millis(250)- ).await;+ for _ in 0..32 {+ // 32 × 250ms = 8s+ tokio::time::sleep(std::time::Duration::from_millis(250)).await;if crate::apps::frontmost_pid() == Some(launched_pid) {late_activations += 1;let _ = crate::apps::activate_pid(prior_pid);@@ -409,9 +411,13 @@ impl Tool for LaunchAppTool {match launch_result {Ok(Ok((pid, app_info, windows))) => {let app_name = app_info.as_ref().map(|a| a.name.as_str()).unwrap_or("?");- let bid = app_info.as_ref().and_then(|a| a.bundle_id.as_deref()).unwrap_or("?");+ let bid = app_info+ .as_ref()+ .and_then(|a| a.bundle_id.as_deref())+ .unwrap_or("?");- let mut summary = format!("Launched {app_name} (pid {pid}) in background.{port_summary}");+ let mut summary =+ format!("Launched {app_name} (pid {pid}) in background.{port_summary}");if !windows.is_empty() {summary.push_str("\n\nWindows:");@@ -428,17 +434,22 @@ impl Tool for LaunchAppTool {));}- let windows_json: Vec<Value> = windows.iter().map(|w| serde_json::json!({- "window_id": w.window_id,- "pid": w.pid,- "app_name": w.app_name,- "title": w.title,- "bounds": {- "x": w.bounds.x, "y": w.bounds.y,- "width": w.bounds.width, "height": w.bounds.height- },- "is_on_screen": w.is_on_screen,- })).collect();+ let windows_json: Vec<Value> = windows+ .iter()+ .map(|w| {+ serde_json::json!({+ "window_id": w.window_id,+ "pid": w.pid,+ "app_name": w.app_name,+ "title": w.title,+ "bounds": {+ "x": w.bounds.x, "y": w.bounds.y,+ "width": w.bounds.width, "height": w.bounds.height+ },+ "is_on_screen": w.is_on_screen,+ })+ })+ .collect();let mut structured = serde_json::json!({"pid": pid,@@ -452,17 +463,21 @@ impl Tool for LaunchAppTool {// (no prior frontmost, or pid == prior) — surfacing// a stale `false` would be misleading.if let Some(suppressed) = self_activation_suppressed {- structured["self_activation_suppressed"] =- serde_json::Value::Bool(suppressed);+ structured["self_activation_suppressed"] = serde_json::Value::Bool(suppressed);}ToolResult::text(summary).with_structured(structured)}Ok(Err(e)) => ToolResult::error(format!("Launch failed: {e}")),- Err(e) => ToolResult::error(format!("Task error: {e}")),+ Err(e) => ToolResult::error(format!("Task error: {e}")),}}}+fn contains_remote_debugging_flag(value: &str) -> bool {+ let lower = value.to_ascii_lowercase();+ lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")+}+// ── Blocking helpers ──────────────────────────────────────────────────────────/// Poll for the pid's layer-0 windows, retrying up to 5x100ms to absorb@@ -484,11 +499,7 @@ fn resolve_windows_for_pid(pid: i32) -> Vec<crate::windows::WindowInfo> {vec![]}-fn structured_launch_error(- code: &str,- message: String,- details: serde_json::Value,-) -> ToolResult {+fn structured_launch_error(code: &str, message: String, details: serde_json::Value) -> ToolResult {let mut payload = serde_json::json!({"error": code,});@@ -592,7 +603,7 @@ fn hex_value(byte: u8) -> Option<u8> {#[cfg(test)]mod tests {- use super::{local_file_target, preflight_file_urls};+ use super::{contains_remote_debugging_flag, local_file_target, preflight_file_urls};use std::path::PathBuf;#[test]@@ -621,7 +632,10 @@ mod tests {assert_eq!(result.is_error, Some(true));let structured = result.structured_content.expect("structured error");assert_eq!(structured["error"], "FILE_NOT_FOUND");- assert_eq!(structured["path"], "/tmp/cua-driver-definitely-missing-file-for-test.md");+ assert_eq!(+ structured["path"],+ "/tmp/cua-driver-definitely-missing-file-for-test.md"+ );assert!(structured.get("details").is_none());}@@ -636,4 +650,13 @@ mod tests {Some(PathBuf::from("/tmp/✓.txt")));}++ #[test]+ fn rejects_all_chromium_remote_debugging_spellings() {+ assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));+ assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));+ assert!(!contains_remote_debugging_flag(+ "--user-data-dir=/tmp/profile"+ ));+ }}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rsindex c1b21a0cee..5c28943d49 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs@@ -486,6 +486,10 @@ pub fn register_all(registry: &mut ToolRegistry, compat: bool) {registry.register(Box::new(cua_driver_core::page::PageTool::new(Arc::new(page::MacOsPageBackend::new(state.clone())),)));+ let browser_engine = cua_driver_core::browser::BrowserEngine::new(Arc::new(+ crate::browser::MacOsBrowserPlatform,+ ));+ cua_driver_core::browser::register_browser_tools(&browser_engine, registry);// Recording / replay + session-lifecycle tools are platform-independent.registry.register_recording_tools();registry.register_session_tools();diff --git a/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rsnew file mode 100644index 0000000000..e4f1955e34--- /dev/null+++ b/libs/cua-driver/rust/crates/platform-windows/src/browser_platform.rs@@ -0,0 +1,432 @@+//! Windows identity and endpoint evidence for the first-class browser tools.++use std::process::Stdio;+use std::time::Duration;++use async_trait::async_trait;+use cua_driver_core::browser::platform::{+ BrowserPlatform, PrepareAction, PrepareOutcome, PrepareRequest,+};+use cua_driver_core::browser::refusal::{BrowserRefusal, BrowserRefusalCode};+use cua_driver_core::browser::types::{+ BrowserClassification, BrowserEngineFamily, EndpointOwnershipMethod, EndpointOwnershipProof,+ NativeOwnershipMethod, NativeOwnershipProof, NativeWindowInfo, OwnedEndpoint,+ ProcessFingerprint, Rect,+};+use tokio::io::{AsyncReadExt, AsyncWriteExt};+use windows::Win32::Foundation::{CloseHandle, FILETIME, HWND, RECT};+use windows::Win32::System::Threading::{+ GetProcessTimes, OpenProcess, QueryFullProcessImageNameW, PROCESS_NAME_FORMAT,+ PROCESS_QUERY_LIMITED_INFORMATION,+};+use windows::Win32::UI::HiDpi::GetDpiForWindow;+use windows::Win32::UI::WindowsAndMessaging::GetWindowRect;++#[derive(Debug, Default)]+pub struct WindowsBrowserPlatform;++fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {+ BrowserRefusal::new(code, message)+}++fn is_chromium(name: &str) -> bool {+ let name = name.to_ascii_lowercase();+ let products = [+ "chrome", "chromium", "electron", "msedge", "brave", "vivaldi", "opera", "arc", "thorium",+ "iridium", "yandex",+ ];+ name.split(|ch: char| !ch.is_ascii_alphanumeric())+ .any(|token| products.contains(&token))+}++fn is_firefox(name: &str) -> bool {+ name.to_ascii_lowercase()+ .split(|ch: char| !ch.is_ascii_alphanumeric())+ .any(|token| token == "firefox")+}++fn loopback_websocket_port(url: &str) -> Option<u16> {+ ["ws://127.0.0.1:", "ws://localhost:", "ws://[::1]:"]+ .iter()+ .find_map(|prefix| {+ url.strip_prefix(prefix)?+ .split('/')+ .next()?+ .parse::<u16>()+ .ok()+ })+}++fn process_identity(pid: u32) -> Result<(u64, Option<String>), BrowserRefusal> {+ let handle =+ unsafe { OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, false, pid) }.map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ )+ })?;+ let mut created = FILETIME::default();+ let mut exited = FILETIME::default();+ let mut kernel = FILETIME::default();+ let mut user = FILETIME::default();+ let times =+ unsafe { GetProcessTimes(handle, &mut created, &mut exited, &mut kernel, &mut user) };+ let mut path_buf = [0u16; 1024];+ let mut path_len = path_buf.len() as u32;+ let path = unsafe {+ QueryFullProcessImageNameW(+ handle,+ PROCESS_NAME_FORMAT(0),+ windows::core::PWSTR(path_buf.as_mut_ptr()),+ &mut path_len,+ )+ }+ .ok()+ .filter(|_| path_len > 0)+ .map(|_| String::from_utf16_lossy(&path_buf[..path_len as usize]));+ let _ = unsafe { CloseHandle(handle) };+ times.map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not fingerprint browser process {pid}: {error}"),+ )+ })?;+ let started = (u64::from(created.dwHighDateTime) << 32) | u64::from(created.dwLowDateTime);+ Ok((started, path))+}++fn cdp_comparable_window_bounds(window_id: u64) -> Result<Rect, BrowserRefusal> {+ let hwnd = HWND(window_id as *mut _);+ let mut outer = RECT::default();+ unsafe { GetWindowRect(hwnd, &mut outer) }.map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("could not read Windows outer bounds for window {window_id}: {error}"),+ )+ })?;+ let dpi = unsafe { GetDpiForWindow(hwnd) };+ let scale = if dpi == 0 { 1.0 } else { f64::from(dpi) / 96.0 };+ Ok(Rect::new(+ f64::from(outer.left) / scale,+ f64::from(outer.top) / scale,+ f64::from(outer.right - outer.left) / scale,+ f64::from(outer.bottom - outer.top) / scale,+ ))+}++fn parse_netstat_loopback_ports(text: &str, pid: u32) -> Vec<u16> {+ let mut ports = text+ .lines()+ .filter_map(|line| {+ let fields = line.split_whitespace().collect::<Vec<_>>();+ if fields.len() < 5+ || !fields[0].eq_ignore_ascii_case("TCP")+ || !fields[3].eq_ignore_ascii_case("LISTENING")+ || fields[4].parse::<u32>().ok() != Some(pid)+ {+ return None;+ }+ let local = fields[1];+ let (host, port) = local.rsplit_once(':')?;+ let host = host.trim_matches(['[', ']']);+ matches!(host, "127.0.0.1" | "::1" | "localhost")+ .then(|| port.parse::<u16>().ok())+ .flatten()+ })+ .collect::<Vec<_>>();+ ports.sort_unstable();+ ports.dedup();+ ports+}++async fn loopback_ports_for_pid(pid: u32) -> Result<Vec<u16>, BrowserRefusal> {+ let output = tokio::process::Command::new("netstat.exe")+ .args(["-ano", "-p", "tcp"])+ .stdin(Stdio::null())+ .stderr(Stdio::null())+ .output()+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not inspect browser listeners: {error}"),+ )+ })?;+ Ok(parse_netstat_loopback_ports(+ &String::from_utf8_lossy(&output.stdout),+ pid,+ ))+}++async fn browser_websocket_url(port: u16) -> Option<String> {+ tokio::time::timeout(Duration::from_secs(2), async move {+ let mut stream = tokio::net::TcpStream::connect(("127.0.0.1", port))+ .await+ .ok()?;+ let request = format!(+ "GET /json/version HTTP/1.1\r\nHost: 127.0.0.1:{port}\r\nConnection: close\r\n\r\n"+ );+ stream.write_all(request.as_bytes()).await.ok()?;+ let mut bytes = Vec::new();+ let mut chunk = [0u8; 4096];+ loop {+ let read = stream.read(&mut chunk).await.ok()?;+ if read == 0 {+ break;+ }+ bytes.extend_from_slice(&chunk[..read]);+ if bytes.len() > 256 * 1024 {+ return None;+ }+ if let Some(header_end) = bytes.windows(4).position(|part| part == b"\r\n\r\n") {+ let headers = String::from_utf8_lossy(&bytes[..header_end]);+ if let Some(length) = headers.lines().find_map(|line| {+ let (name, value) = line.split_once(':')?;+ name.eq_ignore_ascii_case("content-length")+ .then(|| value.trim().parse::<usize>().ok())+ .flatten()+ }) {+ if bytes.len() >= header_end + 4 + length {+ break;+ }+ }+ }+ }+ let body_start = bytes.windows(4).position(|part| part == b"\r\n\r\n")? + 4;+ let value: serde_json::Value = serde_json::from_slice(&bytes[body_start..]).ok()?;+ let url = value.get("webSocketDebuggerUrl")?.as_str()?.to_owned();+ (loopback_websocket_port(&url) == Some(port)).then_some(url)+ })+ .await+ .ok()+ .flatten()+}++#[async_trait]+impl BrowserPlatform for WindowsBrowserPlatform {+ async fn classify_browser(&self, pid: i64) -> Result<BrowserClassification, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Windows process-id range"),+ )+ })?;+ let name = tokio::task::spawn_blocking(move || {+ crate::win32::list_processes()+ .into_iter()+ .find(|process| process.pid == pid_u32)+ .map(|process| process.name)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("browser process {pid} is no longer available"),+ )+ })?;+ let chromium = is_chromium(&name);+ let gecko = is_firefox(&name);+ Ok(BrowserClassification {+ is_browser: chromium || gecko,+ engine: if chromium {+ BrowserEngineFamily::Chromium+ } else if gecko {+ BrowserEngineFamily::Gecko+ } else {+ BrowserEngineFamily::Unknown+ },+ product: Some(name),+ channel: None,+ supports_cdp: chromium,+ })+ }++ async fn native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<NativeWindowInfo, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Windows process-id range"),+ )+ })?;+ let window = tokio::task::spawn_blocking(move || {+ crate::win32::list_windows(Some(pid_u32))+ .into_iter()+ .find(|window| window.hwnd == window_id)+ })+ .await+ .ok()+ .flatten()+ .ok_or_else(|| {+ refusal(+ BrowserRefusalCode::BrowserBindingStale,+ format!("Windows window {window_id} is not owned by pid {pid}"),+ )+ })?;+ // CDP Browser.getWindowBounds reports Chromium's outer Win32 rect,+ // including the invisible resize border. General window enumeration+ // intentionally uses DWM's visible frame instead, so obtain the+ // correlation geometry directly from GetWindowRect here.+ let bounds = cdp_comparable_window_bounds(window_id)?;+ Ok(NativeWindowInfo {+ pid,+ window_id,+ title: window.title,+ bounds,+ geometry_exact: true,+ ownership: NativeOwnershipProof {+ method: NativeOwnershipMethod::WindowServerOwner,+ owner_pid: pid,+ detail: Some("GetWindowThreadProcessId".to_owned()),+ },+ })+ }++ async fn is_only_exact_native_window(+ &self,+ pid: i64,+ window_id: u64,+ ) -> Result<Option<bool>, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Windows process-id range"),+ )+ })?;+ let windows = tokio::task::spawn_blocking(move || {+ crate::win32::list_windows(Some(pid_u32))+ .into_iter()+ .map(|window| window.hwnd)+ .collect::<Vec<_>>()+ })+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("could not enumerate Windows browser windows: {error}"),+ )+ })?;+ Ok(Some(windows.len() == 1 && windows[0] == window_id))+ }++ async fn discover_owned_endpoint(+ &self,+ pid: i64,+ ) -> Result<Option<OwnedEndpoint>, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Windows process-id range"),+ )+ })?;+ for port in loopback_ports_for_pid(pid_u32).await? {+ if let Some(ws_url) = browser_websocket_url(port).await {+ return Ok(Some(OwnedEndpoint {+ ws_url,+ http_port: Some(port),+ ownership: EndpointOwnershipProof {+ method: EndpointOwnershipMethod::ListeningSocketPid,+ owner_pid: pid,+ detail: Some("netstat listener owner pid".to_owned()),+ },+ }));+ }+ }+ Ok(None)+ }++ async fn process_fingerprint(&self, pid: i64) -> Result<ProcessFingerprint, BrowserRefusal> {+ let pid_u32 = u32::try_from(pid).map_err(|_| {+ refusal(+ BrowserRefusalCode::BrowserWrongTargetRefused,+ format!("pid {pid} is outside the Windows process-id range"),+ )+ })?;+ let (start_time, executable) =+ tokio::task::spawn_blocking(move || process_identity(pid_u32))+ .await+ .map_err(|error| {+ refusal(+ BrowserRefusalCode::BrowserRouteUnavailable,+ format!("process fingerprint task failed: {error}"),+ )+ })??;+ Ok(ProcessFingerprint {+ pid,+ start_time: Some(start_time),+ executable,+ })+ }++ async fn prepare_endpoint(+ &self,+ request: PrepareRequest,+ ) -> Result<PrepareOutcome, BrowserRefusal> {+ if let Some(endpoint) = self.discover_owned_endpoint(request.pid).await? {+ return Ok(PrepareOutcome {+ action: PrepareAction::AlreadyPrepared,+ prepared_pid: Some(endpoint.ownership.owner_pid),+ endpoint: Some(endpoint),+ message: "An owned loopback DevTools endpoint is already available.".to_owned(),+ side_effects: Default::default(),+ });+ }+ Err(refusal(+ BrowserRefusalCode::BrowserRequiresSetup,+ "No owned endpoint is available. Acting setup is handled by shared core only for a verified driver-owned isolated profile.",+ ))+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn netstat_parser_requires_loopback_listening_and_exact_pid() {+ let input = "\+ TCP 127.0.0.1:9222 0.0.0.0:0 LISTENING 42\n\+ TCP 0.0.0.0:9333 0.0.0.0:0 LISTENING 42\n\+ TCP [::1]:9444 [::]:0 LISTENING 42\n\+ TCP 127.0.0.1:9555 0.0.0.0:0 LISTENING 7\n";+ assert_eq!(parse_netstat_loopback_ports(input, 42), vec![9222, 9444]);+ }++ #[test]+ fn classifier_covers_embedded_and_standalone_chromium() {+ assert!(is_chromium("CuaTestHarness.Electron.exe"));+ assert!(is_chromium("msedge.exe"));+ assert!(!is_chromium("firefox.exe"));+ assert!(!is_chromium("Operator.exe"));+ assert!(!is_chromium("Knowledge.exe"));+ }++ #[test]+ fn firefox_classifier_uses_product_tokens() {+ assert!(is_firefox("firefox.exe"));+ assert!(is_firefox("Mozilla Firefox.exe"));+ assert!(!is_firefox("FirefoxHelper.exe"));+ assert!(!is_firefox("waterfox.exe"));+ }++ #[test]+ fn websocket_url_must_keep_the_attested_listener_port() {+ assert_eq!(+ loopback_websocket_port("ws://[::1]:9222/devtools/browser/id"),+ Some(9222)+ );+ assert_ne!(+ loopback_websocket_port("ws://127.0.0.1:9333/devtools/browser/foreign"),+ Some(9222)+ );+ assert_eq!(+ loopback_websocket_port("wss://127.0.0.1:9222/devtools"),+ None+ );+ }+}diff --git a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs b/libs/cua-driver/rust/crates/platform-windows/src/lib.rsindex 3addf38d7e..cbe83405d5 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/lib.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/lib.rs@@ -43,6 +43,9 @@ pub mod lparam;#[cfg(target_os = "windows")]pub mod win32;+#[cfg(target_os = "windows")]+pub mod browser_platform;+#[cfg(target_os = "windows")]pub mod uia;diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rsindex 404b6c4f50..78551bad0b 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs@@ -65,9 +65,8 @@ fn resolve_onscreen_point_with_scroll(// visible control covering the stale point (for example a bottom toolbar).if let Some(retained) = element_cache.get_element_retained(pid, hwnd, idx) {if retained.is_uia() {- let is_offscreen = unsafe {- crate::uia::scroll::element_is_offscreen(retained.as_ptr())- };+ let is_offscreen =+ unsafe { crate::uia::scroll::element_is_offscreen(retained.as_ptr()) };if cached_center_in_window && is_offscreen != Some(true) {return Ok((cx, cy));}@@ -1523,6 +1522,11 @@ async fn restore_foreground_polling_best_effort(prior_foreground_addr: usize, sppub struct LaunchAppTool;static LAUNCH_DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();+fn contains_remote_debugging_flag(value: &str) -> bool {+ let lower = value.to_ascii_lowercase();+ lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")+}+#[async_trait]impl Tool for LaunchAppTool {fn def(&self) -> &ToolDef {@@ -1558,11 +1562,11 @@ impl Tool for LaunchAppTool {`null` for ShellExecuteEx launches.\n\n\Windows-only field: `path` (Swift uses `bundle_id` since macOS apps resolve via \LaunchServices; Windows has no LaunchServices, so `path` is the canonical form). \- The macOS-specific `cdp_debugging_port`, `webkit_inspector_port`, \+ The macOS-specific `webkit_inspector_port`, \`creates_new_application_instance`, and `additional_arguments` fields are \accepted; `additional_arguments` is honored (forwarded as ShellExecuteEx \- parameters or as the AUMID activation arguments string), the others currently \- no-op on Windows.".into(),+ parameters or as the AUMID activation arguments string). \+ The remaining macOS-only fields currently no-op on Windows.".into(),input_schema: json!({"type":"object","properties":{"bundle_id":{"type":"string","description":"App User Model ID (AUMID) for a packaged app — pattern `{PackageFamilyName}!{ApplicationId}`, e.g. `Microsoft.WindowsNotepad_8wekyb3d8bbwe!App`. Falls back to a `name` alias if no `!` is present. Either bundle_id, name, aumid, path, or launch_path must be provided."},"aumid":{"type":"string","description":"Explicit AUMID for a packaged app. Cleaner alternative to overloading `bundle_id`. Takes precedence over `bundle_id` / `name` when present."},@@ -1571,7 +1575,6 @@ impl Tool for LaunchAppTool {"launch_path":{"type":"string","description":"Round-trip the `launch_path` returned by `list_apps`. Highest precedence — when set, this exact string is handed to ShellExecuteEx unchanged. For Windows desktop apps it's the full `.exe` commandline (path + arguments preserved from the source shortcut); for UWP apps it's `shell:appsFolder\\{PackageFamilyName}!{AppId}`. For precise UWP pid capture, prefer `aumid` over `launch_path`."},"urls":{"type":"array","items":{"type":"string"},"description":"URLs to open in the default browser via ShellExecuteEx (no activation)."},"additional_arguments":{"type":"array","items":{"type":"string"},"description":"Extra command-line arguments passed to the launched process (or activation arguments for packaged apps)."},- "cdp_debugging_port":{"type":"integer","description":"Accepted for cross-platform parity; currently no-op on Windows."},"webkit_inspector_port":{"type":"integer","description":"Accepted for cross-platform parity; no-op on Windows."},"creates_new_application_instance":{"type":"boolean","description":"Accepted for parity; no-op on Windows (ShellExecuteEx always creates a new process)."},"start_minimized":{"type":"boolean","description":"When true, launch the app's window minimized to the taskbar instead of restored-but-not-activated. Use this when the agent wants to drive the app entirely in the background — the user's previously-frontmost window (e.g. terminal) stays visually on top. Desktop launches hold the foreground lock through startup and use SW_SHOWMINNOACTIVE; packaged-app activation remains broker-controlled and receives a best-effort SW_SHOWMINNOACTIVE post-pass. UIA / background dispatch still work on a minimized window; only `screenshot` and `delivery_mode:\"foreground\"` need it restored."}@@ -1678,6 +1681,23 @@ impl Tool for LaunchAppTool {.collect()}).unwrap_or_default();+ if args.get("cdp_debugging_port").is_some() {+ return ToolResult::error(+ "cdp_debugging_port moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }+ if launch_path_opt+ .as_deref()+ .into_iter()+ .chain(path_opt.as_deref())+ .chain(name_opt.as_deref())+ .chain(extra_args.iter().map(String::as_str))+ .any(contains_remote_debugging_flag)+ {+ return ToolResult::error(+ "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ );+ }// Resolve target — launch_path > path > aumid > name > bundle_id// (alias of name on Windows). launch_path is highest precedence for@@ -1891,7 +1911,9 @@ impl Tool for LaunchAppTool {let args_w = to_wide(&extra_for_shell);let pid = if direct_minimized_exe {- let target = target_for_shell.as_deref().expect("checked executable path");+ let target = target_for_shell+ .as_deref()+ .expect("checked executable path");let mut command_line = to_wide(&if extra_for_shell.is_empty() {format!(r#""{target}""#)} else {@@ -2284,7 +2306,7 @@ impl Tool for LaunchAppTool {use std::collections::HashSet;use windows::Win32::Foundation::HWND;use windows::Win32::UI::WindowsAndMessaging::{- IsIconic, SW_SHOWMINNOACTIVE, ShowWindow,+ IsIconic, ShowWindow, SW_SHOWMINNOACTIVE,};let _foreground_lock = launch_foreground_lock;let mut minimized: HashSet<u64> = immediate_hwnds_for_poll.into_iter().collect();@@ -2532,12 +2554,14 @@ impl Tool for ClickTool {};let target = WindowFromPoint(POINT { x: sx, y: sy });if target.0.is_null() {- return ToolResult::error(format!(- "No window under screen point ({sx},{sy})."- ));+ return ToolResult::error(format!("No window under screen point ({sx},{sy})."));}let root = GetAncestor(target, GA_ROOT);- if root.0.is_null() { target } else { root }+ if root.0.is_null() {+ target+ } else {+ root+ }};let hwnd_u = root.0 as u64;@@ -4228,10 +4252,10 @@ impl Tool for PressKeyTool {None};if let Some(idx) = elem_idx.filter(|_| background_webview_focus) {- let Some((cx, cy)) = self- .state- .element_cache- .get_element_center(pid, hwnd, idx as usize)+ let Some((cx, cy)) =+ self.state+ .element_cache+ .get_element_center(pid, hwnd, idx as usize)else {return ToolResult::error(format!("Element {idx} not in cache for hwnd={hwnd}. Call get_window_state first."@@ -7273,7 +7297,8 @@ impl Tool for GetConfigTool {same fallback the daemon uses at startup. Sibling to `set_config`.\n\n\Current schema (Windows):\n\n \{\n \"schema_version\": 1,\n \"version\": \"<crate version>\",\n \- \"platform\": \"windows\",\n \"capture_mode\": \"ax\" | \"vision\" (DEPRECATED, ignored),\n \+ \"source_sha\": \"<maintainer build commit or null>\",\n \"platform\": \"windows\",\n \+ \"capture_mode\": \"ax\" | \"vision\" (DEPRECATED, ignored),\n \\"max_image_dimension\": 0\n }\n\n\`capture_mode` is deprecated and no longer affects behavior — \`get_window_state` always returns both the UIA tree and a screenshot.".into(),@@ -7294,6 +7319,7 @@ impl Tool for GetConfigTool {let payload = json!({"schema_version": 1,"version": env!("CARGO_PKG_VERSION"),+ "source_sha": option_env!("CUA_DRIVER_SOURCE_SHA"),"platform": "windows","capture_mode": cfg.capture_mode,"capture_scope": cfg.capture_scope,@@ -7492,6 +7518,7 @@ impl Tool for SetConfigTool {let payload = json!({"schema_version": 1,"version": env!("CARGO_PKG_VERSION"),+ "source_sha": option_env!("CUA_DRIVER_SOURCE_SHA"),"platform": "windows","capture_mode": cfg.capture_mode,"capture_scope": cfg.capture_scope,@@ -7867,100 +7894,100 @@ impl Tool for BringToFrontTool {// Edge launch focus-steal recovery case.let outcome =tokio::task::spawn_blocking(move || -> Result<(u64, u64, bool, bool), String> {- use windows::Win32::Foundation::HWND;- use windows::Win32::Graphics::Dwm::DwmFlush;- use windows::Win32::System::Threading::{AttachThreadInput, GetCurrentThreadId};- use windows::Win32::UI::WindowsAndMessaging::{- GetForegroundWindow, GetWindowThreadProcessId, IsIconic, IsWindow,- SetForegroundWindow, SetWindowPos, ShowWindowAsync, HWND_NOTOPMOST, HWND_TOPMOST,- SWP_NOACTIVATE, SWP_NOMOVE, SWP_NOSIZE, SW_RESTORE,- };-- let target = HWND(hwnd as *mut _);- if !unsafe { IsWindow(target) }.as_bool() {- return Err(format!("hwnd 0x{hwnd:x} is not a valid window"));- }+ use windows::Win32::Foundation::HWND;+ use windows::Win32::Graphics::Dwm::DwmFlush;+ use windows::Win32::System::Threading::{AttachThreadInput, GetCurrentThreadId};+ use windows::Win32::UI::WindowsAndMessaging::{+ GetForegroundWindow, GetWindowThreadProcessId, IsIconic, IsWindow,+ SetForegroundWindow, SetWindowPos, ShowWindowAsync, HWND_NOTOPMOST,+ HWND_TOPMOST, SWP_NOACTIVATE, SWP_NOMOVE, SWP_NOSIZE, SW_RESTORE,+ };- let prev_fg = unsafe { GetForegroundWindow() };- let prev_fg_addr = prev_fg.0 as u64;+ let target = HWND(hwnd as *mut _);+ if !unsafe { IsWindow(target) }.as_bool() {+ return Err(format!("hwnd 0x{hwnd:x} is not a valid window"));+ }- // Iconic windows have no rendered pixels and live at the sentinel- // (-32000, -32000) position. Restore before changing z-order so- // bring_to_front is also the advertised recovery path for capture.- let was_minimized = unsafe { IsIconic(target) }.as_bool();- if was_minimized {- let _ = unsafe { ShowWindowAsync(target, SW_RESTORE) };- for _ in 0..20 {- if !unsafe { IsIconic(target) }.as_bool() {- break;+ let prev_fg = unsafe { GetForegroundWindow() };+ let prev_fg_addr = prev_fg.0 as u64;++ // Iconic windows have no rendered pixels and live at the sentinel+ // (-32000, -32000) position. Restore before changing z-order so+ // bring_to_front is also the advertised recovery path for capture.+ let was_minimized = unsafe { IsIconic(target) }.as_bool();+ if was_minimized {+ let _ = unsafe { ShowWindowAsync(target, SW_RESTORE) };+ for _ in 0..20 {+ if !unsafe { IsIconic(target) }.as_bool() {+ break;+ }+ std::thread::sleep(std::time::Duration::from_millis(25));+ }+ if unsafe { IsIconic(target) }.as_bool() {+ return Err(format!(+ "restore request did not complete for minimized hwnd 0x{hwnd:x}"+ ));}- std::thread::sleep(std::time::Duration::from_millis(25));- }- if unsafe { IsIconic(target) }.as_bool() {- return Err(format!(- "restore request did not complete for minimized hwnd 0x{hwnd:x}"- ));}- }- // Lock-free z-order raise FIRST: bring the window to the top of the- // normal band (the HWND_TOPMOST→HWND_NOTOPMOST force-to-front trick)- // so it's brought to the VISIBLE front even when the foreground-lock- // denies focus. SWP_NOACTIVATE → no focus steal; SetWindowPos z-order- // is not gated by the foreground-lock / UIAccess. This is the same- // technique the delivery_mode:"foreground" pointer path uses.- let raised = unsafe {- let a = SetWindowPos(- target,- HWND_TOPMOST,- 0,- 0,- 0,- 0,- SWP_NOACTIVATE | SWP_NOMOVE | SWP_NOSIZE,- )- .is_ok();- let b = SetWindowPos(- target,- HWND_NOTOPMOST,- 0,- 0,- 0,- 0,- SWP_NOACTIVATE | SWP_NOMOVE | SWP_NOSIZE,- )- .is_ok();- a && b- };+ // Lock-free z-order raise FIRST: bring the window to the top of the+ // normal band (the HWND_TOPMOST→HWND_NOTOPMOST force-to-front trick)+ // so it's brought to the VISIBLE front even when the foreground-lock+ // denies focus. SWP_NOACTIVATE → no focus steal; SetWindowPos z-order+ // is not gated by the foreground-lock / UIAccess. This is the same+ // technique the delivery_mode:"foreground" pointer path uses.+ let raised = unsafe {+ let a = SetWindowPos(+ target,+ HWND_TOPMOST,+ 0,+ 0,+ 0,+ 0,+ SWP_NOACTIVATE | SWP_NOMOVE | SWP_NOSIZE,+ )+ .is_ok();+ let b = SetWindowPos(+ target,+ HWND_NOTOPMOST,+ 0,+ 0,+ 0,+ 0,+ SWP_NOACTIVATE | SWP_NOMOVE | SWP_NOSIZE,+ )+ .is_ok();+ a && b+ };- // Then best-effort focus/activation (needed for keyboard) via the- // AttachThreadInput trick — inherits the current FG thread's FG-lock- // token so SetForegroundWindow can succeed at Medium IL. Still denied- // on a maxed lock without UIAccess; the z-raise already made the- // window visible regardless.- let my_tid = unsafe { GetCurrentThreadId() };- let mut fg_pid = 0u32;- let fg_tid = unsafe { GetWindowThreadProcessId(prev_fg, Some(&mut fg_pid)) };- let attached = fg_tid != 0 && fg_tid != my_tid;- if attached {- let _ = unsafe { AttachThreadInput(my_tid, fg_tid, true) };- }- let _ = unsafe { SetForegroundWindow(target) };- if attached {- let _ = unsafe { AttachThreadInput(my_tid, fg_tid, false) };- }- let now_fg = unsafe { GetForegroundWindow() };-- // A restored HWND can stop reporting iconic before its compositor- // surface is painted. Flush DWM before returning, but do not make- // the restore operation depend on any particular capture backend.- // Capture has its own WGC fallback for freshly restored surfaces.- if was_minimized {- let _ = unsafe { DwmFlush() };- }- Ok((prev_fg_addr, now_fg.0 as u64, raised, was_minimized))- })- .await;+ // Then best-effort focus/activation (needed for keyboard) via the+ // AttachThreadInput trick — inherits the current FG thread's FG-lock+ // token so SetForegroundWindow can succeed at Medium IL. Still denied+ // on a maxed lock without UIAccess; the z-raise already made the+ // window visible regardless.+ let my_tid = unsafe { GetCurrentThreadId() };+ let mut fg_pid = 0u32;+ let fg_tid = unsafe { GetWindowThreadProcessId(prev_fg, Some(&mut fg_pid)) };+ let attached = fg_tid != 0 && fg_tid != my_tid;+ if attached {+ let _ = unsafe { AttachThreadInput(my_tid, fg_tid, true) };+ }+ let _ = unsafe { SetForegroundWindow(target) };+ if attached {+ let _ = unsafe { AttachThreadInput(my_tid, fg_tid, false) };+ }+ let now_fg = unsafe { GetForegroundWindow() };++ // A restored HWND can stop reporting iconic before its compositor+ // surface is painted. Flush DWM before returning, but do not make+ // the restore operation depend on any particular capture backend.+ // Capture has its own WGC fallback for freshly restored surfaces.+ if was_minimized {+ let _ = unsafe { DwmFlush() };+ }+ Ok((prev_fg_addr, now_fg.0 as u64, raised, was_minimized))+ })+ .await;match outcome {Ok(Ok((prev, now, raised, restored))) => {@@ -8523,6 +8550,10 @@ pub fn build_registry(compat: bool) -> ToolRegistry {r.register(Box::new(cua_driver_core::page::PageTool::new(std::sync::Arc::new(super::page::WindowsPageBackend::new()),)));+ let browser_engine = cua_driver_core::browser::BrowserEngine::new(std::sync::Arc::new(+ crate::browser_platform::WindowsBrowserPlatform,+ ));+ cua_driver_core::browser::register_browser_tools(&browser_engine, &mut r);r.register_recording_tools();r.register_session_tools();r@@ -8941,3 +8972,20 @@ mod desktop_scope_tests {assert_eq!(d.input_schema["additionalProperties"], json!(false));}}++#[cfg(test)]+mod browser_launch_guard_tests {+ use super::contains_remote_debugging_flag;++ #[test]+ fn rejects_all_chromium_remote_debugging_spellings() {+ assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));+ assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));+ assert!(contains_remote_debugging_flag(+ r#"C:\Program Files\Chrome\chrome.exe --remote-debugging-port 9222"#+ ));+ assert!(!contains_remote_debugging_flag(+ r#"--user-data-dir=C:\Temp\profile"#+ ));+ }+}diff --git a/libs/cua-driver/scripts/_install-local-rust.sh b/libs/cua-driver/scripts/_install-local-rust.shindex ccc27802ba..f1f6265438 100755--- a/libs/cua-driver/scripts/_install-local-rust.sh+++ b/libs/cua-driver/scripts/_install-local-rust.sh@@ -336,16 +336,26 @@ ensure_local_signing_identity() {codesign_bounded() {local timeout_seconds="$1"shift- local keychain_args=()- if [ -n "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ]; then- keychain_args=(--keychain "$CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN")- fiif command -v gtimeout >/dev/null 2>&1; then- gtimeout "$timeout_seconds" codesign "${keychain_args[@]}" "$@"+ if [ -n "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ]; then+ gtimeout "$timeout_seconds" codesign \+ --keychain "$CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN" "$@"+ else+ gtimeout "$timeout_seconds" codesign "$@"+ fielif command -v perl >/dev/null 2>&1; then- perl -e 'alarm shift; exec @ARGV' "$timeout_seconds" codesign "${keychain_args[@]}" "$@"+ if [ -n "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ]; then+ perl -e 'alarm shift; exec @ARGV' "$timeout_seconds" codesign \+ --keychain "$CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN" "$@"+ else+ perl -e 'alarm shift; exec @ARGV' "$timeout_seconds" codesign "$@"+ fielse- codesign "${keychain_args[@]}" "$@"+ if [ -n "${CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN:-}" ]; then+ codesign --keychain "$CUA_DRIVER_LOCAL_SIGNING_KEYCHAIN" "$@"+ else+ codesign "$@"+ fifi}diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/main.js b/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/main.jsindex 8f027d1117..fa06203603 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/main.js+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/main.js@@ -8,6 +8,7 @@ const fs = require('fs');const http = require('http');const path = require('path');const sentinelMode = process.env.CUA_E2E_SENTINEL === '1';+const nativeWayland = process.platform === 'linux' && Boolean(process.env.WAYLAND_DISPLAY);const fixtureJournalUrl = process.env.CUA_E2E_FIXTURE_JOURNAL_URL || '';const sentinelJournalPath = process.env.CUA_E2E_SENTINEL_JOURNAL || '';if (process.env.CUA_E2E_USER_DATA_DIR) {@@ -80,7 +81,7 @@ function createWindow() {// A floating-level macOS window is omitted by cua-driver's deliberate// layer-0 top-level window contract. Foreground + maximized is sufficient// for occlusion there and lets an unexpected target raise remain visible.- alwaysOnTop: sentinelMode && process.platform !== 'darwin',+ alwaysOnTop: sentinelMode && process.platform !== 'darwin' && !nativeWayland,autoHideMenuBar: true,webPreferences: {nodeIntegration: false,@@ -121,7 +122,7 @@ function createWindow() {if (mainWindow && !mainWindow.isDestroyed()) {mainWindow.setTitle(fixedTitle);if (sentinelMode) {- if (process.platform !== 'darwin') {+ if (process.platform !== 'darwin' && !nativeWayland) {mainWindow.setAlwaysOnTop(true);}if (process.platform === 'linux' && process.env.WAYLAND_DISPLAY) {diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.ps1 b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.ps1index dc0e39c211..a517b47403 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.ps1+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.ps1@@ -24,11 +24,11 @@ if (-not (Test-Path $webDir)) { New-Item -ItemType Directory $webDir | Out-NullCopy-Item (Join-Path $harnessDir "shared\web\*") $webDir -Recurse -Force$manifest = Join-Path $tauriDir "src-tauri\Cargo.toml"-Write-Host "[BUILD] cargo build --release --manifest-path $manifest" -ForegroundColor Cyan+Write-Host "[BUILD] cargo build --release --features custom-protocol --manifest-path $manifest" -ForegroundColor Cyan$oldTargetDir = $env:CARGO_TARGET_DIR$env:CARGO_TARGET_DIR = Join-Path $tauriDir "src-tauri\target"try {- & cargo build --release --manifest-path $manifest+ & cargo build --release --features custom-protocol --manifest-path $manifest} finally {$env:CARGO_TARGET_DIR = $oldTargetDir}diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.sh b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.shindex ef10bd5976..d4bd8389e0 100755--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.sh+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/build.sh@@ -22,9 +22,10 @@ fimkdir -p "$tauriDir/web"cp -r "$harnessDir/shared/web/." "$tauriDir/web/"-echo "[BUILD] cargo build --release ..."+echo "[BUILD] cargo build --release --features custom-protocol ..."CARGO_TARGET_DIR="$tauriDir/src-tauri/target" \- cargo build --release --manifest-path "$tauriDir/src-tauri/Cargo.toml"+ cargo build --release --features custom-protocol \+ --manifest-path "$tauriDir/src-tauri/Cargo.toml"rm -rf "$outDir"mkdir -p "$outDir"diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/Cargo.toml b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/Cargo.tomlindex 2b6401a089..2e8fd68cf1 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/Cargo.toml+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/Cargo.toml@@ -5,8 +5,12 @@ description = "cua-driver Tauri test harness"edition = "2021"rust-version = "1.77"+[features]+custom-protocol = ["tauri/custom-protocol"]+[build-dependencies]tauri-build = { version = "2" }[dependencies]tauri = { version = "2", features = [] }+tiny_http = "0.12"diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/build.rs b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/build.rsindex d860e1e6a7..a76fb2be18 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/build.rs+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/build.rs@@ -1,3 +1,5 @@fn main() {+ println!("cargo:rerun-if-changed=../web");+ println!("cargo:rerun-if-changed=tauri.conf.json");tauri_build::build()}diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/src/main.rs b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/src/main.rsindex f974558e81..0b051bab82 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/src/main.rs+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/src/main.rs@@ -1,5 +1,28 @@#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]+use std::thread;++const FIXTURE_HTML: &[u8] = include_bytes!("../../web/index.html");++fn fixture_url() -> tauri::Url {+ let server = tiny_http::Server::http("127.0.0.1:0").expect("bind Tauri fixture server");+ let address = server+ .server_addr()+ .to_ip()+ .expect("Tauri fixture server must use an IP address");+ thread::spawn(move || {+ for request in server.incoming_requests() {+ let content_type =+ tiny_http::Header::from_bytes(b"Content-Type", b"text/html; charset=utf-8")+ .expect("valid fixture response header");+ let response = tiny_http::Response::from_data(FIXTURE_HTML).with_header(content_type);+ let _ = request.respond(response);+ }+ });++ tauri::Url::parse(&format!("http://{address}/")).expect("valid Tauri fixture URL")+}+fn main() {let journal_url = std::env::var("CUA_E2E_FIXTURE_JOURNAL_URL").unwrap_or_default();let journal_plugin = tauri::plugin::Builder::<tauri::Wry, ()>::new("e2e-journal")@@ -9,15 +32,24 @@ fn main() {.build();tauri::Builder::default().plugin(journal_plugin)- .setup(|_app| {+ .setup(|app| {+ #[cfg(target_os = "windows")]+ let height = 640.0;+ #[cfg(not(target_os = "windows"))]+ let height = 760.0;++ let window = tauri::WebviewWindowBuilder::new(+ app,+ "main",+ tauri::WebviewUrl::External(fixture_url()),+ )+ .title("CuaTestHarness Tauri")+ .inner_size(900.0, height)+ .resizable(true);#[cfg(target_os = "windows")]- {- use tauri::{LogicalSize, Manager, Size};+ let window = window.position(40.0, 40.0);- _app.get_webview_window("main")- .expect("Tauri main fixture window")- .set_size(Size::Logical(LogicalSize::new(900.0, 640.0)))?;- }+ window.build()?;Ok(())}).run(tauri::generate_context!())diff --git a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/tauri.conf.json b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/tauri.conf.jsonindex c994485b39..fa67cb4303 100644--- a/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/tauri.conf.json+++ b/libs/cua-driver/tests/fixtures/apps/cross-platform/tauri/src-tauri/tauri.conf.json@@ -9,15 +9,7 @@"frontendDist": "../web"},"app": {- "windows": [- {- "label": "main",- "title": "CuaTestHarness Tauri",- "width": 900,- "height": 760,- "resizable": true- }- ],+ "windows": [],"security": {"csp": null}diff --git a/libs/cua-driver/tests/fixtures/apps/windows/webview2/MainWindow.xaml b/libs/cua-driver/tests/fixtures/apps/windows/webview2/MainWindow.xamlindex 6c1dbb0893..9de361b26d 100644--- a/libs/cua-driver/tests/fixtures/apps/windows/webview2/MainWindow.xaml+++ b/libs/cua-driver/tests/fixtures/apps/windows/webview2/MainWindow.xaml@@ -4,8 +4,9 @@xmlns:wv2="clr-namespace:Microsoft.Web.WebView2.Wpf;assembly=Microsoft.Web.WebView2.Wpf"Title="Loading WebView2 fixture"AutomationProperties.AutomationId="wnd-main"- Width="900" Height="650"- WindowStartupLocation="CenterScreen">+ Width="900" Height="640"+ Left="40" Top="40"+ WindowStartupLocation="Manual"><DockPanel LastChildFill="True"><Border DockPanel.Dock="Top" Background="#F0F0F0" Padding="10,6"><StackPanel Orientation="Horizontal">diff --git a/libs/cua-driver/tests/fixtures/shared/web/index.html b/libs/cua-driver/tests/fixtures/shared/web/index.htmlindex 4b58b8ad4d..1bf54c56d5 100644--- a/libs/cua-driver/tests/fixtures/shared/web/index.html+++ b/libs/cua-driver/tests/fixtures/shared/web/index.html@@ -359,10 +359,13 @@for (const event of ['input', 'change', 'keydown', 'pointerup', 'scroll']) {document.addEventListener(event, queuePublish, true);}- // Keep the external oracle live even when its first loopback POST races- // fixture startup or a host bridge drops one fire-and-forget message.- setInterval(queuePublish, 250);- queuePublish();+ // Start network publication only after navigation completes. WebKit hosts+ // backed by a custom scheme can otherwise keep the initial page load open+ // while the first loopback request is in flight.+ window.addEventListener('load', () => {+ setInterval(queuePublish, 250);+ queuePublish();+ }, { once: true });})();</script></body>diff --git a/libs/cua-driver/tests/runners/macos-lume/README.md b/libs/cua-driver/tests/runners/macos-lume/README.mdindex cbfdf05d9e..b4a9f71e74 100644--- a/libs/cua-driver/tests/runners/macos-lume/README.md+++ b/libs/cua-driver/tests/runners/macos-lume/README.md@@ -263,6 +263,21 @@ cd ~/cualibs/cua-driver/tests/runners/macos-lume/run-all.sh```+When Chrome or Edge is installed in the disposable worker, include the optional+standalone browser-tool matrix in the same exact-source run:++```bash+cd ~/cua+libs/cua-driver/tests/runners/macos-lume/run-all.sh --standalone-browser+```++This adds eight adversarial installed-browser rows and writes their separate+typed results and MP4 evidence under+`artifacts/cua-driver/macos-standalone-browser/`. Missing external browsers are+a hard failure for this option; they never shrink the reported matrix. On a+repeat run, the entrypoint preserves the previous standalone-browser evidence+in a temporary archive before creating a fresh artifact directory.+The entrypoint refuses the wrong OS, user session, SIP state, dirty orunidentified source, missing dependencies, ad-hoc signature, stale installeddaemon, unusable TCC grants, or missing Terminal/CuaDriver Automation grants.@@ -274,6 +289,10 @@ Pull evidence before deleting the worker, even after a failed run:REMOTE_ARTIFACT_DIR=artifacts/cua-driver/macos \libs/cua-driver/scripts/sync-vm-worktree.sh pull-artifacts \"lume@${VM_IP}" '~/cua'+# Also retrieve this directory when --standalone-browser was used.+REMOTE_ARTIFACT_DIR=artifacts/cua-driver/macos-standalone-browser \+ libs/cua-driver/scripts/sync-vm-worktree.sh pull-artifacts \+ "lume@${VM_IP}" '~/cua'lume stop "$WORKER"lume delete "$WORKER" --force```diff --git a/libs/cua-driver/tests/runners/macos-lume/run-all.sh b/libs/cua-driver/tests/runners/macos-lume/run-all.shindex 21ce1adac0..46866e3df4 100755--- a/libs/cua-driver/tests/runners/macos-lume/run-all.sh+++ b/libs/cua-driver/tests/runners/macos-lume/run-all.sh@@ -13,17 +13,23 @@ SIGNING_CN="CuaDriver Local Signing (cua-driver-rs)"usage() {cat <<'EOF'-Usage: run-all.sh [--no-build]+Usage: run-all.sh [--no-build] [--standalone-browser]Run the canonical cua-driver macOS GUI E2E matrix in a disposable clone ofthe maintainer Lume golden image. Start this command from Terminal in the VM'slogged-in desktop session, not over SSH.++--standalone-browser also runs the optional installed Chrome/Edge browser-tool+matrix after the canonical repo-local harness matrix.EOF}+RUN_STANDALONE_BROWSER=0+NO_BUILD=0for arg in "$@"; docase "${arg}" in- --no-build) ;;+ --no-build) NO_BUILD=1 ;;+ --standalone-browser) RUN_STANDALONE_BROWSER=1 ;;-h|--help) usage; exit 0 ;;*) echo "unknown argument: ${arg}" >&2; usage >&2; exit 2 ;;esac@@ -169,4 +175,21 @@ if ! "${INSTALLED_BIN}" list_apps '{}' > "${ARTIFACT_DIR}/driver-list-apps.json"fiecho "[E2E] Running the canonical macOS matrix"-exec "${REPO_ROOT}/scripts/ci/macos/run-rust-e2e.sh" "$@"+if [[ "${NO_BUILD}" == 1 ]]; then+ "${REPO_ROOT}/scripts/ci/macos/run-rust-e2e.sh" --no-build+else+ "${REPO_ROOT}/scripts/ci/macos/run-rust-e2e.sh"+fi++if [[ "${RUN_STANDALONE_BROWSER}" == 1 ]]; then+ echo "[E2E] Running the optional standalone browser matrix"+ BROWSER_ARTIFACT_DIR="${REPO_ROOT}/artifacts/cua-driver/macos-standalone-browser"+ if [[ -d "${BROWSER_ARTIFACT_DIR}" ]] \+ && [[ -n "$(find "${BROWSER_ARTIFACT_DIR}" -mindepth 1 -print -quit)" ]]; then+ BROWSER_ARTIFACT_ARCHIVE="$(mktemp -d "${TMPDIR:-/tmp}/cua-macos-browser-e2e.XXXXXX")"+ mv "${BROWSER_ARTIFACT_DIR}" "${BROWSER_ARTIFACT_ARCHIVE}/macos-standalone-browser"+ echo "Previous standalone-browser evidence preserved at ${BROWSER_ARTIFACT_ARCHIVE}/macos-standalone-browser"+ fi+ CUA_E2E_ARTIFACT_DIR="${BROWSER_ARTIFACT_DIR}" \+ "${REPO_ROOT}/scripts/ci/run-rust-standalone-browser-e2e.sh"+fidiff --git a/nix/cua-driver/README.md b/nix/cua-driver/README.mdindex 1fbaa586c8..a0cb46a8d9 100644--- a/nix/cua-driver/README.md+++ b/nix/cua-driver/README.md@@ -9,7 +9,7 @@ builds and desktop-session dependencies for the canonical Rust harnesses.| `cua-driver-linux-rust-unit` | Compile and run the source-owned headless Rust tests | `ci-nix-linux.yml` || `cua-driver-policy-yaml` | Run YAML permission-policy MCP checks in a NixOS VM | Flake check || `cua-driver-policy-rego` | Run embedded Rego permission-policy MCP checks in a NixOS VM | Flake check |-| `cua-driver-wayland-e2e` | Provide the Sway, GTK, WebKit, Electron, capture, and Rust toolchain used by native Wayland E2E | `e2e-rust-linux-wayland.yml` |+| `cua-driver-wayland-e2e` | Provide the Sway, GTK, WebKit, Chromium, Electron, capture, and Rust toolchain used by native Wayland E2E | `e2e-rust-linux-wayland.yml` || `cua-driver-inject-e2e` | Provide the same typed harness toolchain plus the nested `cua-compositor` package | Experimental nested-injection workflow || `cua-compositor-build` | Build the optional compositor-owned injection backend against pinned wlroots | Flake check |diff --git a/nix/cua-driver/tests/rust-unit.nix b/nix/cua-driver/tests/rust-unit.nixindex 4764783691..1aef6e580d 100644--- a/nix/cua-driver/tests/rust-unit.nix+++ b/nix/cua-driver/tests/rust-unit.nix@@ -6,15 +6,22 @@{pkgs,src,+ sourceSubdir ? null,...}:+let+ rustSrc = if sourceSubdir == null then src else "${src}/${sourceSubdir}";+inpkgs.rustPlatform.buildRustPackage {pname = "cua-driver-rust-unit-tests";- version = (pkgs.lib.importTOML "${src}/Cargo.toml").workspace.package.version;+ version = (pkgs.lib.importTOML "${rustSrc}/Cargo.toml").workspace.package.version;inherit src;- cargoLock.lockFile = "${src}/Cargo.lock";+ cargoLock.lockFile = "${rustSrc}/Cargo.lock";+ postUnpack = pkgs.lib.optionalString (sourceSubdir != null) ''+ sourceRoot="$sourceRoot/${sourceSubdir}"+ '';cargoTestFlags = ["-p""cua-driver"diff --git a/scripts/ci/README.md b/scripts/ci/README.mdindex 7c800722f2..8233c19544 100644--- a/scripts/ci/README.md+++ b/scripts/ci/README.md@@ -4,7 +4,40 @@ These scripts are thin entrypoints around the Rust integration tests. Theybuild the repo-local fixture applications, run one strict Rust environmentpreflight, set testkit paths, execute Rust targets, invoke the Rust reportvalidator, and collect artifacts. They do not define behavioral rows, push-code, or alter branches.+code, or alter branches. The shared lane runs both the cross-platform action+catalog and the embedded-browser exact-or-refused catalog.++Standalone Chrome/Edge adversarial coverage is a separate optional real-browser+suite because it requires an installed external browser. Run it explicitly:++```bash+# macOS and Linux+scripts/ci/run-rust-standalone-browser-e2e.sh++# Windows PowerShell in a console/RDP user session+scripts/ci/windows/run-rust-standalone-browser-e2e.ps1+```++The runners require an existing desktop user session and a fresh artifact+directory. They stage the repo-owned Electron foreground sentinel when the+fixture is absent and execute each scenario in an independent Cargo process.+In a pure native Wayland session, the Unix runner also enables the driver's+native Wayland backend and launches the sentinel through Wayland, so the result+cannot silently fall back to X11. To exercise the same matrix in the repo-owned+native Sway session, run:++```bash+CUA_E2E_WAYLAND_RUNNER="$PWD/scripts/ci/run-rust-standalone-browser-e2e.sh" \+ scripts/ci/linux/run-rust-e2e-wayland.sh+```++When a Nix-store Chromium is used on a non-NixOS VM, its SUID sandbox helper+cannot carry the required root ownership. Set `CUA_E2E_BROWSER_NO_SANDBOX=1`+only for that isolated test VM; ordinary installed-browser runs keep Chromium's+sandbox enabled.++Release validation sets `CUA_TEST_REQUIRE_EXTERNAL_BROWSERS=1` so a missing+browser fails instead of silently omitting the suite.For the test layout and the distinction between unit tests, shared harnesses,and native harnesses, see@@ -28,7 +61,8 @@ The maintainer-facing macOS command is`libs/cua-driver/tests/runners/macos-lume/run-all.sh`. It verifies the privateLume seed, installs the exact committed source, and then delegates to the thin`macos/run-rust-e2e.sh` matrix runner above. There is no GitHub-hosted macOS GUI-job.+job. Pass `--standalone-browser` to run the optional installed Chrome/Edge+browser matrix after the canonical repo-local harness matrix.Run the Wayland wrapper through `nix develop .#cua-driver-wayland-e2e`. Itcreates a pure Wayland session with Xwayland disabled and delegates everydiff --git a/scripts/ci/linux/run-rust-e2e-wayland.sh b/scripts/ci/linux/run-rust-e2e-wayland.shindex c1e64e1e86..ee44b6e9ed 100755--- a/scripts/ci/linux/run-rust-e2e-wayland.sh+++ b/scripts/ci/linux/run-rust-e2e-wayland.sh@@ -7,6 +7,7 @@ REPO_ROOT="$(cd "${SCRIPT_DIR}/../../.." && pwd)"RUNTIME_DIR="$(mktemp -d)"SWAY_CONFIG="$(mktemp)"SESSION_KIND="${CUA_E2E_WAYLAND_SESSION:-sway}"+export CUA_E2E_WAYLAND_SESSION="${SESSION_KIND}"COMPOSITOR_LOG="${REPO_ROOT}/artifacts/cua-driver/linux/${SESSION_KIND}.log"ATSPI_LOG="${REPO_ROOT}/artifacts/cua-driver/linux/at-spi-bus.log"COMPOSITOR_PID=""@@ -209,8 +210,13 @@ elsefiecho "Native Wayland E2E session: ${SESSION_KIND} on ${WAYLAND_DISPLAY}"+SESSION_RUNNER="${CUA_E2E_WAYLAND_RUNNER:-${SCRIPT_DIR}/run-rust-e2e.sh}"+if [[ ! -x "${SESSION_RUNNER}" ]]; then+ echo "Wayland session runner is not executable: ${SESSION_RUNNER}" >&2+ exit 1+fiset +e-"${SCRIPT_DIR}/run-rust-e2e.sh" "$@"+"${SESSION_RUNNER}" "$@"status=$?set -eif [[ "${status}" != 0 && "${SESSION_KIND}" == sway ]]; thendiff --git a/scripts/ci/linux/run-rust-e2e.sh b/scripts/ci/linux/run-rust-e2e.shindex a01f36bbe0..40a72f12df 100755--- a/scripts/ci/linux/run-rust-e2e.sh+++ b/scripts/ci/linux/run-rust-e2e.sh@@ -64,9 +64,15 @@ if [[ ("${SUITE}" == shared || "${SUITE}" == all) \export CUA_E2E_EXPECTED_MIN_CELLS=80fiexport RUST_BACKTRACE="${RUST_BACKTRACE:-1}"-if [[ -z "${CUA_E2E_SOURCE_SHA:-}" && -f "${REPO_ROOT}/.cua-e2e-source-sha" ]]; then- export CUA_E2E_SOURCE_SHA="$(tr -d '[:space:]' < "${REPO_ROOT}/.cua-e2e-source-sha")"- export CUA_E2E_SOURCE_MARKER="${REPO_ROOT}/.cua-e2e-source-sha"+SOURCE_MARKER="${REPO_ROOT}/.cua-e2e-source-sha"+if [[ -f "${SOURCE_MARKER}" ]]; then+ export CUA_E2E_SOURCE_MARKER="${CUA_E2E_SOURCE_MARKER:-${SOURCE_MARKER}}"+ if [[ -z "${CUA_E2E_SOURCE_SHA:-}" ]]; then+ export CUA_E2E_SOURCE_SHA="$(tr -d '[:space:]' < "${SOURCE_MARKER}")"+ fi+fi+if [[ -n "${CUA_E2E_SOURCE_SHA:-}" ]]; then+ export CUA_DRIVER_SOURCE_SHA="${CUA_E2E_SOURCE_SHA}"fiif [[ -n "${WAYLAND_DISPLAY:-}" && -z "${DISPLAY:-}" ]]; thenexport GDK_BACKEND="${GDK_BACKEND:-wayland}"@@ -167,6 +173,10 @@ if [[ "${SUITE}" == shared || "${SUITE}" == all ]]; thencargo test -p cua-driver --test cross_platform_behavior_test -- \--ignored --exact shared_web_action_matrix_is_state_verified \--nocapture --test-threads=1+ run_test embedded-browser-routes \+ cargo test -p cua-driver --test cross_platform_behavior_test -- \+ --ignored --exact embedded_browser_routes_are_exact_or_refused \+ --nocapture --test-threads=1fiif [[ "${SUITE}" == native || "${SUITE}" == all ]]; thendiff --git a/scripts/ci/macos/run-rust-e2e.sh b/scripts/ci/macos/run-rust-e2e.shindex a6a06052b6..51a81c4a8e 100755--- a/scripts/ci/macos/run-rust-e2e.sh+++ b/scripts/ci/macos/run-rust-e2e.sh@@ -177,6 +177,9 @@ if [[ "${SUITE}" == shared || "${SUITE}" == all ]]; thenrun_test shared-app-matrix cargo test -p cua-driver --test cross_platform_behavior_test -- \--ignored --exact shared_web_action_matrix_is_state_verified \--nocapture --test-threads=1+ run_test embedded-browser-routes cargo test -p cua-driver --test cross_platform_behavior_test -- \+ --ignored --exact embedded_browser_routes_are_exact_or_refused \+ --nocapture --test-threads=1fiif [[ "${SUITE}" == native || "${SUITE}" == all ]]; thenfor appkit_test in \diff --git a/scripts/ci/run-rust-standalone-browser-e2e.sh b/scripts/ci/run-rust-standalone-browser-e2e.shnew file mode 100755index 0000000000..e7ab102833--- /dev/null+++ b/scripts/ci/run-rust-standalone-browser-e2e.sh@@ -0,0 +1,136 @@+#!/usr/bin/env bash+# Run the cross-platform external Chromium browser matrix in the caller's desktop session.+set -euo pipefail++SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"+RUST_ROOT="${REPO_ROOT}/libs/cua-driver/rust"+ARTIFACT_DIR="${CUA_E2E_ARTIFACT_DIR:-${REPO_ROOT}/artifacts/cua-driver/standalone-browser}"++if [[ -d "${ARTIFACT_DIR}" ]] \+ && [[ -n "$(find "${ARTIFACT_DIR}" -mindepth 1 -print -quit)" ]]; then+ echo "Standalone-browser artifact directory is not empty: ${ARTIFACT_DIR}" >&2+ echo "Use a fresh CUA_E2E_ARTIFACT_DIR so rows and videos cannot be mixed across runs." >&2+ exit 2+fi++mkdir -p "${ARTIFACT_DIR}/recordings"+export CUA_E2E_DECLARATIONS_FILE="${ARTIFACT_DIR}/cases.jsonl"+export CUA_E2E_ENVIRONMENT_FILE="${ARTIFACT_DIR}/environment.jsonl"+export CUA_E2E_RESULTS_FILE="${ARTIFACT_DIR}/results.jsonl"+export CUA_E2E_RECORDINGS_ROOT="${ARTIFACT_DIR}/recordings"+export CUA_TEST_WORKSPACE_ROOT="${RUST_ROOT}"+export CUA_TEST_DRIVER_BIN="${CUA_TEST_DRIVER_BIN:-${RUST_ROOT}/target/release/cua-driver}"+export CUA_TEST_REQUIRE_EXTERNAL_BROWSERS=1+export CUA_E2E_FORBID_SKIPS=1+export CUA_TEST_DRIVER_STDERR=1+export RUST_BACKTRACE="${RUST_BACKTRACE:-1}"++HOST_OS="$(uname -s)"+if [[ "${HOST_OS}" == Linux ]] \+ && [[ "${XDG_SESSION_TYPE:-}" == wayland ]] \+ && [[ -n "${WAYLAND_DISPLAY:-}" ]] \+ && [[ -z "${DISPLAY:-}" ]]; then+ # This lane promises native Wayland behavior. Opt into the driver's native+ # backend explicitly so a missing caller variable cannot silently exercise+ # the X11 fallback and time out during native-window correlation.+ export CUA_DRIVER_RS_ENABLE_WAYLAND=1+ export ELECTRON_OZONE_PLATFORM_HINT=wayland+fi++case "${HOST_OS}" in+ Darwin)+ SENTINEL_FIXTURE="${RUST_ROOT}/test-apps/harness-electron/CuaTestHarness.Electron.app"+ ;;+ Linux)+ SENTINEL_FIXTURE="${RUST_ROOT}/test-apps/harness-electron/CuaTestHarness.Electron"+ ;;+ MINGW*|MSYS*|CYGWIN*)+ SENTINEL_FIXTURE="${RUST_ROOT}/test-apps/harness-electron/CuaTestHarness.Electron.exe"+ ;;+ *)+ echo "Unsupported standalone-browser host: ${HOST_OS}" >&2+ exit 2+ ;;+esac++if [[ ! -e "${SENTINEL_FIXTURE}" ]]; then+ echo "[FIXTURE] Staging the Electron foreground sentinel"+ if [[ "${HOST_OS}" == MINGW* || "${HOST_OS}" == MSYS* || "${HOST_OS}" == CYGWIN* ]]; then+ powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File \+ "${REPO_ROOT}/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/build.ps1"+ else+ "${REPO_ROOT}/libs/cua-driver/tests/fixtures/apps/cross-platform/electron/build.sh"+ fi+fi+if [[ ! -e "${SENTINEL_FIXTURE}" ]]; then+ echo "Electron foreground sentinel was not staged: ${SENTINEL_FIXTURE}" >&2+ exit 1+fi++: > "${CUA_E2E_DECLARATIONS_FILE}"+: > "${CUA_E2E_ENVIRONMENT_FILE}"+: > "${CUA_E2E_RESULTS_FILE}"++SOURCE_MARKER="${REPO_ROOT}/.cua-e2e-source-sha"+if [[ -f "${SOURCE_MARKER}" ]]; then+ export CUA_E2E_SOURCE_MARKER="${CUA_E2E_SOURCE_MARKER:-${SOURCE_MARKER}}"+ if [[ -z "${CUA_E2E_SOURCE_SHA:-}" ]]; then+ export CUA_E2E_SOURCE_SHA="$(tr -d '[:space:]' < "${SOURCE_MARKER}")"+ fi+fi++if [[ "${CUA_E2E_SKIP_BUILD:-0}" != 1 ]]; then+ cargo build --release -p cua-driver --manifest-path "${RUST_ROOT}/Cargo.toml"+fi+if [[ ! -x "${CUA_TEST_DRIVER_BIN}" ]]; then+ echo "Driver binary not found: ${CUA_TEST_DRIVER_BIN}" >&2+ exit 1+fi++tests=(+ standalone_browser_background_type+ standalone_browser_frames+ standalone_browser_multi_tab+ standalone_browser_prepare_isolated+ standalone_browser_roundtrip+ standalone_browser_stale_ref+ standalone_browser_trusted_click+ standalone_browser_window_collision+)+failure_count=0+for test_name in "${tests[@]}"; do+ echo "[RUN] ${test_name}"+ set +e+ (cd "${RUST_ROOT}" && cargo test --release -p cua-driver \+ --test standalone_browser_behavior_test "${test_name}" -- \+ --ignored --exact --nocapture --test-threads=1) \+ 2>&1 | tee "${ARTIFACT_DIR}/${test_name}.log"+ test_status=${PIPESTATUS[0]}+ set -e+ if [[ "${test_status}" != 0 ]]; then+ failure_count=$((failure_count + 1))+ fi+done++set +e+(cd "${RUST_ROOT}" && cargo run --release -p cua-driver-testkit \+ --bin cua-e2e-report -- \+ --declarations "${CUA_E2E_DECLARATIONS_FILE}" \+ --environment "${CUA_E2E_ENVIRONMENT_FILE}" \+ --results "${CUA_E2E_RESULTS_FILE}" \+ --artifact-root "${ARTIFACT_DIR}" \+ --require-video \+ --output "${ARTIFACT_DIR}/summary.md")+report_status=$?+set -e+if [[ "${report_status}" != 0 ]]; then+ failure_count=$((failure_count + 1))+fi++if [[ "${failure_count}" != 0 ]]; then+ echo "Standalone-browser E2E had ${failure_count} failing step(s)" >&2+ exit 1+fi++echo "Standalone-browser E2E completed"diff --git a/scripts/ci/windows/run-rust-e2e.ps1 b/scripts/ci/windows/run-rust-e2e.ps1index 1f7d4278d9..d3fd8e9a45 100644--- a/scripts/ci/windows/run-rust-e2e.ps1+++ b/scripts/ci/windows/run-rust-e2e.ps1@@ -50,6 +50,16 @@ $env:CUA_TEST_APPS_ROOT = Join-Path $rustRoot "test-apps"$env:CUA_TEST_REQUIRE_FIXTURES = "1"$env:CUA_TEST_DRIVER_STDERR = "1"$env:CUA_E2E_FORBID_SKIPS = "1"+$sourceMarker = Join-Path $repoRoot ".cua-e2e-source-sha"+if (Test-Path $sourceMarker) {+ $env:CUA_E2E_SOURCE_MARKER = $sourceMarker+ if ([string]::IsNullOrWhiteSpace($env:CUA_E2E_SOURCE_SHA)) {+ $env:CUA_E2E_SOURCE_SHA = (Get-Content -Raw $sourceMarker).Trim()+ }+}+if (-not [string]::IsNullOrWhiteSpace($env:CUA_E2E_SOURCE_SHA)) {+ $env:CUA_DRIVER_SOURCE_SHA = $env:CUA_E2E_SOURCE_SHA+}Remove-Item Env:CUA_E2E_EXPECTED_MIN_CELLS -ErrorAction SilentlyContinueif (($suite -in @("shared", "all")) -and[string]::IsNullOrWhiteSpace($env:CUA_E2E_CELL_FILTER) -and@@ -58,10 +68,17 @@ if (($suite -in @("shared", "all")) -and}if (-not $NoBuild) {- & cargo build --release -p cua-driver --manifest-path (Join-Path $rustRoot "Cargo.toml")- if ($LASTEXITCODE -ne 0) { throw "Rust driver build failed" }+ $previousPreference = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ try {+ & cargo build --release -p cua-driver --manifest-path (Join-Path $rustRoot "Cargo.toml")+ $buildExit = $LASTEXITCODE+ } finally {+ $ErrorActionPreference = $previousPreference+ }+ if ($buildExit -ne 0) { throw "Rust driver build failed" }$fixtureTargets = switch ($suite) {- "shared" { @("electron", "tauri") }+ "shared" { @("electron", "tauri", "webview") }"native" { @("wpf", "winui3", "webview", "electron") }"capture" { @("wpf", "electron") }default { @("wpf", "winui3", "webview", "electron", "tauri") }@@ -80,10 +97,12 @@ if ($suite -in @("shared", "all")) {if ($suite -in @("native", "capture", "all")) {$requiredFixtures += Join-Path $env:CUA_TEST_APPS_ROOT "harness-wpf\CuaTestHarness.Wpf.exe"}+if ($suite -in @("shared", "native", "all")) {+ $requiredFixtures += Join-Path $env:CUA_TEST_APPS_ROOT "harness-webview\CuaTestHarness.WebView.exe"+}if ($suite -in @("native", "all")) {$requiredFixtures += @(- (Join-Path $env:CUA_TEST_APPS_ROOT "harness-winui3\CuaTestHarness.WinUI3.exe"),- (Join-Path $env:CUA_TEST_APPS_ROOT "harness-webview\CuaTestHarness.WebView.exe")+ (Join-Path $env:CUA_TEST_APPS_ROOT "harness-winui3\CuaTestHarness.WinUI3.exe"))}foreach ($fixture in $requiredFixtures) {@@ -93,14 +112,27 @@ foreach ($fixture in $requiredFixtures) {function Invoke-E2eReport {Push-Location $rustRoottry {- & cargo run -p cua-driver-testkit --bin cua-e2e-report -- `- --declarations $casesPath `- --environment $environmentPath `- --results $resultsPath `- --artifact-root $artifactDir `- --require-video `- --output $summaryPath | Out-Host- $exitCode = $LASTEXITCODE+ $previousPreference = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ try {+ $reportOutput = @(& cargo run -p cua-driver-testkit --bin cua-e2e-report -- `+ --declarations $casesPath `+ --environment $environmentPath `+ --results $resultsPath `+ --artifact-root $artifactDir `+ --require-video `+ --output $summaryPath 2>&1) | ForEach-Object {+ if ($_ -is [System.Management.Automation.ErrorRecord]) {+ $_.Exception.Message+ } else {+ $_.ToString()+ }+ }+ $exitCode = $LASTEXITCODE+ } finally {+ $ErrorActionPreference = $previousPreference+ }+ $reportOutput | Out-Hostreturn $exitCode} finally {Pop-Location@@ -111,9 +143,26 @@ Write-Host "[PREFLIGHT] Windows desktop, fixture, UIA, capture, and video" -ForePush-Location $rustRoottry {$preflightLog = Join-Path $artifactDir "environment-preflight.log"- $preflightOutput = & cargo test -p cua-driver --test e2e_environment_preflight_test -- `- --ignored --exact canonical_e2e_environment_is_ready --nocapture --test-threads=1 2>&1- $preflightExit = $LASTEXITCODE+ # Windows PowerShell 5.1 wraps native stderr as ErrorRecord objects. With+ # the script-wide Stop preference, normal Cargo progress would terminate+ # the lane before LASTEXITCODE can be inspected. Relax only around the+ # captured native process; the real exit code remains authoritative.+ $previousPreference = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ try {+ $preflightOutput = @(& cargo test -p cua-driver --test e2e_environment_preflight_test -- `+ --ignored --exact canonical_e2e_environment_is_ready --nocapture --test-threads=1 2>&1) | `+ ForEach-Object {+ if ($_ -is [System.Management.Automation.ErrorRecord]) {+ $_.Exception.Message+ } else {+ $_.ToString()+ }+ }+ $preflightExit = $LASTEXITCODE+ } finally {+ $ErrorActionPreference = $previousPreference+ }$preflightOutput | Tee-Object -FilePath $preflightLog} finally {Pop-Location@@ -129,8 +178,20 @@ function Invoke-CargoTest {Push-Location $rustRoottry {$logPath = Join-Path $artifactDir ("$($Name -replace '[^A-Za-z0-9_.-]', '-').log")- $output = & cargo @Arguments 2>&1- $exitCode = $LASTEXITCODE+ $previousPreference = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ try {+ $output = @(& cargo @Arguments 2>&1) | ForEach-Object {+ if ($_ -is [System.Management.Automation.ErrorRecord]) {+ $_.Exception.Message+ } else {+ $_.ToString()+ }+ }+ $exitCode = $LASTEXITCODE+ } finally {+ $ErrorActionPreference = $previousPreference+ }$output | Tee-Object -FilePath $logPathif ($exitCode -ne 0) {$script:FailureCount++@@ -172,7 +233,14 @@ function Test-E2eRecordings {}}foreach ($video in $videos) {- $relative = [System.IO.Path]::GetRelativePath($artifactDir, $video.FullName).Replace("\", "/")+ $artifactPrefix = ([System.IO.Path]::GetFullPath($artifactDir)).TrimEnd("\") + "\"+ $videoPath = [System.IO.Path]::GetFullPath($video.FullName)+ if (-not $videoPath.StartsWith($artifactPrefix, [System.StringComparison]::OrdinalIgnoreCase)) {+ Write-Host "[VIDEO FAIL] Trajectory escaped artifact root: $videoPath" -ForegroundColor Red+ $failureCount+++ continue+ }+ $relative = $videoPath.Substring($artifactPrefix.Length).Replace("\", "/")if ($relative -like "recordings/environment-preflight-*/recording.mp4") {continue}@@ -192,6 +260,11 @@ if ($suite -in @("shared", "all")) {"--ignored", "--exact", "shared_web_action_matrix_is_state_verified","--nocapture", "--test-threads=1")+ Invoke-CargoTest "embedded browser routes" @(+ "test", "-p", "cua-driver", "--test", "cross_platform_behavior_test", "--",+ "--ignored", "--exact", "embedded_browser_routes_are_exact_or_refused",+ "--nocapture", "--test-threads=1"+ )}if ($suite -in @("native", "all")) {diff --git a/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1 b/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1new file mode 100644index 0000000000..6fa85c5c99--- /dev/null+++ b/scripts/ci/windows/run-rust-standalone-browser-e2e.ps1@@ -0,0 +1,152 @@+# Run installed Chrome/Edge browser scenarios in independent Windows processes.+param(+ [switch]$NoBuild+)++Set-StrictMode -Version Latest+$ErrorActionPreference = "Stop"++$scriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition+$repoRoot = (Resolve-Path (Join-Path $scriptDir "..\..\..")).Path+$rustRoot = Join-Path $repoRoot "libs\cua-driver\rust"+$artifactDir = if ([string]::IsNullOrWhiteSpace($env:CUA_E2E_ARTIFACT_DIR)) {+ Join-Path $repoRoot "artifacts\cua-driver\standalone-browser"+} else {+ [System.IO.Path]::GetFullPath($env:CUA_E2E_ARTIFACT_DIR)+}++if ((Test-Path $artifactDir) -and+ $null -ne (Get-ChildItem -Force $artifactDir -ErrorAction SilentlyContinue | Select-Object -First 1)) {+ throw "Standalone-browser artifact directory is not empty: $artifactDir. Use a fresh CUA_E2E_ARTIFACT_DIR."+}++$recordings = Join-Path $artifactDir "recordings"+New-Item -ItemType Directory -Force $recordings | Out-Null+$env:CUA_E2E_DECLARATIONS_FILE = Join-Path $artifactDir "cases.jsonl"+$env:CUA_E2E_ENVIRONMENT_FILE = Join-Path $artifactDir "environment.jsonl"+$env:CUA_E2E_RESULTS_FILE = Join-Path $artifactDir "results.jsonl"+$env:CUA_E2E_RECORDINGS_ROOT = $recordings+$env:CUA_TEST_WORKSPACE_ROOT = $rustRoot+$env:CUA_TEST_DRIVER_BIN = Join-Path $rustRoot "target\release\cua-driver.exe"+$env:CUA_TEST_APPS_ROOT = Join-Path $rustRoot "test-apps"+$env:CUA_TEST_REQUIRE_EXTERNAL_BROWSERS = "1"+$env:CUA_E2E_FORBID_SKIPS = "1"+$env:CUA_TEST_DRIVER_STDERR = "1"++foreach ($path in @(+ $env:CUA_E2E_DECLARATIONS_FILE,+ $env:CUA_E2E_ENVIRONMENT_FILE,+ $env:CUA_E2E_RESULTS_FILE+)) {+ New-Item -ItemType File -Path $path | Out-Null+}++if ([string]::IsNullOrWhiteSpace($env:CUA_E2E_SOURCE_SHA)) {+ $sourceMarker = Join-Path $repoRoot ".cua-e2e-source-sha"+ if (Test-Path $sourceMarker) {+ $env:CUA_E2E_SOURCE_MARKER = $sourceMarker+ $env:CUA_E2E_SOURCE_SHA = (Get-Content -Raw $sourceMarker).Trim()+ } else {+ $env:CUA_E2E_SOURCE_SHA = (& git -C $repoRoot rev-parse HEAD).Trim()+ }+}+if ($env:CUA_E2E_SOURCE_SHA -notmatch "^[0-9a-fA-F]{40}$") {+ throw "CUA_E2E_SOURCE_SHA must be a full 40-character commit SHA"+}++foreach ($tool in @("ffmpeg.exe", "ffprobe.exe")) {+ if ($null -eq (Get-Command $tool -ErrorAction SilentlyContinue)) {+ throw "$tool is required for standalone-browser trajectory evidence"+ }+}++& (Join-Path $scriptDir "verify-user-session.ps1")++$sentinelFixture = Join-Path $rustRoot "test-apps\harness-electron\CuaTestHarness.Electron.exe"+if (-not (Test-Path $sentinelFixture)) {+ Write-Host "[FIXTURE] Staging the Electron foreground sentinel" -ForegroundColor Yellow+ & (Join-Path $scriptDir "build-harnesses.ps1") -Targets @("electron")+}+if (-not (Test-Path $sentinelFixture)) {+ throw "Electron foreground sentinel was not staged: $sentinelFixture"+}++function Invoke-CargoStep {+ param(+ [Parameter(Mandatory = $true)]+ [string]$Name,+ [Parameter(Mandatory = $true)]+ [string[]]$Arguments,+ [Parameter(Mandatory = $true)]+ [string]$LogPath+ )++ Write-Host "[RUN] $Name" -ForegroundColor Yellow+ Push-Location $rustRoot+ try {+ $previousPreference = $ErrorActionPreference+ $ErrorActionPreference = "Continue"+ try {+ $output = @(& cargo @Arguments 2>&1) | ForEach-Object {+ if ($_ -is [System.Management.Automation.ErrorRecord]) {+ $_.Exception.Message+ } else {+ $_.ToString()+ }+ }+ $exitCode = $LASTEXITCODE+ } finally {+ $ErrorActionPreference = $previousPreference+ }+ $output | Tee-Object -FilePath $LogPath | Out-Host+ return $exitCode+ } finally {+ Pop-Location+ }+}++if (-not $NoBuild) {+ $buildExit = Invoke-CargoStep -Name "source driver" -Arguments @(+ "build", "--release", "-p", "cua-driver"+ ) -LogPath (Join-Path $artifactDir "build.log")+ if ($buildExit -ne 0) { throw "cua-driver build failed with exit code $buildExit" }+}+if (-not (Test-Path $env:CUA_TEST_DRIVER_BIN)) {+ throw "Driver binary not found: $($env:CUA_TEST_DRIVER_BIN)"+}++$tests = @(+ "standalone_browser_background_type",+ "standalone_browser_frames",+ "standalone_browser_multi_tab",+ "standalone_browser_prepare_isolated",+ "standalone_browser_roundtrip",+ "standalone_browser_stale_ref",+ "standalone_browser_trusted_click",+ "standalone_browser_window_collision"+)+$failureCount = 0+foreach ($testName in $tests) {+ $testExit = Invoke-CargoStep -Name $testName -Arguments @(+ "test", "--release", "-p", "cua-driver",+ "--test", "standalone_browser_behavior_test", $testName, "--",+ "--ignored", "--exact", "--nocapture", "--test-threads=1"+ ) -LogPath (Join-Path $artifactDir "$testName.log")+ if ($testExit -ne 0) { $failureCount++ }+}++$reportExit = Invoke-CargoStep -Name "standalone browser report" -Arguments @(+ "run", "--release", "-p", "cua-driver-testkit", "--bin", "cua-e2e-report", "--",+ "--declarations", $env:CUA_E2E_DECLARATIONS_FILE,+ "--environment", $env:CUA_E2E_ENVIRONMENT_FILE,+ "--results", $env:CUA_E2E_RESULTS_FILE,+ "--artifact-root", $artifactDir,+ "--require-video",+ "--output", (Join-Path $artifactDir "summary.md")+) -LogPath (Join-Path $artifactDir "report.log")+if ($reportExit -ne 0) { $failureCount++ }++if ($failureCount -ne 0) {+ throw "Standalone-browser E2E had $failureCount failing step(s)"+}+Write-Host "Standalone-browser E2E completed" -ForegroundColor Green