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.

feat(cua-driver): attach to an existing Chrome profile in the background when Chrome is on another Space (macOS) (#5052)

Francesco Bonacci10c5d3f3d40f
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
index d910d246d8..bb777fb13d 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
@@ -77,14 +77,14 @@ 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 then brought back afterwards.
+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.
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| <span id="browser_prepare--allow_launch"></span>`allow_launch` | `boolean` | | Allow a separate driver-owned isolated Chromium process to be launched (default false). |
-| <span id="browser_prepare--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Existing-profile attachment only. background (default) refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards. |
+| <span id="browser_prepare--delivery_mode"></span>`delivery_mode` | `"background" \| "foreground"` | `"background"` | Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards. |
| <span id="browser_prepare--pid"></span>`pid` | `integer` | | Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true. |
| <span id="browser_prepare--profile"></span>`profile` | `object` | | Driver-owned isolated Chromium profile to launch with allow_launch=true. mode=isolated_new creates a fresh throwaway profile; mode=isolated_named reuses the named driver-owned profile. Never an existing user profile. |
| <span id="browser_prepare--profile-mode"></span>`profile.mode` | `"isolated_new" \| "isolated_named"` | | |
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index 8f2c4c7350..7ddd90977d 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -202,9 +202,14 @@ authorize generic pixel interaction.
On macOS this attachment cannot stay in the background. Chrome brings itself
to the front to show its "Allow remote debugging?" prompt for every new
DevTools connection, and turning remote debugging on needs Chrome in front.
-So when another app is in front, `browser_prepare` with
-`strategy.kind:"existing_profile"` refuses with `background_unavailable`
-before it opens a tab or connects. Pass `delivery_mode:"foreground"` only when
+When the Chrome window is on another Space than the user's, the attach runs in
+the background: the driver turns remote debugging on without bringing Chrome
+forward, and reverts Chrome's own brief activations (its consent window opens
+on Chrome's Space, out of the user's sight) within milliseconds, giving the
+user's window front and key status back. On the user's Space, while another
+app is in front, `browser_prepare` with `strategy.kind:"existing_profile"`
+refuses with `background_unavailable` before it opens a tab or connects. Keep
+or put Chrome on another Space, or pass `delivery_mode:"foreground"` only when
nobody is using the screen or the user agreed to Chrome coming forward; the
driver then brings the previous app back and reports
`side_effects.restored_frontmost_app`. If the user is working in another app,
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
index 8410fcec4c..98296acb6a 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/platform.rs
@@ -386,6 +386,22 @@ pub trait BrowserPlatform: Send + Sync {
None
}
+ /// Guard a background existing-profile attachment that
+ /// [`Self::existing_profile_attach_background_limitation`] would refuse,
+ /// when the platform can keep it out of the user's way: while the returned
+ /// value is alive, every self-activation of `browser_pid` is reverted
+ /// within milliseconds. `None` (the default) keeps the refusal. macOS
+ /// returns a guard only when `window_id` is on another Space than the
+ /// user's active one, where the browser's consent window stays out of
+ /// sight.
+ fn guard_background_attach(
+ &self,
+ _browser_pid: i64,
+ _window_id: u64,
+ ) -> Option<Box<dyn std::any::Any + Send>> {
+ None
+ }
+
/// Pid of the app the user has in front, when the platform can tell.
fn frontmost_app_pid(&self) -> Option<i64> {
None
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
index aaa3345863..bff1d430bd 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/prepare.rs
@@ -934,14 +934,32 @@ impl BrowserEngine {
request: PrepareRequest,
) -> Result<PrepareOutcome, BrowserRefusal> {
let browser_pid = request.pid;
+ // Where the platform can guard it (macOS: the browser window is on
+ // another Space), attach in the background under the guard instead of
+ // refusing.
+ let background_guard = match (browser_pid, request.window_id) {
+ (Some(pid), Some(window_id))
+ if !request.foreground
+ && self
+ .platform
+ .existing_profile_attach_background_limitation()
+ .is_some()
+ && self.platform.frontmost_app_pid() != Some(pid) =>
+ {
+ self.platform.guard_background_attach(pid, window_id)
+ }
+ _ => None,
+ };
+ let guarded = background_guard.is_some();
let previous_front = match browser_pid {
- Some(pid) if request.foreground => self
+ Some(pid) if request.foreground || guarded => self
.platform
.frontmost_app_pid()
.filter(|front| *front != pid),
_ => None,
};
- let mut result = self.attach_existing_profile_checked(request).await;
+ let mut result = self.attach_existing_profile_checked(request, guarded).await;
+ drop(background_guard);
if let (Some(previous), Some(pid)) = (previous_front, browser_pid) {
let restored = self.platform.restore_frontmost_app(previous, pid);
match &mut result {
@@ -985,11 +1003,12 @@ impl BrowserEngine {
BrowserRefusalCode::BackgroundUnavailable,
format!(
"{limitation}, so attaching now would bring the browser in front of the app the \
- user is working in. Nothing was changed. Retry with delivery_mode:\"foreground\" \
- only when nobody is using this screen or the user agreed to the browser coming \
- forward; the driver then brings the user's app back. Otherwise work from the \
- window's accessibility tree and screenshot (get_window_state), which need no \
- attachment."
+ user is working in. Nothing was changed. A browser window on another Space than \
+ the user's attaches in the background: keep or put it on another Space and \
+ retry. Retry with delivery_mode:\"foreground\" only when nobody is using this \
+ screen or the user agreed to the browser coming forward; the driver then brings \
+ the user's app back. Otherwise work from the window's accessibility tree and \
+ screenshot (get_window_state), which need no attachment."
),
)
.with_detail(serde_json::json!({
@@ -997,6 +1016,7 @@ impl BrowserEngine {
"browser_pid": pid,
"frontmost_pid": frontmost,
"alternative_delivery_mode": "foreground",
+ "background_attach_requires": "browser_window_on_another_space",
"visible_effects": false,
})))
}
@@ -1004,6 +1024,7 @@ impl BrowserEngine {
async fn attach_existing_profile_checked(
&self,
request: PrepareRequest,
+ guarded: bool,
) -> Result<PrepareOutcome, BrowserRefusal> {
enum ConsentPath {
Protected,
@@ -1090,7 +1111,7 @@ impl BrowserEngine {
));
}
self.native_window_checked(pid, window_id).await?;
- self.existing_profile_background_check(pid, request.foreground)?;
+ self.existing_profile_background_check(pid, request.foreground || guarded)?;
let fingerprint = self.platform.process_fingerprint(pid).await?;
let mut setup = ExistingProfileSetupOutcome::default();
let setup_request = ExistingProfileSetupRequest {
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 e26d3617d3..1d0db839b4 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
@@ -628,8 +628,10 @@ impl BrowserPrepareTool {
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 then brought back afterwards."
+ 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."
.into(),
input_schema: json!({
"type": "object",
@@ -663,7 +665,7 @@ impl BrowserPrepareTool {
"type": "string",
"enum": ["background", "foreground"],
"default": "background",
- "description": "Existing-profile attachment only. background (default) refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards."
+ "description": "Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards."
},
"session": schema_session(),
},
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 14e196c8d6..a65cf71781 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
@@ -724,6 +724,10 @@ struct FixtureFocus {
attach_activates_browser: bool,
frontmost: StdMutex<Option<i64>>,
restores: StdMutex<Vec<(i64, i64)>>,
+ /// The browser window is on another Space than the user's: the platform
+ /// can guard a background attach.
+ browser_off_space: bool,
+ guards: StdMutex<Vec<(i64, u64)>>,
}
#[async_trait]
@@ -743,6 +747,22 @@ impl BrowserPlatform for FixturePlatform {
*self.focus.frontmost.lock().unwrap()
}
+ fn guard_background_attach(
+ &self,
+ browser_pid: i64,
+ window_id: u64,
+ ) -> Option<Box<dyn std::any::Any + Send>> {
+ if !self.focus.browser_off_space {
+ return None;
+ }
+ self.focus
+ .guards
+ .lock()
+ .unwrap()
+ .push((browser_pid, window_id));
+ Some(Box::new(()))
+ }
+
fn restore_frontmost_app(&self, previous_pid: i64, browser_pid: i64) -> bool {
self.focus
.restores
@@ -1076,6 +1096,13 @@ async fn existing_profile_setup_fixture() -> (Fixture, Arc<AtomicBool>) {
/// on attach, with `frontmost` in front when the call starts.
async fn foreground_attach_fixture(
frontmost: i64,
+) -> (Fixture, Arc<FixtureFocus>, Arc<FixtureProtectedProvider>) {
+ attach_fixture_with_space(frontmost, false).await
+}
+
+async fn attach_fixture_with_space(
+ frontmost: i64,
+ browser_off_space: bool,
) -> (Fixture, Arc<FixtureFocus>, Arc<FixtureProtectedProvider>) {
let state = Arc::new(StdMutex::new(FixtureState::default()));
let server = MockCdpServer::start(fixture_handler(state.clone())).await;
@@ -1084,6 +1111,8 @@ async fn foreground_attach_fixture(
attach_activates_browser: true,
frontmost: StdMutex::new(Some(frontmost)),
restores: StdMutex::new(Vec::new()),
+ browser_off_space,
+ guards: StdMutex::new(Vec::new()),
});
let provider = Arc::new(FixtureProtectedProvider {
consent_seen: AtomicBool::new(false),
@@ -1414,6 +1443,66 @@ async fn background_existing_profile_attach_refuses_before_any_visible_effect()
assert!(focus.restores.lock().unwrap().is_empty());
}
+#[tokio::test]
+async fn background_existing_profile_attach_runs_guarded_when_the_browser_is_off_space() {
+ // pid 99 (the user's app) is in front on its Space; the browser window is
+ // on another Space, so the platform guards a background attach.
+ let (f, focus, _) = attach_fixture_with_space(99, true).await;
+ let result = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" }
+ }))
+ .await;
+ let prepared = structured(&result);
+ assert_eq!(prepared["status"], "ok", "{prepared}");
+ assert_eq!(prepared["action"], "attached_existing_profile");
+ assert!(f.setup_invoked.load(Ordering::SeqCst));
+ assert_eq!(*focus.guards.lock().unwrap(), vec![(1, 7)]);
+ // The user's app is brought back if the browser is left in front.
+ assert_eq!(*focus.restores.lock().unwrap(), vec![(99, 1)]);
+ assert_eq!(prepared["side_effects"]["restored_frontmost_app"], true);
+}
+
+#[tokio::test]
+async fn background_existing_profile_attach_on_the_users_space_still_refuses() {
+ let (f, focus, _) = attach_fixture_with_space(99, false).await;
+ let result = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" }
+ }))
+ .await;
+ let refused = structured(&result);
+ assert_eq!(refused["code"], "background_unavailable", "{refused}");
+ assert_eq!(
+ refused["refusal"]["detail"]["background_attach_requires"],
+ "browser_window_on_another_space"
+ );
+ assert!(!f.setup_invoked.load(Ordering::SeqCst));
+ assert!(focus.guards.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn foreground_existing_profile_attach_does_not_use_the_background_guard() {
+ let (f, focus, _) = attach_fixture_with_space(99, true).await;
+ let result = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "delivery_mode": "foreground",
+ "strategy": { "kind": "existing_profile" }
+ }))
+ .await;
+ assert_eq!(structured(&result)["status"], "ok");
+ assert!(focus.guards.lock().unwrap().is_empty());
+}
+
#[tokio::test]
async fn existing_profile_attach_proceeds_when_the_browser_is_already_in_front() {
let (f, focus, _) = foreground_attach_fixture(1).await;
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
index cda3820990..f56ce6973e 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/platform.rs
@@ -275,6 +275,110 @@ impl Default for MacOsBrowserPlatform {
}
}
+/// Number of live [`SelfActivationGuard`]s. Setup reads it to choose the
+/// background routes.
+static GUARDED_ATTACHES: std::sync::atomic::AtomicUsize = std::sync::atomic::AtomicUsize::new(0);
+
+/// Whether a background existing-profile attach may run under the guard: only
+/// when WindowServer places the approved window on another Space than the
+/// user's active one. Chrome's consent window then opens on that Space, out of
+/// the user's sight; on the user's Space it would sit over their window.
+/// Whether an attach or cleanup is running under [`SelfActivationGuard`]: the
+/// setup then uses its background routes.
+pub(crate) fn guarded_attach_active() -> bool {
+ GUARDED_ATTACHES.load(std::sync::atomic::Ordering::SeqCst) > 0
+}
+
+fn guarded_attach_allowed(window_on_current_space: Option<bool>) -> bool {
+ window_on_current_space == Some(false)
+}
+
+/// While alive, reverts every self-activation of `pid` within milliseconds:
+/// gives the user's exact key window front and key status back, re-keys it
+/// if key status stayed with Chrome, and puts it back above Chrome's window
+/// if Chrome lifted it. It holds off while the driver's own foreground or
+/// background-key turns run, so it never undoes the driver's input.
+struct SelfActivationGuard {
+ stop: Arc<std::sync::atomic::AtomicBool>,
+}
+
+impl SelfActivationGuard {
+ fn start(pid: i32) -> Self {
+ GUARDED_ATTACHES.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+ let stop = Arc::new(std::sync::atomic::AtomicBool::new(false));
+ let flag = stop.clone();
+ let user_front = crate::apps::frontmost_pid().filter(|front| *front != pid);
+ std::thread::spawn(move || {
+ if let Some(front) = user_front {
+ watch_self_activation(pid, front, &flag);
+ }
+ });
+ Self { stop }
+ }
+}
+
+impl Drop for SelfActivationGuard {
+ fn drop(&mut self) {
+ self.stop.store(true, std::sync::atomic::Ordering::SeqCst);
+ GUARDED_ATTACHES.fetch_sub(1, std::sync::atomic::Ordering::SeqCst);
+ }
+}
+
+fn watch_self_activation(pid: i32, front: i32, stop: &std::sync::atomic::AtomicBool) {
+ use std::sync::atomic::Ordering;
+ use std::time::Instant;
+ // Read before anything happens: after a key loss the user's app may
+ // report no focused window.
+ let user_key_window = crate::input::skylight::key_window_of_pid(front);
+ // A Chrome window the user had placed above their own stays there.
+ let above_before = crate::key_focus_guard::target_window_above_front(pid, front);
+ let rekey = || {
+ user_key_window.is_some_and(|wid| crate::input::skylight::make_exact_window_key(front, wid))
+ };
+ let mut last_rekey = Instant::now();
+ let mut last_order_check = Instant::now();
+ let mut epoch = crate::window_change_detector::intentional_epoch();
+ let mut quiet_until = Instant::now();
+ while !stop.load(Ordering::SeqCst) {
+ let now_epoch = crate::window_change_detector::intentional_epoch();
+ if now_epoch != epoch {
+ epoch = now_epoch;
+ quiet_until = Instant::now() + Duration::from_millis(400);
+ }
+ let calm = !crate::input::skylight::foreground_turn_active()
+ && !super::setup_ui::BACKGROUND_KEY_TURN.load(Ordering::SeqCst)
+ && Instant::now() >= quiet_until;
+ if calm {
+ let front_now = crate::input::skylight::front_process_pid();
+ if front_now == Some(pid) {
+ if !rekey() {
+ crate::key_focus_guard::revert_now(pid, front);
+ }
+ last_rekey = Instant::now();
+ } else if front_now == Some(front) {
+ if !above_before && last_order_check.elapsed() >= Duration::from_millis(20) && {
+ last_order_check = Instant::now();
+ crate::key_focus_guard::target_window_above_front(pid, front)
+ } {
+ // Chrome orders its window front a few ms after it
+ // activates itself.
+ rekey();
+ if crate::key_focus_guard::target_window_above_front(pid, front) {
+ crate::key_focus_guard::restore_order_now(pid, front);
+ }
+ } else if crate::input::skylight::key_focus_pid() != Some(front)
+ && last_rekey.elapsed() >= Duration::from_millis(30)
+ {
+ // In front again, but key status stayed with Chrome.
+ rekey();
+ last_rekey = Instant::now();
+ }
+ }
+ }
+ std::thread::sleep(Duration::from_millis(2));
+ }
+}
+
/// Bring `previous_pid` back to the front when `browser_pid` is in front.
/// Leaves things alone when some other app took the front in the meantime.
fn restore_front_app_if_browser_front(previous_pid: i64, browser_pid: i64) -> bool {
@@ -798,6 +902,17 @@ impl BrowserPlatform for MacOsBrowserPlatform {
)
}
+ fn guard_background_attach(
+ &self,
+ browser_pid: i64,
+ window_id: u64,
+ ) -> Option<Box<dyn std::any::Any + Send>> {
+ let pid = i32::try_from(browser_pid).ok()?;
+ let window_id = u32::try_from(window_id).ok()?;
+ guarded_attach_allowed(crate::windows::window_on_current_space_by_id(window_id))
+ .then(|| Box::new(SelfActivationGuard::start(pid)) as Box<dyn std::any::Any + Send>)
+ }
+
fn frontmost_app_pid(&self) -> Option<i64> {
crate::apps::frontmost_pid().map(i64::from)
}
@@ -1100,13 +1215,8 @@ impl BrowserPlatform for MacOsBrowserPlatform {
)
})?;
let listeners_before = loopback_ports_for_pid(request.pid).await?;
- let handle = crate::focus_guard::with_focus_suppressed_now(
- Some(pid),
- "browser_prepare.remote_debugging",
- || async move {
- tokio::task::spawn_blocking(move || {
- super::setup_ui::enable(pid, window_id, descriptor)
- })
+ let run_setup = move || async move {
+ tokio::task::spawn_blocking(move || super::setup_ui::enable(pid, window_id, descriptor))
.await
.map_err(|error| {
refusal(
@@ -1117,9 +1227,21 @@ impl BrowserPlatform for MacOsBrowserPlatform {
),
)
})?
- },
- )
- .await?;
+ };
+ // Under the self-activation guard, the setup's background key turns make
+ // Chrome's window key on purpose; the generic focus-steal lease would
+ // re-activate the user's app in the middle of them and drop Chrome's
+ // input. The guard reverts Chrome's own activations instead.
+ let handle = if GUARDED_ATTACHES.load(std::sync::atomic::Ordering::SeqCst) > 0 {
+ run_setup().await?
+ } else {
+ crate::focus_guard::with_focus_suppressed_now(
+ Some(pid),
+ "browser_prepare.remote_debugging",
+ run_setup,
+ )
+ .await?
+ };
let opened_setup_page = handle.opened_setup_page;
let enabled_remote_debugging = handle.enabled_remote_debugging;
let used_bounded_pixel_fallback = handle.used_bounded_pixel_fallback;
@@ -1286,6 +1408,13 @@ impl BrowserPlatform for MacOsBrowserPlatform {
// Turning remote debugging back off reopens Chrome's setup page,
// which brings Chrome to the front; hand the front back afterwards.
let previous_front = crate::apps::frontmost_pid().filter(|front| *front != pid);
+ // Chrome on another Space: the same guarded background routes as the
+ // attach, so the cleanup does not bring Chrome forward either.
+ let _guard = previous_front
+ .filter(|_| {
+ guarded_attach_allowed(crate::windows::window_on_current_space_by_id(window_id))
+ })
+ .map(|_| SelfActivationGuard::start(pid));
let result = run_committed_consent_cleanup(
CONSENT_CLEANUP_PASSES,
|| super::consent_ui::dismiss(pid, window_id),
@@ -1725,6 +1854,23 @@ mod tests {
assert!(limitation.contains("Allow remote debugging?"));
}
+ #[test]
+ fn guarded_background_attach_only_for_a_window_on_another_space() {
+ assert!(guarded_attach_allowed(Some(false)));
+ assert!(!guarded_attach_allowed(Some(true)));
+ // Unknown Space placement keeps the honest refusal.
+ assert!(!guarded_attach_allowed(None));
+ }
+
+ #[test]
+ fn guarded_attach_flag_follows_live_guards() {
+ assert!(!guarded_attach_active());
+ let guard = SelfActivationGuard::start(i32::MAX);
+ assert!(guarded_attach_active());
+ drop(guard);
+ assert!(!guarded_attach_active());
+ }
+
#[test]
fn front_restore_never_targets_the_browser_or_an_invalid_pid() {
assert!(!restore_front_app_if_browser_front(42, 42));
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs b/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs
index f9f4838aa1..25270f7acd 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/browser/setup_ui.rs
@@ -226,7 +226,9 @@ fn native_setup_page_committed(
unsafe { CFRelease(element as CFTypeRef) };
matches
});
- !omnibox_focused
+ // After background typing the omnibox keeps AX focus with the committed
+ // URL and no popup (both proven above); that is not an active edit.
+ !omnibox_focused || super::platform::guarded_attach_active()
}
fn exact_setup_checkbox(
@@ -378,6 +380,25 @@ fn new_tab_button(
})
}
+/// Set while [`with_background_key_window`] runs: the browser window is key
+/// inside the browser on purpose, so the self-activation guard must not hand
+/// key focus back to the user's window in the middle of it.
+pub(crate) static BACKGROUND_KEY_TURN: std::sync::atomic::AtomicBool =
+ std::sync::atomic::AtomicBool::new(false);
+
+/// Run `body` with the approved browser window made key inside the browser
+/// only: a focus record goes to that window and none to the user's front app,
+/// so the browser is neither activated nor raised and the user's window keeps
+/// key status. Keyboard events posted to the browser's pid then reach its
+/// focused control. Used only under the guarded background attach.
+fn with_background_key_window<T>(pid: i32, window_id: u32, body: impl FnOnce() -> T) -> T {
+ BACKGROUND_KEY_TURN.store(true, std::sync::atomic::Ordering::SeqCst);
+ crate::input::mouse::prepare_background_pixel_click(pid, window_id);
+ let result = body();
+ BACKGROUND_KEY_TURN.store(false, std::sync::atomic::Ordering::SeqCst);
+ result
+}
+
fn is_same_element(left: usize, right: usize) -> bool {
unsafe { CFEqual(left as CFTypeRef, right as CFTypeRef) != 0 }
}
@@ -928,10 +949,19 @@ fn press_pixel_checkbox(
descriptor: &BrowserSetupDescriptor,
navigation_committed: bool,
) -> anyhow::Result<bool> {
- crate::input::skylight::with_foreground_assist(pid, window_id, || {
- std::thread::sleep(Duration::from_millis(60));
- if crate::apps::frontmost_pid() != Some(pid) {
- anyhow::bail!("the approved browser lost foreground before the setup click");
+ // Under the guarded background attach the browser window is on another
+ // Space: the checkbox is toggled by keyboard, with Chrome left in the
+ // background.
+ let background = super::platform::guarded_attach_active();
+ let click = |delivery: crate::input::mouse::WindowClickDelivery| -> anyhow::Result<()> {
+ if matches!(
+ delivery,
+ crate::input::mouse::WindowClickDelivery::Foreground
+ ) {
+ std::thread::sleep(Duration::from_millis(60));
+ if crate::apps::frontmost_pid() != Some(pid) {
+ anyhow::bail!("the approved browser lost foreground before the setup click");
+ }
}
let current = walk_tree(pid, Some(window_id), None);
let validation = (|| {
@@ -976,22 +1006,82 @@ fn press_pixel_checkbox(
})();
release_actionable_nodes(&current.nodes);
let refreshed = validation?;
- crate::input::mouse::click_at_xy_with_window_local(
- pid,
- refreshed.screen_x,
- refreshed.screen_y,
- refreshed.window_local_x,
- refreshed.window_local_y,
- window_id,
- 1,
- &[],
- crate::input::mouse::WindowClickDelivery::Foreground,
- )?;
+ if matches!(
+ delivery,
+ crate::input::mouse::WindowClickDelivery::Background
+ ) {
+ if !toggle_checkbox_by_keyboard(pid, window_id, descriptor) {
+ anyhow::bail!("the exact setup checkbox could not be toggled in the background");
+ }
+ } else {
+ crate::input::mouse::click_at_xy_with_window_local(
+ pid,
+ refreshed.screen_x,
+ refreshed.screen_y,
+ refreshed.window_local_x,
+ refreshed.window_local_y,
+ window_id,
+ 1,
+ &[],
+ delivery,
+ )?;
+ }
std::thread::sleep(Duration::from_millis(100));
Ok(())
+ };
+ if background {
+ return click(crate::input::mouse::WindowClickDelivery::Background).map(|()| false);
+ }
+ crate::input::skylight::with_foreground_assist(pid, window_id, || {
+ click(crate::input::mouse::WindowClickDelivery::Foreground)
})
}
+/// Toggle the setup checkbox with the keyboard: give the exact AX checkbox
+/// focus and send Space to the browser's pid while its window is key inside
+/// the browser only. Works for a window on another Space, where a pointer
+/// event cannot land. The caller re-reads the checkbox state.
+fn toggle_checkbox_by_keyboard(
+ pid: i32,
+ window_id: u32,
+ descriptor: &BrowserSetupDescriptor,
+) -> bool {
+ let find = |tree: &TreeWalkResult| {
+ let matches = tree
+ .nodes
+ .iter()
+ .filter(|node| {
+ node.role == "AXCheckBox"
+ && node.title.as_deref() == Some(descriptor.checkbox_label)
+ })
+ .map(|node| node.element_ptr)
+ .collect::<Vec<_>>();
+ match matches.as_slice() {
+ [element] => Some(*element),
+ _ => None,
+ }
+ };
+ let mut tree = walk_tree(pid, Some(window_id), None);
+ let mut checkbox = find(&tree);
+ if checkbox.is_none() {
+ release_actionable_nodes(&tree.nodes);
+ tree = walk_tree(pid, None, None);
+ checkbox = find(&tree);
+ }
+ let Some(checkbox) = checkbox else {
+ release_actionable_nodes(&tree.nodes);
+ return false;
+ };
+ let toggled = with_background_key_window(pid, window_id, || {
+ let focused = unsafe { set_bool_attr_true(checkbox as AXUIElementRef, "AXFocused") };
+ std::thread::sleep(Duration::from_millis(60));
+ focused == kAXErrorSuccess && crate::input::keyboard::press_key(pid, "space", &[]).is_ok()
+ });
+ release_actionable_nodes(&tree.nodes);
+ std::thread::sleep(Duration::from_millis(150));
+ toggled
+}
+
fn checkbox_state(value: Option<bool>) -> Result<CheckboxState, BrowserRefusal> {
match value {
Some(false) => Ok(CheckboxState::Off),
@@ -1321,7 +1411,15 @@ fn set_remote_debugging(
return Err(error);
}
};
- let pressed = unsafe { perform_action(new_tab as AXUIElementRef, "AXPress") };
+ // Under the guarded background attach, the window is made key inside
+ // Chrome first, so the New Tab action has no reason to activate it.
+ let pressed = if super::platform::guarded_attach_active() {
+ with_background_key_window(pid, window_id, || unsafe {
+ perform_action(new_tab as AXUIElementRef, "AXPress")
+ })
+ } else {
+ unsafe { perform_action(new_tab as AXUIElementRef, "AXPress") }
+ };
if pressed != kAXErrorSuccess {
release_actionable_nodes(&initial.nodes);
return Err(refusal(
@@ -1456,7 +1554,53 @@ fn set_remote_debugging(
),
));
}
- if confirmed {
+ // The omnibox commits a URL only on real keystrokes. Under the
+ // guarded background attach, type it with
+ // events routed to Chrome's pid while its window is key inside
+ // Chrome only, so Chrome stays in the background.
+ let showing_setup_page = || {
+ let tree = walk_tree(pid, Some(window_id), None);
+ let shown = tree.nodes.iter().any(|node| {
+ node.role == "AXWindow"
+ && node.title.as_deref().is_some_and(|title| {
+ descriptor
+ .page_titles
+ .iter()
+ .any(|page| title.starts_with(page))
+ })
+ });
+ release_actionable_nodes(&tree.nodes);
+ shown
+ };
+ let typed_in_background = !confirmed
+ && super::platform::guarded_attach_active()
+ && with_background_key_window(pid, window_id, || {
+ let _ = unsafe { perform_action(omnibox as AXUIElementRef, "AXPress") };
+ let _ = unsafe { set_bool_attr_true(omnibox as AXUIElementRef, "AXFocused") };
+ std::thread::sleep(Duration::from_millis(60));
+ let typed = crate::input::keyboard::press_key(pid, "a", &["cmd"])
+ .and_then(|()| crate::input::keyboard::type_text(pid, descriptor.setup_url))
+ .is_ok()
+ && await_exact_value(
+ || unsafe { copy_string_attr(omnibox as AXUIElementRef, "AXValue") },
+ descriptor.setup_url,
+ TYPED_URL_SETTLE_TIMEOUT,
+ Duration::from_millis(50),
+ )
+ .is_ok();
+ if !typed || crate::input::keyboard::press_key(pid, "return", &[]).is_err() {
+ return false;
+ }
+ let deadline = Instant::now() + Duration::from_millis(3000);
+ while Instant::now() < deadline {
+ if showing_setup_page() {
+ return true;
+ }
+ std::thread::sleep(Duration::from_millis(100));
+ }
+ false
+ });
+ if confirmed || typed_in_background {
unsafe { CFRelease(omnibox as CFTypeRef) };
} else {
let deadline = Instant::now() + Duration::from_secs(2);
@@ -1616,7 +1760,20 @@ fn set_remote_debugging(
let deadline = Instant::now() + EXISTING_PROFILE_SETUP_READY_TIMEOUT;
loop {
- let tree = walk_tree(pid, Some(window_id), None);
+ let mut tree = walk_tree(pid, Some(window_id), None);
+ if super::platform::guarded_attach_active()
+ && !tree.nodes.iter().any(|node| node.role == "AXCheckBox")
+ {
+ // A page loaded while Chrome is on another Space can be missing
+ // from the window-scoped walk; the application walk reaches it.
+ let app_tree = walk_tree(pid, None, None);
+ if app_tree.nodes.iter().any(|node| node.role == "AXCheckBox") {
+ release_actionable_nodes(&tree.nodes);
+ tree = app_tree;
+ } else {
+ release_actionable_nodes(&app_tree.nodes);
+ }
+ }
let checkbox = exact_setup_checkbox(&tree, descriptor);
match checkbox {
Ok(Some(element)) => {
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/input/skylight.rs b/libs/cua-driver/rust/crates/platform-macos/src/input/skylight.rs
index 45cb68b941..9da32128df 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/input/skylight.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/input/skylight.rs
@@ -948,6 +948,12 @@ impl Drop for ForegroundTurn {
}
}
+/// Whether some thread holds a foreground turn right now (the driver is
+/// deliberately fronting a target).
+pub fn foreground_turn_active() -> bool {
+ FOREGROUND_LOCK.try_lock().is_err()
+}
+
fn foreground_turn() -> ForegroundTurn {
// An intentional activation ends the previous action's detached window
// watch, whose wildcard lease would otherwise revert it.
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/key_focus_guard.rs b/libs/cua-driver/rust/crates/platform-macos/src/key_focus_guard.rs
index 9096e6b4a5..b21548c3da 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/key_focus_guard.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/key_focus_guard.rs
@@ -78,6 +78,28 @@ fn target_above_front_in(windows: &[crate::windows::WindowInfo], target: i32, fr
/// lifts its parent window). Re-activating the already-active front app with
/// all its windows restores the order without moving key status; the
/// target's menu stays open.
+/// Put `front`'s windows back above `target` if the target's window was
+/// lifted over them (see [`restore_front_if_raised`]).
+pub fn restore_order_now(target: i32, front: i32) -> bool {
+ // NSWorkspace's frontmost reading can lag inside the daemon; the caller
+ // has already checked WindowServer's front process.
+ if !target_above_front(target, front) {
+ return false;
+ }
+ use objc2_app_kit::{NSApplicationActivationOptions, NSRunningApplication};
+ unsafe {
+ NSRunningApplication::runningApplicationWithProcessIdentifier(front).is_some_and(|app| {
+ app.activateWithOptions(NSApplicationActivationOptions::NSApplicationActivateAllWindows)
+ })
+ }
+}
+
+/// Whether a normal-level window of `target` sits above `front`'s frontmost
+/// normal-level window.
+pub fn target_window_above_front(target: i32, front: i32) -> bool {
+ target_above_front(target, front)
+}
+
fn restore_front_if_raised(target: i32, front: i32) -> bool {
if crate::apps::frontmost_pid() != Some(front) || !target_above_front(target, front) {
return false;
@@ -110,6 +132,12 @@ fn target_self_activated(front_process: Option<i32>, target: i32, front: i32) ->
/// and hand key focus back to its window. Reads WindowServer's front process
/// directly; `NSWorkspace` only learns of the activation once the daemon's run
/// loop processes the notice, which took about a second in Bench v2 CDB-G04.
+/// Revert `target`'s self-activation right now, giving `front` its key
+/// window back (see [`revert_self_activation`]).
+pub fn revert_now(target: i32, front: i32) -> bool {
+ revert_self_activation(target, front)
+}
+
fn revert_self_activation(target: i32, front: i32) -> bool {
if !target_self_activated(skylight::front_process_pid(), target, front) {
return false;
diff --git a/libs/cua/skills/cua-driver/BROWSER.md b/libs/cua/skills/cua-driver/BROWSER.md
index 8f2c4c7350..7ddd90977d 100644
--- a/libs/cua/skills/cua-driver/BROWSER.md
+++ b/libs/cua/skills/cua-driver/BROWSER.md
@@ -202,9 +202,14 @@ authorize generic pixel interaction.
On macOS this attachment cannot stay in the background. Chrome brings itself
to the front to show its "Allow remote debugging?" prompt for every new
DevTools connection, and turning remote debugging on needs Chrome in front.
-So when another app is in front, `browser_prepare` with
-`strategy.kind:"existing_profile"` refuses with `background_unavailable`
-before it opens a tab or connects. Pass `delivery_mode:"foreground"` only when
+When the Chrome window is on another Space than the user's, the attach runs in
+the background: the driver turns remote debugging on without bringing Chrome
+forward, and reverts Chrome's own brief activations (its consent window opens
+on Chrome's Space, out of the user's sight) within milliseconds, giving the
+user's window front and key status back. On the user's Space, while another
+app is in front, `browser_prepare` with `strategy.kind:"existing_profile"`
+refuses with `background_unavailable` before it opens a tab or connects. Keep
+or put Chrome on another Space, or pass `delivery_mode:"foreground"` only when
nobody is using the screen or the user agreed to Chrome coming forward; the
driver then brings the previous app back and reports
`side_effects.restored_frontmost_app`. If the user is working in another app,
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
index 34f9c6aced..b499d1f0ea 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
@@ -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 then brought back afterwards.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2449,7 +2449,7 @@
},
"delivery_mode": {
"default": "background",
- "description": "Existing-profile attachment only. background (default) refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
+ "description": "Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
"enum": [
"background",
"foreground"
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
index 049a78bd0c..3b8f52415e 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -2076,7 +2076,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 then brought back afterwards.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2088,7 +2088,7 @@
},
"delivery_mode": {
"default": "background",
- "description": "Existing-profile attachment only. background (default) refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
+ "description": "Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
"enum": [
"background",
"foreground"
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
index 1bc8858b8b..757d732fd4 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -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 then brought back afterwards.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2144,7 +2144,7 @@
},
"delivery_mode": {
"default": "background",
- "description": "Existing-profile attachment only. background (default) refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
+ "description": "Existing-profile attachment only. background (default) attaches in the background when the browser window is on another Space than the user's, and otherwise refuses with background_unavailable, before any visible effect, where attaching would bring the browser in front of the user's app. foreground accepts that, for a screen nobody else is using or when the user agreed; the app that was in front is brought back afterwards.",
"enum": [
"background",
"foreground"