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
fix(cua-driver): harden browser preview boundaries
trycua-release[bot]667646af2d63
diff --git a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdxindex 8969a0a2d9..13777479f4 100644--- a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx+++ b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx@@ -120,6 +120,40 @@ approval is not enough. The initial existing-profile route requires a separateinteractive artifact bound to one process, native window, and named driversession.+## The CDP trust boundary++CDP is used because it is the only supported Chromium interface that can+address an exact inactive tab, inspect its document, and perform declared+background operations without borrowing the person's keyboard or pointer.+That power is also the reason Cua Driver treats attachment as a security+boundary rather than a connection detail. CDP exposes broad browser authority,+including page runtime, DOM, network, storage, and cookie domains; it is not a+least-privilege API for one button or one tab.++A loopback listener prevents remote hosts from connecting directly, but+loopback is not authentication. Another process running as the same operating+system user may be able to discover and connect to an exposed endpoint. Cua+Driver's PID ownership proof, native-window correlation, scoped capabilities,+and approval grant prevent the driver from attaching to the wrong endpoint;+they cannot turn the Chromium endpoint itself into an authenticated service or+protect it from unrelated local software.++Use a driver-owned isolated profile by default. Attach an existing profile+only when the task genuinely needs its authenticated session, only on a trusted+machine, and only for the duration of that task. An endpoint that the browser+already exposes can use the ordinary exact binding route without another setup+transition because Cua Driver did not create or widen the listener. That does+not reduce the endpoint's authority: the operator is responsible for how that+browser was started and for closing remote debugging when it is no longer+needed.++Chromium applies its own protections to remote debugging on default profiles.+Cua Driver does not bypass those protections, copy a profile, or weaken the+browser's data encryption. See Chromium's+[remote-debugging security guidance](https://developer.chrome.com/blog/remote-debugging-port)+and the [Chrome DevTools Protocol domains](https://chromedevtools.github.io/devtools-protocol/)+for the underlying browser boundary.+Chrome can ask for consent whenever a genuinely new browser-level socket isopened. Cua Driver therefore keeps one socket for each approved connectiongeneration and multiplexes tabs over it. If the socket drops, one reconnectdiff --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 c23e70cded..ac2dd03ec0 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@@ -22,6 +22,13 @@ binding.## Inspect the selected browser first+<Callout type="warn">+ Prefer a driver-owned isolated profile. Existing-profile attachment gives+ CDP broad access to that profile's live pages, cookies, and storage. Use it+ only when the task needs an existing authenticated session and the machine+ and its local processes are trusted.+</Callout>+First use `list_apps` and `list_windows` as usual, then call`get_browser_state` with the selected native `(pid, window_id)`. If that browseralready exposes an owned loopback DevTools endpoint, the driver binds it without@@ -341,11 +348,16 @@ 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.+The older `page` tool remains available for compatibility. Its read-only+`get_text` and `query_dom` actions are available by default. Legacy mutation+actions are disabled unless the daemon operator explicitly starts Cua Driver+with `CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1`.++That flag is a temporary compatibility escape hatch, not an equivalent browser+grant: legacy CDP ports and URL hints do not receive the typed surface's exact+native-window correlation, endpoint lifetime, or existing-profile consent+checks. Do not enable it for untrusted agents or shared hosts. Migrate mutation+workflows to `get_browser_state` and the typed `browser_*` tools.## Relateddiff --git a/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdx b/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdxindex 2d5f6460d5..894019752d 100644--- a/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdx+++ b/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdx@@ -76,6 +76,51 @@ Each `constraints` key matches a JSON argument name. A rule allows the call onlyThe `type_text_chars` tool name is automatically aliased to `type_text` before policy evaluation, so a rule on `type_text` covers both forms.</Callout>+## Restrict a browser-only agent++For an agent that should work only in a browser Cua Driver has already+prepared, allow inspection and ordinary page interaction while denying profile+setup, local-file transfer, downloads, and the legacy mutation surface:++```yaml+allow:+ tools:+ - list_apps+ - list_windows+ - start_session+ - end_session+ - get_browser_state+ - browser_click+ - browser_type+ - browser_pointer+ - browser_dialog+ - wait+ rules:+ - tool: browser_navigate+ constraints:+ url:+ pattern: "^https://(docs\\.example\\.com|app\\.example\\.com)(/|$)"+deny:+ tools:+ - browser_prepare+ - browser_set_input_files+ - browser_download+ - page+ - shell_execute+```++Replace the example hosts with the exact destinations required for the task.+Run profile preparation separately under maintainer control before starting the+restricted agent.++<Callout type="warn">+ Tool policy cannot predict what a page will do after a click, form submit,+ script, or redirect. A host allowlist constrains explicit+ `browser_navigate` calls, not destinations reached through page behavior.+ Keep consequential accounts and existing authenticated profiles outside an+ untrusted agent's policy boundary.+</Callout>+## Create a Rego policyFor more complex access control — for example, allowing different tool sets based on the active task or runtime conditions — write a Rego policy:diff --git a/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx b/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdxindex a0a536cb2d..da4eb05720 100644--- a/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx+++ b/docs/content/docs/reference/cua-driver/browser-profile-attachment.mdx@@ -74,6 +74,22 @@ attempts are made after a socket loss. A successful reconnect increments thegeneration and invalidates every target, tab, snapshot, frame, and ref mintedby the previous generation.+## Security properties++| Property | Guarantee |+| --- | --- |+| Network exposure | The accepted DevTools endpoint must be loopback-only. |+| Process binding | The endpoint, native window, and live process fingerprint must agree before every mutation. |+| Driver authorization | Existing-profile setup needs a single-use interactive artifact; a model-supplied Boolean and ordinary MCP approval are insufficient. |+| Capability scope | Targets, tabs, dialogs, frames, and refs are opaque, session-scoped, and invalidated after navigation or connection-generation changes. |+| Profile handling | Cua Driver does not copy, edit, restart, or terminate the selected existing profile. |+| Residual local risk | CDP itself is not authenticated. Another process running as the same OS user may connect to an exposed endpoint outside Cua Driver. |++An isolated profile is the recommended default. Existing-profile attachment is+appropriate only when the task requires its authenticated state and the host is+trusted. See [Browser targeting and background delivery](/concepts/browser-targeting-and-background-delivery#the-cdp-trust-boundary)+for why Cua Driver uses CDP and which risks remain outside the driver.+## Refusals| Code | Meaning |diff --git a/docs/content/docs/reference/cua-driver/limits.mdx b/docs/content/docs/reference/cua-driver/limits.mdxindex e334c121a3..7a45c5b32f 100644--- a/docs/content/docs/reference/cua-driver/limits.mdx+++ b/docs/content/docs/reference/cua-driver/limits.mdx@@ -35,6 +35,22 @@ Apple Events JavaScript is not equivalent to trusted browser input, and mutabletab ordinals cannot satisfy exact window targeting. These surfaces thereforeremain capability-visible but mutation-unavailable instead of being guessed.+The typed browser surface is preview-grade before 1.0. Product support means+that the exact binding, supported mutations, declared background posture, and+structured refusals have release evidence. Recognition alone is not a support+claim.++| Platform and surface | Current typed-browser status |+| --- | --- |+| Windows Chrome and Edge | Validated. Trusted background pointer and synthetic DOM routes are covered. An interactive desktop is required. |+| macOS Chrome and Edge | Existing-profile attachment is validated. Synthetic DOM actions can remain fully background; trusted standalone pointer routes refuse when Chromium would activate. |+| Linux X11 Chrome and Edge | Validated for exact binding and synthetic DOM background routes. Trusted standalone pointer routes refuse when activation is unavoidable. |+| Linux Sway with Chrome | Validated only when compositor identity, process, window, and geometry are exact. |+| Generic GNOME or KDE Wayland | Read-only discovery or structured refusal; mutation is not claimed. |+| Electron | Validated only for the bounded one-native-window to one-CDP-page shape. |+| Brave, Vivaldi, Opera, Arc, and other detected Chromium derivatives | Detected but not release-accepted; use at your own risk. |+| Safari, Firefox, WebView2, Tauri, WKWebView, and WebKitGTK | Typed mutation unsupported. Use documented native AX/PX fallbacks where available. |+Page refs traverse open shadow roots and same-process frames and are capped tothe first 300 interactive elements. Out-of-process frames are included onlywhen the runtime exposes a capability-tested CDP session for that frame;diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 214ebcf287..23920fb6e6 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -472,7 +472,7 @@ After a zoom, pass `from_zoom=true` to click/type_text to auto-translate coordin### `page`-Interact with the browser page loaded in a running app. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.+Legacy browser compatibility tool. Prefer get_browser_state and the typed browser_* tools for exact targeting, endpoint ownership, and consent. Read-only get_text and query_dom remain available by default. Mutating actions require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1; this escape hatch does not provide the typed browser surface's exact binding or existing-profile grant guarantees. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.Actions:- execute_javascript: Run JS and return the result.diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.mdindex 21592797a1..42e4e57aaa 100644--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md@@ -87,6 +87,12 @@ Attaching to an authenticated profile requires a separate interactive grantbound to the exact process, native window, and caller session. Ordinary MCPapproval is not enough:+CDP exposes broad authority over the profile's live pages, cookies, storage,+runtime, and network state. Loopback prevents remote-host access but is not+authentication against other processes running as the same OS user. Use this+route only on a trusted machine and only when an isolated profile cannot+satisfy the task.+```bashcua-driver browser-approve --strategy existing_profile \--pid 4242 --window-id 991 --session browser-run-1@@ -248,9 +254,11 @@ task result.Use `browser_pointer` for `hover`, `right_click`, `double_click`, `scroll`, and`drag`. It uses the same `trusted` versus explicit `dom_event` distinction as-`browser_click`. The synthetic route requires a current ref; drag also requires-`destination_ref` in the same proven frame. Coordinate origins and destinations-are available only where the trusted route can preserve the requested posture.+`browser_click`. A ref used here must declare `pointer` in its `actions` array.+The synthetic route requires a current ref; drag also requires+`destination_ref` in the same proven frame. Coordinate origins and+destinations are available only where the trusted route can preserve the+requested posture.```bashcua-driver browser_pointer \@@ -311,7 +319,10 @@ AX/PX ladder for browser chrome.The legacy `page` tool remains a compatibility surface for older clients. Donot start new browser workflows with it: its backend and trust semantics areless precise than the typed browser tools, and it does not replace exact-window binding.+window binding. Its mutations are disabled by default. Only a trusted daemon+operator can enable the temporary compatibility path with+`CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1`; that flag does not add typed+endpoint ownership, capabilities, or existing-profile consent.## Support boundariesdiff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rsindex d8e08507ad..6058a47f09 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs@@ -19,7 +19,7 @@ use crate::tool_args::ArgsExt;use super::cdp_ws::CdpConnection;use super::engine::{BrowserEngine, ValidatedTab};use super::refusal::{BrowserRefusal, BrowserRefusalCode};-use super::store::{FrameKind, FrameRef};+use super::store::{BrowserActionKind, FrameKind, FrameRef};#[derive(Debug, Clone, Copy, PartialEq, Eq)]enum PointerAction {@@ -296,7 +296,7 @@ impl BrowserPointerTool {read_only: false,destructive: false,idempotent: false,- open_world: false,+ open_world: true,},engine,}@@ -315,6 +315,13 @@ impl BrowserPointerTool {.store.resolve_ref(session, target_id, tab_id, external).map_err(|refusal| refusal.to_tool_result())?;+ if entry.semantic && !entry.actions.contains(&BrowserActionKind::Pointer) {+ return Err(BrowserRefusal::new(+ BrowserRefusalCode::BrowserActionUnavailable,+ format!("semantic ref {external} does not declare the pointer action"),+ )+ .to_tool_result());+ }let cdp_session = self.engine.frame_session_for_mutation(session, target_id, tab_id, validated, &entry.frame)diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/semantic.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/semantic.rsindex b2348ef831..ec0b6de93f 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/semantic.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/semantic.rs@@ -810,6 +810,17 @@ fn action_kinds({actions.push(BrowserActionKind::Click);}+ if !actions.is_empty()+ && layout.is_some_and(|meta| {+ meta.bounds.is_some_and(Rect::has_area)+ && !meta+ .styles+ .get("pointer-events")+ .is_some_and(|value| value.eq_ignore_ascii_case("none"))+ })+ {+ actions.push(BrowserActionKind::Pointer);+ }actions}@@ -1184,7 +1195,7 @@ mod tests {let page = document.page(0, 300, None, None);assert!(page.selected.iter().any(|node| {node.name.as_deref() == Some("Custom action")- && node.actions == vec![BrowserActionKind::Click]+ && node.actions == vec![BrowserActionKind::Click, BrowserActionKind::Pointer]}));assert!(page.selecteddiff --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.rsindex 7bc9740510..98752e7dc4 100644--- 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.rs@@ -33,6 +33,7 @@ pub enum BrowserActionKind {Click,Type,Upload,+ Pointer,}impl BrowserActionKind {@@ -41,6 +42,7 @@ impl BrowserActionKind {Self::Click => "click",Self::Type => "type",Self::Upload => "upload",+ Self::Pointer => "pointer",}}}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.rsindex fcbe2bcad3..bdc9cf3b29 100644--- 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.rs@@ -443,7 +443,7 @@ impl BrowserPrepareTool {read_only: false,destructive: true,idempotent: false,- open_world: false,+ open_world: true,};Self { def, engine }}@@ -689,7 +689,7 @@ impl BrowserClickTool {read_only: false,destructive: false,idempotent: false,- open_world: false,+ open_world: true,};Self { def, engine }}@@ -1071,7 +1071,7 @@ impl BrowserTypeTool {read_only: false,destructive: false,idempotent: false,- open_world: false,+ open_world: true,};Self { def, engine }}@@ -1445,7 +1445,7 @@ impl BrowserDialogTool {read_only: false,destructive: false,idempotent: false,- open_world: false,+ open_world: true,},engine,}@@ -1970,12 +1970,21 @@ mod tests {assert!(!def.read_only, "{name} is a mutation");assert!(def.input_schema["properties"].is_object(), "{name} schema");}- // Navigate and download reach the open web; ordinary input does not.- assert!(BrowserNavigateTool::new(e.clone()).def().open_world);- assert!(BrowserDownloadTool::new(e.clone()).def().open_world);+ // Every browser mutation can affect web or browser state outside the+ // client, even when the immediate delivery route is local CDP.+ for def in [+ BrowserPrepareTool::new(e.clone()).def().clone(),+ BrowserNavigateTool::new(e.clone()).def().clone(),+ BrowserClickTool::new(e.clone()).def().clone(),+ BrowserTypeTool::new(e.clone()).def().clone(),+ BrowserDialogTool::new(e.clone()).def().clone(),+ BrowserSetInputFilesTool::new(e.clone()).def().clone(),+ BrowserDownloadTool::new(e.clone()).def().clone(),+ BrowserPointerTool::new(e.clone()).def().clone(),+ ] {+ assert!(def.open_world, "{} can affect open-world state", def.name);+ }assert!(BrowserDownloadTool::new(e.clone()).def().destructive);- assert!(!BrowserClickTool::new(e.clone()).def().open_world);- assert!(!BrowserPointerTool::new(e).def().open_world);}#[test]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.rsindex 5d06256d13..74311929ae 100644--- 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.rs@@ -21,6 +21,7 @@ use super::platform::{BrowserConsentOutcome, BrowserConsentRequest, BrowserPlatform, ExistingProfileSetupOutcome,ExistingProfileSetupRequest, PrepareAction, PrepareOutcome, PrepareRequest,};+use super::pointer::BrowserPointerTool;use super::refusal::BrowserRefusal;use super::tools::{BrowserClickTool, BrowserNavigateTool, BrowserPrepareTool, BrowserTypeTool, GetBrowserStateTool,@@ -1397,6 +1398,21 @@ async fn semantic_refs_enforce_declared_action_kinds_before_delivery() {"browser_action_unavailable");+ let pointer = BrowserPointerTool::new(f.engine.clone())+ .invoke(json!({+ "target_id": target,+ "tab_id": tab,+ "session": SESSION,+ "ref": content_ref,+ "action": "hover",+ "input_route": "dom_event"+ }))+ .await;+ assert_eq!(+ structured(&pointer)["refusal"]["code"],+ "browser_action_unavailable"+ );+let button_ref = snap["refs"].as_array().unwrap()diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/page.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/page.rsindex 731c248a50..79b2f7a0c6 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/page.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/page.rs@@ -25,6 +25,28 @@ use crate::{tool::{Tool, ToolDef},};+const LEGACY_PAGE_MUTATIONS_ENV: &str = "CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS";++fn env_flag_enabled(name: &str) -> bool {+ std::env::var(name).is_ok_and(|value| {+ matches!(+ value.trim().to_ascii_lowercase().as_str(),+ "1" | "true" | "yes" | "on"+ )+ })+}++fn is_mutating_action(action: &str) -> bool {+ matches!(+ action,+ "execute_javascript"+ | "click_element"+ | "insert_text"+ | "type_keystrokes"+ | "enable_javascript_apple_events"+ )+}+/// Result of a `click_element` call. The backend is responsible for driving/// the cursor overlay before returning; `screen_x` / `screen_y` are reported/// back to the caller for diagnostics + downstream chaining.@@ -208,11 +230,23 @@ pub trait PageBackend: Send + Sync {/// host platform constructs and passes in at registration time.pub struct PageTool {backend: Arc<dyn PageBackend>,+ legacy_mutations_enabled: bool,}impl PageTool {pub fn new(backend: Arc<dyn PageBackend>) -> Self {- Self { backend }+ Self {+ backend,+ legacy_mutations_enabled: env_flag_enabled(LEGACY_PAGE_MUTATIONS_ENV),+ }+ }++ #[cfg(test)]+ fn with_legacy_mutations(backend: Arc<dyn PageBackend>, enabled: bool) -> Self {+ Self {+ backend,+ legacy_mutations_enabled: enabled,+ }}}@@ -220,7 +254,12 @@ fn def() -> &'static ToolDef {static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();DEF.get_or_init(|| ToolDef {name: "page".into(),- description: "Interact with the browser page loaded in a running app. Supports \+ description: "Legacy browser compatibility tool. Prefer get_browser_state and the \+ typed browser_* tools for exact targeting, endpoint ownership, and consent. \+ Read-only get_text and query_dom remain available by default. Mutating actions \+ require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1; \+ this escape hatch does not provide the typed browser surface's exact binding or \+ existing-profile grant guarantees. Supports \Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), \Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when \--remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.\n\n\@@ -308,7 +347,7 @@ fn def() -> &'static ToolDef {read_only: false,destructive: false,idempotent: false,- open_world: false,+ open_world: true,})}@@ -324,6 +363,15 @@ impl Tool for PageTool {None => return ToolResult::error("Missing required parameter: action"),};+ if is_mutating_action(&action) && !self.legacy_mutations_enabled {+ return ToolResult::error(format!(+ "legacy page mutation {action:?} is disabled by default because it does not use \+ the typed browser surface's exact endpoint and consent checks; use \+ get_browser_state plus browser_* tools, or have the daemon operator explicitly \+ set {LEGACY_PAGE_MUTATIONS_ENV}=1 for temporary compatibility"+ ));+ }+// `pid` / `window_id` are resolved per-action: every action except// `enable_javascript_apple_events` needs both. We resolve once here// so each arm can `?` on the Result and we get matching error text.@@ -584,7 +632,7 @@ mod tests {#[tokio::test]async fn execute_javascript_forwards_explicit_page_target() {let backend = Arc::new(RecordingBackend::default());- let tool = PageTool::new(backend.clone());+ let tool = PageTool::with_legacy_mutations(backend.clone(), true);let synthetic_wayland_window_id = u64::from(u32::MAX) + 0x1234;let result = tool@@ -626,10 +674,35 @@ mod tests {.contains("exactly one"));}+ #[tokio::test]+ async fn every_legacy_mutation_refuses_without_operator_opt_in() {+ let backend = Arc::new(RecordingBackend::default());+ let tool = PageTool::with_legacy_mutations(backend.clone(), false);++ for action in [+ "execute_javascript",+ "click_element",+ "insert_text",+ "type_keystrokes",+ "enable_javascript_apple_events",+ ] {+ let result = tool.invoke(serde_json::json!({ "action": action })).await;+ assert_eq!(result.is_error, Some(true), "{action}");+ assert!(+ serde_json::to_string(&result)+ .unwrap()+ .contains(LEGACY_PAGE_MUTATIONS_ENV),+ "{action}"+ );+ }+ assert!(backend.targeted.lock().unwrap().is_none());+ assert!(def().open_world);+ }+#[tokio::test]async fn rejects_out_of_range_cdp_port_before_dispatch() {let backend = Arc::new(RecordingBackend::default());- let tool = PageTool::new(backend.clone());+ let tool = PageTool::with_legacy_mutations(backend.clone(), true);let result = tool.invoke(serde_json::json!({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 86fb24c7f7..e2063c43fc 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@@ -1211,20 +1211,6 @@ fn cell_selected(case: &CaseSpec) -> bool {}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.driverdiff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rsindex 4a87868558..d82ae939f3 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rs@@ -126,7 +126,10 @@ fn run_web_case_with_preparation<P, F>(let journal = FixtureJournal::start();let mut driver = McpDriver::spawn_named_with_env(&cell_id,- &[("CUA_DRIVER_CDP_PORT", cdp_port_string.as_str())],+ &[+ ("CUA_DRIVER_CDP_PORT", cdp_port_string.as_str()),+ ("CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS", "1"),+ ],).expect("required source-built Windows driver did not start");*evidence = recording_evidence(driver.recording_dir());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.rsindex 43701e107b..65607596e6 100644--- 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.rs@@ -2560,8 +2560,42 @@ fn run_pointer_actions(spec: &BrowserSpec) {*evidence = recording_evidence(fixture.driver.recording_dir());run_with_background_oracles(&mut fixture, |fixture| {let session = format!("standalone-pointer-{}", fixture.pid);- let (target, tab, snapshot) = bind(fixture, &session);- let click_ref = ref_by_label(&snapshot, "id=click-target");+ let (target, tab, _) = bind(fixture, &session);+ let snapshot = fixture.driver.call(+ "get_browser_state",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "session": session,+ "snapshot_format": "semantic_v2",+ }),+ );+ assert_eq!(snapshot.structured()["status"], "ok", "{}", snapshot.raw);++ let content_ref = snapshot.structured()["content_refs"]+ .as_array()+ .and_then(|refs| refs.first())+ .and_then(|entry| entry["ref"].as_str())+ .expect("semantic snapshot content ref");+ let refused = fixture.driver.call(+ "browser_pointer",+ serde_json::json!({+ "target_id": target,+ "tab_id": tab,+ "ref": content_ref,+ "action": "hover",+ "input_route": "dom_event",+ "session": session,+ }),+ );+ assert_eq!(+ refused.structured()["refusal"]["code"],+ "browser_action_unavailable",+ "{}",+ refused.raw+ );++ let click_ref = semantic_ref_by_name(&snapshot, "border-click-target", "pointer");for action in ["hover", "right_click", "double_click"] {let response = fixture.driver.call(@@ -2589,7 +2623,7 @@ fn run_pointer_actions(spec: &BrowserSpec) {serde_json::json!({"target_id": target,"tab_id": tab,- "ref": ref_by_label(&snapshot, "id=scroll-tall"),+ "ref": semantic_ref_by_name(&snapshot, "scroll-tall", "pointer"),"action": "scroll","input_route": "dom_event","delta_y": 240,@@ -2615,8 +2649,8 @@ fn run_pointer_actions(spec: &BrowserSpec) {serde_json::json!({"target_id": target,"tab_id": tab,- "ref": ref_by_label(&snapshot, "id=drag-source"),- "destination_ref": ref_by_label(&snapshot, "id=drop-target"),+ "ref": semantic_ref_by_name(&snapshot, "drag-source", "pointer"),+ "destination_ref": semantic_ref_by_name(&snapshot, "drop-target", "pointer"),"action": "drag","input_route": "dom_event","session": session,