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)(linux): typed no-usable-display error instead of 0/null screen size on WSL (#2006)

Francesco Bonacci1f70a53849fe
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/harness_web_windows_test.rs
similarity index 100%
rename from libs/cua-driver/rust/crates/cua-driver/tests/harness_web_test.rs
rename to libs/cua-driver/rust/crates/cua-driver/tests/harness_web_windows_test.rs
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/capture.rs b/libs/cua-driver/rust/crates/platform-linux/src/capture.rs
index 28908bb509..1483a9a18f 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/capture.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/capture.rs
@@ -138,12 +138,24 @@ pub(crate) fn screenshot_display_bytes_x11() -> Result<Vec<u8>> {
use x11rb::connection::Connection;
use x11rb::protocol::xproto::*;
use x11rb::rust_connection::RustConnection;
- let (conn, screen_num) = RustConnection::connect(None)?;
+ let (conn, screen_num) = RustConnection::connect(None)
+ .map_err(|e| anyhow::anyhow!("{e}{}", crate::no_display_hint()))?;
let root = conn.setup().roots[screen_num].root;
// Get root geometry.
let geom = conn.get_geometry(root)?.reply()?;
let w = geom.width as u32;
let h = geom.height as u32;
+ // WSLg / headless XWayland quirk: the X server connects but the root
+ // window reports a 0-px geometry until a real output is attached.
+ // `get_image` with w/h == 0 yields an empty buffer that later decodes
+ // to null/zero dimensions downstream. Fail with an actionable, typed
+ // error instead of emitting a 0-px image. See issue #2005.
+ if w == 0 || h == 0 {
+ anyhow::bail!(
+ "X11 root window reports a 0x0 geometry — no usable display to capture.{}",
+ crate::no_display_hint()
+ );
+ }
let img = conn.get_image(ImageFormat::Z_PIXMAP, root, 0, 0, w as u16, h as u16, !0u32)?.reply()?;
let bytes = img.data;
let bpp = match img.depth { 32 | 24 => 4usize, _ => anyhow::bail!("Unsupported depth") };
diff --git a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
index 248529e802..c7b387df65 100644
--- a/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
+++ b/libs/cua-driver/rust/crates/platform-linux/src/lib.rs
@@ -51,6 +51,59 @@ pub mod terminal;
#[cfg(target_os = "linux")]
pub mod xauth;
+/// Pure WSL-detection predicate, split out from [`is_wsl`] so both branches
+/// are unit-testable without the process-global env / `OnceLock` cache.
+/// `wsl_env` mirrors `$WSL_DISTRO_NAME`/`$WSL_INTEROP` being set; `osrelease`
+/// is the `/proc/sys/kernel/osrelease` contents.
+fn detect_wsl(wsl_env_set: bool, osrelease: Option<&str>) -> bool {
+ if wsl_env_set {
+ return true;
+ }
+ osrelease
+ .map(|s| {
+ let s = s.to_ascii_lowercase();
+ s.contains("microsoft") || s.contains("wsl")
+ })
+ .unwrap_or(false)
+}
+
+/// True when this process is running under WSL (Windows Subsystem for Linux).
+/// WSL leaks its identity through the kernel release string ("microsoft" /
+/// "WSL") and `/proc/sys/kernel/osrelease`. Cheap, side-effect-free, cached
+/// after the first probe.
+pub fn is_wsl() -> bool {
+ use std::sync::OnceLock;
+ static IS_WSL: OnceLock<bool> = OnceLock::new();
+ *IS_WSL.get_or_init(|| {
+ let env_set = std::env::var_os("WSL_DISTRO_NAME").is_some()
+ || std::env::var_os("WSL_INTEROP").is_some();
+ let osrelease = std::fs::read_to_string("/proc/sys/kernel/osrelease").ok();
+ detect_wsl(env_set, osrelease.as_deref())
+ })
+}
+
+/// Actionable hint appended to "no usable display" errors. Tailored for WSL,
+/// where the common failure is "no real X/Wayland display, or WSLg geometry
+/// isn't resolvable". Kept as a trailing fragment so callers can splice it
+/// onto a more specific message. See issue #2005.
+pub fn no_display_hint() -> String {
+ let neither_display_set =
+ std::env::var_os("DISPLAY").is_none() && std::env::var_os("WAYLAND_DISPLAY").is_none();
+ if is_wsl() {
+ " — no usable display detected (WSL). WSLg provides $DISPLAY/$WAYLAND_DISPLAY \
+ under a recent Windows 11 + 'wsl --update'; on older setups install an X server \
+ (e.g. VcXsrv) and export DISPLAY. cua-driver needs a real display to capture and \
+ report screen size."
+ .to_owned()
+ } else if neither_display_set {
+ " — no usable display detected: neither $DISPLAY (X11) nor $WAYLAND_DISPLAY is set. \
+ Start an X server / Wayland compositor (or Xvfb for headless) before running cua-driver."
+ .to_owned()
+ } else {
+ String::new()
+ }
+}
+
pub fn register_tools() -> ToolRegistry {
#[cfg(target_os = "linux")]
wayland::ensure_nested_session();
@@ -70,3 +123,33 @@ pub fn register_tools_with_cursor(cfg: cursor_overlay::CursorConfig, compat: boo
}
tools::build_registry(compat)
}
+
+#[cfg(test)]
+mod display_detection_tests {
+ use super::detect_wsl;
+
+ #[test]
+ fn wsl_env_var_short_circuits() {
+ // $WSL_DISTRO_NAME / $WSL_INTEROP present → WSL regardless of osrelease.
+ assert!(detect_wsl(true, None));
+ assert!(detect_wsl(true, Some("6.1.0-generic")));
+ }
+
+ #[test]
+ fn wsl2_osrelease_microsoft_tag_detected() {
+ // Real WSL2 kernel release string (verified live on a WSL2 box).
+ assert!(detect_wsl(false, Some("6.18.33.1-microsoft-standard-WSL2")));
+ }
+
+ #[test]
+ fn wsl1_osrelease_microsoft_tag_detected() {
+ // WSL1 kernels also carry the Microsoft tag, mixed-case.
+ assert!(detect_wsl(false, Some("4.4.0-19041-Microsoft")));
+ }
+
+ #[test]
+ fn plain_linux_is_not_wsl() {
+ assert!(!detect_wsl(false, Some("6.8.0-39-generic")));
+ assert!(!detect_wsl(false, None));
+ }
+}
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 08da3548cb..cb6dbae181 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
@@ -2794,18 +2794,32 @@ impl Tool for GetScreenSizeTool {
let result = tokio::task::spawn_blocking(|| {
use x11rb::connection::Connection;
use x11rb::rust_connection::RustConnection;
- let (conn, screen_num) = RustConnection::connect(None)?;
+ let (conn, screen_num) = RustConnection::connect(None)
+ .map_err(|e| anyhow::anyhow!("{e}{}", crate::no_display_hint()))?;
let setup = conn.setup();
let screen = &setup.roots[screen_num];
+ let w = screen.width_in_pixels as u32;
+ let h = screen.height_in_pixels as u32;
+ // WSLg / headless XWayland quirk: the X server connects but the
+ // root screen advertises a 0-px geometry until a real output is
+ // attached. Returning {width:0,height:0} here would propagate a
+ // success with zero dimensions to the client, which then either
+ // divides by zero when scaling or feeds the value into `int(...)`
+ // after the missing key collapses to None. Fail loudly with an
+ // actionable, typed error instead (never emit a 0/null where the
+ // client expects a usable int). See issue #2005.
+ if w == 0 || h == 0 {
+ anyhow::bail!(
+ "X11 connected but reports a 0x0 root screen — no usable \
+ display geometry.{}",
+ crate::no_display_hint()
+ );
+ }
// X11 reports pixel dimensions; scale factor on X11 is not
// well-defined per-monitor, so report 1.0 (matches DPI-unaware
// assumption). Wayland/HiDPI X11 callers should query
// `xrandr --query` for true scale.
- Ok::<(u32, u32, f64), anyhow::Error>((
- screen.width_in_pixels as u32,
- screen.height_in_pixels as u32,
- 1.0,
- ))
+ Ok::<(u32, u32, f64), anyhow::Error>((w, h, 1.0))
}).await;
match result {
// Matches Swift text format 1:1.