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
docs(cua-driver): update delivery_mode wording in comments (#2092)
injaneitye46456923c13
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 58f59b8159..7618e109d3 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -183,7 +183,7 @@ Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill### `bring_to_front`-Persistently activate an app so it genuinely holds macOS foreground, then leave it there. Most input does NOT need this — every macOS dispatch reaches backgrounded windows, and `dispatch:"foreground"` does its own brief front→act→restore. Reach for `bring_to_front` only for a focus-proxy surface that re-arms its own input channel on activation and must stay frontmost across the interaction — chiefly a remote-desktop client (Microsoft Windows App / RDP), where the brief flash drops keystrokes. Fronts the exact macOS window through WindowServer when `window_id` is present, with app-level Cocoa activation as a fallback. This DOES steal foreground — explicit opt-in, never used by the input ladder.+Persistently activate an app so it genuinely holds macOS foreground, then leave it there. Most input does NOT need this — every macOS dispatch reaches backgrounded windows, and `delivery_mode:"foreground"` does its own brief front→act→restore. Reach for `bring_to_front` only for a focus-proxy surface that re-arms its own input channel on activation and must stay frontmost across the interaction — chiefly a remote-desktop client (Microsoft Windows App / RDP), where the brief flash drops keystrokes. Fronts the exact macOS window through WindowServer when `window_id` is present, with app-level Cocoa activation as a fallback. This DOES steal foreground — explicit opt-in, never used by the input ladder.**Arguments:**diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rsindex a71831a292..29c6b66c03 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/harness_winui3_test.rs@@ -248,7 +248,7 @@ fn harness_winui3_xaml_popup_open() {/// Regression guard for the click → TogglePattern dispatch fix./// cua-driver `click` now tries Invoke → Toggle → SelectionItem →/// ExpandCollapse before falling through to PostMessage, so WinUI3-/// CheckBox toggles correctly via UIA without needing dispatch:foreground.+/// CheckBox toggles correctly via UIA without needing delivery_mode:foreground.#[test]#[ignore]fn harness_winui3_checkbox_toggle() {diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rsindex 43e334432f..61f48b5f71 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/harness_wpf_test.rs@@ -24,7 +24,7 @@//! sandbox runner unignores them explicitly via the `--ignored` arg.//!//! **Foreground-lock caveat:** a handful of these tests (`double_click`,-//! `right_click`, `type_text`) rely on `dispatch:"foreground"` to reach+//! `right_click`, `type_text`) rely on `delivery_mode:"foreground"` to reach//! WPF's input chain reliably. Windows' system-wide foreground-lock//! kicks in after ~30s with no real user input — once that happens,//! `SetForegroundWindow` is denied for non-UIAccess processes and the@@ -95,7 +95,7 @@ fn launch_harness_with_state_file(// wait happens via polling in find_window. A 200ms-only// wait turned out to be too short for the harness to establish// foreground reliably under test-batch load, which caused- // SetForegroundWindow-needing tests (dispatch:foreground) to+ // SetForegroundWindow-needing tests (delivery_mode:foreground) to// fail with a foreground-lock rejection.std::thread::sleep(Duration::from_millis(800));Some(pid)@@ -535,7 +535,7 @@ fn harness_wpf_type_text() {// WPF's TextBox needs *keyboard focus* for WM_CHAR delivery — and// PostMessage(WM_LBUTTONDOWN) doesn't reliably transfer keyboard// focus (WPF's input system treats posted events differently from- // real ones). Use dispatch:"foreground" → SendInput synthesizes+ // real ones). Use delivery_mode:"foreground" → SendInput synthesizes// an OS-level click that WPF treats identically to a user mouse,// landing actual keyboard focus on the TextBox.let _ = driver.call(@@ -666,7 +666,7 @@ fn harness_wpf_right_click() {let snap = snapshot(driver, pid, wid);let idx = ax::element_index_by_id(snap.text(), "border-click-target").expect("border-click-target not in snapshot");- // Same dispatch:foreground rationale as type_text — PostMessage+ // Same delivery_mode:foreground rationale as type_text — PostMessage// WM_RBUTTONDOWN doesn't always reach WPF's MouseRightButtonDown// routed-event chain (intermittent in batch runs).let resp = driver.call(@@ -709,7 +709,7 @@ fn harness_wpf_double_click() {let snap = snapshot(driver, pid, wid);let idx = ax::element_index_by_id(snap.text(), "border-click-target").expect("border-click-target not in snapshot");- // dispatch:foreground for the same reason as right_click —+ // delivery_mode:foreground for the same reason as right_click —// PostMessage WM_LBUTTONDOWN ×2 doesn't always reach WPF's// MouseDoubleClick / ClickCount=2 path under test-batch load.let resp = driver.call(@@ -1144,7 +1144,7 @@ fn harness_wpf_slider_drag() {// Regression guard for the SendInput drag path. PostMessage drag// doesn't update GetKeyState, so WPF's Thumb-drag handler (which// polls Mouse.LeftButton via GetKeyState) never sees the button- // held — the thumb stays put. dispatch:"foreground" routes through+ // held — the thumb stays put. delivery_mode:"foreground" routes through// send_drag_synthesized which goes via the system input queue and// DOES update GetKeyState, so the thumb actually tracks.//@@ -1323,7 +1323,7 @@ fn harness_wpf_checkbox_toggle() {// CheckBox exposes UIA TogglePattern (actions=[toggle]), not Invoke.// cua-driver's click tool tries UIA Invoke first; for elements that// don't support it the PostMessage fallback path runs. Use- // dispatch:"foreground" to land a SendInput click that WPF+ // delivery_mode:"foreground" to land a SendInput click that WPF// recognises as a real user click and processes through Toggle.let resp = driver.call("click",@@ -1363,7 +1363,7 @@ fn harness_wpf_radio_select() {let snap = snapshot(driver, pid, wid);let idx = ax::element_index_by_id(snap.text(), "rdo-high").expect("rdo-high missing");// RadioButton exposes SelectionItem pattern (actions=[select]).- // Same dispatch:foreground rationale as the checkbox test.+ // Same delivery_mode:foreground rationale as the checkbox test.let response = driver.call("click",serde_json::json!({diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rsindex 75f5908165..d2aaa26eee 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/bring_to_front.rs@@ -4,7 +4,7 @@//! swap before driving a focus-proxy target — a window that only accepts input//! while its host app genuinely holds activation. The macOS input rungs never//! need this internally: every `CGEvent.postToPid` dispatch reaches a-//! backgrounded window, and the `dispatch:"foreground"` rung does its own+//! backgrounded window, and the `delivery_mode:"foreground"` rung does its own//! sub-millisecond front→act→restore flash. The one surface that flash can't//! satisfy is a remote-desktop client (e.g. Microsoft's Windows App / RDP),//! which re-establishes its keyboard channel with the remote host *on@@ -35,7 +35,7 @@ fn def() -> &'static ToolDef {name: "bring_to_front".into(),description: "Persistently activate an app so it genuinely holds macOS foreground, \then leave it there. Most input does NOT need this — every macOS \- dispatch reaches backgrounded windows, and `dispatch:\"foreground\"` \+ dispatch reaches backgrounded windows, and `delivery_mode:\"foreground\"` \does its own brief front→act→restore. Reach for `bring_to_front` only \for a focus-proxy surface that re-arms its own input channel on \activation and must stay frontmost across the interaction — chiefly a \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 93aca9a094..e5c641d0a0 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@@ -187,7 +187,7 @@ pub fn would_be_silently_dropped(hwnd: u64, kind: EventKind) -> bool {// clicks, drawing-area widgets accept them. We cannot distinguish// at the HWND level (single HWND for the whole GTK window) so we// flag mouse clicks broadly. Canvas-style drag works in practice;- // caller can still opt to retry with dispatch:"background" on the+ // caller can still opt to retry with delivery_mode:"background" on the// drag path if the click error wasn't actually load-bearing.return matches!(kind, MouseClick);}@@ -200,7 +200,7 @@ pub fn would_be_silently_dropped(hwnd: u64, kind: EventKind) -> bool {// Alt+F4) silently fail. Plain WM_CHAR text input through the// document widgets still works (verified end-to-end against// Writer's main editing area). Flag the keystroke-class events- // so dispatch:"background" surfaces a structured error instead+ // so delivery_mode:"background" surfaces a structured error instead// of pretending to succeed.return matches!(kind, Keystroke | KeyCombo);}@@ -323,7 +323,7 @@ pub fn read_class_name(hwnd: u64) -> String {}/// Build the structured `background_unavailable` error returned when-/// `dispatch:"background"` would silently drop.+/// `delivery_mode:"background"` would silently drop.pub fn background_unavailable_error(hwnd: u64,kind: EventKind,diff --git a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rsindex 7c22217467..e47db06a2d 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/uia/mod.rs@@ -297,7 +297,7 @@ unsafe fn walk_tree_unsafe(// The diagnostic tells callers exactly how to drive the SAL// dialog without the tree: pixel click off the screenshot// get_window_state always returns, or press_key with- // dispatch:"foreground" for accelerator-style dismissal. That's enough for the+ // delivery_mode:"foreground" for accelerator-style dismissal. That's enough for the// common modal-dismissal case (Yes/No/Esc on a Confirmation),// which is what SAL dialogs almost always need.let is_sal = {