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): find a macOS app by any name it ships, without guessing (#6657)
injaneity22d8c1b9867f
diff --git a/libs/cua-driver/rust/Cargo.lock b/libs/cua-driver/rust/Cargo.lockindex c6dd17e17e..1060900240 100644--- a/libs/cua-driver/rust/Cargo.lock+++ b/libs/cua-driver/rust/Cargo.lock@@ -1274,6 +1274,7 @@ dependencies = ["getrandom 0.4.2","hkdf","hmac",+ "icu_normalizer","image","indexmap","jsonschema",diff --git a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.tomlindex cba09886d2..d8e2a5d9ee 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml+++ b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml@@ -48,6 +48,9 @@ base64 = { workspace = true }sha2 = "0.10"indexmap = "2"url = "2.5"+# Canonical (NFD) comparison of app names (`app_names`), as macOS stores+# file names decomposed; already in the graph through `url`'s IDNA support.+icu_normalizer = { version = "2", default-features = false, features = ["compiled_data"] }chacha20poly1305 = { workspace = true }hkdf = { workspace = true }zeroize = { workspace = true }diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/app_names.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/app_names.rsnew file mode 100644index 0000000000..f082635489--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/app_names.rs@@ -0,0 +1,349 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! Match an app name a caller gives against every name an installed app+//! ships, in any language, so "Échecs" finds Chess on any Mac.+//!+//! Platform adapters read the names (macOS: the bundle's file name,+//! `CFBundleDisplayName` / `CFBundleName` and their localizations); this+//! module only ranks them. Names compare without case but otherwise as+//! shipped: forgiving how a user spells a name (accents, spaces) is the+//! client's job. An exact name wins over a name the query starts, a name in+//! one of the user's languages wins over the same rank in another, and a tie+//! at the top is refused with suggestions instead of guessed.++use icu_normalizer::DecomposingNormalizerBorrowed;++/// How many names a refusal suggests.+pub const SUGGESTION_LIMIT: usize = 5;++/// One name an app ships.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct AppName {+ pub text: String,+ /// The localization the name comes from (`fr`, `pt_BR`); empty for the+ /// file name and the unlocalized metadata, which belong to no language.+ pub language: String,+}++impl AppName {+ pub fn new(text: impl Into<String>, language: impl Into<String>) -> Self {+ Self {+ text: text.into(),+ language: language.into(),+ }+ }+}++/// An installed app as the matcher sees it.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct NamedApp {+ /// The name shown when no localized name fits the user's languages.+ pub title: String,+ pub names: Vec<AppName>,+ /// The bundle id; copies of one app tie to the first copy, not to a+ /// refusal.+ pub id: Option<String>,+}++/// Why a name did not resolve to exactly one app.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct NameMiss {+ /// Several apps match the name equally well.+ pub ambiguous: bool,+ /// The closest app names, best first, at most [`SUGGESTION_LIMIT`].+ pub suggestions: Vec<String>,+}++#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]+enum Rank {+ NoMatch,+ Contains,+ Prefix,+ PrefixPreferred,+ Exact,+ ExactPreferred,+}++/// The text as names are compared: trimmed, without case, and canonically+/// decomposed, so a name stored decomposed (as macOS file names are) meets the+/// same name typed composed. Accents and spaces stay: "Échecs" meets "ÉCHECS",+/// not "echecs".+///+/// Case in Turkish pairs `ı` with `I` and `i` with `İ`, which the default+/// mapping can't undo from upper case ("AYARLARI" is "Ayarları"), so the four+/// forms of i count as one letter.+pub fn fold(text: &str) -> String {+ DecomposingNormalizerBorrowed::new_nfd()+ .normalize(&text.trim().to_lowercase())+ .replace("i\u{307}", "i")+ .replace('ı', "i")+}++/// Whether a localization (`fr`, `pt_BR`, `zh_CN`) is one of the user's+/// preferred languages (`fr-FR`, `pt-BR`, `zh-Hans-CN`). A region-tagged+/// localization also matches a tag that puts a script between language and+/// region.+pub fn preferred(language: &str, languages: &[String]) -> bool {+ let code = language.replace('_', "-").to_lowercase();+ if code.is_empty() {+ return false;+ }+ let (tongue, region) = code.split_once('-').unwrap_or((&code, ""));+ languages.iter().any(|wanted| {+ let wanted = wanted.replace('_', "-").to_lowercase();+ if wanted == code || wanted.starts_with(&format!("{code}-")) {+ return true;+ }+ let parts: Vec<&str> = wanted.split('-').collect();+ !region.is_empty()+ && !region.contains('-')+ && parts[0] == tongue+ && parts[1..].contains(®ion)+ })+}++fn rank(query: &str, app: &NamedApp, languages: &[String]) -> Rank {+ app.names+ .iter()+ .map(|name| {+ let folded = fold(&name.text);+ let liked = preferred(&name.language, languages);+ if folded == query {+ if liked {+ Rank::ExactPreferred+ } else {+ Rank::Exact+ }+ } else if folded.starts_with(query) {+ if liked {+ Rank::PrefixPreferred+ } else {+ Rank::Prefix+ }+ } else if folded.contains(query) {+ Rank::Contains+ } else {+ Rank::NoMatch+ }+ })+ .max()+ .unwrap_or(Rank::NoMatch)+}++/// The app's name in the first of the user's languages it has one for,+/// else its title.+fn display_name<'a>(app: &'a NamedApp, languages: &[String]) -> &'a str {+ languages+ .iter()+ .find_map(|language| {+ app.names+ .iter()+ .find(|name| preferred(&name.language, std::slice::from_ref(language)))+ })+ .map_or(app.title.as_str(), |name| name.text.as_str())+}++/// The index of the one app `query` names, by an exact name or the start of+/// one, or why there is none.+pub fn lookup(query: &str, apps: &[NamedApp], languages: &[String]) -> Result<usize, NameMiss> {+ let query = fold(query);+ if query.is_empty() {+ return Err(NameMiss {+ ambiguous: false,+ suggestions: Vec::new(),+ });+ }+ let mut ranked: Vec<(Rank, usize)> = apps+ .iter()+ .enumerate()+ .map(|(index, app)| (rank(&query, app, languages), index))+ .filter(|(rank, _)| *rank != Rank::NoMatch)+ .collect();+ // Stable, so equal ranks keep the adapter's (root) order.+ ranked.sort_by_key(|(rank, _)| std::cmp::Reverse(*rank));++ let shown: Vec<&str> = ranked+ .iter()+ .map(|(_, index)| display_name(&apps[*index], languages))+ .collect();+ let mut suggestions: Vec<String> = Vec::new();+ for (name, (_, index)) in shown.iter().zip(&ranked) {+ // Two apps shown under one name are told apart by their titles.+ let shared = shown.iter().filter(|other| *other == name).count() > 1;+ let name = if shared {+ apps[*index].title.as_str()+ } else {+ name+ };+ if !suggestions.iter().any(|known| known == name) {+ suggestions.push(name.to_owned());+ }+ }+ suggestions.truncate(SUGGESTION_LIMIT);++ let top = ranked.first().map_or(Rank::NoMatch, |(rank, _)| *rank);+ let mut best: Vec<usize> = Vec::new();+ for (_, index) in ranked.iter().take_while(|(rank, _)| *rank == top) {+ let id = &apps[*index].id;+ if id.is_none() || !best.iter().any(|known| apps[*known].id == *id) {+ best.push(*index);+ }+ }+ match best.as_slice() {+ [one] if top >= Rank::Prefix => Ok(*one),+ _ => Err(NameMiss {+ ambiguous: top >= Rank::Prefix,+ suggestions,+ }),+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ fn app(title: &str, names: &[(&str, &str)]) -> NamedApp {+ NamedApp {+ title: title.to_owned(),+ names: names+ .iter()+ .map(|(text, language)| AppName::new(*text, *language))+ .collect(),+ id: None,+ }+ }++ fn langs(tags: &[&str]) -> Vec<String> {+ tags.iter().map(|tag| (*tag).to_owned()).collect()+ }++ #[test]+ fn fold_drops_case_and_encoding_but_keeps_accents_and_spaces() {+ assert_eq!(fold(" Échecs "), fold("échecs"));+ // The same name, stored decomposed as macOS file names are.+ assert_eq!(fold("E\u{301}checs"), fold("Échecs"));+ assert_ne!(fold("Échecs"), fold("echecs"));+ assert_ne!(fold("Bambu Studio"), fold("BambuStudio"));+ }++ /// Names macOS ships in Turkish, in upper and lower case.+ #[test]+ fn turkish_dotted_and_dotless_i_are_one_letter_without_case() {+ assert_eq!(fold("Sistem Ayarları"), fold("SISTEM AYARLARI"));+ assert_eq!(fold("İpuçları"), fold("ipuçları"));+ assert_eq!(fold("İpuçları"), fold("İPUÇLARI"));+ assert_ne!(fold("Ayarları"), fold("Ayarlar"));+ }++ #[test]+ fn a_localized_name_finds_the_app_in_any_case() {+ let apps = [+ app("Calculator", &[("Calculator", "")]),+ app(+ "Chess",+ &[("Chess", ""), ("Échecs", "fr"), ("Schach", "de")],+ ),+ ];+ assert_eq!(lookup("Échecs", &apps, &langs(&["en-US"])), Ok(1));+ assert_eq!(lookup("ÉCHECS", &apps, &langs(&["fr-FR"])), Ok(1));+ assert_eq!(lookup("schach", &apps, &[]), Ok(1));+ // A spelling the app does not ship is the client's to forgive.+ assert!(!lookup("echec", &apps, &[]).unwrap_err().ambiguous);+ }++ #[test]+ fn an_exact_name_wins_over_a_longer_one_it_starts() {+ let apps = [+ app("Notes Plus", &[("Notes Plus", "")]),+ app("Notes", &[("Notes", "")]),+ ];+ assert_eq!(lookup("notes", &apps, &[]), Ok(1));+ }++ #[test]+ fn the_users_language_breaks_an_exact_tie() {+ let apps = [+ app("Mail", &[("Mail", ""), ("Post", "de")]),+ app("Post", &[("Post", "")]),+ ];+ assert_eq!(lookup("post", &apps, &langs(&["de-DE"])), Ok(0));+ let refused = lookup("post", &apps, &langs(&["en-US"])).unwrap_err();+ assert!(refused.ambiguous);+ }++ #[test]+ fn a_tie_is_refused_with_both_names_never_guessed() {+ let apps = [+ app("Adobe InDesign 2025", &[("Adobe InDesign 2025", "")]),+ app("Adobe InDesign 2026", &[("Adobe InDesign 2026", "")]),+ ];+ assert_eq!(+ lookup("adobe indesign", &apps, &[]),+ Err(NameMiss {+ ambiguous: true,+ suggestions: vec![+ "Adobe InDesign 2025".to_owned(),+ "Adobe InDesign 2026".to_owned()+ ],+ })+ );+ assert_eq!(lookup("Adobe InDesign 2026", &apps, &[]), Ok(1));+ }++ #[test]+ fn copies_of_one_app_tie_to_the_first_copy() {+ let copy = |names: &[(&str, &str)]| NamedApp {+ id: Some("com.example.notes".to_owned()),+ ..app("Notes", names)+ };+ let apps = [+ copy(&[("Notes", "")]),+ copy(&[("Notes", ""), ("Notes Beta", "")]),+ ];+ assert_eq!(lookup("notes", &apps, &[]), Ok(0));+ // A name only the second copy ships launches that copy.+ assert_eq!(lookup("notes beta", &apps, &[]), Ok(1));+ }++ #[test]+ fn a_name_found_only_inside_another_is_a_suggestion_not_a_match() {+ let apps = [app("Keynote", &[("Keynote", "")])];+ assert_eq!(+ lookup("note", &apps, &[]),+ Err(NameMiss {+ ambiguous: false,+ suggestions: vec!["Keynote".to_owned()],+ })+ );+ assert_eq!(+ lookup("zzz", &apps, &[]),+ Err(NameMiss {+ ambiguous: false,+ suggestions: Vec::new(),+ })+ );+ }++ #[test]+ fn suggestions_use_the_users_language_and_titles_for_shared_names() {+ let apps = [+ app("Chess", &[("Chess", ""), ("Échecs", "fr")]),+ app("Chess Pro", &[("Chess Pro", ""), ("Échecs", "fr")]),+ ];+ let refused = lookup("ess", &apps, &langs(&["fr-FR"])).unwrap_err();+ assert_eq!(refused.suggestions, ["Chess", "Chess Pro"]);+ let apps = [app("Chess", &[("Chess", ""), ("Échecs", "fr")])];+ let refused = lookup("ess", &apps, &langs(&["fr-FR"])).unwrap_err();+ assert_eq!(refused.suggestions, ["Échecs"]);+ }++ #[test]+ fn preferred_matches_folders_against_language_tags() {+ assert!(preferred("fr", &langs(&["fr-FR"])));+ assert!(preferred("pt_BR", &langs(&["pt-BR"])));+ assert!(preferred("zh_CN", &langs(&["zh-Hans-CN"])));+ assert!(!preferred("pt_PT", &langs(&["pt-BR"])));+ assert!(!preferred("", &langs(&["en"])));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rsindex 7a23ef2c79..3e4db3833d 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/lib.rs@@ -60,6 +60,7 @@ pub fn parent_liveness_stdin_enabled() -> bool {pub mod action_record;pub mod action_target;pub mod agent_cursor;+pub mod app_names;pub mod authorization;pub mod background_input;pub mod batch_nudge;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 cc1d355581..9371f5de94 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@@ -3,6 +3,7 @@//! macOS app enumeration via NSWorkspace and NSRunningApplication.+mod names;pub mod nsworkspace;use anyhow::Context;@@ -15,6 +16,7 @@ use core_foundation::{propertylist::{create_with_data, kCFPropertyListImmutable},string::CFString,};+use cua_driver_core::app_names::NameMiss;use serde::{Deserialize, Serialize};use std::{ffi::c_void,@@ -394,22 +396,16 @@ pub fn launch_app(bundle_id: &str) -> anyhow::Result<i32> {Ok(pid)}-/// Launch an app by display name via NSWorkspace. Background-only.+/// Launch the app a name resolved to via NSWorkspace. Background-only./// Returns the pid on success.-///-/// Mirror of Swift `AppLauncher.locate(name:)`: scan the standard-/// roots for `<Name>.app`, then fall back to a LaunchServices lookup-/// in case the caller passed a bundle identifier in the `name` slot.-pub fn launch_app_by_name(name: &str) -> anyhow::Result<i32> {- let located = locate_by_name(name)- .ok_or_else(|| anyhow::anyhow!("Could not locate app with name '{name}'"))?;+pub(crate) fn launch_located(located: AppLocator) -> anyhow::Result<i32> {let (app_ref, bid) = located.app_ref_and_bundle_id();let cfg = nsworkspace::OpenConfig {apple_event_bundle_id: bid,..Default::default()};let running = nsworkspace::open_application(&app_ref, &cfg)- .with_context(|| format!("Failed to launch '{name}'"))?;+ .with_context(|| format!("Failed to launch '{app_ref}'"))?;let pid: i32 = unsafe { running.processIdentifier() };Ok(pid)}@@ -463,18 +459,15 @@ pub fn launch_with_urls_by_bundle(Ok(pid)}-/// Launch by name with URL handoff. Same contract as-/// `launch_with_urls_by_bundle` but resolves the bundle URL by display-/// name first.-pub fn launch_with_urls_by_name(- name: &str,+/// Launch the app a name resolved to, with URL handoff. Same contract as+/// `launch_with_urls_by_bundle`.+pub(crate) fn launch_with_urls_located(+ located: AppLocator,urls: &[String],additional_args: &[String],env: &std::collections::HashMap<String, String>,creates_new_instance: bool,) -> anyhow::Result<i32> {- let located = locate_by_name(name)- .ok_or_else(|| anyhow::anyhow!("Could not locate app with name '{name}'"))?;let (app_ref, bid) = located.app_ref_and_bundle_id();if additional_args.is_empty()&& env.is_empty()@@ -498,7 +491,7 @@ pub fn launch_with_urls_by_name(} else {nsworkspace::open_urls_with_application(urls, &app_ref, &cfg)}- .with_context(|| format!("Failed to launch '{name}'"))?;+ .with_context(|| format!("Failed to launch '{app_ref}'"))?;let pid: i32 = unsafe { running.processIdentifier() };Ok(pid)}@@ -611,12 +604,16 @@ impl AppLocator {/// when it couldn't be determined — callers use it for the `oapp`/// AppleEvent attachment on the no-URL launch path.pub(crate) fn app_ref_and_bundle_id(self) -> (String, Option<String>) {+ let bid = self.bundle_id();match self {- AppLocator::Path(p) => {- let bid = bundle_id_for_app_path(&p);- (p, bid)- }- AppLocator::BundleId(bid) => (bid.clone(), Some(bid)),+ AppLocator::Path(p) | AppLocator::BundleId(p) => (p, bid),+ }+ }++ pub(crate) fn bundle_id(&self) -> Option<String> {+ match self {+ AppLocator::Path(p) => bundle_id_for_app_path(p),+ AppLocator::BundleId(bid) => Some(bid.clone()),}}}@@ -644,54 +641,71 @@ pub(crate) fn resolve_bundle_id_to_locator(bundle_id: &str) -> Option<AppLocator}}-/// Mirror of Swift's `AppLauncher.locate(name:)`.+/// The folders installed apps live in, system first so /Applications wins+/// over ~/Applications, then Finder: the rest of CoreServices is agents and+/// helpers no one launches by name.+fn app_roots() -> Vec<std::path::PathBuf> {+ let home = std::path::PathBuf::from(std::env::var("HOME").unwrap_or_default());+ vec![+ "/Applications".into(),+ "/System/Applications".into(),+ "/System/Applications/Utilities".into(),+ "/Applications/Utilities".into(),+ home.join("Applications"),+ home.join("Applications/Chrome Apps.localized"),+ "/System/Library/CoreServices/Finder.app".into(),+ ]+}++/// What a `name` argument resolves to:////// 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-/// bundle identifier in the `name` slot — preserved as-/// `AppLocator::BundleId` so the launch path uses the live NSURL-/// (Cryptex-safe — see CodeRabbit #3);-/// 3. (skipped) full localized-name scan — not yet needed by current-/// 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> {+/// 1. a bundle identifier LaunchServices knows resolves as+/// `AppLocator::BundleId`, so the launch path uses the live NSURL+/// (Cryptex-safe, see CodeRabbit #3);+/// 2. every name the bundles in the roots, one folder down and Finder ship+/// (file name, `CFBundleDisplayName` / `CFBundleName` and their+/// localizations) is ranked, in any case, accents and spaces as shipped.+/// A name that fits several apps equally well is refused with+/// suggestions, not guessed.+pub(crate) fn locate_by_name(name: &str) -> Result<AppLocator, NameMiss> {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()));+ if as_path.is_absolute() {+ return (as_path.extension().is_some_and(|ext| ext == "app") && as_path.is_dir())+ .then(|| AppLocator::Path(as_path.to_string_lossy().into_owned()))+ .ok_or(NameMiss {+ ambiguous: false,+ suggestions: Vec::new(),+ });}- let app_name = if name.ends_with(".app") {- name.to_owned()- } else {- format!("{name}.app")- };- let home = std::env::var("HOME").unwrap_or_default();- let roots = [- "/Applications".to_owned(),- "/System/Applications".to_owned(),- "/System/Applications/Utilities".to_owned(),- "/Applications/Utilities".to_owned(),- format!("{home}/Applications"),- format!("{home}/Applications/Chrome Apps.localized"),- ];- for root in &roots {- let path = format!("{root}/{app_name}");- if std::path::Path::new(&path).is_dir() {- return Some(AppLocator::Path(path));- }+ locate_in(name, &app_roots(), resolve_bundle_id_to_locator)+}++fn locate_in(+ name: &str,+ roots: &[std::path::PathBuf],+ bundle_id: impl FnOnce(&str) -> Option<AppLocator>,+) -> Result<AppLocator, NameMiss> {+ if let Some(locator) = bundle_id(name) {+ return Ok(locator);}- if app_name.eq_ignore_ascii_case("Finder.app") {- return resolve_bundle_id_to_locator("com.apple.finder");+ names::find(name, roots, &names::preferred_languages())+ .map(|path| AppLocator::Path(path.to_string_lossy().into_owned()))+}++/// The refusal text for a name [`locate_by_name`] could not resolve.+pub(crate) fn name_miss_message(name: &str, miss: &NameMiss) -> String {+ let listed = miss.suggestions.join(", ");+ if miss.ambiguous {+ format!(+ "The name '{name}' matches several installed macOS apps: {listed}. Pass one of these names or a bundle_id."+ )+ } else if listed.is_empty() {+ format!("No installed macOS app found for name '{name}'.")+ } else {+ format!("No installed macOS app found for name '{name}'. Closest names: {listed}.")}- // Fallback: maybe caller passed a bundle id as `name`. Use the- // Cryptex-safe locator (carries the bundle id, never the lossy- // url.path()).- resolve_bundle_id_to_locator(name)}/// Read `CFBundleIdentifier` from an `.app` bundle's `Info.plist`.@@ -1213,12 +1227,12 @@ mod tests {let expected = bundle.to_string_lossy().into_owned();assert!(matches!(super::locate_by_name(&expected),- Some(super::AppLocator::Path(p)) if p == expected+ Ok(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+ Ok(super::AppLocator::Path(p)) if p == expected));// A missing bundle is still "not installed".let missing = dir@@ -1226,7 +1240,7 @@ mod tests {.join("Missing.app").to_string_lossy().into_owned();- assert!(super::locate_by_name(&missing).is_none());+ assert!(super::locate_by_name(&missing).is_err());}#[test]@@ -1330,6 +1344,47 @@ mod tests {assert_eq!(merged[1].pid, 42);}+ #[test]+ fn a_file_name_another_app_also_shows_is_refused_not_guessed() {+ let root = tempfile::tempdir().unwrap();+ for (file, id, display) in [+ ("Notes.app", "com.example.notes", ""),+ ("Jot.app", "com.example.jot", "Notes"),+ ] {+ let contents = root.path().join(file).join("Contents");+ std::fs::create_dir_all(&contents).unwrap();+ std::fs::write(+ contents.join("Info.plist"),+ format!(+ r#"<?xml version="1.0" encoding="UTF-8"?>+<plist version="1.0"><dict>+<key>CFBundleIdentifier</key><string>{id}</string>+<key>CFBundleDisplayName</key><string>{display}</string>+</dict></plist>"#+ ),+ )+ .unwrap();+ }+ let roots = [root.path().to_path_buf()];+ let miss = super::locate_in("Notes", &roots, |_| None).err().unwrap();+ assert!(miss.ambiguous);+ assert!(super::locate_in("Notes.app", &roots, |_| None).is_err());+ }++ #[test]+ fn a_known_bundle_id_wins_over_a_name_it_starts() {+ let root = tempfile::tempdir().unwrap();+ std::fs::create_dir_all(root.path().join("com.example.notes Helper.app")).unwrap();+ let roots = [root.path().to_path_buf()];+ let known = |id: &str| {+ (id == "com.example.notes").then(|| super::AppLocator::BundleId(id.to_owned()))+ };+ assert!(matches!(+ super::locate_in("com.example.notes", &roots, known),+ Ok(super::AppLocator::BundleId(id)) if id == "com.example.notes"+ ));+ }+#[test]fn finder_is_located_by_name_outside_the_app_roots() {let (_, bundle_id) = super::locate_by_name("Finder")diff --git a/libs/cua-driver/rust/crates/platform-macos/src/apps/names.rs b/libs/cua-driver/rust/crates/platform-macos/src/apps/names.rsnew file mode 100644index 0000000000..8673cc72f5--- /dev/null+++ b/libs/cua-driver/rust/crates/platform-macos/src/apps/names.rs@@ -0,0 +1,392 @@+// SPDX-License-Identifier: MIT+// Copyright (c) 2026 Cua AI, Inc.++//! Find an installed `.app` bundle by any name it ships.++use super::{plist_string, read_bundle_plist};+use core_foundation::{+ array::{CFArray, CFArrayRef},+ base::{CFType, TCFType},+ dictionary::CFDictionary,+ string::CFString,+};+use cua_driver_core::app_names::{self, AppName, NameMiss, NamedApp};+use std::path::{Path, PathBuf};++/// The metadata keys that hold a bundle's shown name, display name first.+const NAME_KEYS: [&str; 2] = ["CFBundleDisplayName", "CFBundleName"];++/// The language each pre-ISO `.lproj` folder name stands for.+const LEGACY_LANGUAGES: [(&str, &str); 19] = [+ ("English", "en"),+ ("French", "fr"),+ ("German", "de"),+ ("Japanese", "ja"),+ ("Spanish", "es"),+ ("Italian", "it"),+ ("Dutch", "nl"),+ ("Swedish", "sv"),+ ("Danish", "da"),+ ("Norwegian", "no"),+ ("Finnish", "fi"),+ ("Portuguese", "pt"),+ ("Korean", "ko"),+ ("Russian", "ru"),+ ("Polish", "pl"),+ ("Turkish", "tr"),+ ("Greek", "el"),+ ("Hebrew", "he"),+ ("Arabic", "ar"),+];++struct Bundle {+ path: PathBuf,+ app: NamedApp,+}++/// The bundle in `roots` that `query` names in any language it ships, by an+/// exact name or the start of one; several equally good bundles are refused.+pub(crate) fn find(+ query: &str,+ roots: &[PathBuf],+ languages: &[String],+) -> Result<PathBuf, NameMiss> {+ let bundles = scan(roots);+ let apps: Vec<NamedApp> = bundles.iter().map(|bundle| bundle.app.clone()).collect();+ let query = query.trim().trim_end_matches(".app");+ app_names::lookup(query, &apps, languages).map(|index| bundles[index].path.clone())+}++/// The Mac's languages, first choice first (`fr-FR`, `en-US`).+pub(crate) fn preferred_languages() -> Vec<String> {+ #[link(name = "CoreFoundation", kind = "framework")]+ extern "C" {+ fn CFLocaleCopyPreferredLanguages() -> CFArrayRef;+ }+ let raw = unsafe { CFLocaleCopyPreferredLanguages() };+ if raw.is_null() {+ return Vec::new();+ }+ let languages = unsafe { CFArray::<CFString>::wrap_under_create_rule(raw) };+ languages+ .iter()+ .map(|language| language.to_string())+ .collect()+}++/// The `.app` bundles inside each root and one folder down (Adobe's+/// `Adobe InDesign 2026/Adobe InDesign 2026.app`), in root order, each once+/// (`/Applications/Utilities` is a root and one folder down). A root that is+/// itself a bundle is that one bundle.+fn scan(roots: &[PathBuf]) -> Vec<Bundle> {+ let mut paths: Vec<PathBuf> = Vec::new();+ for root in roots {+ if is_app(root) {+ paths.extend(root.is_dir().then(|| root.clone()));+ continue;+ }+ let (apps, folders): (Vec<PathBuf>, Vec<PathBuf>) =+ sorted_dirs(root).into_iter().partition(|path| is_app(path));+ let nested = folders+ .iter()+ .flat_map(|folder| sorted_dirs(folder).into_iter().filter(|path| is_app(path)));+ paths.extend(apps.into_iter().chain(nested));+ }+ let mut seen = std::collections::HashSet::new();+ paths.retain(|path| seen.insert(path.clone()));+ paths.into_iter().map(load_bundle).collect()+}++fn is_app(path: &Path) -> bool {+ path.extension().is_some_and(|ext| ext == "app")+}++fn sorted_dirs(folder: &Path) -> Vec<PathBuf> {+ let Ok(entries) = std::fs::read_dir(folder) else {+ return Vec::new();+ };+ let mut dirs: Vec<PathBuf> = entries+ .flatten()+ .map(|entry| entry.path())+ .filter(|path| path.is_dir())+ .collect();+ dirs.sort();+ dirs+}++fn load_bundle(path: PathBuf) -> Bundle {+ let stem = path+ .file_stem()+ .map(|stem| stem.to_string_lossy().into_owned())+ .unwrap_or_default();+ let info = read_bundle_plist(&path.join("Contents/Info.plist"));+ let own = info+ .as_ref()+ .map(|info| named(info, ""))+ .unwrap_or_default();+ let title = own+ .first()+ .map_or_else(|| stem.clone(), |name| name.text.clone());+ let mut names = vec![AppName::new(stem, "")];+ names.extend(own);+ names.extend(localized_names(&path.join("Contents/Resources")));+ Bundle {+ path,+ app: NamedApp {+ title,+ names,+ id: info+ .as_ref()+ .and_then(|info| plist_string(info, "CFBundleIdentifier")),+ },+ }+}++/// Every language's shown names, from the loctable and the `.lproj` folders.+/// `Base` holds names for no one language, like the unlocalized metadata.+fn localized_names(resources: &Path) -> Vec<AppName> {+ let mut names = Vec::new();+ if let Some(table) = read_bundle_plist(&resources.join("InfoPlist.loctable")) {+ let (keys, values) = table.get_keys_and_values();+ for (key, value) in keys.into_iter().zip(values) {+ let key = unsafe { CFType::wrap_under_get_rule(key) };+ let value = unsafe { CFType::wrap_under_get_rule(value) };+ let (Some(language), Some(strings)) =+ (key.downcast::<CFString>(), value.downcast::<CFDictionary>())+ else {+ continue;+ };+ names.extend(named(&strings, &language_code(&language.to_string())));+ }+ }+ for folder in sorted_dirs(resources) {+ if folder.extension().is_none_or(|ext| ext != "lproj") {+ continue;+ }+ let stem = folder.file_stem().unwrap_or_default().to_string_lossy();+ if let Some(strings) = read_bundle_plist(&folder.join("InfoPlist.strings")) {+ names.extend(named(&strings, &language_code(&stem)));+ }+ }+ names+}++/// The language a loctable key or `.lproj` folder stands for: legacy names+/// mapped to their code, `Base` to none.+fn language_code(folder: &str) -> String {+ if folder == "Base" {+ return String::new();+ }+ LEGACY_LANGUAGES+ .iter()+ .find(|(legacy, _)| *legacy == folder)+ .map_or(folder, |(_, code)| *code)+ .to_owned()+}++fn named(strings: &CFDictionary, language: &str) -> Vec<AppName> {+ NAME_KEYS+ .iter()+ .filter_map(|key| plist_string(strings, key))+ .map(|text| AppName::new(text, language))+ .collect()+}++#[cfg(test)]+mod tests {+ use super::find;+ use cua_driver_core::app_names::NameMiss;+ use std::path::{Path, PathBuf};++ /// Write an `.app` bundle with `info` inside its Info.plist dict. Nothing+ /// runs: the lookup only reads files.+ fn bundle(at: &Path, bundle_id: &str, info: &str) -> PathBuf {+ let contents = at.join("Contents");+ std::fs::create_dir_all(contents.join("Resources")).unwrap();+ std::fs::write(+ contents.join("Info.plist"),+ format!(+ r#"<?xml version="1.0" encoding="UTF-8"?>+<plist version="1.0"><dict>+<key>CFBundleIdentifier</key><string>{bundle_id}</string>+{info}+</dict></plist>"#+ ),+ )+ .unwrap();+ at.to_path_buf()+ }++ fn langs(tags: &[&str]) -> Vec<String> {+ tags.iter().map(|tag| (*tag).to_owned()).collect()+ }++ #[test]+ fn an_app_one_folder_down_is_found_by_its_name() {+ let root = tempfile::tempdir().unwrap();+ let indesign = bundle(+ &root+ .path()+ .join("Adobe InDesign 2026/Adobe InDesign 2026.app"),+ "com.adobe.InDesign",+ "",+ );+ let roots = [root.path().to_path_buf()];+ assert_eq!(+ find("Adobe InDesign 2026", &roots, &[]),+ Ok(indesign.clone())+ );+ assert_eq!(+ find("indesign", &roots, &[]).unwrap_err().suggestions,+ ["Adobe InDesign 2026"]+ );+ assert_eq!(find("adobe indesign", &roots, &[]), Ok(indesign));+ }++ #[test]+ fn the_shown_name_finds_a_bundle_whose_file_name_differs() {+ let root = tempfile::tempdir().unwrap();+ let bambu = bundle(+ &root.path().join("BambuStudio.app"),+ "com.bambulab.bambu-studio",+ "<key>CFBundleName</key><string>BambuStudio</string>",+ );+ let viewer = bundle(+ &root.path().join("PV.app"),+ "com.example.viewer",+ "<key>CFBundleDisplayName</key><string>Photo Viewer</string>",+ );+ let roots = [root.path().to_path_buf()];+ assert_eq!(find("bambustudio", &roots, &[]), Ok(bambu));+ assert_eq!(find("photo viewer", &roots, &[]), Ok(viewer));+ }++ #[test]+ fn a_localized_name_from_a_loctable_or_strings_file_finds_the_app() {+ let root = tempfile::tempdir().unwrap();+ let chess = bundle(+ &root.path().join("Chess.app"),+ "com.apple.Chess",+ "<key>CFBundleName</key><string>Chess</string>",+ );+ std::fs::write(+ chess.join("Contents/Resources/InfoPlist.loctable"),+ r#"<?xml version="1.0" encoding="UTF-8"?>+<plist version="1.0"><dict>+<key>fr</key><dict><key>CFBundleDisplayName</key><string>Échecs</string></dict>+<key>LocProvenance</key><dict><key>fr</key><integer>1</integer></dict>+</dict></plist>"#,+ )+ .unwrap();+ let mail = bundle(&root.path().join("Mail.app"), "com.apple.mail", "");+ // A legacy folder name and an old-style UTF-16 strings file.+ let german = mail.join("Contents/Resources/German.lproj");+ std::fs::create_dir_all(&german).unwrap();+ let strings: Vec<u8> = "\u{FEFF}/* names */\n\"CFBundleDisplayName\" = \"Post\";\n"+ .encode_utf16()+ .flat_map(u16::to_le_bytes)+ .collect();+ std::fs::write(german.join("InfoPlist.strings"), strings).unwrap();+ let roots = [root.path().to_path_buf()];++ assert_eq!(+ find("échecs", &roots, &langs(&["en-US"])),+ Ok(chess.clone())+ );+ assert_eq!(find("Échecs", &roots, &langs(&["fr-FR"])), Ok(chess));+ assert_eq!(find("post", &roots, &langs(&["de-DE"])), Ok(mail));+ }++ #[test]+ fn two_apps_answering_to_a_name_are_refused_with_suggestions() {+ let root = tempfile::tempdir().unwrap();+ bundle(+ &root+ .path()+ .join("Adobe InDesign 2025/Adobe InDesign 2025.app"),+ "com.adobe.InDesign.2025",+ "",+ );+ bundle(+ &root+ .path()+ .join("Adobe InDesign 2026/Adobe InDesign 2026.app"),+ "com.adobe.InDesign",+ "",+ );+ let roots = [root.path().to_path_buf()];+ assert_eq!(+ find("Adobe InDesign", &roots, &[]),+ Err(NameMiss {+ ambiguous: true,+ suggestions: vec![+ "Adobe InDesign 2025".to_owned(),+ "Adobe InDesign 2026".to_owned()+ ],+ })+ );+ }++ #[test]+ fn copies_of_one_bundle_id_launch_the_copy_the_name_belongs_to() {+ let system = tempfile::tempdir().unwrap();+ let user = tempfile::tempdir().unwrap();+ let first = bundle(&system.path().join("Notes.app"), "com.apple.Notes", "");+ let copy = bundle(&user.path().join("Notes copy.app"), "com.apple.Notes", "");+ let roots = [system.path().to_path_buf(), user.path().to_path_buf()];+ assert_eq!(find("notes", &roots, &[]), Ok(first));+ assert_eq!(find("notes copy", &roots, &[]), Ok(copy));+ }++ #[test]+ fn a_bundle_under_two_overlapping_roots_is_one_app() {+ let root = tempfile::tempdir().unwrap();+ let tool = root.path().join("Utilities/Tool.app");+ std::fs::create_dir_all(&tool).unwrap();+ let roots = [root.path().to_path_buf(), root.path().join("Utilities")];+ assert_eq!(find("tool", &roots, &[]), Ok(tool));+ }++ #[test]+ fn a_base_localization_name_finds_the_app() {+ let root = tempfile::tempdir().unwrap();+ let app = bundle(&root.path().join("PV.app"), "com.example.viewer", "");+ std::fs::write(+ app.join("Contents/Resources/InfoPlist.loctable"),+ r#"<?xml version="1.0" encoding="UTF-8"?>+<plist version="1.0"><dict>+<key>Base</key><dict><key>CFBundleDisplayName</key><string>Photo Viewer</string></dict>+</dict></plist>"#,+ )+ .unwrap();+ let other = bundle(&root.path().join("Other.app"), "com.example.other", "");+ let base = other.join("Contents/Resources/Base.lproj");+ std::fs::create_dir_all(&base).unwrap();+ std::fs::write(+ base.join("InfoPlist.strings"),+ "\"CFBundleDisplayName\" = \"Other Viewer\";\n",+ )+ .unwrap();+ let roots = [root.path().to_path_buf()];+ assert_eq!(find("photo viewer", &roots, &langs(&["en-US"])), Ok(app));+ assert_eq!(find("other viewer", &roots, &langs(&["en-US"])), Ok(other));+ }++ #[test]+ fn a_root_that_is_a_bundle_is_scanned_as_that_bundle() {+ let root = tempfile::tempdir().unwrap();+ let finder = bundle(+ &root.path().join("CoreServices/Finder.app"),+ "com.apple.finder",+ "",+ );+ bundle(+ &root.path().join("CoreServices/Siri.app"),+ "com.apple.Siri",+ "",+ );+ let roots = [finder.clone()];+ assert_eq!(find("finder", &roots, &[]), Ok(finder));+ assert!(find("siri", &roots, &[]).is_err());+ }+}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.rsindex 32f887b107..e4a97b156e 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@@ -95,6 +95,7 @@ impl Tool for LaunchAppTool {crate::window_change_detector::note_intentional_activation();let bundle_id = args.opt_str("bundle_id");let name = args.opt_str("name");+ let mut located = None;let mut response_bundle_id = bundle_id.clone();let response_requested_name = name.clone();let urls: Vec<String> = args@@ -141,22 +142,19 @@ impl Tool for LaunchAppTool {serde_json::json!({ "bundle_id": bid }),);}- } else if let Some(ref n) = name {- let Some(locator) = crate::apps::locate_by_name(n) else {- return structured_launch_error(- "APP_NOT_INSTALLED",- format!("No installed macOS app found for name '{n}'."),- serde_json::json!({ "name": n }),- );+ } else if let Some(n) = name.as_deref() {+ let locator = match crate::apps::locate_by_name(n) {+ Ok(locator) => locator,+ Err(miss) => return name_miss_refusal(n, &miss),};- let (_, resolved_bundle_id) = locator.app_ref_and_bundle_id();- response_bundle_id = resolved_bundle_id.clone();- if resolved_bundle_id+ response_bundle_id = locator.bundle_id();+ if response_bundle_id.as_deref().is_some_and(is_cua_driver_bundle_id){return protected_host_launch_refusal();}+ located = Some(locator);}if let Some(err) = preflight_file_urls(&urls) {return err;@@ -250,16 +248,16 @@ impl Tool for LaunchAppTool {)?}} else {- let n = name.as_deref().unwrap();+ let located = located.expect("a name resolves before launch");if urls.is_empty()&& additional_arguments.is_empty()&& env.is_empty()&& !creates_new_instance{- crate::apps::launch_app_by_name(n)?+ crate::apps::launch_located(located)?} else {- crate::apps::launch_with_urls_by_name(- n,+ crate::apps::launch_with_urls_located(+ located,&urls,&additional_arguments,&env,@@ -538,6 +536,20 @@ fn rank_launch_windows(windows: &mut [crate::windows::WindowInfo]) {windows.sort_by_key(|window| std::cmp::Reverse(!window.title.trim().is_empty()));}+/// A name that resolves to no app is `APP_NOT_INSTALLED`, one that fits+/// several equally well `APP_NAME_AMBIGUOUS`; both carry the closest names.+fn name_miss_refusal(name: &str, miss: &cua_driver_core::app_names::NameMiss) -> ToolResult {+ structured_launch_error(+ if miss.ambiguous {+ "APP_NAME_AMBIGUOUS"+ } else {+ "APP_NOT_INSTALLED"+ },+ crate::apps::name_miss_message(name, miss),+ serde_json::json!({ "name": name, "suggestions": miss.suggestions }),+ )+}+fn structured_launch_error(code: &str, message: String, details: serde_json::Value) -> ToolResult {let mut payload = serde_json::json!({"error": code,@@ -720,13 +732,44 @@ fn hex_value(byte: u8) -> Option<u8> {#[cfg(test)]mod tests {use super::{- is_cua_driver_bundle_id, local_file_target, normalize_launch_url, preflight_file_urls,- rank_launch_windows, response_identity, structured_launch_failure, LaunchAppTool,+ is_cua_driver_bundle_id, local_file_target, name_miss_refusal, normalize_launch_url,+ preflight_file_urls, rank_launch_windows, response_identity, structured_launch_failure,+ LaunchAppTool,};+ use cua_driver_core::app_names::NameMiss;use cua_driver_core::tool::Tool;use serde_json::json;use std::path::PathBuf;+ #[test]+ fn a_name_two_apps_answer_to_is_refused_with_both() {+ let result = name_miss_refusal(+ "Adobe InDesign",+ &NameMiss {+ ambiguous: true,+ suggestions: vec!["Adobe InDesign 2025".into(), "Adobe InDesign 2026".into()],+ },+ );+ assert_eq!(result.is_error, Some(true));+ let structured = result.structured_content.expect("structured error");+ assert_eq!(structured["error"], "APP_NAME_AMBIGUOUS");+ assert_eq!(+ structured["suggestions"],+ json!(["Adobe InDesign 2025", "Adobe InDesign 2026"])+ );++ let result = name_miss_refusal(+ "note",+ &NameMiss {+ ambiguous: false,+ suggestions: vec!["Keynote".into()],+ },+ );+ let structured = result.structured_content.expect("structured error");+ assert_eq!(structured["error"], "APP_NOT_INSTALLED");+ assert_eq!(structured["suggestions"], json!(["Keynote"]));+ }+fn window(window_id: u32, title: &str, width: f64, height: f64) -> crate::windows::WindowInfo {crate::windows::WindowInfo {window_id,diff --git a/libs/cua-spacesd/Cargo.lock b/libs/cua-spacesd/Cargo.lockindex a9c92a2b2f..c66f8c1600 100644--- a/libs/cua-spacesd/Cargo.lock+++ b/libs/cua-spacesd/Cargo.lock@@ -1892,6 +1892,7 @@ dependencies = ["getrandom 0.4.3","hkdf 0.12.4","hmac 0.12.1",+ "icu_normalizer","image","indexmap","jsonschema",diff --git a/libs/cua-spacesd/tests/spaces-e2e/Cargo.lock b/libs/cua-spacesd/tests/spaces-e2e/Cargo.lockindex bf12fb836e..919f231cd5 100644--- a/libs/cua-spacesd/tests/spaces-e2e/Cargo.lock+++ b/libs/cua-spacesd/tests/spaces-e2e/Cargo.lock@@ -2331,6 +2331,7 @@ dependencies = ["getrandom 0.4.3","hkdf 0.12.4","hmac 0.12.1",+ "icu_normalizer","image","indexmap","jsonschema",diff --git a/libs/cua-spacesd/tests/teleport-e2e/Cargo.lock b/libs/cua-spacesd/tests/teleport-e2e/Cargo.lockindex f587a249fa..280bf9455e 100644--- a/libs/cua-spacesd/tests/teleport-e2e/Cargo.lock+++ b/libs/cua-spacesd/tests/teleport-e2e/Cargo.lock@@ -1426,6 +1426,7 @@ dependencies = ["getrandom 0.4.3","hkdf 0.12.4","hmac 0.12.1",+ "icu_normalizer","image","indexmap","jsonschema",