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): 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.mdx
index 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.rs
index 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 live
diff --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.rs
index 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.rs
index 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.json
index 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": {