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): route browser pages to browser_prepare and refuse desktop pointer over background apps (#5066)
Francesco Bonacci18da1bcbfe98
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdxindex 5d71308446..ff21a326e4 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx@@ -160,7 +160,7 @@ Read and act on web pages, and prepare and navigate browsers. [Reference](/cua-d| --- | --- | --- || <span id="page"></span>[`page`](/cua-driver/reference/mcp-tools/page#page) | Legacy browser compatibility tool. | macOS, Linux, Windows || <span id="get_browser_state"></span>[`get_browser_state`](/cua-driver/reference/mcp-tools/page#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |-| <span id="browser_prepare"></span>[`browser_prepare`](/cua-driver/reference/mcp-tools/page#browser_prepare) | Explicitly prepare an owned DevTools endpoint for a browser. | macOS, Linux, Windows |+| <span id="browser_prepare"></span>[`browser_prepare`](/cua-driver/reference/mcp-tools/page#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows || <span id="browser_navigate"></span>[`browser_navigate`](/cua-driver/reference/mcp-tools/page#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |## Browser input toolsdiff --git a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdxindex 69e96f06f5..42896d7c9f 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx@@ -14,7 +14,7 @@ description: "Read and act on web pages, and prepare and navigate browsers."| --- | --- | --- || [`page`](#page) | Legacy browser compatibility tool. | macOS, Linux, Windows || [`get_browser_state`](#get_browser_state) | Read-only browser inspection. | macOS, Linux, Windows |-| [`browser_prepare`](#browser_prepare) | Explicitly prepare an owned DevTools endpoint for a browser. | macOS, Linux, Windows |+| [`browser_prepare`](#browser_prepare) | Attach the browser tools to a browser. | macOS, Linux, Windows || [`browser_navigate`](#browser_navigate) | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.@@ -58,7 +58,7 @@ Effect: mutating. Platforms: macOS, Linux, Windows.## `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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.+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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.@@ -77,7 +77,7 @@ Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.## `browser_prepare`-Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.+Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {"kind":"existing_profile"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.Effect: destructive. Platforms: macOS, Linux, Windows.@@ -90,7 +90,7 @@ Effect: destructive. Platforms: macOS, Linux, Windows.| <span id="browser_prepare--profile-mode"></span>`profile.mode` | `"isolated_new" \| "isolated_named"` | | || <span id="browser_prepare--profile-name"></span>`profile.name` | `string` | | Required only for isolated_named; 1-64 path-safe ASCII characters. || <span id="browser_prepare--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. Browser targets, tabs, and refs belong to the resolved lifecycle session. |-| <span id="browser_prepare--strategy"></span>`strategy` | `object` | | Attach to an already-running browser instead of launching one. kind=existing_profile attaches to the user's running profile at pid/window_id and requires explicit profile authorization. |+| <span id="browser_prepare--strategy"></span>`strategy` | `object` | | Attach to an already-running browser instead of launching one. Pass an object, {"kind":"existing_profile"}, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization. || <span id="browser_prepare--strategy-kind"></span>`strategy.kind` | `"existing_profile"` | | || <span id="browser_prepare--window_id"></span>`window_id` | `integer` | | Exact native window approval anchor; required for strategy.kind=existing_profile. |diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdxindex da920e6d70..f5441240f8 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/pointer.mdx@@ -229,12 +229,13 @@ Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.<Tabs items={['macOS', 'Linux', 'Windows']} groupId="platform" persist><Tab value="macOS">-Move a cursor to (x, y). With target {kind: "window", pid, window_id}, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover. With scope=desktop, moves the real OS pointer in native get_desktop_state screenshot coordinates.+Move a cursor to (x, y). With target {kind: "window", pid, window_id}, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover; for a web page in Chrome, Edge or Brave use browser_pointer hover instead. With scope=desktop, moves the user's real OS pointer in native get_desktop_state screenshot coordinates; over a window of an app that is not in front it refuses unless delivery_mode is "foreground".**macOS parameters**| Parameter | Type | Default | Description || --- | --- | --- | --- |+| <span id="move_cursor--macos--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | | Desktop scope only. Default "background": refuses, before moving anything, when the point is over a window of an app that is not in front, since that would move the user's pointer. "foreground": move the real pointer anyway; only when nobody is using this screen or the user agreed. || <span id="move_cursor--macos--scope"></span>`scope` | `"window" \| "desktop"` | `"window"` | "window" (default) moves only the agent cursor overlay; "desktop" moves the real OS pointer. || <span id="move_cursor--macos--x"></span>`x` | `number` | required | Destination X. Window target: window screenshot pixels. No target: screen points for the agent cursor overlay. Desktop scope: native get_desktop_state screenshot pixels. |diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.mdindex 7ddd90977d..a2980d73c2 100644--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md@@ -109,7 +109,13 @@ title looks close.`get_browser_state` is strictly read-only. It never launches a browser,changes a profile, enables remote debugging, or accepts a consent prompt. Ifit returns `browser_requires_setup` or `browser_consent_required`, choose one-explicit preparation flow. A standalone consumer browser cannot bind through+explicit preparation flow. For the user's running Chrome, Edge or Brave the+refusal's `detail.next_call` is the exact `browser_prepare` call to make next+(`pid`, `window_id`, `session`, `strategy:{"kind":"existing_profile"}`). It is+the driver's own setup step, not a question for the user: make the call, and it+attaches or refuses with nothing changed and says why. Do not fall back to+desktop-target pointer tools for the page; they move the user's real pointer,+and over a background window they refuse. A standalone consumer browser cannot bind througha DevTools listener merely because the listener belongs to that process.### Driver-owned isolated profilediff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.mdindex 9f271ecf74..04ce019572 100644--- a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md+++ b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md@@ -123,7 +123,7 @@ is safe even for apps that normally foreground on media-load| Click / type / scroll / keys | `click`, `type_text`, `scroll`, `press_key`, `hotkey` | `osascript`, `cliclick`, raw `CGEvent`, `open <url>` || Loop, branch or retry over app actions | `run_script({script})` (sandboxed JavaScript over the `cua` API, one call); `run_steps` for a fixed list | an AppleScript or shell loop around `osascript` or `cua-driver` calls || Drag / drag-and-drop / marquee select | `drag({pid, window_id, from_x, from_y, to_x, to_y, delivery_mode:"foreground"})` (pixel-only and foreground-only: macOS AX has no semantic drag, and there is no background drag) | `cliclick dd:`, `osascript drag` |-| Hover (reveal a hover-only control) | Window-targeted `move_cursor`; its result says whether it hovered (AX alternate UI or an Electron page). If not, look for the same command elsewhere (menu item, context menu, shortcut, help text in `get_window_state`); only `move_cursor({scope:"desktop"})` (moves the user's pointer) or `bring_to_front` reveals it, and only if the user allows it | assuming a window-targeted `move_cursor` hovered when its result says the app sees no hover |+| Hover (reveal a hover-only control) | Window-targeted `move_cursor`; its result says whether it hovered (AX alternate UI or an Electron page). A web page in Chrome, Edge or Brave: `browser_pointer` hover after `get_browser_state`. If not, look for the same command elsewhere (menu item, context menu, shortcut, help text in `get_window_state`); only `move_cursor({scope:"desktop", delivery_mode:"foreground"})` (moves the user's pointer) or `bring_to_front` reveals it, and only if the user allows it | assuming a window-targeted `move_cursor` hovered when its result says the app sees no hover; a desktop `move_cursor` over a background browser page || Screenshot | `get_window_state` (window) or authorized `get_desktop_state` (desktop) | `screencapture` || Quit an app | ask the user first, then `hotkey({pid, keys:["cmd","q"]})` | `kill`, `killall`, `pkill` || Hand a file/URL to an app | `launch_app({bundle_id, urls:[<path>]})` | `open -a <App> <path>`, `open <url>` |@@ -351,14 +351,26 @@ and how:the app's main process, so page hover effects update. Native tooltips donot show.-For a web page in Chrome use `browser_pointer` hover. Otherwise-`move_cursor` moves only the agent cursor and says so. Look for the same-command elsewhere first: a menu item, a context menu, a keyboard-shortcut, or the control's help text in `get_window_state` (toolbar-tooltips are usually there as `help=`). Otherwise the step needs the-user's pointer (`move_cursor` with `scope:"desktop"`) or the app in front+For a web page in Chrome, Edge or Brave use `browser_pointer` hover: a+window-target `move_cursor` there says the page saw no hover and names+`get_browser_state` as the next call. Otherwise `move_cursor` moves only the+agent cursor and says so. Look for the same command elsewhere first: a menu+item, a context menu, a keyboard shortcut, or the control's help text in+`get_window_state` (toolbar tooltips are usually there as `help=`).+Otherwise the step needs the user's pointer (`move_cursor` with+`scope:"desktop"` and `delivery_mode:"foreground"`) or the app in front(`bring_to_front`); use either only if the user allows it, and say which.+### Desktop-target pointer input over a background app++`move_cursor`, `click`, `drag` and `scroll` with a desktop target move the+user's real pointer. When the point lands on a window of an app that is not+in front, they refuse with `background_unavailable` before sending anything,+unless the call passes `delivery_mode:"foreground"`. Over a web browser the+refusal names the browser tools (`get_browser_state`, then+`browser_pointer`, `browser_click` or `browser_type`) instead of foreground.+Points over the app in front, or over no window, behave as before.+### `delivery_mode` on the pointer family (macOS)`click`, `double_click`, `right_click`, `drag`, and `scroll` acceptdiff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.mdindex 2900aa3d0d..7c6f311a1f 100644--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md@@ -57,7 +57,7 @@ The MCP server instructions carry the same rules, so they apply even when this f| Use pixels when semantics cannot reach it | Fresh target screenshot, then `x,y` on the same target | [Workflow](WORKFLOW.md) || Verify the outcome | `verify_state({pid, window_id, expect})` or a fresh snapshot read by the agent | [Workflow](WORKFLOW.md) || Operate the authorized desktop | `get_desktop_state` → input with `target:{kind:"desktop",display_id:"primary"}` → `get_desktop_state` | [Workflow](WORKFLOW.md), [Linux](LINUX.md) on Wayland |-| Drive supported browser page content | `get_browser_state` → typed browser action → fresh state | [Browser](BROWSER.md) |+| Drive supported browser page content | `get_browser_state` → `browser_prepare` from `detail.next_call` if refused → typed browser action | [Browser](BROWSER.md) || Record an explicitly requested run | `start_recording` → actions → `stop_recording`; verify artifacts | [Recording](RECORDING.md) || Finish | Stop after proof; `end_session` for this run, not `cua-driver stop` on a shared service | [Runtime](RUNTIME.md) |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.rsindex 68ca93ce8e..5599276b79 100644--- 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.rs@@ -173,6 +173,47 @@ pub(super) fn unsupported_engine_refusal(}))}+/// What an agent reads when a user's own browser is not attached yet. Agents+/// read the old "requires explicit existing-profile approval" wording as a+/// request for the user's approval and gave up, or fell back to desktop pointer+/// tools that move the user's pointer (Bench v2 PR-02: 23 of 28 trials stopped+/// here without calling browser_prepare). Name the call that attaches instead.+const CONSUMER_PROFILE_NOT_ATTACHED: &str = "Cua is not attached to this browser window yet. \+ Call browser_prepare with this pid and window_id and strategy {\"kind\":\"existing_profile\"} \+ (detail.next_call has the exact arguments). It attaches the browser tools, or refuses \+ with nothing changed and says why; any approval the host requires is handled there. \+ Do not switch to desktop pointer tools for this page: they move the user's pointer.";++/// Add the exact `browser_prepare` call to a not-yet-attached refusal.+fn with_existing_profile_next_call(+ mut refusal: BrowserRefusal,+ session: &str,+ pid: i64,+ window_id: u64,+) -> BrowserRefusal {+ if refusal.code != BrowserRefusalCode::BrowserConsentRequired {+ return refusal;+ }+ let mut detail = match refusal.detail.take() {+ Some(Value::Object(detail)) => detail,+ _ => serde_json::Map::new(),+ };+ detail.insert(+ "next_call".to_owned(),+ json!({+ "tool": "browser_prepare",+ "arguments": {+ "pid": pid,+ "window_id": window_id,+ "session": session,+ "strategy": { "kind": "existing_profile" },+ },+ }),+ );+ refusal.detail = Some(Value::Object(detail));+ refusal+}+fn endpoint_access_class(has_existing_profile_grant: bool,driver_owned: bool,@@ -188,7 +229,7 @@ fn endpoint_access_class(BrowserProcessRole::EmbeddedApplication => Ok(EndpointAccessClass::EmbeddedApplication),BrowserProcessRole::StandaloneConsumer => Err(refuse(BrowserRefusalCode::BrowserConsentRequired,- "this standalone browser profile requires explicit existing-profile approval before Cua can inspect its DevTools endpoint",+ CONSUMER_PROFILE_NOT_ATTACHED,).with_detail(json!({"reason": "consumer_profile_endpoint_requires_grant",@@ -1258,8 +1299,8 @@ impl BrowserEngine {let driver_owned = self.is_driver_owned_pid_for_session(session, pid)|| transport_session.is_some_and(|owner| self.is_driver_owned_pid_for_session(owner, pid));- let access_class =- endpoint_access_class(grant.is_some(), driver_owned, class.process_role)?;+ let access_class = endpoint_access_class(grant.is_some(), driver_owned, class.process_role)+ .map_err(|refusal| with_existing_profile_next_call(refusal, session, pid, window_id))?;let native = self.native_window_checked(pid, window_id).await?;let fingerprint = self.platform.process_fingerprint(pid).await?;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 1d0db839b4..4aed3981f4 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@@ -275,9 +275,11 @@ impl GetBrowserStateTool {semantic_v2 joins accessibility, DOM, layout, and viewport state; \ranks visible content before retained/offscreen state; and returns a \semantic outline, typed action refs, content refs, scoped reads, and \- opaque continuation. Never performs setup — a missing \- endpoint is a structured browser_requires_setup refusal pointing at \- browser_prepare."+ opaque continuation. Never performs setup: a browser that is not \+ attached yet refuses with browser_consent_required or \+ browser_requires_setup, and detail.next_call names the browser_prepare call \+ that attaches it. Use this route for any web page in Chrome, Edge or Brave; \+ desktop pointer tools move the user's pointer.".into(),input_schema: json!({"type": "object",@@ -607,7 +609,13 @@ 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. \+ description: "Attach the browser tools to a browser. For a page in the user's \+ running Chrome, Edge or Brave, call it once with pid, window_id, session and \+ strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with \+ browser_consent_required or browser_requires_setup; then call \+ get_browser_state again and act with browser_click, browser_type or \+ browser_pointer. It attaches, or refuses with nothing changed and says why. \+ Explicitly prepare an owned DevTools endpoint for a browser. \pid is required for an existing process or existing-profile attachment, \and optional only for allow_launch=true with an isolated profile. Existing \endpoints are detected without side effects. Acting setup \@@ -654,7 +662,7 @@ impl BrowserPrepareTool {},"strategy": {"type": "object",- "description": "Attach to an already-running browser instead of launching one. kind=existing_profile attaches to the user's running profile at pid/window_id and requires explicit profile authorization.",+ "description": "Attach to an already-running browser instead of launching one. Pass an object, {\"kind\":\"existing_profile\"}, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization.","properties": {"kind": { "type": "string", "enum": ["existing_profile"] }},@@ -710,7 +718,9 @@ impl Tool for BrowserPrepareTool {Ok(strategy) => Some(strategy),Err(error) => {return ToolResult::error(format!(- "invalid browser preparation strategy: {error}"+ "invalid browser preparation strategy ({error}). Pass an object: \+ \"strategy\": {{\"kind\": \"existing_profile\"}}, with pid and \+ window_id from list_windows."))}},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 a65cf71781..15c8c3085d 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@@ -1201,6 +1201,24 @@ async fn standalone_consumer_bind_without_grant_refuses_before_endpoint_discoverrefusal["refusal"]["detail"]["next_action"],"browser_prepare");+ // The refusal names the exact call that attaches, so an agent does not+ // read it as a request for the user's approval (Bench v2 PR-02).+ assert_eq!(+ refusal["refusal"]["detail"]["next_call"],+ json!({+ "tool": "browser_prepare",+ "arguments": {+ "pid": 1,+ "window_id": 7,+ "session": SESSION,+ "strategy": { "kind": "existing_profile" },+ },+ })+ );+ let message = refusal["refusal"]["message"].as_str().unwrap();+ assert!(message.contains("not attached to this browser window yet"));+ assert!(message.contains("Call browser_prepare"));+ assert!(!message.contains("approval before"));assert!(!managed_discovery_invoked.load(Ordering::SeqCst),"read-only bind must not inspect a consent-gated endpoint"diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rsindex 79cc410e9c..f3db20d16e 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs@@ -393,14 +393,16 @@ fn agent_instructions() -> String {r#"cua-driver: background GUI automation. No shell: for non-GUI outcomes use an app API/SDK, CLI or filesystem and read the result back there.Efficient loop:-1. `list_windows({{app:"Name"}})` or `launch_app` for `pid` and `window_id`. Unfiltered `list_windows`/`list_apps` list the whole host.-2. Read narrowly: `get_window_state` with `query:"Save"` (or `max_elements`). Re-read with `since:"latest"` for only what changed. For just a picture, `include_accessibility_tree:false` (tokens stay valid).+1. `list_windows({{app:"Name"}})` or `launch_app` for `pid` and `window_id`.+2. Read narrowly: `get_window_state` with `query:"Save"` (or `max_elements`). Re-read with `since:"latest"`; for just a picture, `include_accessibility_tree:false`.3. Act by `element_token` ({tree_kind}): row `[N]` is `<snapshot_id>:N`. Pixel `x,y` only for surfaces missing from the tree.-4. Act through `run_steps({{steps:[{{tool,args}}],observe:{{}}}})`, even for one step: it stops at the first failure and returns what changed, so no separate re-read.{script_line}+4. Act through `run_steps({{steps:[{{tool,args}}],observe:{{}}}})`, even for one step: it stops at the first failure and returns what changed.{script_line}5. Verify at checkpoints, not after every action: `verify_state(pid, window_id, expect)`. `unknown` and `effect:"unverifiable"` are not success.Use the narrowest semantic route first: `set_window_frame` plus `list_windows` for geometry, typed browser tools for pages, clipboard tools for the clipboard. Stay in the background; `delivery_mode:"foreground"` only if refused or unverifiable.+Chrome/Edge/Brave page: `get_browser_state({{pid, window_id}})`, its `detail.next_call` (`browser_prepare`) if refused, then `browser_click`/`browser_type`/`browser_pointer` (hover, drag); never desktop pointer tools.+`start_session` is optional; repeat a short `session` label on every call that accepts it. On continuation/recent-work, call `history_status`; if ready, make one bounded initial `history_query` before broad discovery.Details: `skill://cua-driver/SKILL.md` and {platform_skill_pointer}."#@@ -501,6 +503,11 @@ mod agent_instruction_tests {assert!(instructions.contains("narrowest semantic route first"));assert!(instructions.contains("`set_window_frame` plus `list_windows`"));assert!(instructions.contains("typed browser tools"));+ assert!(instructions.contains("`get_browser_state({pid, window_id})`"));+ assert!(instructions.contains("`detail.next_call` (`browser_prepare`)"));+ assert!(+ instructions.contains("`browser_pointer` (hover, drag); never desktop pointer tools")+ );assert!(instructions.contains("No shell"));// The efficient workflow must be front-loaded: targeted read, act by// token, verify at checkpoints.diff --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 51c6c505b6..8a0b00b9ca 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@@ -243,6 +243,10 @@ fn assert_tools_list_schema_shape(mut d: RawDriver) {"browser_prepare",// The batch's default for its steps' own delivery_mode."run_steps",+ // macOS desktop move_cursor refuses over a background app unless+ // foreground is requested.+ #[cfg(target_os = "macos")]+ "move_cursor",// macOS set_value has no delivery ladder.#[cfg(any(target_os = "linux", target_os = "windows"))]"set_value",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rsindex d6285b383b..b15687b123 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs@@ -402,6 +402,11 @@ impl Tool for ClickTool {return ToolResult::error("click.count must be at least 1.").with_structured(serde_json::json!({ "code": "invalid_arguments" }));}+ if let Some(refusal) =+ super::desktop_pointer_guard::check("click", &args, vec![(sx, sy)]).await+ {+ return refusal;+ }// Glide the session's agent cursor to the screen point for visibility.let cursor_key = super::cursor_tools::resolve_cursor_key(&args);crate::cursor::overlay::animate_cursor_to(cursor_key.clone(), sx, sy).await;diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/desktop_pointer_guard.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/desktop_pointer_guard.rsnew file mode 100644index 0000000000..9d31492e16--- /dev/null+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/desktop_pointer_guard.rs@@ -0,0 +1,295 @@+//! Desktop-target pointer input drives the user's real pointer.+//!+//! `move_cursor`, `click`, `drag` and `scroll` with a desktop target post+//! their events at a screen point through the real pointer. Over a window of+//! the app the user is in (the frontmost one), that is ordinary foreground+//! work. Over a window of another app it is background work done with the+//! user's pointer: the pointer jumps out from under the user, and a click also+//! activates that app. Bench v2 caught this on Chrome pages: when the browser+//! route was refused, agents hovered the page with a desktop `move_cursor`+//! and moved the user's pointer (PR-03: 10 of 31 trials).+//!+//! So a desktop-target pointer action whose point lands on a window of an+//! app that is not frontmost refuses with `background_unavailable`, before+//! any event, unless the caller passed `delivery_mode:"foreground"`. Over a+//! Chromium browser the refusal names the browser tools, which act on the+//! page without the user's pointer, instead of recommending foreground.+//! Points over no window, or over the frontmost app, are unchanged.++use cua_driver_core::{+ delivery::{background_unavailable_result, DeliveryMode},+ protocol::ToolResult,+};+use serde_json::{json, Value};++/// The window under a desktop point, as the guard needs it.+#[derive(Clone, Debug, PartialEq)]+pub(crate) struct WindowUnderPoint {+ pub pid: i32,+ pub window_id: u32,+ pub app_name: String,+ pub bundle_id: String,+}++impl WindowUnderPoint {+ fn is_chromium_browser(&self) -> bool {+ super::type_text::is_chromium_identity(&self.bundle_id)+ }+}++/// Topmost ordinary (layer 0, on-screen) window containing the desktop point+/// `(x, y)` in screen points, skipping the driver's own windows (the cursor+/// overlay). Blocking: enumerates windows.+pub(crate) fn window_under_point(x: f64, y: f64) -> Option<WindowUnderPoint> {+ let own = std::process::id() as i32;+ let window = crate::windows::visible_windows()+ .into_iter()+ .filter(|w| w.layer == 0 && w.is_on_screen && w.pid != own)+ .filter(|w| {+ let b = &w.bounds;+ x >= b.x && x < b.x + b.width && y >= b.y && y < b.y + b.height+ })+ .max_by_key(|w| w.z_index)?;+ Some(WindowUnderPoint {+ pid: window.pid,+ window_id: window.window_id,+ app_name: window.app_name,+ bundle_id: crate::apps::bundle_id_for_pid(window.pid).unwrap_or_default(),+ })+}++/// The refusal for a desktop-target pointer action at `point` over `under`,+/// or `None` when it may proceed. Pure, for tests.+pub(crate) fn refusal_for(+ tool: &str,+ point: (f64, f64),+ under: Option<&WindowUnderPoint>,+ frontmost_pid: Option<i32>,+ delivery: DeliveryMode,+) -> Option<ToolResult> {+ let under = under?;+ if delivery.is_foreground() || frontmost_pid == Some(under.pid) {+ return None;+ }+ let (x, y) = point;+ let event_kind = match tool {+ "move_cursor" => "pointer_move",+ "drag" => "drag",+ "scroll" => "scroll",+ _ => "click",+ };+ let lead = format!(+ "{tool} with a desktop target moves the user's real pointer, and ({x:.0}, {y:.0}) is over \+ {app} (pid {pid}, window {wid}), which is not the app in front, so this would do \+ background work with the user's pointer. Nothing was sent.",+ app = under.app_name,+ pid = under.pid,+ wid = under.window_id,+ );+ let window = json!({+ "pid": under.pid,+ "window_id": under.window_id,+ "app_name": under.app_name,+ });+ if under.is_chromium_browser() {+ let message = format!(+ "{lead} {app} is a web browser: act on the page with the browser tools, which leave \+ the user's pointer alone. Call get_browser_state with pid {pid} and window_id {wid}, \+ then browser_pointer (hover, drag, scroll, double or right click), browser_click or \+ browser_type with its target_id and tab_id. If get_browser_state refuses, make the \+ browser_prepare call in its detail.next_call. If browser_prepare refuses too, this \+ page cannot be driven in the background right now: say so rather than taking the \+ user's pointer.",+ app = under.app_name,+ pid = under.pid,+ wid = under.window_id,+ );+ return Some(+ ToolResult::error(message).with_structured(json!({+ "code": "background_unavailable",+ "event_kind": event_kind,+ "window": window,+ "suggestion": "Use the browser tools: get_browser_state, then browser_pointer, browser_click or browser_type.",+ "escalation": {+ "recommended": "page",+ "reason": "the point is on a background web browser page; the browser tools act on it without the user's pointer",+ },+ "next_call": {+ "tool": "get_browser_state",+ "arguments": { "pid": under.pid, "window_id": under.window_id },+ },+ })),+ );+ }+ let message = format!(+ "{lead} Use a window target instead: target {{kind:\"window\", pid:{pid}, \+ window_id:{wid}}} with x,y in that window's screenshot pixels{move_note}. Retry with \+ delivery_mode:\"foreground\" only when nobody is using this screen or the user agreed \+ to hand over the pointer.",+ pid = under.pid,+ wid = under.window_id,+ move_note = if tool == "move_cursor" {+ " (it moves only the agent cursor and hovers through a background route where one \+ exists)"+ } else {+ ""+ },+ );+ Some(background_unavailable_result(+ message,+ "background_unavailable",+ "the desktop point is over a background app; a desktop-target pointer action would move the user's pointer",+ json!({ "event_kind": event_kind, "window": window }),+ ))+}++/// Guard a desktop-target pointer action whose events land at `points`+/// (screen points). Returns the refusal for the first point over a background+/// app, or `None` when every point may proceed.+pub(crate) async fn check(+ tool: &'static str,+ args: &Value,+ points: Vec<(f64, f64)>,+) -> Option<ToolResult> {+ let delivery = DeliveryMode::from_args(args);+ if delivery.is_foreground() {+ return None;+ }+ tokio::task::spawn_blocking(move || {+ let frontmost = crate::apps::frontmost_pid();+ points.into_iter().find_map(|point| {+ let under = window_under_point(point.0, point.1);+ refusal_for(tool, point, under.as_ref(), frontmost, delivery)+ })+ })+ .await+ .ok()+ .flatten()+}++#[cfg(test)]+mod tests {+ use super::*;++ fn chrome() -> WindowUnderPoint {+ WindowUnderPoint {+ pid: 8601,+ window_id: 659,+ app_name: "Google Chrome".into(),+ bundle_id: "com.google.Chrome".into(),+ }+ }++ fn benchlab() -> WindowUnderPoint {+ WindowUnderPoint {+ pid: 4242,+ window_id: 77,+ app_name: "BenchLab".into(),+ bundle_id: "com.trycua.benchlab".into(),+ }+ }++ fn text(result: &ToolResult) -> String {+ serde_json::to_value(result).unwrap()["content"][0]["text"]+ .as_str()+ .unwrap()+ .to_owned()+ }++ #[test]+ fn a_desktop_move_over_a_background_chrome_names_the_browser_route() {+ // Bench v2 PR-03: Chrome on the user's Space, another app in front.+ let refusal = refusal_for(+ "move_cursor",+ (384.0, 490.0),+ Some(&chrome()),+ Some(1),+ DeliveryMode::Background,+ )+ .expect("refuses");+ assert_eq!(refusal.is_error, Some(true));+ let message = text(&refusal);+ assert!(message.contains("Nothing was sent"));+ assert!(message.contains("get_browser_state with pid 8601 and window_id 659"));+ assert!(message.contains("browser_pointer (hover"));+ assert!(message.contains("detail.next_call"));+ assert!(!message.contains("delivery_mode:\"foreground\""));+ let structured = refusal.structured_content.unwrap();+ assert_eq!(structured["code"], "background_unavailable");+ assert_eq!(structured["event_kind"], "pointer_move");+ assert_eq!(structured["escalation"]["recommended"], "page");+ assert_eq!(structured["next_call"]["tool"], "get_browser_state");+ assert_eq!(structured["next_call"]["arguments"]["window_id"], 659);+ }++ #[test]+ fn a_desktop_pointer_action_over_another_background_app_offers_a_window_target() {+ for (tool, kind) in [+ ("move_cursor", "pointer_move"),+ ("click", "click"),+ ("drag", "drag"),+ ("scroll", "scroll"),+ ] {+ let refusal = refusal_for(+ tool,+ (10.0, 10.0),+ Some(&benchlab()),+ Some(1),+ DeliveryMode::Background,+ )+ .expect("refuses");+ let message = text(&refusal);+ assert!(message.starts_with(tool), "{message}");+ assert!(message.contains("target {kind:\"window\", pid:4242, window_id:77}"));+ assert!(message.contains("delivery_mode:\"foreground\" only when"));+ let structured = refusal.structured_content.unwrap();+ assert_eq!(structured["code"], "background_unavailable");+ assert_eq!(structured["event_kind"], kind);+ assert_eq!(structured["escalation"]["recommended"], "foreground");+ assert_eq!(structured["window"]["pid"], 4242);+ }+ }++ #[test]+ fn the_frontmost_app_foreground_delivery_and_bare_desktop_are_unchanged() {+ // The app the user is in: ordinary foreground work.+ assert!(refusal_for(+ "move_cursor",+ (1.0, 1.0),+ Some(&chrome()),+ Some(8601),+ DeliveryMode::Background,+ )+ .is_none());+ // The caller explicitly accepted using the real pointer.+ assert!(refusal_for(+ "move_cursor",+ (1.0, 1.0),+ Some(&chrome()),+ Some(1),+ DeliveryMode::Foreground,+ )+ .is_none());+ // No window under the point.+ assert!(refusal_for(+ "move_cursor",+ (1.0, 1.0),+ None,+ Some(1),+ DeliveryMode::Background,+ )+ .is_none());+ }++ #[test]+ fn an_unknown_frontmost_app_still_refuses_over_a_window() {+ assert!(refusal_for(+ "click",+ (1.0, 1.0),+ Some(&benchlab()),+ None,+ DeliveryMode::Background,+ )+ .is_some());+ }+}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rsindex 85e3579685..d08518eb06 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs@@ -157,6 +157,15 @@ impl Tool for DragTool {let (from_x, from_y, to_x, to_y) = (input.from_x, input.from_y, input.to_x, input.to_y);let (from_x, from_y) = super::desktop_screenshot_point(from_x, from_y).await;let (to_x, to_y) = super::desktop_screenshot_point(to_x, to_y).await;+ if let Some(refusal) = super::desktop_pointer_guard::check(+ "drag",+ &args,+ vec![(from_x, from_y), (to_x, to_y)],+ )+ .await+ {+ return refusal;+ }let duration_ms = input.duration_ms.unwrap_or(500).min(10_000);let steps = input.steps.unwrap_or(20).clamp(1, 200) as usize;let modifiers = input.modifier.unwrap_or_default();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 234d04b49b..1d14c4e638 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@@ -27,6 +27,7 @@ mod type_text;// through GetWindowStateTool.mod check_permissions;mod cursor_tools;+mod desktop_pointer_guard;mod get_accessibility_tree;mod get_config;mod get_cursor_position;diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rsindex 88b3cf0e8e..669f409bf6 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs@@ -31,8 +31,10 @@ fn def() -> &'static ToolDef {pointer alone where one exists (AXShowAlternateUI on the element under the point, \or an Electron page) and says so. Without a target, moves only the agent cursor \overlay, in screen points. Other macOS hover and tooltips follow the real pointer, \- so most background apps see no hover. With scope=desktop, moves the real OS pointer \- in native get_desktop_state screenshot coordinates.".into(),+ so most background apps see no hover; for a web page in Chrome, Edge or Brave use \+ browser_pointer hover instead. With scope=desktop, moves the user's real OS pointer \+ in native get_desktop_state screenshot coordinates; over a window of an app that is \+ not in front it refuses unless delivery_mode is \"foreground\".".into(),input_schema: serde_json::json!({"type": "object","required": ["x", "y"],@@ -41,7 +43,8 @@ fn def() -> &'static ToolDef {"x": { "type": "number", "description": "Destination X. Window target: window screenshot pixels. No target: screen points for the agent cursor overlay. Desktop scope: native get_desktop_state screenshot pixels." },"y": { "type": "number", "description": "Destination Y, in the same space as x." },"scope": { "type": "string", "enum": ["window", "desktop"], "default": "window", "description": "\"window\" (default) moves only the agent cursor overlay; \"desktop\" moves the real OS pointer." },- "cursor_id": { "type": "string", "description": "Cursor instance to move. Default: 'default'." }+ "cursor_id": { "type": "string", "description": "Cursor instance to move. Default: 'default'." },+ "delivery_mode": cua_driver_core::tool_schema::delivery_mode_schema_with("Desktop scope only. Default \"background\": refuses, before moving anything, when the point is over a window of an app that is not in front, since that would move the user's pointer. \"foreground\": move the real pointer anyway; only when nobody is using this screen or the user agreed.")},"additionalProperties": false}),@@ -67,6 +70,11 @@ impl Tool for MoveCursorTool {};let (x, y) = (input.x, input.y);let (x, y) = super::desktop_screenshot_point(x, y).await;+ if let Some(refusal) =+ super::desktop_pointer_guard::check("move_cursor", &args, vec![(x, y)]).await+ {+ return refusal;+ }let result =tokio::task::spawn_blocking(move || crate::input::mouse::move_cursor_desktop(x, y)).await;@@ -183,6 +191,13 @@ impl MoveCursorTool {}));}// Background app: try the hover routes that leave the real pointer alone.+ let chromium = tokio::task::spawn_blocking(move || {+ super::type_text::is_chromium_identity(+ &crate::apps::bundle_id_for_pid(pid).unwrap_or_default(),+ )+ })+ .await+ .unwrap_or(false);let ax = tokio::task::spawn_blocking(move || {crate::input::hover::reveal_alternate_ui(pid, wid, screen_x, screen_y)})@@ -196,6 +211,9 @@ impl MoveCursorTool {format!(" \"{}\"", reveal.label)};let revealed = reveal.revealed_new_controls();+ if !revealed && chromium {+ return browser_hover_result(&cursor_id, pid, wid, x, y, screen_x, screen_y);+ }let outcome = if revealed {format!("Revealed the hover-only controls of {}{label} through AXShowAlternateUI \@@ -250,6 +268,9 @@ impl MoveCursorTool {}}}+ if chromium {+ return browser_hover_result(&cursor_id, pid, wid, x, y, screen_x, screen_y);+ }ToolResult::text(format!("Agent cursor '{cursor_id}' moved over window {wid} at ({x:.0}, {y:.0}); the real \pointer did not move.{BACKGROUND_HOVER_NOTE}"@@ -264,6 +285,44 @@ impl MoveCursorTool {}}+/// A window-target move over a background Chromium browser: the page saw no+/// hover, and the browser tools are the route that delivers one without the+/// user's pointer. Bench v2 PR-03 agents read the generic note's desktop+/// option as the way forward and moved the user's pointer.+fn browser_hover_result(+ cursor_id: &str,+ pid: i32,+ wid: u32,+ x: f64,+ y: f64,+ screen_x: f64,+ screen_y: f64,+) -> ToolResult {+ ToolResult::text(format!(+ "Agent cursor '{cursor_id}' moved over window {wid} at ({x:.0}, {y:.0}); the real \+ pointer did not move and the page saw no hover. {BROWSER_HOVER_NOTE}"+ ))+ .with_structured(serde_json::json!({+ "scope": "window",+ "window_id": wid,+ "screen_point": [screen_x, screen_y],+ "hover_delivered": false,+ "effect": "unverifiable",+ "next_call": {+ "tool": "get_browser_state",+ "arguments": { "pid": pid, "window_id": wid },+ },+ }))+}++/// The browser route for hover on a background web page.+const BROWSER_HOVER_NOTE: &str = "This is a web browser page: hover it with the browser tools, \+ which reach the page without the user's pointer. Call get_browser_state with this pid and \+ window_id, then browser_pointer with action \"hover\" and the element's ref (or viewport \+ x,y) from that snapshot. If get_browser_state refuses, make the browser_prepare call in its \+ detail.next_call. A desktop-scope move_cursor would move the user's pointer and refuses \+ over a background app.";+/// What a window-target move does not do for a background app.const BACKGROUND_HOVER_NOTE: &str = " The app is in the background, so it sees no hover: \macOS apps track hover and show tooltips from the real pointer, and nothing under this \@@ -310,6 +369,36 @@ mod tests {assert!(note.contains("only if the user allows it"));}+ #[test]+ fn the_browser_hover_note_routes_to_the_browser_tools_not_the_desktop() {+ let result = super::browser_hover_result("default", 8601, 659, 344.0, 450.0, 384.0, 490.0);+ let value = serde_json::to_value(&result).unwrap();+ let text = value["content"][0]["text"].as_str().unwrap();+ assert!(text.contains("the page saw no hover"));+ assert!(text.contains("get_browser_state"));+ assert!(text.contains("browser_pointer with action \"hover\""));+ assert!(text.contains("detail.next_call"));+ assert!(!text.contains("scope:\"desktop\""));+ let structured = result.structured_content.unwrap();+ assert_eq!(structured["hover_delivered"], false);+ assert_eq!(structured["next_call"]["tool"], "get_browser_state");+ assert_eq!(structured["next_call"]["arguments"]["pid"], 8601);+ }++ #[test]+ fn desktop_scope_advertises_the_foreground_opt_in() {+ let def = super::def();+ assert!(def+ .description+ .contains("refuses unless delivery_mode is \"foreground\""));+ assert!(def.description.contains("browser_pointer hover"));+ let mode = &def.input_schema["properties"]["delivery_mode"];+ assert_eq!(+ mode["enum"],+ serde_json::json!(["background", "foreground"])+ );+ }+#[test]fn the_inactive_app_note_names_the_route_to_a_tooltip() {let note = super::inactive_app_note("BenchLab");diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rsindex df35919e5e..3a2554aaf7 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs@@ -146,6 +146,11 @@ impl Tool for ScrollTool {ScrollDirection::Left => (0, step),};let (x, y) = super::desktop_screenshot_point(x, y).await;+ if let Some(refusal) =+ super::desktop_pointer_guard::check("scroll", &args, vec![(x, y)]).await+ {+ return refusal;+ }let result = tokio::task::spawn_blocking(move || {crate::input::mouse::scroll_wheel_desktop(x, y, delta_y, delta_x, amount)})diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rsindex 41069d7610..b8016a8db5 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs@@ -1103,7 +1103,7 @@ pub(super) fn is_browser_pid(pid: i32) -> bool {crate::browser::browser_js::BrowserJs::supports(&bundle_id) || is_chromium_identity(&bundle_id)}-fn is_chromium_identity(bundle_id: &str) -> bool {+pub(crate) fn is_chromium_identity(bundle_id: &str) -> bool {bundle_id.to_ascii_lowercase().split(|ch: char| !ch.is_ascii_alphanumeric())diff --git a/libs/cua-spacesd/crates/cua-spacesd-desktop/src/tool_input.rs b/libs/cua-spacesd/crates/cua-spacesd-desktop/src/tool_input.rsindex c4cc837527..c0bf38a292 100644--- a/libs/cua-spacesd/crates/cua-spacesd-desktop/src/tool_input.rs+++ b/libs/cua-spacesd/crates/cua-spacesd-desktop/src/tool_input.rs@@ -226,6 +226,17 @@ fn desktop_arguments() -> Map<String, Value> {arguments}+/// Desktop pointer input from a person driving the display. The macOS driver+/// refuses a desktop pointer action over a background app unless the caller+/// accepts using the real pointer; this viewer is the person at the pointer.+fn desktop_pointer_arguments() -> Map<String, Value> {+ #[allow(unused_mut)]+ let mut arguments = desktop_arguments();+ #[cfg(target_os = "macos")]+ arguments.insert("delivery_mode".into(), "foreground".into());+ arguments+}+impl ToolInputLease {/// The Windows driver can move the real desktop pointer. Window scope/// moves only its agent overlay, so never opt that route into hover.@@ -257,7 +268,7 @@ impl ToolInputLease {ToolInputTarget::Window { pid, window_id, .. } => {window_arguments(*pid, *window_id, self.mode)}- ToolInputTarget::Display { .. } => desktop_arguments(),+ ToolInputTarget::Display { .. } => desktop_pointer_arguments(),}}@@ -401,7 +412,7 @@ impl InteractiveInputLease for ToolInputLease {calls.extend(self.call(gesture, extent));}let (x, y) = self.point(x, y, extent);- let mut arguments = desktop_arguments();+ let mut arguments = desktop_pointer_arguments();arguments.insert("x".into(), x.into());arguments.insert("y".into(), y.into());calls.push(("move_cursor", arguments));@@ -531,6 +542,26 @@ mod tests {}}+ /// Expected desktop pointer arguments: the macOS driver needs the+ /// viewer's explicit foreground opt-in for the real pointer.+ fn desktop_pointer(mut expected: Value) -> Value {+ if cfg!(target_os = "macos") {+ expected["delivery_mode"] = json!("foreground");+ }+ expected+ }++ #[test]+ fn desktop_pointer_input_opts_into_the_real_pointer_on_macos_only() {+ let pointer = Value::Object(desktop_pointer_arguments());+ assert_eq!(pointer, desktop_pointer(json!({"scope": "desktop"})));+ // Keys keep the plain desktop scope.+ assert_eq!(+ Value::Object(desktop_arguments()),+ json!({"scope": "desktop"})+ );+ }+fn hover_lease(tools: Arc<Recorded>) -> ToolInputLease {open(&display_target(),@@ -598,7 +629,9 @@ mod tests {vec![("click".into(),- json!({"scope": "desktop", "x": 640.0, "y": 400.0, "button": "left"})+ desktop_pointer(+ json!({"scope": "desktop", "x": 640.0, "y": 400.0, "button": "left"})+ )),// Keys and text go to the focused window, in the foreground.(@@ -617,7 +650,9 @@ mod tests {),("scroll".into(),- json!({"scope": "desktop", "x": 320.0, "y": 200.0, "direction": "down", "amount": 2})+ desktop_pointer(+ json!({"scope": "desktop", "x": 320.0, "y": 200.0, "direction": "down", "amount": 2})+ )),]);@@ -656,7 +691,7 @@ mod tests {vec![("move_cursor".into(),- json!({"scope":"desktop", "x":-1280.0, "y":100.0})+ desktop_pointer(json!({"scope":"desktop", "x":-1280.0, "y":100.0}))),("press_key".into(),@@ -664,11 +699,13 @@ mod tests {),("click".into(),- json!({"scope":"desktop", "x":-960.0, "y":100.0, "button":"left"})+ desktop_pointer(+ json!({"scope":"desktop", "x":-960.0, "y":100.0, "button":"left"})+ )),("move_cursor".into(),- json!({"scope":"desktop", "x":-321.0, "y":499.0})+ desktop_pointer(json!({"scope":"desktop", "x":-321.0, "y":499.0}))),]);@@ -702,18 +739,18 @@ mod tests {vec![("move_cursor".into(),- json!({"scope":"desktop", "x":320.0, "y":200.0})+ desktop_pointer(json!({"scope":"desktop", "x":320.0, "y":200.0}))),("drag".into(),- json!({+ desktop_pointer(json!({"scope":"desktop", "from_x":320.0, "from_y":200.0,"to_x":959.0, "to_y":599.0, "button":"left",- })+ }))),("move_cursor".into(),- json!({"scope":"desktop", "x":1279.0, "y":799.0})+ desktop_pointer(json!({"scope":"desktop", "x":1279.0, "y":799.0}))),]);@@ -739,15 +776,19 @@ mod tests {vec![("scroll".into(),- json!({"scope":"desktop", "x":640.0, "y":400.0, "direction":"down", "amount":3})+ desktop_pointer(+ json!({"scope":"desktop", "x":640.0, "y":400.0, "direction":"down", "amount":3})+ )),("move_cursor".into(),- json!({"scope":"desktop", "x":959.0, "y":599.0})+ desktop_pointer(json!({"scope":"desktop", "x":959.0, "y":599.0}))),("scroll".into(),- json!({"scope":"desktop", "x":959.0, "y":599.0, "direction":"down", "amount":1})+ desktop_pointer(+ json!({"scope":"desktop", "x":959.0, "y":599.0, "direction":"down", "amount":1})+ )),]);diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.jsonindex b499d1f0ea..02acd029a9 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json@@ -2379,7 +2379,7 @@"read_only": false},{- "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup — a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.",+ "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.","destructive": false,"idempotent": true,"input_schema": {@@ -2437,7 +2437,7 @@"read_only": true},{- "description": "Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.","destructive": true,"idempotent": false,"input_schema": {@@ -2487,7 +2487,7 @@},"strategy": {"additionalProperties": false,- "description": "Attach to an already-running browser instead of launching one. kind=existing_profile attaches to the user's running profile at pid/window_id and requires explicit profile authorization.",+ "description": "Attach to an already-running browser instead of launching one. Pass an object, {\"kind\":\"existing_profile\"}, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization.","properties": {"kind": {"enum": [diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.jsonindex 9a3eaf2e0a..8169cb81b4 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json@@ -1401,7 +1401,7 @@"read_only": true},{- "description": "Move a cursor to (x, y). With target {kind: \"window\", pid, window_id}, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover. With scope=desktop, moves the real OS pointer in native get_desktop_state screenshot coordinates.",+ "description": "Move a cursor to (x, y). With target {kind: \"window\", pid, window_id}, x/y are window screenshot pixels (as for click) and only the agent cursor moves there; in a background app it also hovers through a route that leaves the real pointer alone where one exists (AXShowAlternateUI on the element under the point, or an Electron page) and says so. Without a target, moves only the agent cursor overlay, in screen points. Other macOS hover and tooltips follow the real pointer, so most background apps see no hover; for a web page in Chrome, Edge or Brave use browser_pointer hover instead. With scope=desktop, moves the user's real OS pointer in native get_desktop_state screenshot coordinates; over a window of an app that is not in front it refuses unless delivery_mode is \"foreground\".","destructive": false,"idempotent": true,"input_schema": {@@ -1411,6 +1411,14 @@"description": "Cursor instance to move. Default: 'default'.","type": "string"},+ "delivery_mode": {+ "description": "Desktop scope only. Default \"background\": refuses, before moving anything, when the point is over a window of an app that is not in front, since that would move the user's pointer. \"foreground\": move the real pointer anyway; only when nobody is using this screen or the user agreed.",+ "enum": [+ "background",+ "foreground"+ ],+ "type": "string"+ },"scope": {"default": "window","description": "\"window\" (default) moves only the agent cursor overlay; \"desktop\" moves the real OS pointer.",@@ -2018,7 +2026,7 @@"read_only": false},{- "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup — a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.",+ "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.","destructive": false,"idempotent": true,"input_schema": {@@ -2076,7 +2084,7 @@"read_only": true},{- "description": "Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.","destructive": true,"idempotent": false,"input_schema": {@@ -2126,7 +2134,7 @@},"strategy": {"additionalProperties": false,- "description": "Attach to an already-running browser instead of launching one. kind=existing_profile attaches to the user's running profile at pid/window_id and requires explicit profile authorization.",+ "description": "Attach to an already-running browser instead of launching one. Pass an object, {\"kind\":\"existing_profile\"}, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization.","properties": {"kind": {"enum": [diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.jsonindex 757d732fd4..3ee1ebce92 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json@@ -2074,7 +2074,7 @@"read_only": false},{- "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup — a missing endpoint is a structured browser_requires_setup refusal pointing at browser_prepare.",+ "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. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer.","destructive": false,"idempotent": true,"input_schema": {@@ -2132,7 +2132,7 @@"read_only": true},{- "description": "Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.",+ "description": "Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {\"kind\":\"existing_profile\"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front for every new connection), existing-profile attachment refuses with background_unavailable unless delivery_mode is \"foreground\" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations.","destructive": true,"idempotent": false,"input_schema": {@@ -2182,7 +2182,7 @@},"strategy": {"additionalProperties": false,- "description": "Attach to an already-running browser instead of launching one. kind=existing_profile attaches to the user's running profile at pid/window_id and requires explicit profile authorization.",+ "description": "Attach to an already-running browser instead of launching one. Pass an object, {\"kind\":\"existing_profile\"}, not a string. kind=existing_profile attaches to the user's running profile at pid/window_id under the runtime's profile authorization.","properties": {"kind": {"enum": [