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): bound Windows app-name lookup (#2858)

Francesco Bonacci2be7aab3de35
diff --git a/.github/workflows/ci-rust-windows.yml b/.github/workflows/ci-rust-windows.yml
index 7b56dce7ac..b75085f3bf 100644
--- a/.github/workflows/ci-rust-windows.yml
+++ b/.github/workflows/ci-rust-windows.yml
@@ -77,6 +77,12 @@ jobs:
- name: Run Windows installed-app discovery unit tests
working-directory: libs/cua-driver/rust
run: "cargo test -p platform-windows win32::installed_apps::tests:: --lib --locked"
+ - name: Run Windows app-name lookup deadline tests
+ working-directory: libs/cua-driver/rust
+ run: "cargo test -p platform-windows launch_uwp::tests::apps_folder_lookup_timeout_is_single_flight_and_recovers_after_cooldown --lib --locked -- --exact"
+ - name: Prove unknown app launch stays bounded and responsive
+ working-directory: libs/cua-driver/rust
+ run: "cargo test -p cua-driver --test protocol_tools_call_test launch_unknown_app_is_bounded_and_keeps_mcp_session_responsive --locked -- --exact --nocapture"
- name: Run transport-independent authorization and SDK tests
working-directory: libs/cua-driver/rust
run: |
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_tools_call_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_tools_call_test.rs
index 86f7f0c8f6..d10a8ca023 100644
--- a/libs/cua-driver/rust/crates/cua-driver/tests/protocol_tools_call_test.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/protocol_tools_call_test.rs
@@ -12,6 +12,8 @@
#![cfg(any(target_os = "macos", target_os = "windows"))]
use cua_driver_testkit::RawDriver;
+#[cfg(target_os = "windows")]
+use cua_driver_testkit::{Driver, McpDriver};
fn spawn_unrestricted() -> Option<RawDriver> {
RawDriver::spawn_with_env(&[
@@ -73,6 +75,57 @@ fn tools_call_list_apps() {
}
}
+#[test]
+#[cfg(target_os = "windows")]
+fn launch_unknown_app_is_bounded_and_keeps_mcp_session_responsive() {
+ let Some(mut driver) = McpDriver::spawn_with_env(&[
+ ("CUA_DRIVER_PERMISSION_MODE", "unrestricted"),
+ ("CUA_DRIVER_DANGEROUSLY_BYPASS_APPROVALS", "1"),
+ ]) else {
+ return;
+ };
+ let missing_name = format!("CuaMissingAppIssue2856_{}.exe", std::process::id());
+
+ let launch_started = std::time::Instant::now();
+ let launch = driver.call("launch_app", serde_json::json!({ "name": missing_name }));
+ let launch_elapsed = launch_started.elapsed();
+ assert!(
+ launch_elapsed < std::time::Duration::from_secs(10),
+ "unknown-app launch exceeded its hard response budget: {launch_elapsed:?}; response={:?}",
+ launch.raw
+ );
+ assert!(
+ launch.is_error(),
+ "unknown app should fail: {:?}",
+ launch.raw
+ );
+ let error = launch.text().to_ascii_lowercase();
+ assert!(
+ error.contains("not found") || error.contains("lookup") && error.contains("unavailable"),
+ "expected an explicit not-found or lookup-unavailable error, got: {}",
+ launch.text()
+ );
+
+ let follow_up_started = std::time::Instant::now();
+ let windows = driver.call("list_windows", serde_json::json!({}));
+ let follow_up_elapsed = follow_up_started.elapsed();
+ assert!(
+ follow_up_elapsed < std::time::Duration::from_secs(5),
+ "follow-up list_windows call was not responsive: {follow_up_elapsed:?}; response={:?}",
+ windows.raw
+ );
+ assert!(
+ !windows.is_error(),
+ "follow-up list_windows failed after unknown launch: {:?}",
+ windows.raw
+ );
+ assert!(
+ windows.structured()["windows"].is_array(),
+ "follow-up list_windows returned no windows array: {:?}",
+ windows.raw
+ );
+}
+
#[test]
#[cfg(any(target_os = "macos", target_os = "windows"))]
fn get_config_and_check_permissions() {
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/launch_uwp.rs b/libs/cua-driver/rust/crates/platform-windows/src/launch_uwp.rs
index 53f8d65a6e..1564f12baf 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/launch_uwp.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/launch_uwp.rs
@@ -33,7 +33,9 @@
//! the module is `#[cfg(target_os = "windows")]`-gated at the crate
//! root.
-use std::sync::{OnceLock, RwLock};
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, OnceLock, RwLock};
+use std::time::{Duration, Instant};
use windows::core::{Interface, GUID, HSTRING, PCWSTR, PWSTR};
use windows::Win32::Foundation::HWND;
@@ -236,10 +238,152 @@ struct AppsFolderEntry {
/// `bundle_id` always works regardless of cache state.
static APPS_FOLDER_CACHE: OnceLock<RwLock<Option<Vec<AppsFolderEntry>>>> = OnceLock::new();
+const APPS_FOLDER_LOOKUP_TIMEOUT: Duration = Duration::from_secs(4);
+const APPS_FOLDER_LOOKUP_RECOVERY_COOLDOWN: Duration = Duration::from_secs(30);
+
+/// Why a display-name lookup could not produce a definitive answer.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum AppsFolderLookupError {
+ Timeout,
+ Busy,
+ Unavailable,
+}
+
+/// Process-wide bound for the uncancellable `shell:AppsFolder` COM walk.
+///
+/// A timed-out blocking task keeps this gate until the COM call actually
+/// returns. Retries therefore fail fast instead of accumulating abandoned
+/// Tokio blocking workers. Once a late worker returns, a short cooldown keeps
+/// a hot retry loop from immediately entering the same unhealthy shell broker.
+struct AppsFolderLookupSingleFlight {
+ in_flight: AtomicBool,
+ cooldown_until_ms: AtomicU64,
+ cooldown_ms: u64,
+}
+
+impl AppsFolderLookupSingleFlight {
+ const fn new(cooldown_ms: u64) -> Self {
+ Self {
+ in_flight: AtomicBool::new(false),
+ cooldown_until_ms: AtomicU64::new(0),
+ cooldown_ms,
+ }
+ }
+
+ async fn run<T, F>(
+ self: &Arc<Self>,
+ timeout: Duration,
+ work: F,
+ ) -> Result<T, AppsFolderLookupError>
+ where
+ T: Send + 'static,
+ F: FnOnce() -> T + Send + 'static,
+ {
+ let now = apps_folder_lookup_now_ms();
+ if now < self.cooldown_until_ms.load(Ordering::Acquire)
+ || self
+ .in_flight
+ .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)
+ .is_err()
+ {
+ return Err(AppsFolderLookupError::Busy);
+ }
+
+ let timed_out = Arc::new(AtomicBool::new(false));
+ let worker_timed_out = Arc::clone(&timed_out);
+ let worker_gate = Arc::clone(self);
+ let worker = tokio::task::spawn_blocking(move || {
+ let _guard = AppsFolderLookupInFlightGuard {
+ gate: worker_gate,
+ timed_out: worker_timed_out,
+ };
+ work()
+ });
+
+ match tokio::time::timeout(timeout, worker).await {
+ Ok(Ok(result)) => Ok(result),
+ Ok(Err(error)) => {
+ tracing::warn!(
+ target: "launch_uwp",
+ "shell:AppsFolder lookup worker failed: {error}"
+ );
+ Err(AppsFolderLookupError::Unavailable)
+ }
+ Err(_) => {
+ timed_out.store(true, Ordering::Release);
+ // Also arm the cooldown on the caller side. The worker can
+ // return between the deadline firing and observing
+ // `timed_out`; recording it here closes that race.
+ self.cooldown_until_ms.store(
+ apps_folder_lookup_now_ms().saturating_add(self.cooldown_ms),
+ Ordering::Release,
+ );
+ Err(AppsFolderLookupError::Timeout)
+ }
+ }
+ }
+}
+
+struct AppsFolderLookupInFlightGuard {
+ gate: Arc<AppsFolderLookupSingleFlight>,
+ timed_out: Arc<AtomicBool>,
+}
+
+impl Drop for AppsFolderLookupInFlightGuard {
+ fn drop(&mut self) {
+ if self.timed_out.load(Ordering::Acquire) {
+ self.gate.cooldown_until_ms.store(
+ apps_folder_lookup_now_ms().saturating_add(self.gate.cooldown_ms),
+ Ordering::Release,
+ );
+ }
+ self.gate.in_flight.store(false, Ordering::Release);
+ }
+}
+
+fn apps_folder_lookup_gate() -> &'static Arc<AppsFolderLookupSingleFlight> {
+ static GATE: OnceLock<Arc<AppsFolderLookupSingleFlight>> = OnceLock::new();
+ GATE.get_or_init(|| {
+ Arc::new(AppsFolderLookupSingleFlight::new(
+ APPS_FOLDER_LOOKUP_RECOVERY_COOLDOWN.as_millis() as u64,
+ ))
+ })
+}
+
+fn apps_folder_lookup_now_ms() -> u64 {
+ static START: OnceLock<Instant> = OnceLock::new();
+ START.get_or_init(Instant::now).elapsed().as_millis() as u64
+}
+
fn cache() -> &'static RwLock<Option<Vec<AppsFolderEntry>>> {
APPS_FOLDER_CACHE.get_or_init(|| RwLock::new(None))
}
+/// Resolve a display name without allowing an unhealthy shell broker to wedge
+/// the async tool stream.
+pub async fn resolve_aumid_by_name_bounded(
+ display_name: String,
+) -> Result<Option<String>, AppsFolderLookupError> {
+ let result = apps_folder_lookup_gate()
+ .run(APPS_FOLDER_LOOKUP_TIMEOUT, move || {
+ resolve_aumid_by_name(&display_name)
+ })
+ .await;
+ match result {
+ Err(AppsFolderLookupError::Timeout) => tracing::warn!(
+ target: "launch_uwp",
+ "shell:AppsFolder name lookup exceeded {}ms; keeping its worker single-flight until COM returns",
+ APPS_FOLDER_LOOKUP_TIMEOUT.as_millis()
+ ),
+ Err(AppsFolderLookupError::Busy) => tracing::debug!(
+ target: "launch_uwp",
+ "shell:AppsFolder name lookup skipped while a prior lookup is running or cooling down"
+ ),
+ Err(AppsFolderLookupError::Unavailable) | Ok(_) => {}
+ }
+ result
+}
+
/// Resolve a packaged-app display name to its AUMID.
///
/// Lookup order, all case-insensitive against the display name shown
@@ -411,6 +555,57 @@ fn pwstr_to_string_and_free(p: PWSTR) -> String {
mod tests {
use super::*;
+ #[tokio::test]
+ async fn apps_folder_lookup_timeout_is_single_flight_and_recovers_after_cooldown() {
+ let gate = Arc::new(AppsFolderLookupSingleFlight::new(20));
+ let (release_tx, release_rx) = std::sync::mpsc::channel();
+ let work_started = Arc::new(AtomicBool::new(false));
+ let worker_started = Arc::clone(&work_started);
+
+ let started = Instant::now();
+ let first = gate
+ .run(Duration::from_millis(100), move || {
+ worker_started.store(true, Ordering::Release);
+ release_rx.recv().expect("release timed-out lookup worker");
+ 1_u8
+ })
+ .await;
+ assert_eq!(first, Err(AppsFolderLookupError::Timeout));
+ assert!(started.elapsed() < Duration::from_secs(1));
+ assert!(work_started.load(Ordering::Acquire));
+
+ let retry_count = Arc::new(AtomicU64::new(0));
+ for _ in 0..100 {
+ let retry_count = Arc::clone(&retry_count);
+ let retry = gate
+ .run(Duration::from_millis(10), move || {
+ retry_count.fetch_add(1, Ordering::AcqRel);
+ })
+ .await;
+ assert_eq!(retry, Err(AppsFolderLookupError::Busy));
+ }
+ assert_eq!(retry_count.load(Ordering::Acquire), 0);
+
+ release_tx.send(()).expect("release first lookup");
+ let worker_deadline = Instant::now() + Duration::from_secs(1);
+ while gate.in_flight.load(Ordering::Acquire) && Instant::now() < worker_deadline {
+ tokio::time::sleep(Duration::from_millis(2)).await;
+ }
+ assert!(!gate.in_flight.load(Ordering::Acquire));
+
+ assert_eq!(
+ gate.run(Duration::from_millis(10), || 2_u8).await,
+ Err(AppsFolderLookupError::Busy),
+ "late worker completion must leave a recovery cooldown"
+ );
+ tokio::time::sleep(Duration::from_millis(100)).await;
+ assert_eq!(
+ gate.run(Duration::from_millis(100), || 3_u8).await,
+ Ok(3),
+ "lookup should recover after the cooldown"
+ );
+ }
+
#[test]
fn is_aumid_recognises_canonical_form() {
assert!(is_aumid("Microsoft.WindowsNotepad_8wekyb3d8bbwe!App"));
diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
index 55baef2d1e..152aeb9782 100644
--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs
@@ -2022,6 +2022,7 @@ impl Tool for LaunchAppTool {
// `path` is intentionally excluded from packaged routing — when
// the caller has a concrete executable in mind they want
// CreateProcess semantics, not Start Menu activation.
+ let mut name_lookup_missed = false;
let aumid_for_uwp: Option<String> = if launch_path_opt.is_some() || path_opt.is_some() {
None
} else if let Some(a) = aumid_opt.clone() {
@@ -2032,12 +2033,31 @@ impl Tool for LaunchAppTool {
{
Some(b)
} else if let Some(n) = name_opt.clone() {
- // Run the (cached) AppsFolder lookup on a blocking thread to
- // avoid stalling the async runtime on the cold-enumeration
- // path (~200 ms first call, ~µs after).
- tokio::task::spawn_blocking(move || crate::launch_uwp::resolve_aumid_by_name(&n))
- .await
- .unwrap_or(None)
+ // The cold AppsFolder COM walk can stop making progress when its
+ // interactive shell broker is unhealthy. Bound it before the
+ // separate ShellExecuteEx deadline below; the resolver keeps a
+ // timed-out worker single-flight until COM really returns.
+ match crate::launch_uwp::resolve_aumid_by_name_bounded(n.clone()).await {
+ Ok(resolved) => {
+ name_lookup_missed = resolved.is_none();
+ resolved
+ }
+ Err(crate::launch_uwp::AppsFolderLookupError::Timeout) => {
+ return ToolResult::error(format!(
+ "App name lookup for {n:?} is temporarily unavailable: Windows did not respond to the shell:AppsFolder query within 4s. No app was launched; retry after the shell recovers, or pass an explicit path or aumid."
+ ))
+ }
+ Err(crate::launch_uwp::AppsFolderLookupError::Busy) => {
+ return ToolResult::error(format!(
+ "App name lookup for {n:?} is temporarily unavailable because a prior Windows shell lookup is still running or cooling down. No app was launched; retry later, or pass an explicit path or aumid."
+ ))
+ }
+ Err(crate::launch_uwp::AppsFolderLookupError::Unavailable) => {
+ return ToolResult::error(format!(
+ "App name lookup for {n:?} is unavailable because the Windows shell lookup worker failed. No app was launched; pass an explicit path or aumid."
+ ))
+ }
+ }
} else {
None
};
@@ -2262,6 +2282,12 @@ impl Tool for LaunchAppTool {
match result {
Ok(Ok(Ok(p))) => p,
+ Ok(Ok(Err(e))) if name_lookup_missed => {
+ return ToolResult::error(format!(
+ "App {:?} was not found in shell:AppsFolder or by Windows PATH/association lookup: {e}",
+ name_opt.as_deref().unwrap_or("")
+ ))
+ }
Ok(Ok(Err(e))) => return ToolResult::error(format!("Failed to launch: {e}")),
Ok(Err(e)) => return ToolResult::error(format!("Task error: {e}")),
Err(_elapsed) => {