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): 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.md
index 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** rung
diff --git a/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.md b/libs/cua-driver/rust/Skills/cua-driver/WINDOWS.md
index 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). The
guard 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 shims
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 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 / \