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): let launch_app take the .app path that list_apps reports
injaneity8ae3222b5939
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdxindex 58f8942318..9a95e02b86 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/apps-windows-and-screen.mdx@@ -54,7 +54,7 @@ List macOS apps, both currently running and installed-but-not-running, with per-- running: is a process for this app live? (pid is 0 when false)- active: is it the system-frontmost app? (implies running)-- launch_path: filesystem path to the `.app` bundle, when known. Pass this to `launch_app` to start the app cold.+- launch_path: filesystem path to the `.app` bundle, when known. Pass this as `name` to `launch_app` to start the app cold.- kind: `"desktop"` for `.app` bundles on macOS.- last_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable.@@ -174,7 +174,7 @@ Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.Launch a macOS app in the background: the target does NOT come to the foreground.-Provide either `bundle_id` (preferred: unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. "Calculator"). If both are given, bundle_id wins.+Provide either `bundle_id` (preferred: unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. "Calculator", or the absolute `.app` path from `list_apps` `launch_path`). If both are given, bundle_id wins.Optional `urls` are handed to the app as open targets: for Finder, pass a folder path to open a backgrounded Finder window there.@@ -195,7 +195,7 @@ Returns the launched app's pid, bundle_id, name, and a `windows` array (same sha| <span id="launch_app--macos--additional_arguments"></span>`additional_arguments` | `string[]` | | Extra arguments appended after --args when launching. || <span id="launch_app--macos--bundle_id"></span>`bundle_id` | `string` | | App bundle identifier, e.g. com.apple.calculator. Preferred over name. || <span id="launch_app--macos--creates_new_application_instance"></span>`creates_new_application_instance` | `boolean` | | When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one: on single-instance apps (e.g. Calculator) every caller otherwise gets the same window and the sessions clobber each other. |-| <span id="launch_app--macos--name"></span>`name` | `string` | | App display name. Used only when bundle_id is absent. |+| <span id="launch_app--macos--name"></span>`name` | `string` | | App display name, or absolute path to a .app bundle (e.g. launch_path from list_apps). Used only when bundle_id is absent. || <span id="launch_app--macos--urls"></span>`urls` | `string[]` | | Optional file paths or URLs to open with the app (e.g. a folder path for Finder). || <span id="launch_app--macos--webkit_inspector_port"></span>`webkit_inspector_port` | `integer` | | Open a WebKit inspector server on this port (sets WEBKIT_INSPECTOR_SERVER env var). |diff --git a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rsindex cc46479c20..af80ee2ca9 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs@@ -645,6 +645,8 @@ pub(crate) fn resolve_bundle_id_to_locator(bundle_id: &str) -> Option<AppLocator/// Mirror of Swift's `AppLauncher.locate(name:)`.///+/// 0. an absolute path to an existing `.app` bundle (the `launch_path`+/// `list_apps` reports) is used as given;/// 1. filesystem lookup by bundle filename in the canonical roots/// (system first so /Applications wins over ~/Applications);/// 2. LaunchServices bundle-id lookup, in case the caller passed a@@ -655,6 +657,13 @@ pub(crate) fn resolve_bundle_id_to_locator(bundle_id: &str) -> Option<AppLocator/// integration tests; can be added if we hit a non-English-name app/// in the wild.pub(crate) fn locate_by_name(name: &str) -> Option<AppLocator> {+ let as_path = std::path::Path::new(name.trim_end_matches('/'));+ if as_path.is_absolute()+ && as_path.extension().is_some_and(|ext| ext == "app")+ && as_path.is_dir()+ {+ return Some(AppLocator::Path(as_path.to_string_lossy().into_owned()));+ }let app_name = if name.ends_with(".app") {name.to_owned()} else {@@ -1194,6 +1203,30 @@ mod tests {)}+ #[test]+ fn locate_by_name_accepts_absolute_app_bundle_path() {+ let dir = tempfile::tempdir().unwrap();+ let bundle = dir.path().join("Zz Path Only Fixture.app");+ std::fs::create_dir(&bundle).unwrap();+ let expected = bundle.to_string_lossy().into_owned();+ assert!(matches!(+ super::locate_by_name(&expected),+ Some(super::AppLocator::Path(p)) if p == expected+ ));+ // A trailing slash (as shells and Finder add) resolves to the same bundle.+ assert!(matches!(+ super::locate_by_name(&format!("{expected}/")),+ Some(super::AppLocator::Path(p)) if p == expected+ ));+ // A missing bundle is still "not installed".+ let missing = dir+ .path()+ .join("Missing.app")+ .to_string_lossy()+ .into_owned();+ assert!(super::locate_by_name(&missing).is_none());+ }+#[test]fn installed_app_running_as_accessory_reports_live_state() {// The #3060 shape: CuaDriver.app ships LSUIElement=true, so its livediff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rsindex dd879312fd..be0d3ea9a5 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs@@ -16,7 +16,8 @@ fn def() -> &'static ToolDef {description:"Launch a macOS app in the background — the target does NOT come to the foreground.\n\n\Provide either `bundle_id` (preferred — unambiguous, e.g. `com.apple.calculator`) \- or `name` (e.g. \"Calculator\"). If both are given, bundle_id wins.\n\n\+ or `name` (e.g. \"Calculator\", or the absolute `.app` path from `list_apps` \+ `launch_path`). If both are given, bundle_id wins.\n\n\Optional `urls` are handed to the app as open targets — for Finder, pass a folder \path to open a backgrounded Finder window there.\n\n\Browser DevTools setup belongs to `browser_prepare`, which can prove that a \@@ -49,7 +50,7 @@ fn def() -> &'static ToolDef {},"name": {"type": "string",- "description": "App display name. Used only when bundle_id is absent."+ "description": "App display name, or absolute path to a .app bundle (e.g. launch_path from list_apps). Used only when bundle_id is absent."},"urls": {"type": "array",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/list_apps.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/list_apps.rsindex 65cb5f6320..c56eed9740 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/list_apps.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/list_apps.rs@@ -17,7 +17,7 @@ fn def() -> &'static ToolDef {- running: is a process for this app live? (pid is 0 when false)\n\- active: is it the system-frontmost app? (implies running)\n\- launch_path: filesystem path to the `.app` bundle, when known. \- Pass this to `launch_app` to start the app cold.\n\+ Pass this as `name` to `launch_app` to start the app cold.\n\- kind: `\"desktop\"` for `.app` bundles on macOS.\n\- last_used: RFC3339 timestamp from the bundle's filesystem mtime, \when readable.\n\n\diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.jsonindex 23cadfc474..e918b6394f 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json@@ -1,7 +1,7 @@{"tools": [{- "description": "List macOS apps — both currently running and installed-but-not-running — with per-app state flags:\n\n- running: is a process for this app live? (pid is 0 when false)\n- active: is it the system-frontmost app? (implies running)\n- launch_path: filesystem path to the `.app` bundle, when known. Pass this to `launch_app` to start the app cold.\n- kind: `\"desktop\"` for `.app` bundles on macOS.\n- last_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable.\n\nOptional fields (bundle_id, launch_path, kind, last_used) are omitted when unknown, never null.\n\nStandalone running entries include only apps with NSApplicationActivationPolicyRegular — background helpers and system UI agents are filtered out. Installed apps resolve their running/pid state against all live processes by bundle identifier, so an installed app whose process runs as an accessory (LSUIElement / menu-bar apps, e.g. Cua Driver itself) still reports its live pid. Installed apps come from scanning /Applications, /Applications/Utilities, ~/Applications, /System/Applications, and /System/Applications/Utilities.\n\nUse this for \"is X installed?\" as well as \"is X running?\"; the list includes every installed app. To get an open app's pid and window_id, call list_windows({app: \"Name\"}) instead, which also gives per-window state (on-screen, on-current-Space, minimized, window titles). For just opening an app — running or not — call launch_app({bundle_id: ...}) directly; list_apps is not a prerequisite.",+ "description": "List macOS apps — both currently running and installed-but-not-running — with per-app state flags:\n\n- running: is a process for this app live? (pid is 0 when false)\n- active: is it the system-frontmost app? (implies running)\n- launch_path: filesystem path to the `.app` bundle, when known. Pass this as `name` to `launch_app` to start the app cold.\n- kind: `\"desktop\"` for `.app` bundles on macOS.\n- last_used: RFC3339 timestamp from the bundle's filesystem mtime, when readable.\n\nOptional fields (bundle_id, launch_path, kind, last_used) are omitted when unknown, never null.\n\nStandalone running entries include only apps with NSApplicationActivationPolicyRegular — background helpers and system UI agents are filtered out. Installed apps resolve their running/pid state against all live processes by bundle identifier, so an installed app whose process runs as an accessory (LSUIElement / menu-bar apps, e.g. Cua Driver itself) still reports its live pid. Installed apps come from scanning /Applications, /Applications/Utilities, ~/Applications, /System/Applications, and /System/Applications/Utilities.\n\nUse this for \"is X installed?\" as well as \"is X running?\"; the list includes every installed app. To get an open app's pid and window_id, call list_windows({app: \"Name\"}) instead, which also gives per-window state (on-screen, on-current-Space, minimized, window titles). For just opening an app — running or not — call launch_app({bundle_id: ...}) directly; list_apps is not a prerequisite.","destructive": false,"idempotent": true,"input_schema": {@@ -290,7 +290,7 @@"read_only": true},{- "description": "Launch a macOS app in the background — the target does NOT come to the foreground.\n\nProvide either `bundle_id` (preferred — unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. \"Calculator\"). If both are given, bundle_id wins.\n\nOptional `urls` are handed to the app as open targets — for Finder, pass a folder path to open a backgrounded Finder window there.\n\nBrowser DevTools setup belongs to `browser_prepare`, which can prove that a separate isolated profile is driver-owned before enabling CDP.\n\nOptional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.\n\nOptional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this when another agent or session may drive the SAME app concurrently — it returns a fresh pid + window so each session acts on its own isolated window instead of clobbering one shared instance. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions fight over it.\n\nOptional `additional_arguments`: extra argv strings appended after --args.\n\nReturns the launched app's pid, bundle_id, name, and a `windows` array (same shape as `list_windows`) so callers can skip an extra round-trip before `get_window_state(pid, window_id)`. `launch_state` distinguishes whether the request was sent, the process is running, and a window is ready. When the focus-steal belt-and-braces demotion check ran (target pid ≠ prior frontmost), the response also includes `self_activation_suppressed: bool` — true if focus stayed with the prior frontmost, false if the launched app held focus despite the re-demote attempt.",+ "description": "Launch a macOS app in the background — the target does NOT come to the foreground.\n\nProvide either `bundle_id` (preferred — unambiguous, e.g. `com.apple.calculator`) or `name` (e.g. \"Calculator\", or the absolute `.app` path from `list_apps` `launch_path`). If both are given, bundle_id wins.\n\nOptional `urls` are handed to the app as open targets — for Finder, pass a folder path to open a backgrounded Finder window there.\n\nBrowser DevTools setup belongs to `browser_prepare`, which can prove that a separate isolated profile is driver-owned before enabling CDP.\n\nOptional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.\n\nOptional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this when another agent or session may drive the SAME app concurrently — it returns a fresh pid + window so each session acts on its own isolated window instead of clobbering one shared instance. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions fight over it.\n\nOptional `additional_arguments`: extra argv strings appended after --args.\n\nReturns the launched app's pid, bundle_id, name, and a `windows` array (same shape as `list_windows`) so callers can skip an extra round-trip before `get_window_state(pid, window_id)`. `launch_state` distinguishes whether the request was sent, the process is running, and a window is ready. When the focus-steal belt-and-braces demotion check ran (target pid ≠ prior frontmost), the response also includes `self_activation_suppressed: bool` — true if focus stayed with the prior frontmost, false if the launched app held focus despite the re-demote attempt.","destructive": false,"idempotent": true,"input_schema": {@@ -312,7 +312,7 @@"type": "boolean"},"name": {- "description": "App display name. Used only when bundle_id is absent.",+ "description": "App display name, or absolute path to a .app bundle (e.g. launch_path from list_apps). Used only when bundle_id is absent.","type": "string"},"session": {