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): share delivery mode and admission helpers in core (#4139)
Francesco Bonacci4a64cb46f4be
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/action_target.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/action_target.rsindex ce27b9736a..0c3a36596b 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/action_target.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/action_target.rs@@ -141,15 +141,12 @@ pub fn enforce_delivery_target(tool_name: &str, args: &Value) -> Result<(), Tool}let message = cua_driver_contract::ClickInput::DESKTOP_BACKGROUND_MESSAGE;- Err(ToolResult::error(message).with_structured(json!({- "code": "background_unavailable",- "effect": "refused",- "suggestion": "Retry this action with delivery_mode:\"foreground\".",- "escalation": {- "recommended": "foreground",- "reason": message,- },- })))+ Err(crate::delivery::background_unavailable_result(+ message,+ "background_unavailable",+ message,+ json!({ "effect": "refused" }),+ ))}#[cfg(test)]diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/delivery.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/delivery.rsnew file mode 100644index 0000000000..36bb84833e--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/delivery.rs@@ -0,0 +1,154 @@+//! Per-call input delivery mode and the shared `background_unavailable`+//! refusal envelope.+//!+//! Every platform accepts the same two `delivery_mode` rungs, parsed the same+//! way, and refuses an impossible background delivery with the same+//! foreground-escalation contract. Platform adapters keep only the+//! platform-specific reason text and fields.++use serde_json::{json, Value};++use crate::protocol::ToolResult;++/// Input delivery modality: the agent-selected rung of the+/// best-effort-background ladder, passed per call (never a stored or+/// configured setting).+///+/// - `Background` (default): inject without activating or raising the target.+/// When the platform cannot do that for the target, the tool refuses with+/// [`background_unavailable_result`] instead of fronting.+/// - `Foreground`: activate the target for the action. This is the agent's+/// explicit last resort.+#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]+pub enum DeliveryMode {+ #[default]+ Background,+ Foreground,+}++impl DeliveryMode {+ /// Parse the per-call `delivery_mode` argument. Anything other than an+ /// explicit case-insensitive `"foreground"` resolves to `Background`, so+ /// an omitted, garbage, or removed legacy value (`"auto"`) never silently+ /// fronts.+ pub fn parse(arg: Option<&str>) -> Self {+ match arg {+ Some(s) if s.eq_ignore_ascii_case("foreground") => Self::Foreground,+ _ => Self::Background,+ }+ }++ /// Parse from a tool's JSON args, reading the `delivery_mode` field.+ pub fn from_args(args: &Value) -> Self {+ Self::parse(args.get("delivery_mode").and_then(Value::as_str))+ }++ pub fn is_foreground(self) -> bool {+ matches!(self, Self::Foreground)+ }+}++/// The `suggestion` every background refusal carries.+pub const FOREGROUND_RETRY_SUGGESTION: &str =+ "Retry this action with delivery_mode:\"foreground\".";++/// Build a structured background-delivery refusal.+///+/// The result is an error with `message` as its text. Its structured content+/// holds `code`, the shared [`FOREGROUND_RETRY_SUGGESTION`], and an+/// `escalation` that recommends `foreground` for `escalation_reason`, plus+/// every field of the `fields` object. `fields` cannot override those+/// contract keys.+pub fn background_unavailable_result(+ message: impl Into<String>,+ code: &str,+ escalation_reason: impl Into<String>,+ fields: Value,+) -> ToolResult {+ let mut structured = match fields {+ Value::Object(fields) => fields,+ _ => serde_json::Map::new(),+ };+ structured.insert("code".to_owned(), json!(code));+ structured.insert("suggestion".to_owned(), json!(FOREGROUND_RETRY_SUGGESTION));+ structured.insert(+ "escalation".to_owned(),+ json!({+ "recommended": "foreground",+ "reason": escalation_reason.into(),+ }),+ );+ ToolResult::error(message).with_structured(Value::Object(structured))+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn delivery_mode_parse_fronts_only_on_explicit_foreground() {+ for (args, expected) in [+ (+ json!({"delivery_mode": "background"}),+ DeliveryMode::Background,+ ),+ (+ json!({"delivery_mode": "foreground"}),+ DeliveryMode::Foreground,+ ),+ (+ json!({"delivery_mode": "Foreground"}),+ DeliveryMode::Foreground,+ ),+ (+ json!({"delivery_mode": "FOREGROUND"}),+ DeliveryMode::Foreground,+ ),+ (json!({}), DeliveryMode::Background),+ (+ json!({"delivery_mode": "garbage"}),+ DeliveryMode::Background,+ ),+ (json!({"delivery_mode": "auto"}), DeliveryMode::Background),+ (json!({"delivery_mode": null}), DeliveryMode::Background),+ (json!({"delivery_mode": 1}), DeliveryMode::Background),+ ] {+ let mode = DeliveryMode::from_args(&args);+ assert_eq!(mode, expected, "{args}");+ assert_eq!(mode.is_foreground(), expected == DeliveryMode::Foreground);+ }+ }++ #[test]+ fn background_unavailable_result_carries_the_foreground_escalation() {+ let result = background_unavailable_result(+ "Background delivery is not available.",+ "background_occluded",+ "the target is occluded",+ json!({+ "event_kind": "mouse_click",+ "code": "forged",+ "suggestion": "forged",+ }),+ );+ assert_eq!(result.is_error, Some(true));+ assert_eq!(+ result.structured_content,+ Some(json!({+ "code": "background_occluded",+ "event_kind": "mouse_click",+ "suggestion": "Retry this action with delivery_mode:\"foreground\".",+ "escalation": {+ "recommended": "foreground",+ "reason": "the target is occluded",+ },+ }))+ );+ match &result.content[0] {+ crate::protocol::Content::Text { text, .. } => {+ assert_eq!(text, "Background delivery is not available.")+ }+ _ => panic!("expected text content"),+ }+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rsindex 3792d4bdf0..63061f4e3d 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/image_utils.rs@@ -51,6 +51,38 @@ pub fn png_bytes_to_jpeg(png_bytes: &[u8], quality: u8) -> Result<Vec<u8>> {// ── Downscale ─────────────────────────────────────────────────────────────+/// The screenshot long-edge limits that apply to one capture.+///+/// Fields are named because every source is a `u32` or `Option<u32>`, and+/// positional arguments invite swapping the per-call override with the legacy+/// cap.+#[derive(Clone, Copy, Debug, PartialEq, Eq)]+pub struct ImageDimensionLimits {+ /// The session or global `max_image_dimension` ceiling. `0` means no limit.+ pub configured: u32,+ /// The legacy per-call `max_dimension` cap.+ pub legacy_max_dimension: Option<u32>,+ /// The canonical per-call `max_image_dimension` override.+ pub max_image_dimension: Option<u32>,+}++impl ImageDimensionLimits {+ /// Resolve the `max_dim` to pass to [`resize_png_if_needed`].+ ///+ /// The canonical per-call override wins outright, including `0` for native+ /// resolution. Without it, the legacy cap folds with the configured+ /// ceiling: an unlimited (`0`) ceiling defers to the cap, otherwise the+ /// tighter of the two wins. Returns `0` only when nothing imposes a limit.+ pub fn resolve(self) -> u32 {+ self.max_image_dimension+ .unwrap_or(match self.legacy_max_dimension {+ Some(cap) if self.configured == 0 => cap,+ Some(cap) => self.configured.min(cap),+ None => self.configured,+ })+ }+}+/// Downscale `png_bytes` so neither dimension exceeds `max_dim`.////// `max_dim == 0` is treated as "no cap"; the original bytes are@@ -294,6 +326,37 @@ pub fn encode_bgra_to_png(bgra: &[u8], w: u32, h: u32) -> Result<Vec<u8>> {mod tests {use super::*;+ #[test]+ fn image_dimension_override_wins_and_legacy_cap_folds_with_ceiling() {+ // (configured, legacy max_dimension, max_image_dimension) -> max_dim+ for (configured, legacy, canonical, expected) in [+ // The canonical override wins outright, including 0 = native.+ (1568, None, Some(800), 800),+ (800, None, Some(1568), 1568),+ (1568, None, Some(0), 0),+ (1568, Some(400), Some(1200), 1200),+ (1024, Some(512), Some(2048), 2048),+ (1024, Some(512), Some(0), 0),+ // Without it, the tighter non-zero cap wins.+ (1024, Some(2048), None, 1024),+ (4096, Some(512), None, 512),+ (800, Some(1568), None, 800),+ (1568, Some(800), None, 800),+ // An unlimited (0) ceiling defers to the legacy cap.+ (0, Some(768), None, 768),+ // No per-call limit passes the ceiling through.+ (1600, None, None, 1600),+ (0, None, None, 0),+ ] {+ let limits = ImageDimensionLimits {+ configured,+ legacy_max_dimension: legacy,+ max_image_dimension: canonical,+ };+ assert_eq!(limits.resolve(), expected, "{limits:?}");+ }+ }+#[test]fn png_dimensions_round_trip() {// Build a tiny 3x2 RGBA image then read its dimensions back.diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/launch_guard.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/launch_guard.rsnew file mode 100644index 0000000000..2ff1d39b9d--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/launch_guard.rs@@ -0,0 +1,35 @@+//! Admission checks shared by every platform's `launch_app`.++/// Refusal text for a `launch_app` call that tries to enable Chromium+/// DevTools. `browser_prepare` owns that transition.+pub const REMOTE_DEBUGGING_LAUNCH_REFUSAL: &str = "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile";++/// Whether a launch argument, executable path, or command line carries a+/// Chromium remote-debugging switch in any spelling or case.+pub fn contains_remote_debugging_flag(value: &str) -> bool {+ let lower = value.to_ascii_lowercase();+ lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")+}++#[cfg(test)]+mod tests {+ use super::contains_remote_debugging_flag;++ #[test]+ fn rejects_all_chromium_remote_debugging_spellings() {+ for flagged in [+ "--remote-debugging-port=0",+ "--REMOTE-DEBUGGING-PIPE",+ "/usr/bin/chrome --remote-debugging-port 9222",+ r#"C:\Program Files\Chrome\chrome.exe --remote-debugging-port 9222"#,+ ] {+ assert!(contains_remote_debugging_flag(flagged), "{flagged}");+ }+ for clean in [+ "--user-data-dir=/tmp/profile",+ r#"--user-data-dir=C:\Temp\profile"#,+ ] {+ assert!(!contains_remote_debugging_flag(clean), "{clean}");+ }+ }+}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 7ce702bebc..b7549c13a6 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@@ -58,6 +58,7 @@ pub mod cursor_hook;pub mod cursor_sampler;pub mod cursor_shape;pub mod daemon;+pub mod delivery;pub mod desktop_capture_scale;pub mod element_cache;pub mod element_frame;@@ -68,6 +69,7 @@ pub mod ffmpeg_install;pub mod health_report;pub mod history;pub mod image_utils;+pub mod launch_guard;pub mod mcp_result;pub mod page;pub mod perception_client;@@ -85,6 +87,7 @@ pub mod session;pub mod session_authorization;pub mod session_manifest;pub mod session_tools;+pub mod single_flight;#[cfg(test)]pub(crate) mod snapshot_test_support;pub mod socket_io;diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/single_flight.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/single_flight.rsnew file mode 100644index 0000000000..9e7a6583e1--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/single_flight.rs@@ -0,0 +1,149 @@+//! A process-wide single-flight gate for blocking platform calls that cannot+//! be cancelled once they start (COM, WinRT, and similar provider calls).+//!+//! A caller that gives up on a timed-out worker cannot stop it. The worker+//! therefore keeps the gate's permit until the blocking call actually returns,+//! so retries fail fast instead of stranding one more thread per attempt. When+//! a timed-out worker finally returns, an optional cooldown keeps a hot retry+//! loop from immediately re-entering the same unhealthy provider.+//!+//! The gate owns only admission. Each adapter keeps its own worker spawning,+//! deadline, and error type.++use std::sync::atomic::{AtomicBool, Ordering};+use std::sync::{Arc, Mutex};+use std::time::{Duration, Instant};++#[derive(Debug)]+pub struct SingleFlight {+ in_flight: AtomicBool,+ cooldown: Duration,+ cooldown_until: Mutex<Option<Instant>>,+}++impl SingleFlight {+ /// A gate that, after a timed-out worker returns, refuses new work for+ /// `cooldown`. Pass [`Duration::ZERO`] to reopen as soon as it returns.+ pub const fn new(cooldown: Duration) -> Self {+ Self {+ in_flight: AtomicBool::new(false),+ cooldown,+ cooldown_until: Mutex::new(None),+ }+ }++ /// Admit one worker, or return `None` while another worker holds the gate+ /// or the recovery cooldown is running. Move the permit into the worker so+ /// the gate stays closed until the blocking call returns.+ pub fn try_acquire(self: &Arc<Self>) -> Option<SingleFlightPermit> {+ if self.is_cooling_down()+ || self+ .in_flight+ .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)+ .is_err()+ {+ return None;+ }+ Some(SingleFlightPermit {+ gate: Arc::clone(self),+ timed_out: Arc::new(AtomicBool::new(false)),+ })+ }++ /// Whether a worker currently holds the gate.+ pub fn is_in_flight(&self) -> bool {+ self.in_flight.load(Ordering::Acquire)+ }++ /// Start the recovery cooldown now.+ ///+ /// The permit also arms it when a timed-out worker returns. Callers arm it+ /// when their deadline fires as well, because the worker can return between+ /// the deadline and observing the timeout flag.+ pub fn arm_cooldown(&self) {+ let until = Instant::now() + self.cooldown;+ *self+ .cooldown_until+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner()) = Some(until);+ }++ fn is_cooling_down(&self) -> bool {+ self.cooldown_until+ .lock()+ .unwrap_or_else(|poisoned| poisoned.into_inner())+ .is_some_and(|until| Instant::now() < until)+ }+}++/// Ownership of a [`SingleFlight`] gate. Dropping it reopens the gate, after+/// arming the cooldown if the caller marked the work as timed out.+#[derive(Debug)]+pub struct SingleFlightPermit {+ gate: Arc<SingleFlight>,+ timed_out: Arc<AtomicBool>,+}++impl SingleFlightPermit {+ /// The flag the caller sets when its deadline fires. Workers that can+ /// stop early poll it as their cancellation signal.+ pub fn timeout_flag(&self) -> Arc<AtomicBool> {+ Arc::clone(&self.timed_out)+ }++ /// Whether the caller gave up on this worker.+ pub fn timed_out(&self) -> bool {+ self.timed_out.load(Ordering::Acquire)+ }+}++impl Drop for SingleFlightPermit {+ fn drop(&mut self) {+ if self.timed_out() {+ self.gate.arm_cooldown();+ }+ self.gate.in_flight.store(false, Ordering::Release);+ }+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn one_worker_at_a_time_and_cooldown_only_after_a_timed_out_worker() {+ let gate = Arc::new(SingleFlight::new(Duration::from_millis(50)));++ let permit = gate.try_acquire().expect("idle gate admits");+ assert!(gate.is_in_flight());+ assert!(gate.try_acquire().is_none(), "second worker must wait");+ drop(permit);+ assert!(!gate.is_in_flight());++ // A worker that finished in time reopens the gate immediately.+ drop(gate.try_acquire().expect("reopened without cooldown"));++ // A timed-out worker keeps the gate until it returns, then cools down.+ let permit = gate.try_acquire().expect("idle gate admits");+ permit.timeout_flag().store(true, Ordering::Release);+ assert!(permit.timed_out());+ assert!(gate.try_acquire().is_none());+ drop(permit);+ assert!(!gate.is_in_flight());+ assert!(gate.try_acquire().is_none(), "late return starts cooldown");++ std::thread::sleep(Duration::from_millis(80));+ assert!(gate.try_acquire().is_some(), "gate recovers after cooldown");+ }++ #[test]+ fn zero_cooldown_reopens_as_soon_as_the_timed_out_worker_returns() {+ let gate = Arc::new(SingleFlight::new(Duration::ZERO));+ let permit = gate.try_acquire().unwrap();+ permit.timeout_flag().store(true, Ordering::Release);+ gate.arm_cooldown();+ assert!(gate.try_acquire().is_none());+ drop(permit);+ assert!(gate.try_acquire().is_some());+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rsindex 56fa539c22..a972c7241d 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_args.rs@@ -212,14 +212,55 @@ mod session_identity_tests {/// anonymous calls. Mirrors the cursor/mouse-hold isolation convention so new/// per-call state (e.g. desktop screenshot scale) doesn't invent its own.pub fn resolve_session_key(args: &Value) -> String {- for key in ["session", "_session_id", "cursor_id"] {- if let Some(v) = args.get(key).and_then(Value::as_str) {- if !v.is_empty() {- return v.to_owned();- }+ session_key(args).unwrap_or_else(|| "default".to_owned())+}++/// The first non-empty of `session`, the proxy-minted `_session_id`, and the+/// legacy `cursor_id`, or `None` for an anonymous call. Callers pick their own+/// anonymous fallback: [`resolve_session_key`] uses a shared `"default"`+/// bucket, and the Windows cursor key stays cursor-less.+pub fn session_key(args: &Value) -> Option<String> {+ ["session", "_session_id", "cursor_id"]+ .into_iter()+ .filter_map(|key| args.get(key).and_then(Value::as_str))+ .find(|value| !value.is_empty())+ .map(str::to_owned)+}++#[cfg(test)]+mod session_key_tests {+ use super::{resolve_session_key, session_key};+ use serde_json::json;++ #[test]+ fn session_then_implicit_session_then_legacy_cursor_id() {+ for (args, expected) in [+ (json!({}), None),+ (json!({ "pid": 1 }), None),+ (json!({ "session": "research-run" }), Some("research-run")),+ (json!({ "_session_id": "mcp-1-2" }), Some("mcp-1-2")),+ (json!({ "cursor_id": "user-handle" }), Some("user-handle")),+ (+ json!({ "session": "s1", "_session_id": "implicit", "cursor_id": "c1" }),+ Some("s1"),+ ),+ (+ json!({ "_session_id": "implicit", "cursor_id": "c1" }),+ Some("implicit"),+ ),+ // Empty and non-string values fall through to the next source.+ (json!({ "session": "", "cursor_id": "c1" }), Some("c1")),+ (json!({ "session": 7, "_session_id": "mcp" }), Some("mcp")),+ (json!({ "session": "", "cursor_id": "" }), None),+ ] {+ assert_eq!(session_key(&args).as_deref(), expected, "{args}");+ assert_eq!(+ resolve_session_key(&args),+ expected.unwrap_or("default"),+ "{args}"+ );}}- "default".to_owned()}#[cfg(test)]diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rsindex f5e0702c18..f99b68a315 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/window_target.rs@@ -357,6 +357,32 @@ fn note_resolved_window(mut result: ToolResult, candidate: &WindowTargetCandidatresult}+/// Normalize a front-to-back enumeration position into the shared+/// `list_windows` `z_index`: higher values are closer to the front, the+/// frontmost of `total` windows is `total - 1`, and the backmost is `0`.+///+/// macOS `CGWindowListCopyWindowInfo` and Windows `EnumWindows` enumerate+/// front to back. X11 EWMH stacking lists are already bottom to top, so the+/// X11 adapter uses its enumeration index directly and reports the same values.+pub fn z_index_from_front_to_back(total: usize, position: usize) -> usize {+ total.saturating_sub(1).saturating_sub(position)+}++#[cfg(test)]+mod z_index_tests {+ use super::z_index_from_front_to_back;++ #[test]+ fn front_to_back_order_normalizes_to_zero_based_higher_is_frontmost() {+ let indices: Vec<_> = (0..3)+ .map(|position| z_index_from_front_to_back(3, position))+ .collect();+ assert_eq!(indices, vec![2, 1, 0]);+ assert_eq!(z_index_from_front_to_back(0, 0), 0);+ assert_eq!(z_index_from_front_to_back(3, 7), 0);+ }+}+#[cfg(test)]mod tests {use super::*;diff --git a/libs/cua-driver/rust/crates/platform-linux/src/capture_action_frame.rs b/libs/cua-driver/rust/crates/platform-linux/src/capture_action_frame.rsindex 156aa8eb16..9d3b824ecc 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/capture_action_frame.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/capture_action_frame.rs@@ -8,18 +8,6 @@ fn window_target(pid: u32, window_id: u64) -> CaptureTarget {CaptureTarget::Window { pid, window_id }}-pub fn resolve_max_image_dimension(- configured: u32,- legacy_max_dimension: Option<u32>,- max_image_dimension: Option<u32>,-) -> u32 {- max_image_dimension.unwrap_or_else(|| match legacy_max_dimension {- Some(value) if configured == 0 => value,- Some(value) => configured.min(value),- None => configured,- })-}-fn publish(service: &CaptureService,args: &Value,@@ -446,22 +434,6 @@ mod tests {);}- #[test]- fn explicit_image_dimension_override_wins_including_native_zero() {- assert_eq!(- resolve_max_image_dimension(1568, Some(800), Some(2048)),- 2048- );- assert_eq!(resolve_max_image_dimension(1568, Some(800), Some(0)), 0);- }-- #[test]- fn omitted_image_dimension_override_preserves_existing_behavior() {- assert_eq!(resolve_max_image_dimension(1568, None, None), 1568);- assert_eq!(resolve_max_image_dimension(0, None, None), 0);- assert_eq!(resolve_max_image_dimension(1568, Some(800), None), 800);- }-#[test]fn live_resize_refuses_before_dispatch_without_consuming_capture() {let service = CaptureService::default();diff --git a/libs/cua-driver/rust/crates/platform-linux/src/input/delivery.rs b/libs/cua-driver/rust/crates/platform-linux/src/input/delivery.rsindex 35edfb0f6a..381b4996c8 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/input/delivery.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/input/delivery.rs@@ -29,39 +29,8 @@use serde_json::Value;-/// Input delivery modality — the agent-selected rung of the best-effort--/// background ladder, passed per call (never a stored/config setting). Mirrors-/// macOS `tools::DeliveryMode` and Windows `input::delivery::DeliveryMode`.-#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]-pub enum DeliveryMode {- /// Inject without activating the target (X11 XTEST/MPX; Wayland libei-to-focus).- #[default]- Background,- /// Activate the target, confirm focus, inject real input, leave it active.- Foreground,-}--impl DeliveryMode {- /// Parse the per-call `delivery_mode` argument. Anything other than an- /// explicit case-insensitive `"foreground"` resolves to `Background` — the- /// correct default, so an omitted/garbage value never silently fronts.- /// Matches macOS / Windows `DeliveryMode::parse`.- pub fn parse(arg: Option<&str>) -> Self {- match arg {- Some(s) if s.eq_ignore_ascii_case("foreground") => Self::Foreground,- _ => Self::Background,- }- }-- /// Parse from a tool's JSON args, reading the `delivery_mode` field.- pub fn from_args(args: &Value) -> Self {- Self::parse(args.get("delivery_mode").and_then(|v| v.as_str()))- }-- pub fn is_foreground(self) -> bool {- matches!(self, Self::Foreground)- }-}+/// The shared per-call delivery mode; see [`cua_driver_core::delivery`].+pub use cua_driver_core::delivery::DeliveryMode;/// JSON-schema fragment for the `delivery_mode` field. Include this in every/// input tool's `input_schema.properties.delivery_mode`. Two modes, matching@@ -144,67 +113,23 @@ pub fn background_unavailable_error(reason: BackgroundUnavailable,) -> cua_driver_core::protocol::ToolResult {let detail = reason.detail();- cua_driver_core::protocol::ToolResult::error(format!(- "Background delivery is not available: {detail}. Retry this action with \- delivery_mode:\"foreground\"; Cua Driver will activate the target window, \- confirm it holds the input focus, and deliver real input to it."- ))- .with_structured(serde_json::json!({- "code": reason.code(),- "detail": detail,- "suggestion": "Retry this action with delivery_mode:\"foreground\".",- "escalation": {- "recommended": "foreground",- "reason": "background input is unavailable on this surface; retry this \- action with delivery_mode:\"foreground\".",- },- }))+ cua_driver_core::delivery::background_unavailable_result(+ format!(+ "Background delivery is not available: {detail}. Retry this action with \+ delivery_mode:\"foreground\"; Cua Driver will activate the target window, \+ confirm it holds the input focus, and deliver real input to it."+ ),+ reason.code(),+ "background input is unavailable on this surface; retry this \+ action with delivery_mode:\"foreground\".",+ serde_json::json!({ "detail": detail }),+ )}#[cfg(test)]mod tests {use super::*;- #[test]- fn delivery_mode_parses_known_values() {- let j = |s: &str| serde_json::json!({"delivery_mode": s});- assert_eq!(- DeliveryMode::from_args(&j("background")),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&j("foreground")),- DeliveryMode::Foreground- );- // Case-insensitive, matching macOS / Windows.- assert_eq!(- DeliveryMode::from_args(&j("Foreground")),- DeliveryMode::Foreground- );- }-- #[test]- fn delivery_mode_defaults_to_background() {- // Missing field, garbage value, null, and the removed legacy "auto" all- // resolve to Background — the no-foreground-by-default contract.- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": "garbage"})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": "auto"})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": null})),- DeliveryMode::Background- );- }-#[test]fn delivery_mode_schema_advertises_two_modes() {let s = delivery_mode_schema();@@ -221,33 +146,4 @@ mod tests {.expect("delivery_mode description");assert!(!description.contains("bring_to_front"));}-- #[test]- fn background_unavailable_error_carries_code() {- let r = background_unavailable_error(BackgroundUnavailable::NoLibeiBackend);- assert_eq!(r.is_error, Some(true));- assert_eq!(- r.structured_content.as_ref().unwrap()["code"],- serde_json::json!("background_unavailable")- );- let text = match &r.content[0] {- cua_driver_core::protocol::Content::Text { text, .. } => text,- _ => panic!("expected text content"),- };- let structured = r.structured_content.as_ref().unwrap();- assert!(text.contains("Retry this action with delivery_mode:\"foreground\""));- assert!(!text.contains("bring_to_front"));- assert_eq!(- structured["suggestion"].as_str(),- Some("Retry this action with delivery_mode:\"foreground\".")- );- assert_eq!(- structured["escalation"]["recommended"].as_str(),- Some("foreground")- );- assert!(!structured["escalation"]["reason"]- .as_str()- .unwrap_or_default()- .contains("bring_to_front"));- }}diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex 3fef85729a..1785f4063f 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs@@ -1151,11 +1151,12 @@ impl Tool for GetWindowStateTool {let explicit_max_image_dimension = max_image_dimension.is_some();let max_dim = {let cfg = self.state.config.read().unwrap();- crate::capture_action_frame::resolve_max_image_dimension(- cfg.max_image_dimension,- max_dimension,+ cua_driver_core::image_utils::ImageDimensionLimits {+ configured: cfg.max_image_dimension,+ legacy_max_dimension: max_dimension,max_image_dimension,- )+ }+ .resolve()};// `capture_mode` is DEPRECATED and ignored — get_window_state always// returns BOTH the AT-SPI tree and a screenshot now, so the agent grounds@@ -1755,11 +1756,6 @@ mod get_window_state_actions_tests;pub struct LaunchAppTool;static LAUNCH_DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();-fn contains_remote_debugging_flag(value: &str) -> bool {- let lower = value.to_ascii_lowercase();- lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")-}-/// Spawn a launcher command line (an executable plus arguments, e.g. an XDG/// `Exec=` value with field codes stripped) in the background and return the/// child pid.@@ -1921,10 +1917,10 @@ impl Tool for LaunchAppTool {.into_iter().chain(name_opt.as_deref()).chain(additional_arguments.iter().map(String::as_str))- .any(contains_remote_debugging_flag)+ .any(cua_driver_core::launch_guard::contains_remote_debugging_flag){return ToolResult::error(- "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ cua_driver_core::launch_guard::REMOTE_DEBUGGING_LAUNCH_REFUSAL,);}@@ -14047,9 +14043,6 @@ pub fn build_registry_with_provider(#[cfg(test)]mod click_button_schema_tests;-#[cfg(test)]-mod browser_launch_guard_tests;-#[cfg(test)]mod pid_window_target_tests;diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_/browser_launch_guard_tests.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_/browser_launch_guard_tests.rsdeleted file mode 100644index f9fefecaa6..0000000000--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_/browser_launch_guard_tests.rs+++ /dev/null@@ -1,13 +0,0 @@-use super::contains_remote_debugging_flag;--#[test]-fn rejects_all_chromium_remote_debugging_spellings() {- assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));- assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));- assert!(contains_remote_debugging_flag(- "/usr/bin/chrome --remote-debugging-port 9222"- ));- assert!(!contains_remote_debugging_flag(- "--user-data-dir=/tmp/profile"- ));-}diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rsindex b2f7fa86e8..84d48c7294 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs@@ -140,27 +140,6 @@ fn def() -> &'static ToolDef {})}-/// Fold a per-call `max_dimension` cap with the session/global-/// `max_image_dimension` ceiling. `resize_png_if_needed` treats `0` as "no-/// limit", so when the ceiling is unlimited the per-call cap stands alone;-/// otherwise the tighter (smaller, non-zero) of the two wins. Returns `0` only-/// when neither imposes a limit.-fn fold_max_dimension(ceiling: u32, per_call: Option<u32>) -> u32 {- match per_call {- Some(md) if ceiling == 0 => md,- Some(md) => ceiling.min(md),- None => ceiling,- }-}--fn resolve_max_dimension(- configured: u32,- legacy_cap: Option<u32>,- per_call_override: Option<u32>,-) -> u32 {- per_call_override.unwrap_or_else(|| fold_max_dimension(configured, legacy_cap))-}-fn chromium_browser_window(pid: i32) -> bool {let identity = format!("{} {}",@@ -375,7 +354,12 @@ impl Tool for GetWindowStateTool {// The portable `max_image_dimension` is an explicit per-call override,// including 0 for native resolution. Without it, preserve the existing// configured ceiling and legacy `max_dimension` tighter-cap behavior.- let max_dim = resolve_max_dimension(effective_max_dim, max_dimension, max_image_dimension);+ let max_dim = cua_driver_core::image_utils::ImageDimensionLimits {+ configured: effective_max_dim,+ legacy_max_dimension: max_dimension,+ max_image_dimension,+ }+ .resolve();// Returns the exact delivered PNG bytes, optional file path, delivered// and native dimensions, the WindowServer bounds it was validated// against, and the raw capture's backing scale.@@ -1131,31 +1115,6 @@ mod window_scope_contract_tests {"description must document the both-false error");}-- /// The per-call `max_dimension` folds with the session/global ceiling: the- /// tighter non-zero cap wins, an unlimited (0) ceiling defers to the- /// per-call cap, and absent inputs pass the ceiling through unchanged.- #[test]- fn max_dimension_folds_tighter_cap() {- // Ceiling wins when it is tighter than the per-call cap.- assert_eq!(fold_max_dimension(1024, Some(2048)), 1024);- // Per-call wins when it is tighter than the ceiling.- assert_eq!(fold_max_dimension(4096, Some(512)), 512);- // Unlimited ceiling (0) defers entirely to the per-call cap.- assert_eq!(fold_max_dimension(0, Some(768)), 768);- // No per-call cap → the ceiling passes through (0 stays unlimited).- assert_eq!(fold_max_dimension(1600, None), 1600);- assert_eq!(fold_max_dimension(0, None), 0);- }-- #[test]- fn max_image_dimension_explicit_override_wins() {- assert_eq!(resolve_max_dimension(1024, None, Some(2048)), 2048);- assert_eq!(resolve_max_dimension(1024, Some(512), Some(2048)), 2048);- assert_eq!(resolve_max_dimension(1024, Some(512), Some(0)), 0);- assert_eq!(resolve_max_dimension(1024, Some(512), None), 512);- assert_eq!(resolve_max_dimension(1024, None, None), 1024);- }}#[cfg(test)]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 6085da9947..bdbe72a15d 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@@ -112,10 +112,10 @@ impl Tool for LaunchAppTool {}if additional_arguments.iter()- .any(|argument| contains_remote_debugging_flag(argument))+ .any(|argument| cua_driver_core::launch_guard::contains_remote_debugging_flag(argument)){return ToolResult::error(- "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ cua_driver_core::launch_guard::REMOTE_DEBUGGING_LAUNCH_REFUSAL,);}@@ -498,11 +498,6 @@ impl Tool for LaunchAppTool {}}-fn contains_remote_debugging_flag(value: &str) -> bool {- let lower = value.to_ascii_lowercase();- lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")-}-fn is_cua_driver_bundle_id(bundle_id: &str) -> bool {matches!(bundle_id, "com.trycua.driver" | "com.trycua.driver.local")}@@ -718,9 +713,8 @@ fn hex_value(byte: u8) -> Option<u8> {#[cfg(test)]mod tests {use super::{- contains_remote_debugging_flag, is_cua_driver_bundle_id, local_file_target,- normalize_launch_url, preflight_file_urls, response_identity, structured_launch_failure,- LaunchAppTool,+ is_cua_driver_bundle_id, local_file_target, normalize_launch_url, preflight_file_urls,+ response_identity, structured_launch_failure, LaunchAppTool,};use cua_driver_core::tool::Tool;use serde_json::json;@@ -785,15 +779,6 @@ mod tests {);}- #[test]- fn rejects_all_chromium_remote_debugging_spellings() {- assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));- assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));- assert!(!contains_remote_debugging_flag(- "--user-data-dir=/tmp/profile"- ));- }-#[test]fn recognizes_release_and_local_protected_host_bundle_ids() {assert!(is_cua_driver_bundle_id("com.trycua.driver"));diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rsindex 7896fd9ca8..91542d95a2 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/mod.rs@@ -150,37 +150,14 @@ pub use cua_driver_core::element_cache::{SnapshotBoundZoomContext as ZoomContext, SnapshotBoundZoomRegistry as ZoomRegistry,};-/// Input delivery modality — the agent-selected rung of the best-effort-background-/// ladder, passed per call (never a stored/config setting).+/// The shared per-call delivery mode; see [`cua_driver_core::delivery`].///-/// - `Background` (default): post synthetic input to the pid without fronting.-/// - `Foreground`: briefly front the target window, act, then restore the prior-/// frontmost (see [`crate::input::skylight::with_foreground_assist`]). The-/// agent's vision-driven last resort — and the only way `click` reaches a-/// foreground rung. Orthogonal to addressing (`element_index` vs `x/y`, which-/// selects AX vs pixel).-#[derive(Clone, Copy, PartialEq, Eq, Debug, Default)]-pub enum DeliveryMode {- #[default]- Background,- Foreground,-}--impl DeliveryMode {- /// Parse the per-call `delivery_mode` argument. Anything other than an- /// explicit case-insensitive `"foreground"` resolves to `Background` — the- /// correct default, so an omitted/garbage value never silently fronts.- pub fn parse(arg: Option<&str>) -> Self {- match arg {- Some(s) if s.eq_ignore_ascii_case("foreground") => Self::Foreground,- _ => Self::Background,- }- }-- pub fn is_foreground(self) -> bool {- matches!(self, Self::Foreground)- }-}+/// On macOS, `Foreground` briefly fronts the target window, acts, then+/// restores the prior frontmost (see+/// [`crate::input::skylight::with_foreground_assist`]). It is the only way+/// `click` reaches a foreground rung and is orthogonal to addressing+/// (`element_index` vs `x/y`, which selects AX vs pixel).+pub use cua_driver_core::delivery::DeliveryMode;/// Convert a pure background-input refusal into the structured refusal result/// shape shared by exact-target tools: `code`, `effect: "refused"`, thediff --git a/libs/cua-driver/rust/crates/platform-macos/src/windows.rs b/libs/cua-driver/rust/crates/platform-macos/src/windows.rsindex cc849c5be7..d9b146569b 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/windows.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/windows.rs@@ -235,7 +235,7 @@ fn enumerate_windows(options: u32, layers: LayerFilter) -> WindowEnumeration {};// z_index: CGWindowList front-to-back → assign reverse index.- let z_index = z_index_from_front_to_back(total, idx);+ let z_index = cua_driver_core::window_target::z_index_from_front_to_back(total, idx);results.push(WindowInfo {window_id,@@ -291,10 +291,6 @@ fn window_on_current_space(Some(space_ids?.contains(¤t_space_id?))}-fn z_index_from_front_to_back(total: usize, position: usize) -> usize {- total.saturating_sub(position)-}-fn get_bounds_num(dict: &core_foundation::dictionary::CFDictionary<*const std::os::raw::c_void,@@ -412,15 +408,6 @@ pub fn resolve_main_window_id(pid: i32) -> anyhow::Result<u32> {mod tests {use super::*;- #[test]- fn cg_front_to_back_order_normalizes_to_higher_is_frontmost() {- let indices: Vec<_> = (0..3)- .map(|position| z_index_from_front_to_back(3, position))- .collect();- assert_eq!(indices, vec![3, 2, 1]);- assert!(indices[0] > indices[2]);- }-#[test]fn space_membership_checks_all_spaces_for_a_window() {assert_eq!(window_on_current_space(Some(&[2, 4]), Some(4)), Some(true));diff --git a/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs b/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rsindex 6aba44d95c..032cf9ee46 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/input/delivery.rs@@ -63,46 +63,8 @@ impl EventKind {}}-/// Input delivery modality — the agent-selected rung of the best-effort--/// background ladder, passed per call (never a stored/config setting).-/// Mirrors macOS `tools::DeliveryMode`.-///-/// - `Background` (default): post synthetic input to the target without-/// fronting; on a known silent-drop (class, event) pair the tool returns-/// a structured `background_unavailable` error instead of fronting.-/// - `Foreground`: briefly front the target window, act via SendInput, then-/// restore the prior foreground. The agent's explicit last resort.-#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]-pub enum DeliveryMode {- /// PostMessage / UIA only. Error if delivery would be silently dropped.- #[default]- Background,- /// SendInput with brief foreground swap.- Foreground,-}--impl DeliveryMode {- /// Parse the per-call `delivery_mode` argument. Anything other than an- /// explicit case-insensitive `"foreground"` resolves to `Background` —- /// the correct default, so an omitted/garbage value (or the removed- /// legacy `"auto"`) never silently fronts. Matches macOS- /// `DeliveryMode::parse`.- pub fn parse(arg: Option<&str>) -> Self {- match arg {- Some(s) if s.eq_ignore_ascii_case("foreground") => Self::Foreground,- _ => Self::Background,- }- }-- /// Parse from a tool's JSON args, reading the `delivery_mode` field.- pub fn from_args(args: &Value) -> Self {- Self::parse(args.get("delivery_mode").and_then(|v| v.as_str()))- }-- pub fn is_foreground(self) -> bool {- matches!(self, Self::Foreground)- }-}+/// The shared per-call delivery mode; see [`cua_driver_core::delivery`].+pub use cua_driver_core::delivery::DeliveryMode;/// JSON-schema fragment for the `delivery_mode` field. Include this in every/// input tool's `input_schema.properties.delivery_mode`. Two modes, matching@@ -343,19 +305,18 @@ pub fn background_unavailable_error(the action and restore the previous foreground afterward.",kind.name());- cua_driver_core::protocol::ToolResult::error(text).with_structured(serde_json::json!({- "code": "background_unavailable",- "target_class": class,- "event_kind": kind.name(),- "suggestion": "Retry this action with delivery_mode:\"foreground\".",- // Windows analog of the macOS escalation signal: this surface drops- // background input, so the deliberate next rung is foreground delivery.- "escalation": {- "recommended": "foreground",- "reason": "background input is dropped by this surface; retry this \- action with delivery_mode:\"foreground\".",- },- }))+ // Windows analog of the macOS escalation signal: this surface drops+ // background input, so the deliberate next rung is foreground delivery.+ cua_driver_core::delivery::background_unavailable_result(+ text,+ "background_unavailable",+ "background input is dropped by this surface; retry this \+ action with delivery_mode:\"foreground\".",+ serde_json::json!({+ "target_class": class,+ "event_kind": kind.name(),+ }),+ )}/// Build a structured background refusal while preserving the concrete@@ -384,18 +345,17 @@ pub fn background_unavailable_error_with_cause(the action and restore the previous foreground afterward.",kind.name());- cua_driver_core::protocol::ToolResult::error(text).with_structured(serde_json::json!({- "code": code,- "target_class": class,- "event_kind": kind.name(),- "cause": cause,- "suggestion": "Retry this action with delivery_mode:\"foreground\".",- "escalation": {- "recommended": "foreground",- "reason": "background input could not be delivered by the coordinate \- actuator; retry this action with delivery_mode:\"foreground\".",- },- }))+ cua_driver_core::delivery::background_unavailable_result(+ text,+ code,+ "background input could not be delivered by the coordinate \+ actuator; retry this action with delivery_mode:\"foreground\".",+ serde_json::json!({+ "target_class": class,+ "event_kind": kind.name(),+ "cause": cause,+ }),+ )}#[cfg(test)]@@ -432,47 +392,6 @@ mod tests {assert!(!tk_drops_event(EventKind::MouseScroll));}- #[test]- fn delivery_mode_parses_known_values() {- let j = |s: &str| serde_json::json!({"delivery_mode": s});- assert_eq!(- DeliveryMode::from_args(&j("background")),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&j("foreground")),- DeliveryMode::Foreground- );- // Case-insensitive, matching macOS DeliveryMode::parse.- assert_eq!(- DeliveryMode::from_args(&j("Foreground")),- DeliveryMode::Foreground- );- }-- #[test]- fn delivery_mode_defaults_to_background() {- // Missing field, garbage value, null, and the removed legacy "auto"- // all resolve to Background. This is the cua-driver no-foreground-by-- // default contract: an unrecognised value never silently fronts.- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": "garbage"})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": "auto"})),- DeliveryMode::Background- );- assert_eq!(- DeliveryMode::from_args(&serde_json::json!({"delivery_mode": null})),- DeliveryMode::Background- );- }-#[test]fn delivery_mode_schema_keeps_persistent_activation_out_of_the_input_ladder() {let schema = delivery_mode_schema();@@ -483,31 +402,6 @@ mod tests {assert!(!description.contains("bring_to_front"));}- #[test]- fn background_unavailable_prefers_action_scoped_foreground_delivery() {- let result = background_unavailable_error(0, EventKind::MouseClick);- let structured = result.structured_content.as_ref().expect("structured");- let text = match &result.content[0] {- cua_driver_core::protocol::Content::Text { text, .. } => text,- _ => panic!("expected text content"),- };-- assert!(text.contains("Retry this action with delivery_mode:\"foreground\""));- assert!(!text.contains("bring_to_front"));- assert_eq!(- structured["suggestion"].as_str(),- Some("Retry this action with delivery_mode:\"foreground\".")- );- assert_eq!(- structured["escalation"]["recommended"].as_str(),- Some("foreground")- );- assert!(!structured["escalation"]["reason"]- .as_str()- .unwrap_or_default()- .contains("bring_to_front"));- }-#[test]fn background_unavailable_with_cause_preserves_actuator_failure() {let result = background_unavailable_error_with_cause(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.rsindex 673920751d..8af89b44c7 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,9 +33,11 @@//! the module is `#[cfg(target_os = "windows")]`-gated at the crate//! root.-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};+use std::sync::atomic::Ordering;use std::sync::{Arc, OnceLock, RwLock};-use std::time::{Duration, Instant};+use std::time::Duration;++use cua_driver_core::single_flight::SingleFlight;use windows::core::{Interface, GUID, HSTRING, PCWSTR, PWSTR};use windows::Win32::Foundation::HWND;@@ -275,106 +277,49 @@ pub enum AppsFolderLookupError {/// 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>,+fn apps_folder_lookup_gate() -> &'static Arc<SingleFlight> {+ static GATE: OnceLock<Arc<SingleFlight>> = OnceLock::new();+ GATE.get_or_init(|| Arc::new(SingleFlight::new(APPS_FOLDER_LOOKUP_RECOVERY_COOLDOWN)))}-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,+async fn run_apps_folder_lookup<T, F>(+ gate: &Arc<SingleFlight>,+ timeout: Duration,+ work: F,+) -> Result<T, AppsFolderLookupError>+where+ T: Send + 'static,+ F: FnOnce() -> T + Send + 'static,+{+ let Some(permit) = gate.try_acquire() else {+ return Err(AppsFolderLookupError::Busy);+ };+ let timed_out = permit.timeout_flag();+ let worker = tokio::task::spawn_blocking(move || {+ let _permit = permit;+ 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.+ gate.arm_cooldown();+ Err(AppsFolderLookupError::Timeout)}- 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))}@@ -384,11 +329,12 @@ fn cache() -> &'static RwLock<Option<Vec<AppsFolderEntry>>> {pub async fn resolve_apps_folder_target_by_name_bounded(display_name: String,) -> Result<Option<AppsFolderLaunchTarget>, AppsFolderLookupError> {- let result = apps_folder_lookup_gate()- .run(APPS_FOLDER_LOOKUP_TIMEOUT, move || {- resolve_apps_folder_target_by_name(&display_name)- })- .await;+ let result = run_apps_folder_lookup(+ apps_folder_lookup_gate(),+ APPS_FOLDER_LOOKUP_TIMEOUT,+ move || resolve_apps_folder_target_by_name(&display_name),+ )+ .await;match result {Err(AppsFolderLookupError::Timeout) => tracing::warn!(target: "launch_uwp",@@ -574,22 +520,23 @@ fn pwstr_to_string_and_free(p: PWSTR) -> String {#[cfg(test)]mod tests {use super::*;+ use std::sync::atomic::{AtomicBool, AtomicU64};+ use std::time::Instant;#[tokio::test]async fn apps_folder_lookup_timeout_is_single_flight_and_recovers_after_cooldown() {- let gate = Arc::new(AppsFolderLookupSingleFlight::new(20));+ let gate = Arc::new(SingleFlight::new(Duration::from_millis(500)));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;+ let first = run_apps_folder_lookup(&gate, 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));@@ -597,30 +544,29 @@ mod tests {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;+ let retry = run_apps_folder_lookup(&gate, 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 {+ while gate.is_in_flight() && Instant::now() < worker_deadline {tokio::time::sleep(Duration::from_millis(2)).await;}- assert!(!gate.in_flight.load(Ordering::Acquire));+ assert!(!gate.is_in_flight());assert_eq!(- gate.run(Duration::from_millis(10), || 2_u8).await,+ run_apps_folder_lookup(&gate, 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;+ tokio::time::sleep(Duration::from_millis(600)).await;assert_eq!(- gate.run(Duration::from_millis(100), || 3_u8).await,+ run_apps_folder_lookup(&gate, Duration::from_millis(100), || 3_u8).await,Ok(3),"lookup should recover after the cooldown");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_.rsindex 0ce6c1b990..7ca5f8a66e 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@@ -478,14 +478,7 @@ pub(crate) const NO_CURSOR: &str = "";/// then the legacy `cursor_id` alias. A direct platform invocation that has no/// lifecycle metadata remains cursor-less.pub(crate) fn resolve_cursor_key(args: &Value) -> String {- for key in ["session", "_session_id", "cursor_id"] {- if let Some(v) = args.get(key).and_then(|v| v.as_str()) {- if !v.is_empty() {- return v.to_owned();- }- }- }- NO_CURSOR.to_owned()+ cua_driver_core::tool_args::session_key(args).unwrap_or_else(|| NO_CURSOR.to_owned())}/// Returns `true` when a click/scroll invocation should take the **window-less@@ -1010,9 +1003,7 @@ impl Tool for ListWindowsTool {}}-fn z_index_from_front_to_back(total: usize, position: usize) -> usize {- total.saturating_sub(1).saturating_sub(position)-}+use cua_driver_core::window_target::z_index_from_front_to_back;#[cfg(test)]mod list_windows_z_index_tests;@@ -1022,29 +1013,6 @@ mod get_window_state_actions_tests;// ── get_window_state ─────────────────────────────────────────────────────────-/// Fold a per-call `max_dimension` cap with the configured-/// `max_image_dimension` ceiling. `resize_png_if_needed` treats `0` as "no-/// limit", so an unlimited ceiling defers to the per-call cap; otherwise the-/// tighter (smaller, non-zero) of the two wins.-fn fold_max_dimension(ceiling: u32, per_call: Option<u32>) -> u32 {- match per_call {- Some(md) if ceiling == 0 => md,- Some(md) => ceiling.min(md),- None => ceiling,- }-}--/// Resolve the screenshot size limit. The canonical per-call override wins-/// outright, including `0` for native resolution. When omitted, preserve the-/// configured ceiling and legacy `max_dimension` folding behavior.-fn resolve_max_image_dimension(- configured: u32,- max_image_dimension: Option<u32>,- legacy_max_dimension: Option<u32>,-) -> u32 {- max_image_dimension.unwrap_or_else(|| fold_max_dimension(configured, legacy_max_dimension))-}-/// Build a single structured element entry for `get_window_state`./// Returns `None` when the node has no `element_index` (non-actionable rows).fn build_element_entry(@@ -1110,9 +1078,6 @@ pub struct GetWindowStateTool {static GWS_DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();-#[cfg(test)]-mod get_window_state_max_image_dimension_tests;-/// Slack past `timeout_ms` before the walk task is abandoned.const UIA_WALK_BACKSTOP_GRACE: std::time::Duration = std::time::Duration::from_millis(500);/// Deadline for the window capture, separate from the walk budget.@@ -1277,7 +1242,12 @@ impl Tool for GetWindowStateTool {.map(|v| v.max(1));let max_dim = {let cfg = self.state.config.read().unwrap();- resolve_max_image_dimension(cfg.max_image_dimension, max_image_dimension, max_dimension)+ cua_driver_core::image_utils::ImageDimensionLimits {+ configured: cfg.max_image_dimension,+ legacy_max_dimension: max_dimension,+ max_image_dimension,+ }+ .resolve()};// `capture_mode` is DEPRECATED and ignored — get_window_state always// returns BOTH the UIA tree and a screenshot now, so the agent grounds on@@ -2057,11 +2027,6 @@ async fn restore_foreground_polling_best_effort(prior_foreground_addr: usize, sppub struct LaunchAppTool;static LAUNCH_DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();-fn contains_remote_debugging_flag(value: &str) -> bool {- let lower = value.to_ascii_lowercase();- lower.contains("--remote-debugging-port") || lower.contains("--remote-debugging-pipe")-}-#[async_trait]impl Tool for LaunchAppTool {fn def(&self) -> &ToolDef {@@ -2227,10 +2192,10 @@ impl Tool for LaunchAppTool {.chain(path_opt.as_deref()).chain(name_opt.as_deref()).chain(extra_args.iter().map(String::as_str))- .any(contains_remote_debugging_flag)+ .any(cua_driver_core::launch_guard::contains_remote_debugging_flag){return ToolResult::error(- "Chromium remote-debugging flags moved to browser_prepare so DevTools is never enabled on an unproven user profile",+ cua_driver_core::launch_guard::REMOTE_DEBUGGING_LAUNCH_REFUSAL,);}@@ -3031,27 +2996,23 @@ fn finish_pixel_uia_attempt(PointInvokeOutcome::Timeout => "timeout",PointInvokeOutcome::Unavailable => "unavailable",};- Some(- ToolResult::error(format!(+ Some(cua_driver_core::delivery::background_unavailable_result(+ format!("UIA pixel click {status} for pid {pid}. No fallback input was sent. \The click effect is unknown; inspect the target state before another action. \If the provider does not recover, retry this action with delivery_mode:\"foreground\"."- ))- .with_structured(json!({- "code": "background_unavailable",+ ),+ "background_unavailable",+ format!(+ "the UIA provider is {status}; retry this action with delivery_mode:\"foreground\"."+ ),+ json!({"uia_status": status,"path": "ax","verified": false,"effect": "unverifiable",- "suggestion": "Retry this action with delivery_mode:\"foreground\".",- "escalation": {- "recommended": "foreground",- "reason": format!(- "the UIA provider is {status}; retry this action with delivery_mode:\"foreground\"."- ),- },- })),- )+ }),+ ))}enum BackgroundElementClick {@@ -10251,9 +10212,6 @@ mod set_window_frame_geometry_tests;#[cfg(test)]mod desktop_scope_tests;-#[cfg(test)]-mod browser_launch_guard_tests;-#[cfg(test)]mod pid_window_target_tests;diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/browser_launch_guard_tests.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/browser_launch_guard_tests.rsdeleted file mode 100644index af60987603..0000000000--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/browser_launch_guard_tests.rs+++ /dev/null@@ -1,13 +0,0 @@-use super::contains_remote_debugging_flag;--#[test]-fn rejects_all_chromium_remote_debugging_spellings() {- assert!(contains_remote_debugging_flag("--remote-debugging-port=0"));- assert!(contains_remote_debugging_flag("--REMOTE-DEBUGGING-PIPE"));- assert!(contains_remote_debugging_flag(- r#"C:\Program Files\Chrome\chrome.exe --remote-debugging-port 9222"#- ));- assert!(!contains_remote_debugging_flag(- r#"--user-data-dir=C:\Temp\profile"#- ));-}diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/cursor_key_resolution_tests.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/cursor_key_resolution_tests.rsindex 7baba3a989..c943b06a52 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/cursor_key_resolution_tests.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/cursor_key_resolution_tests.rs@@ -1,52 +1,18 @@use super::{resolve_cursor_key, NO_CURSOR};use serde_json::json;+/// Precedence is core `tool_args::session_key`'s contract; Windows only+/// owns the cursor-less fallback for a direct call without lifecycle+/// metadata.#[test]-fn direct_platform_call_without_lifecycle_resolves_to_no_cursor() {- // No session/cursor_id → NO_CURSOR (""): the action still runs but no- // cursor is shown. Canonical core dispatch injects `_session_id` before- // real platform calls.- assert_eq!(resolve_cursor_key(&json!({})), NO_CURSOR);+fn anonymous_direct_call_is_cursor_less() {assert_eq!(resolve_cursor_key(&json!({ "pid": 1 })), NO_CURSOR);- assert_eq!(- resolve_cursor_key(&json!({ "_session_id": "mcp-1-2" })),- "mcp-1-2"- );-}--#[test]-fn explicit_session_owns_a_cursor() {- assert_eq!(- resolve_cursor_key(&json!({ "session": "research-run" })),- "research-run"- );-}--#[test]-fn cursor_id_is_a_legacy_alias_and_session_wins() {- assert_eq!(- resolve_cursor_key(&json!({ "cursor_id": "user-handle" })),- "user-handle"- );- assert_eq!(- resolve_cursor_key(&json!({ "session": "s1", "cursor_id": "c1" })),- "s1"- );- assert_eq!(- resolve_cursor_key(&json!({ "_session_id": "implicit", "cursor_id": "c1" })),- "implicit"- );-}--#[test]-fn empty_strings_fall_through_to_no_cursor() {- // An empty `session` falls through to `cursor_id`; both empty → NO_CURSOR.- assert_eq!(- resolve_cursor_key(&json!({ "session": "", "cursor_id": "c1" })),- "c1"- );assert_eq!(resolve_cursor_key(&json!({ "session": "", "cursor_id": "" })),NO_CURSOR);+ assert_eq!(+ resolve_cursor_key(&json!({ "_session_id": "mcp-1-2" })),+ "mcp-1-2"+ );}diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/get_window_state_max_image_dimension_tests.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/get_window_state_max_image_dimension_tests.rsdeleted file mode 100644index 5273873505..0000000000--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/get_window_state_max_image_dimension_tests.rs+++ /dev/null@@ -1,20 +0,0 @@-use super::resolve_max_image_dimension;--#[test]-fn canonical_override_wins_and_zero_requests_native_resolution() {- assert_eq!(resolve_max_image_dimension(1568, None, None), 1568);- assert_eq!(resolve_max_image_dimension(1568, Some(800), None), 800);- assert_eq!(resolve_max_image_dimension(800, Some(1568), None), 1568);- assert_eq!(resolve_max_image_dimension(1568, Some(0), None), 0);- assert_eq!(- resolve_max_image_dimension(1568, Some(1200), Some(400)),- 1200- );-}--#[test]-fn omitted_canonical_override_preserves_legacy_folding() {- assert_eq!(resolve_max_image_dimension(1568, None, Some(800)), 800);- assert_eq!(resolve_max_image_dimension(800, None, Some(1568)), 800);- assert_eq!(resolve_max_image_dimension(0, None, Some(800)), 800);-}diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/list_windows_z_index_tests.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/list_windows_z_index_tests.rsindex 76c72dd1c9..7c6737a7e9 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/list_windows_z_index_tests.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_/list_windows_z_index_tests.rs@@ -1,13 +1,4 @@-use super::{exact_window_ownership_result, z_index_from_front_to_back};--#[test]-fn enum_windows_front_to_back_order_normalizes_to_higher_is_frontmost() {- let indices: Vec<_> = (0..3)- .map(|position| z_index_from_front_to_back(3, position))- .collect();- assert_eq!(indices, vec![2, 1, 0]);- assert!(indices[0] > indices[2]);-}+use super::exact_window_ownership_result;#[test]fn explicit_pid_hwnd_guard_refuses_wrong_or_stale_owners() {diff --git a/libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rs b/libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rsindex 13b609f0d0..67f875a168 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/uia/windows_enum.rs@@ -23,6 +23,8 @@ use std::sync::{mpsc, Arc, OnceLock};use std::thread;use std::time::Duration;+use cua_driver_core::single_flight::SingleFlight;+use anyhow::{bail, Context};use windows::core::{Interface, BSTR};use windows::Win32::Foundation::{HWND, RECT};@@ -71,93 +73,70 @@ enum UiaDeadlineError {/// Windows offers no safe way to cancel a COM provider call in another thread./// The gate therefore remains owned by a timed-out worker until that worker/// actually returns. Retries fail fast instead of stranding more threads, then-/// resume as soon as the provider call returns.-struct UiaSingleFlight {- in_flight: AtomicBool,+/// resume as soon as the provider call returns (no cooldown).+fn uia_single_flight() -> &'static Arc<SingleFlight> {+ static GATE: OnceLock<Arc<SingleFlight>> = OnceLock::new();+ GATE.get_or_init(|| Arc::new(SingleFlight::new(Duration::ZERO)))}-impl UiaSingleFlight {- const fn new() -> Self {- Self {- in_flight: AtomicBool::new(false),- }+/// Run `f` on a dedicated thread under `gate`. `f` receives the flag that is+/// set when the caller's deadline fires, so it can skip side effects the+/// caller will no longer observe.+fn run_uia_single_flight<T, F>(+ gate: &Arc<SingleFlight>,+ stage: &'static str,+ timeout: Duration,+ fallback: &'static str,+ f: F,+) -> Result<T, UiaDeadlineError>+where+ T: Send + 'static,+ F: FnOnce(Arc<AtomicBool>) -> T + Send + 'static,+{+ let Some(permit) = gate.try_acquire() else {+ tracing::debug!(+ target: "uia_windows_enum",+ "UIA {stage} skipped while another provider call is in flight"+ );+ return Err(UiaDeadlineError::Busy);+ };++ let (tx, rx) = mpsc::channel();+ let cancelled = permit.timeout_flag();+ let worker_cancelled = permit.timeout_flag();+ let spawn = thread::Builder::new()+ .name(format!("cua-uia-{stage}"))+ .spawn(move || {+ let _permit = permit;+ let result = f(worker_cancelled);+ let _ = tx.send(result);+ });++ if let Err(e) = spawn {+ // The unspawned closure, and with it the permit, is already dropped,+ // which reopened the gate.+ tracing::warn!(target: "uia_windows_enum", "failed to spawn UIA {stage} thread: {e}");+ return Err(UiaDeadlineError::Unavailable);}- fn run<T, F>(- self: &Arc<Self>,- stage: &'static str,- timeout: Duration,- fallback: &'static str,- f: F,- ) -> Result<T, UiaDeadlineError>- where- T: Send + 'static,- F: FnOnce(Arc<AtomicBool>) -> T + Send + 'static,- {- if self- .in_flight- .compare_exchange(false, true, Ordering::AcqRel, Ordering::Acquire)- .is_err()- {- tracing::debug!(+ match rx.recv_timeout(timeout) {+ Ok(result) => Ok(result),+ Err(mpsc::RecvTimeoutError::Timeout) => {+ cancelled.store(true, Ordering::Release);+ tracing::warn!(target: "uia_windows_enum",- "UIA {stage} skipped while another provider call is in flight"+ "UIA {stage} exceeded {}ms; falling back to {fallback}; no other UIA worker will start until this provider call returns",+ timeout.as_millis());- return Err(UiaDeadlineError::Busy);+ Err(UiaDeadlineError::Timeout)}-- let (tx, rx) = mpsc::channel();- let cancelled = Arc::new(AtomicBool::new(false));- let worker_cancelled = Arc::clone(&cancelled);- let worker_gate = Arc::clone(self);- let spawn = thread::Builder::new()- .name(format!("cua-uia-{stage}"))- .spawn(move || {- let _guard = InFlightGuard { gate: worker_gate };- let result = f(worker_cancelled);- let _ = tx.send(result);- });-- if let Err(e) = spawn {- self.in_flight.store(false, Ordering::Release);- tracing::warn!(target: "uia_windows_enum", "failed to spawn UIA {stage} thread: {e}");- return Err(UiaDeadlineError::Unavailable);+ Err(mpsc::RecvTimeoutError::Disconnected) => {+ tracing::warn!(target: "uia_windows_enum", "UIA {stage} thread exited without a result");+ Err(UiaDeadlineError::Unavailable)}-- match rx.recv_timeout(timeout) {- Ok(result) => Ok(result),- Err(mpsc::RecvTimeoutError::Timeout) => {- cancelled.store(true, Ordering::Release);- tracing::warn!(- target: "uia_windows_enum",- "UIA {stage} exceeded {}ms; falling back to {fallback}; no other UIA worker will start until this provider call returns",- timeout.as_millis()- );- Err(UiaDeadlineError::Timeout)- }- Err(mpsc::RecvTimeoutError::Disconnected) => {- tracing::warn!(target: "uia_windows_enum", "UIA {stage} thread exited without a result");- Err(UiaDeadlineError::Unavailable)- }- }- }-}--struct InFlightGuard {- gate: Arc<UiaSingleFlight>,-}--impl Drop for InFlightGuard {- fn drop(&mut self) {- self.gate.in_flight.store(false, Ordering::Release);}}-fn uia_single_flight() -> &'static Arc<UiaSingleFlight> {- static GATE: OnceLock<Arc<UiaSingleFlight>> = OnceLock::new();- GATE.get_or_init(|| Arc::new(UiaSingleFlight::new()))-}-fn run_uia_with_deadline<T, F>(stage: &'static str,timeout: Duration,@@ -181,7 +160,7 @@ whereT: Send + 'static,F: FnOnce(Arc<AtomicBool>) -> T + Send + 'static,{- uia_single_flight().run(stage, timeout, fallback, f)+ run_uia_single_flight(uia_single_flight(), stage, timeout, fallback, f)}struct ComInit {@@ -1170,7 +1149,7 @@ mod tests {#[test]fn wedged_provider_has_bounded_worker_growth_and_recovers_immediately() {- let gate = Arc::new(UiaSingleFlight::new());+ let gate = Arc::new(SingleFlight::new(Duration::ZERO));let (started_tx, started_rx) = mpsc::channel();let (release_tx, release_rx) = mpsc::channel();let starts = Arc::new(AtomicUsize::new(0));@@ -1179,23 +1158,24 @@ mod tests {let side_effects = Arc::new(AtomicUsize::new(0));let first_start = Instant::now();- let result = gate.run("test wedge", Duration::from_millis(20), "test", {- let starts = Arc::clone(&starts);- let active = Arc::clone(&active);- let max_active = Arc::clone(&max_active);- let side_effects = Arc::clone(&side_effects);- move |cancelled| {- starts.fetch_add(1, Ordering::AcqRel);- let current = active.fetch_add(1, Ordering::AcqRel) + 1;- max_active.fetch_max(current, Ordering::AcqRel);- started_tx.send(()).unwrap();- release_rx.recv().unwrap();- if !cancelled.load(Ordering::Acquire) {- side_effects.fetch_add(1, Ordering::AcqRel);+ let result =+ run_uia_single_flight(&gate, "test wedge", Duration::from_millis(20), "test", {+ let starts = Arc::clone(&starts);+ let active = Arc::clone(&active);+ let max_active = Arc::clone(&max_active);+ let side_effects = Arc::clone(&side_effects);+ move |cancelled| {+ starts.fetch_add(1, Ordering::AcqRel);+ let current = active.fetch_add(1, Ordering::AcqRel) + 1;+ max_active.fetch_max(current, Ordering::AcqRel);+ started_tx.send(()).unwrap();+ release_rx.recv().unwrap();+ if !cancelled.load(Ordering::Acquire) {+ side_effects.fetch_add(1, Ordering::AcqRel);+ }+ active.fetch_sub(1, Ordering::AcqRel);}- active.fetch_sub(1, Ordering::AcqRel);- }- });+ });assert!(matches!(result, Err(UiaDeadlineError::Timeout)));assert_eq!(PointInvokeOutcome::from_worker(result.map(|()| PointInvokeOutcome::Miss)),@@ -1207,9 +1187,15 @@ mod tests {let retries_start = Instant::now();for _ in 0..100 {let starts = Arc::clone(&starts);- let retry = gate.run("test retry", Duration::from_secs(1), "test", move |_| {- starts.fetch_add(1, Ordering::AcqRel);- });+ let retry = run_uia_single_flight(+ &gate,+ "test retry",+ Duration::from_secs(1),+ "test",+ move |_| {+ starts.fetch_add(1, Ordering::AcqRel);+ },+ );assert!(matches!(retry, Err(UiaDeadlineError::Busy)));assert_eq!(PointInvokeOutcome::from_worker(retry.map(|()| PointInvokeOutcome::Miss)),@@ -1222,24 +1208,25 @@ mod tests {release_tx.send(()).unwrap();let recovery_deadline = Instant::now() + Duration::from_secs(1);- while gate.in_flight.load(Ordering::Acquire) && Instant::now() < recovery_deadline {+ while gate.is_in_flight() && Instant::now() < recovery_deadline {thread::yield_now();}- assert!(!gate.in_flight.load(Ordering::Acquire));+ assert!(!gate.is_in_flight());assert_eq!(side_effects.load(Ordering::Acquire), 0);- let recovered = gate.run("test recovery", Duration::from_secs(1), "test", {- let starts = Arc::clone(&starts);- let active = Arc::clone(&active);- let max_active = Arc::clone(&max_active);- move |_| {- starts.fetch_add(1, Ordering::AcqRel);- let current = active.fetch_add(1, Ordering::AcqRel) + 1;- max_active.fetch_max(current, Ordering::AcqRel);- active.fetch_sub(1, Ordering::AcqRel);- 42- }- });+ let recovered =+ run_uia_single_flight(&gate, "test recovery", Duration::from_secs(1), "test", {+ let starts = Arc::clone(&starts);+ let active = Arc::clone(&active);+ let max_active = Arc::clone(&max_active);+ move |_| {+ starts.fetch_add(1, Ordering::AcqRel);+ let current = active.fetch_add(1, Ordering::AcqRel) + 1;+ max_active.fetch_max(current, Ordering::AcqRel);+ active.fetch_sub(1, Ordering::AcqRel);+ 42+ }+ });assert!(matches!(recovered, Ok(42)));assert_eq!(starts.load(Ordering::Acquire), 2);assert_eq!(max_active.load(Ordering::Acquire), 1);diff --git a/libs/cua-driver/rust/crates/platform-windows/src/win32/installed_apps.rs b/libs/cua-driver/rust/crates/platform-windows/src/win32/installed_apps.rsindex dc8e717c51..faa0cb7ae8 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/win32/installed_apps.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/win32/installed_apps.rs@@ -15,10 +15,12 @@//! Application.Id.use std::path::{Path, PathBuf};-use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};+use std::sync::atomic::Ordering;use std::sync::{mpsc, Arc, OnceLock};use std::thread;-use std::time::{Duration, Instant};+use std::time::Duration;++use cua_driver_core::single_flight::SingleFlight;use windows::core::{Interface, PCWSTR};use windows::Win32::Foundation::MAX_PATH;use windows::Win32::System::Com::{@@ -258,128 +260,84 @@ enum UwpScanDeadlineError {/// retries fail fast instead of accumulating one blocked thread per/// `list_apps` call. Once a late worker returns, a short cooldown prevents a/// hot retry loop against a broken package repository or token context.-struct UwpScanSingleFlight {- in_flight: AtomicBool,- cooldown_until_ms: AtomicU64,- cooldown_ms: u64,+fn uwp_scan_single_flight() -> &'static Arc<SingleFlight> {+ static GATE: OnceLock<Arc<SingleFlight>> = OnceLock::new();+ GATE.get_or_init(|| Arc::new(SingleFlight::new(UWP_SCAN_RECOVERY_COOLDOWN)))}-impl UwpScanSingleFlight {- const fn new(cooldown_ms: u64) -> Self {- Self {- in_flight: AtomicBool::new(false),- cooldown_until_ms: AtomicU64::new(0),- cooldown_ms,- }- }-- fn run<T, F>(self: &Arc<Self>, timeout: Duration, f: F) -> Result<T, UwpScanDeadlineError>- where- T: Send + 'static,- F: FnOnce() -> T + Send + 'static,- {- let now = uwp_scan_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(UwpScanDeadlineError::Busy);- }-- let (tx, rx) = mpsc::channel();- let timed_out = Arc::new(AtomicBool::new(false));- let worker_timed_out = Arc::clone(&timed_out);- let worker_gate = Arc::clone(self);- let spawn = thread::Builder::new()- .name("cua-uwp-package-scan".to_owned())- .spawn(move || {- let _guard = UwpScanInFlightGuard {- gate: worker_gate,- timed_out: worker_timed_out,- };- let _ = tx.send(f());- });-- if let Err(error) = spawn {- self.in_flight.store(false, Ordering::Release);- tracing::warn!(- target: "installed_apps",- "scan_uwp_packages: failed to start bounded WinRT worker: {error}"- );- return Err(UwpScanDeadlineError::Unavailable);- }-- match rx.recv_timeout(timeout) {- Ok(result) => Ok(result),- Err(mpsc::RecvTimeoutError::Timeout) => {- timed_out.store(true, Ordering::Release);- // Arm the cooldown here as well as in the worker guard. The- // worker can return in the narrow interval between- // `recv_timeout` expiring and observing `timed_out`; recording- // it on the caller side ensures that race cannot immediately- // launch another package query.- self.cooldown_until_ms.store(- uwp_scan_now_ms().saturating_add(self.cooldown_ms),- Ordering::Release,- );- tracing::warn!(- target: "installed_apps",- "scan_uwp_packages: current-user WinRT query exceeded {}ms; returning Start Menu apps without UWP results. No additional package worker will start until this query returns",- timeout.as_millis()- );- Err(UwpScanDeadlineError::Timeout)- }- Err(mpsc::RecvTimeoutError::Disconnected) => {+fn run_uwp_scan<T, F>(+ gate: &Arc<SingleFlight>,+ timeout: Duration,+ f: F,+) -> Result<T, UwpScanDeadlineError>+where+ T: Send + 'static,+ F: FnOnce() -> T + Send + 'static,+{+ let Some(permit) = gate.try_acquire() else {+ return Err(UwpScanDeadlineError::Busy);+ };+ let timed_out = permit.timeout_flag();++ let (tx, rx) = mpsc::channel();+ let spawn = thread::Builder::new()+ .name("cua-uwp-package-scan".to_owned())+ .spawn(move || {+ let _ = tx.send(f());+ if permit.timed_out() {tracing::warn!(target: "installed_apps",- "scan_uwp_packages: bounded WinRT worker exited without a result"+ "scan_uwp_packages: timed-out WinRT query returned; cooling down before retry");- Err(UwpScanDeadlineError::Unavailable)}- }- }-}+ // Dropping the permit arms the cooldown after a timeout and+ // reopens the gate.+ drop(permit);+ });-struct UwpScanInFlightGuard {- gate: Arc<UwpScanSingleFlight>,- timed_out: Arc<AtomicBool>,-}+ if let Err(error) = spawn {+ // The unspawned closure, and with it the permit, is already dropped,+ // which reopened the gate.+ tracing::warn!(+ target: "installed_apps",+ "scan_uwp_packages: failed to start bounded WinRT worker: {error}"+ );+ return Err(UwpScanDeadlineError::Unavailable);+ }-impl Drop for UwpScanInFlightGuard {- fn drop(&mut self) {- if self.timed_out.load(Ordering::Acquire) {- self.gate.cooldown_until_ms.store(- uwp_scan_now_ms().saturating_add(self.gate.cooldown_ms),- Ordering::Release,+ match rx.recv_timeout(timeout) {+ Ok(result) => Ok(result),+ Err(mpsc::RecvTimeoutError::Timeout) => {+ timed_out.store(true, Ordering::Release);+ // Arm the cooldown here as well as when the permit drops. The+ // worker can return in the narrow interval between `recv_timeout`+ // expiring and observing `timed_out`; recording it on the caller+ // side ensures that race cannot immediately launch another package+ // query.+ gate.arm_cooldown();+ tracing::warn!(+ target: "installed_apps",+ "scan_uwp_packages: current-user WinRT query exceeded {}ms; returning Start Menu apps without UWP results. No additional package worker will start until this query returns",+ timeout.as_millis());+ Err(UwpScanDeadlineError::Timeout)+ }+ Err(mpsc::RecvTimeoutError::Disconnected) => {tracing::warn!(target: "installed_apps",- "scan_uwp_packages: timed-out WinRT query returned; cooling down for {}ms before retry",- self.gate.cooldown_ms+ "scan_uwp_packages: bounded WinRT worker exited without a result");+ Err(UwpScanDeadlineError::Unavailable)}- self.gate.in_flight.store(false, Ordering::Release);}}-fn uwp_scan_single_flight() -> &'static Arc<UwpScanSingleFlight> {- static GATE: OnceLock<Arc<UwpScanSingleFlight>> = OnceLock::new();- GATE.get_or_init(|| {- Arc::new(UwpScanSingleFlight::new(- UWP_SCAN_RECOVERY_COOLDOWN.as_millis() as u64,- ))- })-}--fn uwp_scan_now_ms() -> u64 {- static START: OnceLock<Instant> = OnceLock::new();- START.get_or_init(Instant::now).elapsed().as_millis() as u64-}-fn scan_uwp_packages() -> Vec<InstalledApp> {- match uwp_scan_single_flight().run(UWP_SCAN_TIMEOUT, scan_uwp_packages_unbounded) {+ match run_uwp_scan(+ uwp_scan_single_flight(),+ UWP_SCAN_TIMEOUT,+ scan_uwp_packages_unbounded,+ ) {Ok(packages) => packages,Err(UwpScanDeadlineError::Busy) => {tracing::debug!(@@ -627,10 +585,11 @@ fn read_install_mtime(pkg: &windows::ApplicationModel::Package) -> Option<Stringmod tests {use super::*;use std::sync::atomic::AtomicUsize;+ use std::time::Instant;#[test]fn wedged_uwp_scan_has_bounded_worker_growth_and_recovers() {- let gate = Arc::new(UwpScanSingleFlight::new(40));+ let gate = Arc::new(SingleFlight::new(Duration::from_millis(500)));let starts = Arc::new(AtomicUsize::new(0));let active = Arc::new(AtomicUsize::new(0));let max_active = Arc::new(AtomicUsize::new(0));@@ -640,7 +599,7 @@ mod tests {let starts_for_worker = Arc::clone(&starts);let active_for_worker = Arc::clone(&active);let max_active_for_worker = Arc::clone(&max_active);- let first = gate.run(Duration::from_millis(20), move || {+ let first = run_uwp_scan(&gate, Duration::from_millis(20), move || {starts_for_worker.fetch_add(1, Ordering::SeqCst);let now_active = active_for_worker.fetch_add(1, Ordering::SeqCst) + 1;max_active_for_worker.fetch_max(now_active, Ordering::SeqCst);@@ -659,7 +618,7 @@ mod tests {for _ in 0..100 {assert_eq!(- gate.run(Duration::from_millis(20), || 99),+ run_uwp_scan(&gate, Duration::from_millis(20), || 99),Err(UwpScanDeadlineError::Busy));}@@ -670,18 +629,18 @@ mod tests {.send(()).expect("worker should still be listening");let wait_deadline = Instant::now() + Duration::from_secs(1);- while gate.in_flight.load(Ordering::Acquire) && Instant::now() < wait_deadline {+ while gate.is_in_flight() && Instant::now() < wait_deadline {thread::yield_now();}- assert!(!gate.in_flight.load(Ordering::Acquire));+ assert!(!gate.is_in_flight());assert_eq!(- gate.run(Duration::from_millis(20), || 99),+ run_uwp_scan(&gate, Duration::from_millis(20), || 99),Err(UwpScanDeadlineError::Busy),"a late return should enter cooldown");- thread::sleep(Duration::from_millis(50));- assert_eq!(gate.run(Duration::from_secs(1), || 42), Ok(42));+ thread::sleep(Duration::from_millis(600));+ assert_eq!(run_uwp_scan(&gate, Duration::from_secs(1), || 42), Ok(42));assert_eq!(max_active.load(Ordering::SeqCst), 1);}