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): 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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: &WindowTargetCandidat
result
}
+/// 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.rs
index 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.rs
index 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_.rs
index 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.rs
deleted file mode 100644
index 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.rs
index 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.rs
index 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.rs
index 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"`, the
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/windows.rs b/libs/cua-driver/rust/crates/platform-macos/src/windows.rs
index 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(&current_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.rs
index 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.rs
index 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_.rs
index 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, sp
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")
-}
-
#[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.rs
deleted file mode 100644
index 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.rs
index 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.rs
deleted file mode 100644
index 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.rs
index 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.rs
index 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 @@ where
T: 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.rs
index 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<String
mod 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);
}