Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): bound macOS capture permission probe (#2761)
Francesco Bonacci14b790f766fe
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 854476088e..92d55d10f7 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -655,7 +655,7 @@ Configure only movement physics and visibility timing for a session cursor.Report TCC permission status for Accessibility and Screen Recording. By default also raises the system permission dialogs for any missing grants — Apple's request APIs are no-ops when the grant is already active, so this is safe to call repeatedly. Pass {"prompt": false} for a purely read-only status check.-Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `blocked_by_screen_recording`, or `not_checked`), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent.+Returns: `accessibility` + `screen_recording` (booleans from the TCC preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit probe when `prompt` is true; null on read-only calls), `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured timeout/probe failure when applicable), and `source` (which TCC identity the booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). macOS attributes grants to the responsible process, so a standalone call from a terminal reports the terminal's grants, not the driver's. The prompt-capable ScreenCaptureKit probe never runs when `prompt` is false. Pass `probe_direct_capture:false` with `prompt:true` to register/request only the two required TCC grants before separately explaining Tahoe's direct-capture consent.**Arguments:**diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rsindex fbcb7e5e02..b9da038baa 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/check_permissions.rs@@ -4,7 +4,7 @@ use cua_driver_core::{tool::{ProtectedResourceOwnership, Tool, ToolDef},};use serde_json::Value;-use std::sync::Arc;+use std::{future::Future, sync::Arc, time::Duration};use super::ToolState;use crate::permissions::status::{@@ -65,6 +65,64 @@ fn screen_recording_capturable() -> bool {.unwrap_or(false)}+const DIRECT_CAPTURE_PROBE_TIMEOUT: Duration = Duration::from_secs(10);++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+enum DirectCaptureProbeResult {+ Ready,+ Unavailable,+ TimedOut,+ Failed,+}++impl DirectCaptureProbeResult {+ fn response_fields(self) -> (Option<bool>, &'static str, Option<Value>) {+ match self {+ Self::Ready => (Some(true), "ready", None),+ Self::Unavailable => (Some(false), "unavailable", None),+ Self::TimedOut => (+ None,+ "timed_out",+ Some(serde_json::json!({+ "code": "direct_capture_probe_timed_out",+ "message": "The ScreenCaptureKit capability probe did not complete within 10 seconds.",+ })),+ ),+ Self::Failed => (+ None,+ "probe_failed",+ Some(serde_json::json!({+ "code": "direct_capture_probe_failed",+ "message": "The ScreenCaptureKit capability probe could not complete.",+ })),+ ),+ }+ }+}++async fn run_direct_capture_probe<F>(timeout: Duration, probe: F) -> DirectCaptureProbeResult+where+ F: Future<Output = Result<bool, tokio::task::JoinError>>,+{+ match tokio::time::timeout(timeout, probe).await {+ Ok(Ok(true)) => DirectCaptureProbeResult::Ready,+ Ok(Ok(false)) => DirectCaptureProbeResult::Unavailable,+ Ok(Err(error)) => {+ tracing::warn!(%error, "direct ScreenCaptureKit capability probe failed");+ DirectCaptureProbeResult::Failed+ }+ Err(_) => DirectCaptureProbeResult::TimedOut,+ }+}++async fn bounded_screen_recording_capturable() -> DirectCaptureProbeResult {+ run_direct_capture_probe(+ DIRECT_CAPTURE_PROBE_TIMEOUT,+ tokio::task::spawn_blocking(screen_recording_capturable),+ )+ .await+}+fn should_probe_direct_capture(should_prompt: bool,screen_recording: bool,@@ -182,8 +240,9 @@ fn def() -> &'static ToolDef {Returns: `accessibility` + `screen_recording` (booleans from the TCC \preflight APIs), `screen_recording_capturable` (a live ScreenCaptureKit \probe when `prompt` is true; null on read-only calls), \- `direct_capture_status` (`ready`, `unavailable`, \- `blocked_by_screen_recording`, or `not_checked`), and `source` (which TCC identity the \+ `direct_capture_status` (`ready`, `unavailable`, `timed_out`, `probe_failed`, \+ `blocked_by_screen_recording`, or `not_checked`), `direct_capture_error` (a structured \+ timeout/probe failure when applicable), and `source` (which TCC identity the \booleans reflect: the CuaDriver daemon vs the launching terminal/IDE). \macOS attributes grants to the responsible process, so a standalone call \from a terminal reports the terminal's grants, not the driver's. The \@@ -260,20 +319,22 @@ impl Tool for CheckPermissionsTool {// private-window-picker bypass consent. A status/read-only call must// therefore never execute it. The explicit grant path opts in with// `prompt:true`, explains the dialog first, and verifies the result.- let (screen_recording_capturable, direct_capture_status) = if !should_prompt {- (None, "not_checked")- } else if !screen_recording {- (None, "blocked_by_screen_recording")- } else if should_probe_direct_capture(should_prompt, screen_recording, probe_direct_capture)- {- let capturable = screen_recording_capturable();- (- Some(capturable),- if capturable { "ready" } else { "unavailable" },- )- } else {- (None, "not_checked")- };+ let (screen_recording_capturable, direct_capture_status, direct_capture_error) =+ if !should_prompt {+ (None, "not_checked", None)+ } else if !screen_recording {+ (None, "blocked_by_screen_recording", None)+ } else if should_probe_direct_capture(+ should_prompt,+ screen_recording,+ probe_direct_capture,+ ) {+ bounded_screen_recording_capturable()+ .await+ .response_fields()+ } else {+ (None, "not_checked", None)+ };// (B) Which identity the booleans above belong to.let source = permission_source(self.state.host_owns_permission_ux,@@ -304,6 +365,16 @@ impl Tool for CheckPermissionsTool {"\n⚠️ Screen Recording reads granted but a live capture probe failed — \the grant likely belongs to a different process, not this one.",);+ } else if direct_capture_status == "timed_out" {+ summary.push_str(+ "\n⚠️ The direct ScreenCaptureKit readiness probe timed out; the permission \+ check returned without waiting indefinitely.",+ );+ } else if direct_capture_status == "probe_failed" {+ summary.push_str(+ "\n⚠️ The direct ScreenCaptureKit readiness probe failed; see \+ direct_capture_error for the bounded failure code.",+ );} else if screen_recording_capturable.is_none() && (!should_prompt || !probe_direct_capture){summary.push_str(@@ -333,6 +404,7 @@ impl Tool for CheckPermissionsTool {"screen_recording": screen_recording,"screen_recording_capturable": screen_recording_capturable,"direct_capture_status": direct_capture_status,+ "direct_capture_error": direct_capture_error,"source": source,}))}@@ -443,6 +515,38 @@ mod tests {assert!(!should_probe_direct_capture(true, true, false));}+ #[tokio::test]+ async fn direct_capture_probe_returns_before_a_hung_probe() {+ let result = run_direct_capture_probe(+ std::time::Duration::from_millis(10),+ std::future::pending::<Result<bool, tokio::task::JoinError>>(),+ )+ .await;++ assert_eq!(result, DirectCaptureProbeResult::TimedOut);+ let (capturable, status, error) = result.response_fields();+ assert_eq!(capturable, None);+ assert_eq!(status, "timed_out");+ assert_eq!(error.unwrap()["code"], "direct_capture_probe_timed_out");+ }++ #[tokio::test]+ async fn direct_capture_probe_preserves_successful_results() {+ let ready = run_direct_capture_probe(+ std::time::Duration::from_secs(1),+ std::future::ready(Ok(true)),+ )+ .await;+ let unavailable = run_direct_capture_probe(+ std::time::Duration::from_secs(1),+ std::future::ready(Ok(false)),+ )+ .await;++ assert_eq!(ready, DirectCaptureProbeResult::Ready);+ assert_eq!(unavailable, DirectCaptureProbeResult::Unavailable);+ }+#[test]fn disclaim_env_var_alone_does_not_grant_daemon_attribution() {// The disclaim env var is caller-controlled, so on its own it must not