Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

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.mdx
index 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 separate
interactive artifact bound to one process, native window, and named driver
session.
+## 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 is
opened. Cua Driver therefore keeps one socket for each approved connection
generation and multiplexes tabs over it. If the socket drops, one reconnect
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.mdx
index 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 browser
already 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.
## Related
diff --git a/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdx b/docs/content/docs/how-to-guides/driver/restrict-tool-access.mdx
index 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 only
The `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 policy
For 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.mdx
index 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 the
generation and invalidates every target, tab, snapshot, frame, and ref minted
by 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.mdx
index 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 mutable
tab ordinals cannot satisfy exact window targeting. These surfaces therefore
remain 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 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;
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
index 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.md
index 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 grant
bound to the exact process, native window, and caller session. Ordinary MCP
approval 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.
+
```bash
cua-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.
```bash
cua-driver browser_pointer \
@@ -311,7 +319,10 @@ AX/PX ladder for browser chrome.
The legacy `page` tool remains a compatibility surface for older clients. Do
not start new browser workflows with it: its backend and trust semantics are
less 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 boundaries
diff --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.rs
index 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.rs
index 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
.selected
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.rs
index 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.rs
index 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.rs
index 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.rs
index 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.rs
index 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
.driver
diff --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.rs
index 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.rs
index 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,