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
feat(platform-macos): port PermissionsGate CLI flow for first-launch UX (#1527) (#1529)
Francesco Bonacci0df35d72a2b7
diff --git a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx b/docs/content/docs/cua-driver/guide/getting-started/installation.mdxindex 9d7069c83d..d97b62cc00 100644--- a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx+++ b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx@@ -75,6 +75,29 @@ cua-driver check_permissionsIf a grant still reads `NOT granted` after granting in the dialog, open **System Settings → Privacy & Security**, find `CuaDriver.app` under Accessibility and Screen Recording, and flip the toggle.+<Callout type="info">+ **First-launch permissions gate (`cua-driver serve`).** On the Rust port,+ `cua-driver serve` runs an interactive permissions gate at startup. If+ Accessibility or Screen Recording is missing it prints a banner, auto-opens+ the matching System Settings pane, and polls until you grant the missing+ items. When both grants are already active the gate is a transparent no-op.++ **CI / headless runners** should skip the gate so the daemon does not block+ waiting for a TTY-attached human:++ ```bash+ # As a flag …+ cua-driver serve --no-permissions-gate++ # … or as an env-var.+ CUA_DRIVER_RS_PERMISSIONS_GATE=0 cua-driver serve+ ```++ Accepted "off" values for the env-var (case-insensitive): `0`, `false`,+ `no`, `off` — so `FALSE`, `Off`, `NO` etc. all work. Any other value+ (including unset) leaves the gate active.+</Callout>+## Requirements- macOS 14 (Sonoma) or laterdiff --git a/docs/content/docs/cua-driver/reference/cli-reference.mdx b/docs/content/docs/cua-driver/reference/cli-reference.mdxindex 9bba78d283..3fbb866803 100644--- a/docs/content/docs/cua-driver/reference/cli-reference.mdx+++ b/docs/content/docs/cua-driver/reference/cli-reference.mdx@@ -142,6 +142,13 @@ Subsequent `cua-driver call/list-tools/describe` invocations auto-detectthe socket and forward their requests, so the AppStateEngine's per-pidelement_index cache survives across CLI calls.+On macOS, `serve` runs a **first-launch permissions gate** before binding+the socket. When TCC grants for Accessibility or Screen Recording are+missing, it prints a banner listing exactly what is missing, auto-opens+the matching `System Settings → Privacy & Security` pane(s), and polls+every second until the user grants both. When grants are already active+the gate is a transparent no-op.+**Options:**| Name | Type | Default | Description |@@ -153,6 +160,7 @@ element_index cache survives across CLI calls.| Name | Description || ---- | ----------- || `--no-relaunch` | Stay in the current process instead of re-execing via `open -n -g -a CuaDriver`. |+| `--no-permissions-gate` | Skip the macOS TCC permissions gate at startup. Use for CI / headless runners where blocking on user input would deadlock the process. Also toggleable by setting `CUA_DRIVER_RS_PERMISSIONS_GATE` to any of `0`, `false`, `no`, or `off` (case-insensitive — e.g. `CUA_DRIVER_RS_PERMISSIONS_GATE=FALSE` works too). |### cua-driver stopdiff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.mdindex 0bf07cf3e1..29a952f2f3 100644--- a/libs/cua-driver-rs/PARITY.md+++ b/libs/cua-driver-rs/PARITY.md@@ -242,6 +242,66 @@ status).---+## Startup flow: permissions gate (`serve`)+- Swift: `libs/cua-driver/Sources/CuaDriverCore/Permissions/PermissionsGate.swift`+ (SwiftUI panel + AppKit window + 1 Hz polling)+- Rust:+ - macos=`crates/platform-macos/src/permissions/gate.rs`+ (CLI banner + auto-open System Settings + 1 Hz polling)+ - windows / linux: N/A — TCC is a macOS concept; the `--no-permissions-gate`+ flag is accepted and silently ignored on those platforms for CLI uniformity.+- Status:+ - macos: PORTED with intentional UX divergence (CLI, not SwiftUI)+ - windows / linux: N/A++### Intentional UX divergence++Swift surfaces a branded SwiftUI window on first launch. The Rust port+ships a terminal-driven banner instead. Rationale:++1. cua-driver-rs already drives an AppKit run loop on the main thread+ for the cursor overlay; bolting on a second window invites+ main-thread deadlocks.+2. The Rust binary's primary deployment shape is the daemon under+ `cua-driver serve` from a shell (Claude Code, Cursor, Codex), which+ already has a terminal attached.+3. Headless / CI use cases need an opt-out; a CLI flow with+ `--no-permissions-gate` + `CUA_DRIVER_RS_PERMISSIONS_GATE=0` is the+ straight-line approach. Replicating Swift's window only to suppress+ it under headless would be more code with no UX upside.++The CLI gate still preserves the substantive Swift behaviours:++- Lists exactly which TCC grants are missing (Accessibility / Screen+ Recording), with the same rationale strings the SwiftUI panel uses.+- Opens both `x-apple.systempreferences:` URLs at once so the user can+ grant both in a single Settings visit. (Swift's "chain to next pane+ when one flips green" trick is unnecessary when both panes are+ pre-opened.)+- Polls at 1 Hz, identical cadence to the Swift `Timer`.+- Auto-continues startup the moment all required grants are green.++### Opt-out signals++| Signal | Effect |+| --------------------------------------- | ----------- |+| `--no-permissions-gate` flag | gate skipped |+| `CUA_DRIVER_RS_PERMISSIONS_GATE=0` | gate skipped |+| `CUA_DRIVER_RS_PERMISSIONS_GATE=false` | gate skipped |+| `CUA_DRIVER_RS_PERMISSIONS_GATE=no` | gate skipped |+| `CUA_DRIVER_RS_PERMISSIONS_GATE=off` | gate skipped |+| any other env value | gate active |++Default deadline is 10 minutes; on timeout the gate logs an error and+`serve` continues to start, mirroring the Swift "user closed the+panel" path (individual tool calls then fail with the underlying TCC+error).++A native `NSAlert` via objc2 is tracked as a follow-up if the+terminal-only flow proves insufficient; the CLI is the MVP.++---+## MCP tool: `list_apps`- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ListAppsTool.swift:6-71`+ `libs/cua-driver/Sources/CuaDriverCore/Apps/AppInfo.swift`diff --git a/libs/cua-driver-rs/crates/cua-driver/src/cli.rs b/libs/cua-driver-rs/crates/cua-driver/src/cli.rsindex 4215bdfff3..c22e324a03 100644--- a/libs/cua-driver-rs/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver-rs/crates/cua-driver/src/cli.rs@@ -22,7 +22,14 @@ pub enum Command {Describe(String),Call { tool: String, json_args: Option<serde_json::Value>, screenshot_out_file: Option<String> },McpConfig { client: Option<String> },- Serve { socket: Option<String> },+ Serve {+ socket: Option<String>,+ /// True when `--no-permissions-gate` is on argv. The env-var+ /// `CUA_DRIVER_RS_PERMISSIONS_GATE=0` short-circuits the gate too+ /// (checked inside the gate itself), so the flag is only one of+ /// two opt-out signals.+ no_permissions_gate: bool,+ },Stop { socket: Option<String> },Status { socket: Option<String> },Recording { subcommand: String, args: Vec<String>, socket: Option<String> },@@ -93,7 +100,11 @@ pub fn parse_command() -> Command {None | Some("mcp") => Command::Mcp,Some("list-tools") => Command::ListTools,Some("mcp-config") => Command::McpConfig { client: mcp_client },- Some("serve") => Command::Serve { socket },+ Some("serve") => Command::Serve {+ socket,+ // Bare flag — present anywhere on argv counts as "skip the gate".+ no_permissions_gate: args.iter().any(|a| a == "--no-permissions-gate"),+ },Some("stop") => Command::Stop { socket },Some("status") => Command::Status { socket },Some("recording") => {diff --git a/libs/cua-driver-rs/crates/cua-driver/src/main.rs b/libs/cua-driver-rs/crates/cua-driver/src/main.rsindex c8f8504187..a6c629ea01 100644--- a/libs/cua-driver-rs/crates/cua-driver/src/main.rs+++ b/libs/cua-driver-rs/crates/cua-driver/src/main.rs@@ -84,7 +84,25 @@ fn main() {cli::run_call(reg, &tool, json_args, screenshot_out_file);return;}- cli::Command::Serve { socket } => {+ cli::Command::Serve { socket, no_permissions_gate } => {+ // First-launch permissions gate (Swift PermissionsGate parity).+ // Runs on every `serve` start; no-op when both grants are+ // already active. Honors --no-permissions-gate and+ // CUA_DRIVER_RS_PERMISSIONS_GATE=0 for CI / headless.+ //+ // Failures (e.g. deadline elapsed without grants) are logged+ // and the daemon continues to start — individual tool calls+ // will then fail with the underlying TCC error, mirroring+ // Swift's "user closed the panel" fallback.+ let gate_opts = platform_macos::permissions::GateOpts::from_env_and_flag(+ no_permissions_gate,+ );+ if let Err(e) = platform_macos::permissions::run_if_needed(gate_opts) {+ eprintln!("[cua-driver] permissions gate: {e}");+ eprintln!("[cua-driver] continuing serve startup anyway — \+ expect tool calls touching AX or Screen Recording \+ to fail until you grant the missing TCC permissions.");+ }mcp_server::recording::set_screenshot_fn(|window_id, pid| {if let Some(wid) = window_id {platform_macos::capture::screenshot_window_bytes(wid as u32).ok()@@ -251,7 +269,11 @@ fn main() -> anyhow::Result<()> {}).join().ok();return Ok(());}- cli::Command::Serve { socket } => {+ cli::Command::Serve { socket, no_permissions_gate } => {+ // The Rust permissions gate is macOS-only (TCC concept).+ // On Windows / Linux the flag is silently accepted for+ // CLI uniformity and ignored.+ let _ = no_permissions_gate;// Serve mode needs the cursor overlay just like MCP mode.let cursor_cfg = cursor_overlay::CursorConfig::from_args();let reg = Arc::new(build_registry(cursor_cfg));diff --git a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs b/libs/cua-driver-rs/crates/platform-macos/src/lib.rsindex c3e469faa9..cf8d92bef1 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs@@ -23,6 +23,8 @@ pub mod browser;#[cfg(target_os = "macos")]pub mod focus_steal;#[cfg(target_os = "macos")]+pub mod permissions;+#[cfg(target_os = "macos")]pub mod tools;use mcp_server::tool::ToolRegistry;diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rsnew file mode 100644index 0000000000..2e0fdf02da--- /dev/null+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/gate.rs@@ -0,0 +1,503 @@+//! First-launch permissions gate — CLI flow.+//!+//! Rust port of Swift's `PermissionsGate` (SwiftUI panel + polling). The+//! Rust port intentionally drops the SwiftUI window and reimplements the+//! flow as a terminal-only experience:+//!+//! 1. Inspect TCC state on `serve` startup.+//! 2. If any required grant is missing, print a clear explanation+//! (which grant, why cua-driver needs it, what to do next).+//! 3. Open the relevant `System Settings` pane(s) via the+//! `x-apple.systempreferences:` URL scheme.+//! 4. Poll TCC state every second. Emit a "still waiting" line every+//! 5 seconds so the user knows the daemon is still alive and what+//! it is waiting for.+//! 5. As soon as everything flips green, print a confirmation and+//! return — `serve` proceeds normally.+//!+//! Opt-out: `--no-permissions-gate` flag or+//! `CUA_DRIVER_RS_PERMISSIONS_GATE` set to `0` / `false` / `no` / `off`+//! (case-insensitive) skips the entire flow. Intended for CI / headless+//! automation where blocking on user input would deadlock the runner.+//!+//! Why no GUI window: the Swift gate uses AppKit + SwiftUI which would+//! require a full overlay + NSApplication run loop just to display a+//! dialog. cua-driver-rs already has a separate AppKit thread for the+//! cursor overlay, and grafting another window onto it is a recipe for+//! main-thread deadlocks. A terminal-driven flow is uglier but reliable+//! and works headless (with the opt-out flag), which is exactly the+//! audience for the Rust port.+//!+//! A future enhancement could open a native `NSAlert` via objc2 for a+//! more polished look — left as a follow-up; CLI is the MVP.++use std::io::Write;+use std::time::{Duration, Instant};++use anyhow::Result;++use crate::permissions::status::{+ current_status, request_accessibility, request_screen_recording, PermissionsStatus,+};++/// Which TCC grant is missing. Each variant maps 1:1 to a System Settings+/// pane URL via [`MissingPermission::settings_url`].+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum MissingPermission {+ Accessibility,+ ScreenRecording,+}++impl MissingPermission {+ /// Short human-readable label used in CLI output.+ pub fn label(self) -> &'static str {+ match self {+ Self::Accessibility => "Accessibility",+ Self::ScreenRecording => "Screen Recording",+ }+ }++ /// One-line rationale shown in the missing-permission listing. Text+ /// adapted from the Swift gate's SwiftUI subtitle copy.+ pub fn rationale(self) -> &'static str {+ match self {+ Self::Accessibility =>+ "lets cua-driver read the accessibility tree of running apps and \+ send clicks / keystrokes via AX RPC.",+ Self::ScreenRecording =>+ "lets cua-driver capture per-window screenshots so agents can see \+ the current UI state alongside the tree.",+ }+ }++ /// `x-apple.systempreferences:` URL that deep-links into the matching+ /// Privacy pane. Same strings the Swift gate uses.+ pub fn settings_url(self) -> &'static str {+ match self {+ Self::Accessibility =>+ "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility",+ Self::ScreenRecording =>+ "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture",+ }+ }+}++/// All missing required permissions, derived from a [`PermissionsStatus`]+/// snapshot. Returns an empty vec when everything is granted.+pub fn missing_from_status(status: PermissionsStatus) -> Vec<MissingPermission> {+ let mut out = Vec::new();+ if !status.accessibility {+ out.push(MissingPermission::Accessibility);+ }+ if !status.screen_recording {+ out.push(MissingPermission::ScreenRecording);+ }+ out+}++/// Inspect live TCC state and return whatever is missing. Convenience+/// wrapper around `missing_from_status(current_status())`.+pub fn check_required_permissions() -> Vec<MissingPermission> {+ missing_from_status(current_status())+}++/// Open the System Settings pane for a single permission via `open(1)`.+///+/// macOS routes `x-apple.systempreferences:` URLs through `System Settings`+/// automatically — same mechanism the Swift gate uses via `NSWorkspace.open`.+pub fn open_system_settings_for(permission: MissingPermission) -> Result<()> {+ let status = std::process::Command::new("open")+ .arg(permission.settings_url())+ .status()?;+ if !status.success() {+ anyhow::bail!(+ "`open {}` exited with status {:?}",+ permission.settings_url(),+ status.code()+ );+ }+ Ok(())+}++/// Knobs for [`run_if_needed`]. Defaults are tuned for an interactive+/// `serve` startup; CI callers should set `opt_out = true` (either via+/// the `--no-permissions-gate` flag or the env-var honored by+/// [`GateOpts::from_env_and_flag`]).+#[derive(Debug, Clone)]+pub struct GateOpts {+ /// When `true` the gate is a no-op even if permissions are missing.+ pub opt_out: bool,+ /// Cap the polling phase so a forgotten daemon does not hang+ /// forever. `None` means "wait indefinitely" — matches Swift's+ /// SwiftUI panel which has no built-in timeout. Default: 10 min.+ pub deadline: Option<Duration>,+ /// How often to re-check TCC state. Default: 1s — same cadence as+ /// the Swift gate's `Timer.scheduledTimer(withTimeInterval: 1.0)`.+ pub poll_interval: Duration,+ /// How often to print a "still waiting for X" status line. Default:+ /// 5s — frequent enough to reassure the user the daemon is alive,+ /// rare enough not to spam the terminal.+ pub status_interval: Duration,+ /// When `true` and a required permission is missing, also raise the+ /// macOS TCC prompts (`AXIsProcessTrustedWithOptions` /+ /// `CGRequestScreenCaptureAccess`). Helpful on first launch when+ /// the process has never asked before. Default: true.+ pub also_raise_prompts: bool,+ /// When `true` (default), `open` the System Settings pane for the+ /// missing permission(s). Set false to suppress the auto-open in+ /// tests or scripted scenarios.+ pub open_settings: bool,+}++impl Default for GateOpts {+ fn default() -> Self {+ Self {+ opt_out: false,+ deadline: Some(Duration::from_secs(10 * 60)),+ poll_interval: Duration::from_secs(1),+ status_interval: Duration::from_secs(5),+ also_raise_prompts: true,+ open_settings: true,+ }+ }+}++impl GateOpts {+ /// Construct from the standard env-var+ /// (`CUA_DRIVER_RS_PERMISSIONS_GATE` set to `0` / `false` / `no` /+ /// `off`, case-insensitive, disables the gate) and an explicit+ /// `--no-permissions-gate` flag. Either signal is sufficient to opt+ /// out.+ pub fn from_env_and_flag(no_gate_flag: bool) -> Self {+ // Match the standard list of "off" sentinels case-insensitively so+ // CI scripts can use any of `0`, `false`, `no`, `off`, `FALSE`,+ // `Off`, etc. without surprises. Anything not in this set leaves+ // the gate active — fail-safe default for first-launch UX.+ let env_disabled = std::env::var("CUA_DRIVER_RS_PERMISSIONS_GATE")+ .ok()+ .map(|v| {+ let lower = v.to_ascii_lowercase();+ matches!(lower.as_str(), "0" | "false" | "no" | "off")+ })+ .unwrap_or(false);+ Self {+ opt_out: no_gate_flag || env_disabled,+ ..Self::default()+ }+ }+}++/// Run the gate if needed. When called and the process already has both+/// grants, this returns immediately without printing anything — the+/// `serve` happy path is unaffected.+///+/// When grants are missing and `opt_out` is false:+/// - Prints the missing-permissions banner.+/// - Optionally raises the system TCC prompts (`also_raise_prompts`).+/// - Opens the System Settings pane(s) for the user.+/// - Polls TCC every `poll_interval` and re-emits a status line every+/// `status_interval` until everything is green or `deadline` elapses.+///+/// Returns `Ok(())` on success (all green or opt-out). Returns+/// `Err` only if the deadline elapsed without all permissions granted —+/// callers may choose to continue anyway and let individual tools fail+/// with their existing error messages, mirroring Swift's "user closes+/// the panel" path.+pub fn run_if_needed(opts: GateOpts) -> Result<()> {+ if opts.opt_out {+ tracing::debug!("permissions gate skipped (opt_out=true)");+ return Ok(());+ }++ let initial = current_status();+ if initial.all_granted() {+ // Fast path: everything already green. No banner, no polling —+ // the user sees nothing different from before this gate existed.+ return Ok(());+ }++ let missing = missing_from_status(initial);+ print_banner(&missing, opts.open_settings);++ if opts.also_raise_prompts {+ // These are no-ops when the grant is already active and are the+ // documented way to fire the first-launch system dialogs. Match+ // the behaviour of the `check_permissions` MCP tool's default path.+ if missing.contains(&MissingPermission::Accessibility) {+ let _ = request_accessibility();+ }+ if missing.contains(&MissingPermission::ScreenRecording) {+ let _ = request_screen_recording();+ }+ }++ if opts.open_settings {+ // Open *both* missing panes up front. System Settings collapses+ // duplicate-open requests to a single navigation, so this isn't+ // disruptive even when only one grant is needed.+ for m in &missing {+ if let Err(e) = open_system_settings_for(*m) {+ eprintln!(" (could not auto-open Settings for {}: {e})", m.label());+ }+ }+ }++ wait_for_grants(&opts)+}++/// Block until all required permissions are granted or the deadline+/// elapses. Emits a status line every `opts.status_interval` while+/// waiting so the user has feedback.+///+/// Exposed separately from [`run_if_needed`] for callers that want to+/// drive the wait phase manually (e.g. tests that pre-skip the banner).+pub fn wait_for_grants(opts: &GateOpts) -> Result<()> {+ let start = Instant::now();+ let mut last_status_print = start;+ let mut last_missing: Vec<MissingPermission> = check_required_permissions();++ loop {+ if last_missing.is_empty() {+ println!("[cua-driver] permissions granted — continuing startup");+ let _ = std::io::stdout().flush();+ return Ok(());+ }++ if let Some(deadline) = opts.deadline {+ if start.elapsed() >= deadline {+ anyhow::bail!(+ "permissions gate timed out after {:?} — still missing: {}",+ deadline,+ fmt_missing(&last_missing)+ );+ }+ }++ std::thread::sleep(opts.poll_interval);++ let new_missing = check_required_permissions();+ if new_missing != last_missing {+ // State changed (red→green, or order-flipped). Re-emit so the+ // user sees progress without waiting for the next status tick.+ if !new_missing.is_empty() {+ println!(+ "[cua-driver] progress — still waiting on: {}",+ fmt_missing(&new_missing)+ );+ let _ = std::io::stdout().flush();+ }+ last_status_print = Instant::now();+ last_missing = new_missing;+ continue;+ }++ if last_status_print.elapsed() >= opts.status_interval {+ println!(+ "[cua-driver] still waiting on: {} \+ (open System Settings → Privacy & Security to grant)",+ fmt_missing(&last_missing)+ );+ let _ = std::io::stdout().flush();+ last_status_print = Instant::now();+ }+ }+}++fn print_banner(missing: &[MissingPermission], open_settings: bool) {+ println!();+ println!("──────────────────────────────────────────────────────────────");+ println!(" cua-driver needs your permission before `serve` can start");+ println!("──────────────────────────────────────────────────────────────");+ println!();+ println!(" Missing TCC grant(s) for this process:");+ for m in missing {+ println!(" • {}", m.label());+ println!(" {}", m.rationale());+ }+ println!();+ if open_settings {+ println!(" Opening System Settings → Privacy & Security now.");+ } else {+ // open_settings was suppressed by the caller — print the manual+ // command(s) instead so the user still knows where to go. Listing+ // each pane keeps copy-paste working when only one grant is needed.+ println!(" Open System Settings → Privacy & Security manually, e.g.:");+ for m in missing {+ println!(" open \"{}\" # {}", m.settings_url(), m.label());+ }+ }+ println!(" Grant each item, then this prompt will auto-continue.");+ println!();+ println!(" Skip this gate (CI / headless): re-run with");+ println!(" cua-driver serve --no-permissions-gate");+ println!(" or set CUA_DRIVER_RS_PERMISSIONS_GATE to 0/false/no/off");+ println!(" (case-insensitive) in the environment.");+ println!();+ let _ = std::io::stdout().flush();+}++fn fmt_missing(missing: &[MissingPermission]) -> String {+ missing+ .iter()+ .map(|m| m.label())+ .collect::<Vec<_>>()+ .join(", ")+}++#[cfg(test)]+mod tests {+ use super::*;+ use std::sync::{Mutex, OnceLock};++ /// Serializes every test that mutates `CUA_DRIVER_RS_PERMISSIONS_GATE`.+ /// `cargo test` runs tests in parallel by default and `std::env::set_var`+ /// / `remove_var` touch a process-global table — without this lock the+ /// env-var tests race and produce flaky failures.+ static TEST_ENV_MUTEX: OnceLock<Mutex<()>> = OnceLock::new();++ fn env_lock() -> std::sync::MutexGuard<'static, ()> {+ // `lock()` can only fail if a previous holder panicked. Recover the+ // guard and keep going — the env var will be re-set/cleared by this+ // test anyway, so a poisoned mutex carries no stale invariant.+ TEST_ENV_MUTEX+ .get_or_init(|| Mutex::new(()))+ .lock()+ .unwrap_or_else(|e| e.into_inner())+ }++ #[test]+ fn opt_out_short_circuits_run_if_needed() {+ // With opt_out=true the gate must return Ok(()) without touching+ // TCC state, opening Settings, or sleeping. We can't easily assert+ // "didn't sleep" without a clock, but we can assert that an+ // unrealistically short deadline still produces Ok — which proves+ // the wait loop was not entered.+ let opts = GateOpts {+ opt_out: true,+ deadline: Some(Duration::from_nanos(1)),+ poll_interval: Duration::from_secs(60),+ status_interval: Duration::from_secs(60),+ also_raise_prompts: false,+ open_settings: false,+ };+ assert!(run_if_needed(opts).is_ok());+ }++ #[test]+ fn env_var_disables_gate() {+ let _guard = env_lock();+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", "0");+ let opts = GateOpts::from_env_and_flag(false);+ assert!(opts.opt_out, "env=0 must opt out");+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");+ }++ #[test]+ fn flag_disables_gate() {+ let _guard = env_lock();+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");+ let opts = GateOpts::from_env_and_flag(true);+ assert!(opts.opt_out, "--no-permissions-gate must opt out");+ }++ #[test]+ fn neither_flag_nor_env_does_not_opt_out() {+ let _guard = env_lock();+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");+ let opts = GateOpts::from_env_and_flag(false);+ assert!(!opts.opt_out);+ }++ #[test]+ fn env_var_truthy_values_do_not_opt_out() {+ let _guard = env_lock();+ // Only the explicit "off" sentinels disable the gate. Anything+ // else (including empty string or unknown garbage) leaves the gate+ // active — fail-safe default for first-launch UX.+ for v in &["1", "true", "yes", "on", "garbage", ""] {+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", v);+ let opts = GateOpts::from_env_and_flag(false);+ assert!(+ !opts.opt_out,+ "env={v:?} must not opt out (only 0/false/no/off do)"+ );+ }+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");+ }++ #[test]+ fn env_var_off_sentinels_are_case_insensitive() {+ let _guard = env_lock();+ // Every documented off-sentinel must opt out regardless of case so+ // CI scripts can use whatever convention they prefer.+ for v in &[+ "0", "false", "FALSE", "False", "no", "NO", "No", "off", "OFF", "Off", "TrUe",+ ] {+ std::env::set_var("CUA_DRIVER_RS_PERMISSIONS_GATE", v);+ let opts = GateOpts::from_env_and_flag(false);+ // "TrUe" is in the list intentionally — it must NOT opt out+ // (it's not in the off-sentinel set), so split the assertion.+ let expected_opt_out =+ matches!(v.to_ascii_lowercase().as_str(), "0" | "false" | "no" | "off");+ assert_eq!(+ opts.opt_out, expected_opt_out,+ "env={v:?} opt_out mismatch (expected {expected_opt_out})"+ );+ }+ std::env::remove_var("CUA_DRIVER_RS_PERMISSIONS_GATE");+ }++ #[test]+ fn missing_from_status_orders_accessibility_first() {+ let neither = PermissionsStatus {+ accessibility: false,+ screen_recording: false,+ };+ assert_eq!(+ missing_from_status(neither),+ vec![+ MissingPermission::Accessibility,+ MissingPermission::ScreenRecording+ ]+ );++ let only_sr = PermissionsStatus {+ accessibility: false,+ screen_recording: true,+ };+ assert_eq!(+ missing_from_status(only_sr),+ vec![MissingPermission::Accessibility]+ );++ let only_ax = PermissionsStatus {+ accessibility: true,+ screen_recording: false,+ };+ assert_eq!(+ missing_from_status(only_ax),+ vec![MissingPermission::ScreenRecording]+ );++ let all = PermissionsStatus {+ accessibility: true,+ screen_recording: true,+ };+ assert!(missing_from_status(all).is_empty());+ }++ #[test]+ fn settings_urls_match_swift() {+ // Verbatim parity with PermissionsGate.swift's SettingsPane enum so+ // grant-flows opens the exact same panes on both the Swift and+ // Rust binaries.+ assert_eq!(+ MissingPermission::Accessibility.settings_url(),+ "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"+ );+ assert_eq!(+ MissingPermission::ScreenRecording.settings_url(),+ "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"+ );+ }+}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rsnew file mode 100644index 0000000000..fbf043a5c1--- /dev/null+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/mod.rs@@ -0,0 +1,20 @@+//! macOS TCC permission checks + first-launch CLI gate.+//!+//! Two layers:+//! - [`status`] — low-level booleans for Accessibility / Screen Recording.+//! - [`gate`] — startup-time interactive flow that walks the user through+//! granting the missing permissions before `serve` binds.+//!+//! The gate is a Rust port of Swift's `PermissionsGate` (SwiftUI panel),+//! re-implemented as a terminal-only flow so the Rust port does not pull in+//! a GUI framework. See `gate.rs` for the rationale + UX shape.+//!+//! Mirrors `libs/cua-driver/Sources/CuaDriverCore/Permissions/`:+//! - `Permissions.swift` → `permissions::status`+//! - `PermissionsGate.swift` → `permissions::gate` (CLI-only)++pub mod gate;+pub mod status;++pub use status::{PermissionsStatus, current_status};+pub use gate::{GateOpts, MissingPermission, run_if_needed};diff --git a/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rs b/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rsnew file mode 100644index 0000000000..2b6b25c1ab--- /dev/null+++ b/libs/cua-driver-rs/crates/platform-macos/src/permissions/status.rs@@ -0,0 +1,86 @@+//! Low-level TCC permission status probes.+//!+//! Mirrors Swift `Permissions.currentStatus()` / `Permissions.requestAccessibility()`+//! / `Permissions.requestScreenRecording()` — bare booleans, no UI. Used by+//! both the `check_permissions` MCP tool and the startup permissions gate+//! (`super::gate`).++/// Snapshot of which TCC grants are active for the current process.+///+/// Field naming matches the JSON shape used by the `check_permissions`+/// MCP tool: `accessibility` + `screen_recording`.+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]+pub struct PermissionsStatus {+ pub accessibility: bool,+ #[serde(rename = "screen_recording")]+ pub screen_recording: bool,+}++impl PermissionsStatus {+ /// True when **both** required TCC grants are active.+ pub fn all_granted(self) -> bool {+ self.accessibility && self.screen_recording+ }+}++/// Read the live TCC status for both required grants. Cheap to call+/// repeatedly — `AXIsProcessTrusted` is a quick C function and the+/// screen recording probe falls back to the window-enumeration heuristic+/// when `CGPreflightScreenCaptureAccess` reports false.+///+/// Mirrors Swift `Permissions.currentStatus()`. Difference: Swift uses+/// `SCShareableContent.excludingDesktopWindows` (ScreenCaptureKit) for+/// the screen recording probe, which is unavailable from Rust without+/// large bindings — same caveat documented in `check_permissions.rs`.+pub fn current_status() -> PermissionsStatus {+ PermissionsStatus {+ accessibility: accessibility_granted(),+ screen_recording: screen_recording_granted(),+ }+}++/// Live AX trust state — `AXIsProcessTrusted()`.+pub fn accessibility_granted() -> bool {+ unsafe { crate::ax::bindings::AXIsProcessTrusted() }+}++/// Best-effort screen recording probe. Uses `CGPreflightScreenCaptureAccess`+/// then falls back to the window-enumeration heuristic for parity with+/// the existing `check_permissions` tool — see that file for rationale.+pub fn screen_recording_granted() -> bool {+ #[link(name = "CoreGraphics", kind = "framework")]+ extern "C" {+ fn CGPreflightScreenCaptureAccess() -> bool;+ }+ if unsafe { CGPreflightScreenCaptureAccess() } {+ return true;+ }+ !crate::windows::all_windows().is_empty()+}++/// Raise the Accessibility TCC prompt if not yet granted. No-op when+/// already active. Mirrors Swift `Permissions.requestAccessibility()`.+pub fn request_accessibility() -> bool {+ use core_foundation::base::TCFType;+ use core_foundation::boolean::CFBoolean;+ use core_foundation::dictionary::CFDictionary;+ use core_foundation::string::CFString;++ let key = CFString::new("AXTrustedCheckOptionPrompt");+ let val = CFBoolean::true_value();+ let options =+ CFDictionary::from_CFType_pairs(&[(key.as_CFType(), val.as_CFType())]);+ unsafe {+ crate::ax::bindings::AXIsProcessTrustedWithOptions(options.as_concrete_TypeRef())+ }+}++/// Raise the Screen Recording TCC prompt if not yet granted.+/// Mirrors Swift `Permissions.requestScreenRecording()`.+pub fn request_screen_recording() -> bool {+ #[link(name = "CoreGraphics", kind = "framework")]+ extern "C" {+ fn CGRequestScreenCaptureAccess() -> bool;+ }+ unsafe { CGRequestScreenCaptureAccess() }+}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rsindex 40e9cde230..7d87269f06 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/check_permissions.rs@@ -2,6 +2,11 @@ use async_trait::async_trait;use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};use serde_json::Value;+use crate::permissions::status::{+ accessibility_granted, request_accessibility, request_screen_recording,+ screen_recording_granted,+};+pub struct CheckPermissionsTool;static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();@@ -45,8 +50,8 @@ impl Tool for CheckPermissionsTool {let _ = request_accessibility();let _ = request_screen_recording();}- let accessibility = unsafe { crate::ax::bindings::AXIsProcessTrusted() };- let screen_recording = probe_screen_recording();+ let accessibility = accessibility_granted();+ let screen_recording = screen_recording_granted();// Text format mirrors Swift 1:1:// "✅ Accessibility: granted.\n✅ Screen Recording: granted."@@ -65,45 +70,3 @@ impl Tool for CheckPermissionsTool {}))}}--/// Raise the Accessibility TCC prompt if not yet granted. No-op when active.-/// Mirrors Swift `Permissions.requestAccessibility()`.-fn request_accessibility() -> bool {- use core_foundation::base::TCFType;- use core_foundation::boolean::CFBoolean;- use core_foundation::dictionary::CFDictionary;- use core_foundation::string::CFString;-- let key = CFString::new("AXTrustedCheckOptionPrompt");- let val = CFBoolean::true_value();- let options = CFDictionary::from_CFType_pairs(&[(key.as_CFType(), val.as_CFType())]);- unsafe {- crate::ax::bindings::AXIsProcessTrustedWithOptions(options.as_concrete_TypeRef())- }-}--/// Raise the Screen Recording TCC prompt if not yet granted.-/// Mirrors Swift `Permissions.requestScreenRecording()` (`CGRequestScreenCaptureAccess`).-fn request_screen_recording() -> bool {- #[link(name = "CoreGraphics", kind = "framework")]- extern "C" {- fn CGRequestScreenCaptureAccess() -> bool;- }- unsafe { CGRequestScreenCaptureAccess() }-}--/// Real probe — Swift uses `SCShareableContent.excludingDesktopWindows`,-/// which is unavailable from Rust without large ScreenCaptureKit bindings.-/// `CGPreflightScreenCaptureAccess` returns false negatives for-/// subprocess-launched apps but is the closest stable C API. When that-/// returns false, fall back to the existing window-enumeration heuristic-/// (returns content only when Screen Recording is actually granted).-fn probe_screen_recording() -> bool {- #[link(name = "CoreGraphics", kind = "framework")]- extern "C" {- fn CGPreflightScreenCaptureAccess() -> bool;- }- if unsafe { CGPreflightScreenCaptureAccess() } { return true; }- let windows = crate::windows::all_windows();- !windows.is_empty()-}