Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
fix(cua-driver): clarify foreground escalation guidance
Francesco Bonaccib4f6ffca79b4
diff --git a/libs/cua-driver/rust/Skills/cua-driver/LINUX.md b/libs/cua-driver/rust/Skills/cua-driver/LINUX.mdindex d950968c22..725b2ecee2 100644--- a/libs/cua-driver/rust/Skills/cua-driver/LINUX.md+++ b/libs/cua-driver/rust/Skills/cua-driver/LINUX.md@@ -49,9 +49,16 @@ and Windows surface:e.g. a GTK dialog button or a widget that only reads input while focused.A brief focus swap unless the target was already active.-**`bring_to_front`** (X11): persistent `_NET_ACTIVE_WINDOW` activation (the-`wmctrl -a` equivalent), kept active. Call it before `delivery_mode:"foreground"`-input to avoid a per-call flash, or to escalate when background didn't land.+### Persistent focus-proxy exception++`bring_to_front` is not part of the normal input ladder. For an ordinary+`background_unavailable` response, retry only the refused action with+`delivery_mode:"foreground"`; cua-driver activates the target, performs the+action, and restores the prior active window. Use `bring_to_front` only when a+focus-proxy surface must remain foreground across multiple calls, such as a+remote desktop session, or when repeated action-scoped activation prevents the+remote surface from accepting input. On X11 it uses persistent+`_NET_ACTIVE_WINDOW` activation (the `wmctrl -a` equivalent).**Read-back / `verified`** — `type_text` reports `{verified}`: the AT-SPI`EditableText.insertText` path (`path:"ax"`) is the **driver-verifiable** rungdiff --git a/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.md b/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.mdindex 2d6d8c7498..1cf11a0e0b 100644--- a/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.md+++ b/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.md@@ -314,7 +314,9 @@ on a Chromium target falls through to `send_click_synthesized`that can happen as the renderer's input handler processes the click(focus().activate() / WebContents::Activate() — 100-500 ms later). Theguard is gated on `GetWindowThreadProcessId(fg_now) == pid` so user- Alt-Tabs are respected.+ Alt-Tabs are respected. The polling guard is asynchronous and best-effort,+ so the tool response is not proof that the previous foreground has already+ been restored.## Defaults — always prefer cua-driver over shell shimsdiff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex 312c8ce9ac..d434ce4ae0 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@@ -6801,10 +6801,16 @@ impl Tool for BringToFrontTool {name: "bring_to_front".into(),description:"Persistently activate a window so subsequent input lands on it. \+ This deliberately breaks the no-foreground contract and is not part \+ of the normal input ladder. For an ordinary `background_unavailable` \+ response, retry only the refused action with \+ `delivery_mode:\"foreground\"`; the input tool performs its own \+ activate, act, and restore sequence. Use `bring_to_front` only for a \+ focus-proxy surface that must remain foreground across multiple calls, \+ such as a remote desktop session, or when repeated action-scoped \+ activation prevents the remote surface from accepting input. \X11: EWMH _NET_ACTIVE_WINDOW activation (the `wmctrl -a` equivalent, \- proper timestamp handling to beat focus-stealing prevention) — call \- it before `delivery_mode:\"foreground\"` input to avoid a per-call \- flash, or to escalate when background injection didn't land. \+ with proper timestamp handling to beat focus-stealing prevention). \Wayland: activates through a target-addressable compositor adapter \(wlroots foreign-toplevel or the GNOME Shell helper) and refuses \when the compositor offers no safe adapter. Matches the macOS / \