Skip to content

armgit / cua

Public Imported from GitHub
0

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

fix(cua-driver): refuse background existing-profile attach on macOS instead of bringing Chrome forward (#5007)

Francesco Bonaccie1a6396b42a0
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 ce582c500a..c3d6f64999 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools/page.mdx
@@ -77,13 +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.
+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.
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--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 b0d6168711..8f2c4c7350 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -199,6 +199,17 @@ transition on that same control. Unsupported appearance, scale, zoom,
window-size, or toolbar geometry refuses without a click; the fallback does not
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
+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,
+read the Chrome window with `get_window_state` instead.
+
Chrome 144 and later can expose its agent auto-connect bridge from the running
profile. After approval, Cua reads the exact port and browser WebSocket path
from that process's `DevToolsActivePort` file, cross-checks the loopback socket
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 012658da8b..8410fcec4c 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
@@ -156,6 +156,11 @@ pub struct PrepareRequest {
/// Allows launching a separate driver-owned isolated browser process.
/// It never authorizes terminating or modifying the requested process.
pub allow_launch: bool,
+ /// `delivery_mode:"foreground"`: the caller accepts that existing-profile
+ /// attachment may bring the browser to the front. Without it, a platform
+ /// that cannot attach in the background refuses with
+ /// `background_unavailable` before any visible effect.
+ pub foreground: bool,
}
/// What a platform adapter actually did (or found) during prepare.
@@ -315,6 +320,9 @@ pub struct PrepareSideEffects {
pub focused_setup_address_field: bool,
pub foregrounded_window: bool,
pub injected_global_input: bool,
+ /// A foreground attachment left the browser in front, and the app that
+ /// was in front before the call was brought back.
+ pub restored_frontmost_app: bool,
}
/// OS-identity services a platform crate provides to the browser-tool
@@ -367,6 +375,29 @@ pub trait BrowserPlatform: Send + Sync {
None
}
+ /// Explain why attaching to an existing browser profile cannot keep the
+ /// browser in the background on this platform, for example because the
+ /// browser brings itself to the front to show its own remote-debugging
+ /// consent prompt. `None` (the default) means attachment needs no
+ /// background check. When this returns `Some` and the browser is not the
+ /// frontmost app, a background `browser_prepare` refuses with
+ /// `background_unavailable` before discovery, setup or connection.
+ fn existing_profile_attach_background_limitation(&self) -> Option<&'static str> {
+ None
+ }
+
+ /// Pid of the app the user has in front, when the platform can tell.
+ fn frontmost_app_pid(&self) -> Option<i64> {
+ None
+ }
+
+ /// After a foreground attachment, bring `previous_pid` back to the front
+ /// if `browser_pid` is still in front. Returns true when it did so.
+ /// Implementations must not act when another app took the front since.
+ fn restore_frontmost_app(&self, _previous_pid: i64, _browser_pid: i64) -> bool {
+ false
+ }
+
/// Best-effort, visual-only feedback for an authorized browser action.
/// The default is a no-op so platforms without an agent-cursor overlay do
/// not change behavior. Implementations must not deliver input or alter
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 c8a103bf53..aaa3345863 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
@@ -925,9 +925,85 @@ impl BrowserEngine {
})
}
+ /// Existing-profile attachment, plus the foreground bookkeeping around
+ /// it: with `delivery_mode:"foreground"`, the app that was in front
+ /// before the call is brought back once the browser's setup and consent
+ /// prompt are done, instead of leaving the browser in front.
async fn attach_existing_profile(
&self,
request: PrepareRequest,
+ ) -> Result<PrepareOutcome, BrowserRefusal> {
+ let browser_pid = request.pid;
+ let previous_front = match browser_pid {
+ Some(pid) if request.foreground => self
+ .platform
+ .frontmost_app_pid()
+ .filter(|front| *front != pid),
+ _ => None,
+ };
+ let mut result = self.attach_existing_profile_checked(request).await;
+ if let (Some(previous), Some(pid)) = (previous_front, browser_pid) {
+ let restored = self.platform.restore_frontmost_app(previous, pid);
+ match &mut result {
+ Ok(outcome) => outcome.side_effects.restored_frontmost_app = restored,
+ Err(error) => {
+ if let Some(serde_json::Value::Object(detail)) = error.detail.as_mut() {
+ detail.insert(
+ "restored_frontmost_app".to_owned(),
+ serde_json::Value::Bool(restored),
+ );
+ }
+ }
+ }
+ }
+ result
+ }
+
+ /// Refuse a background attachment the platform cannot make without
+ /// bringing the browser in front of the user's app. Runs after the
+ /// read-only target proofs and before discovery, setup or any connection,
+ /// so a refusal has no visible effect.
+ fn existing_profile_background_check(
+ &self,
+ pid: i64,
+ foreground: bool,
+ ) -> Result<(), BrowserRefusal> {
+ if foreground {
+ return Ok(());
+ }
+ let Some(limitation) = self
+ .platform
+ .existing_profile_attach_background_limitation()
+ else {
+ return Ok(());
+ };
+ let frontmost = self.platform.frontmost_app_pid();
+ if frontmost == Some(pid) {
+ return Ok(());
+ }
+ Err(refusal(
+ 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."
+ ),
+ )
+ .with_detail(serde_json::json!({
+ "limitation": limitation,
+ "browser_pid": pid,
+ "frontmost_pid": frontmost,
+ "alternative_delivery_mode": "foreground",
+ "visible_effects": false,
+ })))
+ }
+
+ async fn attach_existing_profile_checked(
+ &self,
+ request: PrepareRequest,
) -> Result<PrepareOutcome, BrowserRefusal> {
enum ConsentPath {
Protected,
@@ -1014,6 +1090,7 @@ impl BrowserEngine {
));
}
self.native_window_checked(pid, window_id).await?;
+ self.existing_profile_background_check(pid, request.foreground)?;
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/refusal.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
index 5aa8d0f8cc..d709315b48 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/refusal.rs
@@ -64,6 +64,11 @@ pub enum BrowserRefusalCode {
/// The live top-level document left the origin set approved in the
/// capability manifest. Further browser input is paused.
BrowserOriginOutsideScope,
+ /// The request cannot be completed without bringing the browser in
+ /// front of the user's work, and the caller did not pass
+ /// `delivery_mode:"foreground"`. Uses the driver-wide wire code shared by
+ /// every background refusal.
+ BackgroundUnavailable,
}
impl BrowserRefusalCode {
@@ -86,6 +91,7 @@ impl BrowserRefusalCode {
Self::BrowserInputIncomplete => "browser_input_incomplete",
Self::BrowserActionUnavailable => "browser_action_unavailable",
Self::BrowserOriginOutsideScope => "browser_origin_outside_scope",
+ Self::BackgroundUnavailable => "background_unavailable",
}
}
}
@@ -306,6 +312,10 @@ mod tests {
BrowserRefusalCode::BrowserOriginOutsideScope,
"browser_origin_outside_scope",
),
+ (
+ BrowserRefusalCode::BackgroundUnavailable,
+ "background_unavailable",
+ ),
];
for (code, wire) in all {
assert_eq!(code.as_str(), wire);
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 b9ed700eab..e26d3617d3 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
@@ -625,7 +625,11 @@ impl BrowserPrepareTool {
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."
+ 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."
.into(),
input_schema: json!({
"type": "object",
@@ -655,6 +659,12 @@ impl BrowserPrepareTool {
"required": ["kind"],
"additionalProperties": false
},
+ "delivery_mode": {
+ "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."
+ },
"session": schema_session(),
},
// Keep the top-level input schema a plain object. Bedrock rejects
@@ -704,6 +714,10 @@ impl Tool for BrowserPrepareTool {
},
};
let allow_launch = args.opt_bool("allow_launch").unwrap_or(false);
+ let foreground = match parse_delivery_mode(&args) {
+ Ok(foreground) => foreground,
+ Err(error) => return ToolResult::error(error),
+ };
let pid = match args.get("pid") {
None => None,
Some(_) => match args.require_i64("pid") {
@@ -726,6 +740,7 @@ impl Tool for BrowserPrepareTool {
strategy,
profile,
allow_launch,
+ foreground,
};
match self.engine.prepare_browser(request).await {
Ok(outcome) => {
@@ -751,6 +766,24 @@ impl Tool for BrowserPrepareTool {
"attachment": outcome.attachment,
}))
}
+ Err(refusal) if refusal.code == BrowserRefusalCode::BackgroundUnavailable => {
+ let reason = refusal
+ .detail
+ .as_ref()
+ .and_then(|detail| detail.get("limitation"))
+ .and_then(Value::as_str)
+ .unwrap_or("attaching would bring the browser to the front")
+ .to_owned();
+ crate::delivery::background_unavailable_result(
+ format!("browser_prepare refused: {}", refusal.message),
+ refusal.code.as_str(),
+ reason,
+ json!({
+ "status": "refused",
+ "refusal": refusal,
+ }),
+ )
+ }
Err(refusal) => refusal.to_tool_result(),
}
}
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 42df4b0da1..14e196c8d6 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
@@ -713,6 +713,17 @@ struct FixturePlatform {
setup_invoked: Arc<AtomicBool>,
setup_aborted: Arc<AtomicBool>,
stall_consent: bool,
+ focus: Arc<FixtureFocus>,
+}
+
+/// Foreground model for existing-profile attachment: whether attaching
+/// brings the browser forward on this "platform", which pid is in front,
+/// and which restores core asked for.
+#[derive(Default)]
+struct FixtureFocus {
+ attach_activates_browser: bool,
+ frontmost: StdMutex<Option<i64>>,
+ restores: StdMutex<Vec<(i64, i64)>>,
}
#[async_trait]
@@ -722,6 +733,25 @@ impl BrowserPlatform for FixturePlatform {
.then_some("fixture trusted input raises the standalone window")
}
+ fn existing_profile_attach_background_limitation(&self) -> Option<&'static str> {
+ self.focus
+ .attach_activates_browser
+ .then_some("fixture browser comes to the front to show its consent prompt")
+ }
+
+ fn frontmost_app_pid(&self) -> Option<i64> {
+ *self.focus.frontmost.lock().unwrap()
+ }
+
+ fn restore_frontmost_app(&self, previous_pid: i64, browser_pid: i64) -> bool {
+ self.focus
+ .restores
+ .lock()
+ .unwrap()
+ .push((previous_pid, browser_pid));
+ true
+ }
+
async fn classify_browser(&self, _pid: i64) -> Result<BrowserClassification, BrowserRefusal> {
Ok(BrowserClassification {
is_browser: true,
@@ -939,6 +969,7 @@ async fn fixture_with_platform(
setup_invoked: setup_invoked.clone(),
setup_aborted: Arc::new(AtomicBool::new(false)),
stall_consent: false,
+ focus: Default::default(),
}));
Fixture {
state,
@@ -993,6 +1024,7 @@ async fn protected_existing_profile_fixture() -> (Fixture, Arc<FixtureProtectedP
setup_invoked: setup_invoked.clone(),
setup_aborted: Arc::new(AtomicBool::new(false)),
stall_consent: false,
+ focus: Default::default(),
}),
Some(provider.clone()),
);
@@ -1023,6 +1055,7 @@ async fn existing_profile_setup_fixture() -> (Fixture, Arc<AtomicBool>) {
setup_invoked: setup_invoked.clone(),
setup_aborted: Arc::new(AtomicBool::new(false)),
stall_consent: false,
+ focus: Default::default(),
}),
Some(Arc::new(FixtureProtectedProvider {
consent_seen: AtomicBool::new(false),
@@ -1039,6 +1072,50 @@ async fn existing_profile_setup_fixture() -> (Fixture, Arc<AtomicBool>) {
)
}
+/// Existing-profile setup fixture whose platform brings the browser forward
+/// on attach, with `frontmost` in front when the call starts.
+async fn foreground_attach_fixture(
+ frontmost: i64,
+) -> (Fixture, Arc<FixtureFocus>, Arc<FixtureProtectedProvider>) {
+ let state = Arc::new(StdMutex::new(FixtureState::default()));
+ let server = MockCdpServer::start(fixture_handler(state.clone())).await;
+ let setup_invoked = Arc::new(AtomicBool::new(false));
+ let focus = Arc::new(FixtureFocus {
+ attach_activates_browser: true,
+ frontmost: StdMutex::new(Some(frontmost)),
+ restores: StdMutex::new(Vec::new()),
+ });
+ let provider = Arc::new(FixtureProtectedProvider {
+ consent_seen: AtomicBool::new(false),
+ });
+ let engine = BrowserEngine::new_with_protected_consent_provider(
+ Arc::new(FixturePlatform {
+ endpoint_state: None,
+ ws_url: server.ws_url(),
+ trusted_input_limited: false,
+ managed_endpoint_visible: false,
+ process_role: BrowserProcessRole::StandaloneConsumer,
+ managed_discovery_invoked: Arc::new(AtomicBool::new(false)),
+ existing_endpoint_visible: Arc::new(AtomicBool::new(false)),
+ setup_invoked: setup_invoked.clone(),
+ setup_aborted: Arc::new(AtomicBool::new(false)),
+ stall_consent: false,
+ focus: focus.clone(),
+ }),
+ Some(provider.clone()),
+ );
+ (
+ Fixture {
+ state,
+ _server: server,
+ engine,
+ setup_invoked,
+ },
+ focus,
+ provider,
+ )
+}
+
fn structured(result: &ToolResult) -> &Value {
result
.structured_content
@@ -1078,6 +1155,7 @@ async fn standalone_consumer_bind_without_grant_refuses_before_endpoint_discover
setup_invoked: setup_invoked.clone(),
setup_aborted: Arc::new(AtomicBool::new(false)),
stall_consent: false,
+ focus: Default::default(),
}));
let result = GetBrowserStateTool::new(engine)
@@ -1305,6 +1383,90 @@ async fn approved_existing_profile_setup_reports_exact_side_effects() {
assert_eq!(structured(&state)["status"], "ok", "{}", structured(&state));
}
+#[tokio::test]
+async fn background_existing_profile_attach_refuses_before_any_visible_effect() {
+ // pid 99 (the user's app) is in front; attaching would bring pid 1 forward.
+ let (f, focus, provider) = foreground_attach_fixture(99).await;
+ let result = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "strategy": { "kind": "existing_profile" }
+ }))
+ .await;
+ assert_eq!(result.is_error, Some(true));
+ let refused = structured(&result);
+ assert_eq!(refused["code"], "background_unavailable", "{refused}");
+ assert_eq!(refused["escalation"]["recommended"], "foreground");
+ assert_eq!(refused["status"], "refused");
+ assert_eq!(refused["refusal"]["code"], "background_unavailable");
+ assert_eq!(refused["refusal"]["detail"]["frontmost_pid"], 99);
+ assert_eq!(refused["refusal"]["detail"]["visible_effects"], false);
+ assert!(
+ !f.setup_invoked.load(Ordering::SeqCst),
+ "a background refusal must not open the setup page"
+ );
+ assert!(
+ !provider.consent_seen.load(Ordering::SeqCst),
+ "a background refusal must not ask for consent"
+ );
+ assert!(focus.restores.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;
+ 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!(f.setup_invoked.load(Ordering::SeqCst));
+ assert_eq!(prepared["side_effects"]["restored_frontmost_app"], false);
+ assert!(focus.restores.lock().unwrap().is_empty());
+}
+
+#[tokio::test]
+async fn foreground_existing_profile_attach_brings_the_previous_app_back() {
+ let (f, focus, _) = foreground_attach_fixture(99).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;
+ let prepared = structured(&result);
+ assert_eq!(prepared["status"], "ok", "{prepared}");
+ assert!(f.setup_invoked.load(Ordering::SeqCst));
+ assert_eq!(prepared["side_effects"]["restored_frontmost_app"], true);
+ assert_eq!(*focus.restores.lock().unwrap(), vec![(99, 1)]);
+}
+
+#[tokio::test]
+async fn existing_profile_attach_rejects_an_unknown_delivery_mode() {
+ let (f, _, _) = foreground_attach_fixture(99).await;
+ let result = BrowserPrepareTool::new(f.engine.clone())
+ .invoke(json!({
+ "pid": 1,
+ "window_id": 7,
+ "session": SESSION,
+ "delivery_mode": "auto",
+ "strategy": { "kind": "existing_profile" }
+ }))
+ .await;
+ assert_eq!(result.is_error, Some(true));
+ assert!(!f.setup_invoked.load(Ordering::SeqCst));
+}
+
#[tokio::test]
async fn refused_consent_cancels_stalled_claim_before_revoking_grant() {
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
@@ -1325,6 +1487,7 @@ async fn refused_consent_cancels_stalled_claim_before_revoking_grant() {
setup_invoked: Arc::new(AtomicBool::new(false)),
setup_aborted: Arc::new(AtomicBool::new(false)),
stall_consent: false,
+ focus: Default::default(),
}),
Some(Arc::new(FixtureProtectedProvider {
consent_seen: AtomicBool::new(false),
@@ -1370,6 +1533,7 @@ async fn cancelled_prepare_aborts_the_exact_pending_setup() {
setup_invoked: Arc::new(AtomicBool::new(false)),
setup_aborted: setup_aborted.clone(),
stall_consent: true,
+ focus: Default::default(),
}),
Some(Arc::new(FixtureProtectedProvider {
consent_seen: AtomicBool::new(false),
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs
index 10bd108af5..7c85f09756 100644
--- a/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs
+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/server.rs
@@ -256,6 +256,9 @@ impl From<crate::browser::refusal::BrowserRefusalCode> for ToolRefusalCode {
BrowserRefusalCode::BrowserInputIncomplete => Self::BrowserInputIncomplete,
BrowserRefusalCode::BrowserActionUnavailable => Self::BrowserActionUnavailable,
BrowserRefusalCode::BrowserOriginOutsideScope => Self::BrowserOriginOutsideScope,
+ // Not a browser-specific code: the shared background refusal is
+ // classified through `ToolErrorClass::BackgroundUnavailable`.
+ BrowserRefusalCode::BackgroundUnavailable => Self::Other,
}
}
}
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.rs
index 5113fca3b4..51c6c505b6 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
@@ -238,6 +238,9 @@ fn assert_tools_list_schema_shape(mut d: RawDriver) {
// Chromium); foreground accepts that.
"browser_click",
"browser_pointer",
+ // Existing-profile attachment that would bring the browser forward
+ // (macOS Chrome); foreground accepts that.
+ "browser_prepare",
// The batch's default for its steps' own delivery_mode.
"run_steps",
// macOS set_value has no delivery ladder.
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 ce9ff48b7c..cda3820990 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,19 @@ impl Default for MacOsBrowserPlatform {
}
}
+/// 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 {
+ let (Ok(previous), Ok(browser)) = (i32::try_from(previous_pid), i32::try_from(browser_pid))
+ else {
+ return false;
+ };
+ if previous == browser || crate::apps::frontmost_pid() != Some(browser) {
+ return false;
+ }
+ crate::apps::activate_pid(previous)
+}
+
fn refusal(code: BrowserRefusalCode, message: impl Into<String>) -> BrowserRefusal {
BrowserRefusal::new(code, message)
}
@@ -772,6 +785,27 @@ impl BrowserPlatform for MacOsBrowserPlatform {
Some("Chromium's trusted CDP Input route activates its standalone browser window on macOS")
}
+ fn existing_profile_attach_background_limitation(&self) -> Option<&'static str> {
+ // Measured on Chrome 154 (no driver input involved): Chrome activates
+ // itself ~50 ms after any new DevTools client connects, to show its
+ // "Allow remote debugging?" sheet. Turning the per-instance setting on
+ // also activates it: its New Tab action does, and its address bar
+ // only navigates on real keystrokes.
+ Some(
+ "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",
+ )
+ }
+
+ fn frontmost_app_pid(&self) -> Option<i64> {
+ crate::apps::frontmost_pid().map(i64::from)
+ }
+
+ fn restore_frontmost_app(&self, previous_pid: i64, browser_pid: i64) -> bool {
+ restore_front_app_if_browser_front(previous_pid, browser_pid)
+ }
+
async fn visualize_browser_action(&self, action: BrowserVisualAction) {
if action.session.is_empty()
|| action.cdp_target_id.is_empty()
@@ -1249,13 +1283,20 @@ impl BrowserPlatform for MacOsBrowserPlatform {
"the approved browser window is outside the macOS window-id range",
)
})?;
- run_committed_consent_cleanup(
+ // 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);
+ let result = run_committed_consent_cleanup(
CONSENT_CLEANUP_PASSES,
|| super::consent_ui::dismiss(pid, window_id),
|| super::setup_ui::disable(pid, window_id, descriptor),
|| visible_consent_surfaces(pid),
|| std::thread::sleep(Duration::from_millis(100)),
- )
+ );
+ if let Some(previous) = previous_front {
+ restore_front_app_if_browser_front(i64::from(previous), request.pid);
+ }
+ result
}
async fn abort_existing_profile_setup(
@@ -1675,6 +1716,22 @@ mod tests {
);
}
+ #[test]
+ fn existing_profile_attach_declares_its_foreground_limitation() {
+ let platform = MacOsBrowserPlatform::default();
+ let limitation = platform
+ .existing_profile_attach_background_limitation()
+ .expect("macOS Chrome attachment brings Chrome forward");
+ assert!(limitation.contains("Allow remote debugging?"));
+ }
+
+ #[test]
+ fn front_restore_never_targets_the_browser_or_an_invalid_pid() {
+ assert!(!restore_front_app_if_browser_front(42, 42));
+ assert!(!restore_front_app_if_browser_front(i64::MAX, 42));
+ assert!(!restore_front_app_if_browser_front(42, i64::MIN));
+ }
+
#[test]
fn lsof_parser_accepts_only_loopback_listeners() {
let input = "n127.0.0.1:9222\nn*:9333\nn[::1]:9444\nn0.0.0.0:9555\n";
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/lib.rs b/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
index 37ff1c41ce..76275f9eb3 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/lib.rs
@@ -23,7 +23,7 @@ pub mod browser;
pub mod capture;
#[cfg(target_os = "macos")]
pub mod cursor;
-
+#[cfg(target_os = "macos")]
pub mod document_edit;
#[cfg(target_os = "macos")]
pub mod focus_guard;
diff --git a/libs/cua/skills/cua-driver/BROWSER.md b/libs/cua/skills/cua-driver/BROWSER.md
index b0d6168711..8f2c4c7350 100644
--- a/libs/cua/skills/cua-driver/BROWSER.md
+++ b/libs/cua/skills/cua-driver/BROWSER.md
@@ -199,6 +199,17 @@ transition on that same control. Unsupported appearance, scale, zoom,
window-size, or toolbar geometry refuses without a click; the fallback does not
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
+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,
+read the Chrome window with `get_window_state` instead.
+
Chrome 144 and later can expose its agent auto-connect bridge from the running
profile. After approval, Cua reads the exact port and browser WebSocket path
from that process's `DevToolsActivePort` file, cross-checks the loopback socket
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 637b37bb29..7bfd9055fc 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
@@ -2434,7 +2434,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.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2444,6 +2444,15 @@
"description": "Allow a separate driver-owned isolated Chromium process to be launched (default false).",
"type": "boolean"
},
+ "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.",
+ "enum": [
+ "background",
+ "foreground"
+ ],
+ "type": "string"
+ },
"pid": {
"description": "Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true.",
"type": "integer"
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 1becbc02a7..06b7fcf802 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json
@@ -2073,7 +2073,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.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2083,6 +2083,15 @@
"description": "Allow a separate driver-owned isolated Chromium process to be launched (default false).",
"type": "boolean"
},
+ "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.",
+ "enum": [
+ "background",
+ "foreground"
+ ],
+ "type": "string"
+ },
"pid": {
"description": "Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true.",
"type": "integer"
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 a094c36299..4bd9dd7235 100644
--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json
@@ -2129,7 +2129,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.",
+ "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.",
"destructive": true,
"idempotent": false,
"input_schema": {
@@ -2139,6 +2139,15 @@
"description": "Allow a separate driver-owned isolated Chromium process to be launched (default false).",
"type": "boolean"
},
+ "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.",
+ "enum": [
+ "background",
+ "foreground"
+ ],
+ "type": "string"
+ },
"pid": {
"description": "Browser process id to prepare. Required except for a driver-owned isolated_new/isolated_named launch with allow_launch=true.",
"type": "integer"