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.

9.3 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 Cua AI, Inc.

//! Linux platform backend for cua-driver-rs.
//!
//! Background automation on Linux via:
//! - /proc filesystem for process enumeration
//! - X11 _NET_CLIENT_LIST for window enumeration
//! - X11 XSendEvent for background mouse/keyboard injection (no focus steal)
//! - AT-SPI D-Bus protocol for accessibility tree (via subprocess bridge)
//! - xwd/scrot/import for window screenshots
//!
//! Wayland: falls back to xdg-output and virtual-keyboard protocols when
//! running under a Wayland compositor with XWayland support.

// Off Linux the crate still builds (so workspace-wide checks compile on every
// host) but its native backends are cfg'd out, which strands the shared
// helpers they call. They are live on Linux, where dead_code stays enforced.
#![cfg_attr(not(target_os = "linux"), allow(dead_code))]
// Tool helpers return `Result<_, ToolResult>`: the error arm is the finished
// tool reply (see the note in cua-driver-core), not a propagated error.
#![allow(clippy::result_large_err)]

use cua_driver_core::tool::ToolRegistry;

pub mod health_report;
pub mod overlay;
pub mod overlay_capture;
pub mod pip;
pub mod tools;

#[cfg(target_os = "linux")]
pub mod x11;

#[cfg(any(target_os = "linux", test))]
mod x11_client_pid;

#[cfg(target_os = "linux")]
pub mod input;

#[cfg(target_os = "linux")]
pub mod tty;

#[cfg(target_os = "linux")]
pub mod proc_fs;

#[cfg(target_os = "linux")]
pub mod history;

#[cfg(target_os = "linux")]
pub mod browser_platform;

#[cfg(target_os = "linux")]
mod browser_setup_ui;

#[cfg(target_os = "linux")]
mod browser_consent_ui;

#[cfg(target_os = "linux")]
pub mod installed_apps;

#[cfg(target_os = "linux")]
pub mod capture;
mod capture_action_frame;
#[cfg(target_os = "linux")]
mod clipboard;
#[cfg(target_os = "linux")]
mod interaction;

#[cfg(target_os = "linux")]
pub mod atspi;

#[cfg(any(target_os = "linux", test))]
mod snapshot_queries;

#[cfg(target_os = "linux")]
pub mod a11y;

#[cfg(target_os = "linux")]
pub mod recording_hooks;

#[cfg(target_os = "linux")]
pub mod video_wayland;

#[cfg(target_os = "linux")]
pub mod wayland;

// Pure AT-SPI role / X cursor name tables for presence cursor shapes; tested
// on every host.
pub mod pointer_shape_map;

#[cfg(target_os = "linux")]
pub mod pointer_shape;

/// Install the Linux [`cua_driver_core::pointer_shape::PointerShapeBackend`]
/// (and the X11 real-cursor probe for `cursor_shape`). False off Linux, when
/// no display is reachable, or when a backend is already installed.
pub fn install_pointer_shape_backend() -> bool {
    #[cfg(target_os = "linux")]
    {
        pointer_shape::install()
    }
    #[cfg(not(target_os = "linux"))]
    {
        false
    }
}

// `terminal` is OS-independent (pure string matching + a thin x11 hook).
// Keeping it un-gated lets the unit tests run on any host.
pub mod terminal;

// Pure background pixel-click routing facts; un-gated so their unit tests run
// on every host.
#[cfg_attr(not(target_os = "linux"), allow(dead_code))]
mod at_point_policy;

#[cfg(target_os = "linux")]
pub mod xauth;

#[cfg(target_os = "linux")]
pub mod session_bus;

/// Process-environment overrides for unit tests. Every lib test that changes
/// display variables must go through [`test_env::unreachable_x11_display`] so
/// writers are serialized and the prior values are restored even on panic.
#[cfg(all(test, target_os = "linux"))]
pub(crate) mod test_env {
    use std::ffi::OsString;
    use std::sync::{Mutex, MutexGuard};

    static ENV_LOCK: Mutex<()> = Mutex::new(());

    pub(crate) struct DisplayOverride {
        display: Option<OsString>,
        wayland_display: Option<OsString>,
        _lock: MutexGuard<'static, ()>,
    }

    /// Point `DISPLAY` at a server that cannot exist and hide
    /// `WAYLAND_DISPLAY`, so the X11 path is taken and its connect fails
    /// regardless of the host session.
    pub(crate) fn unreachable_x11_display() -> DisplayOverride {
        x11_display(":9999999")
    }

    /// Point `DISPLAY` at `display` and hide `WAYLAND_DISPLAY`.
    pub(crate) fn x11_display(display: &str) -> DisplayOverride {
        let lock = ENV_LOCK
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let guard = DisplayOverride {
            display: std::env::var_os("DISPLAY"),
            wayland_display: std::env::var_os("WAYLAND_DISPLAY"),
            _lock: lock,
        };
        std::env::set_var("DISPLAY", display);
        std::env::remove_var("WAYLAND_DISPLAY");
        guard
    }

    impl Drop for DisplayOverride {
        fn drop(&mut self) {
            for (name, value) in [
                ("DISPLAY", self.display.take()),
                ("WAYLAND_DISPLAY", self.wayland_display.take()),
            ] {
                match value {
                    Some(value) => std::env::set_var(name, value),
                    None => std::env::remove_var(name),
                }
            }
        }
    }
}

/// 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();
    tools::build_registry(false)
}

/// `compat` is a legacy Claude Code compatibility flag with no current
/// tool-surface effect. It remains accepted for launch compatibility.
pub fn register_tools_with_cursor(cfg: cursor_overlay::CursorConfig, compat: bool) -> ToolRegistry {
    register_tools_with_cursor_and_provider(None, cfg, compat)
}

pub fn register_tools_with_cursor_and_provider(
    provider: Option<std::sync::Arc<dyn cua_driver_core::consent::ProtectedConsentProvider>>,
    cfg: cursor_overlay::CursorConfig,
    compat: bool,
) -> ToolRegistry {
    #[cfg(target_os = "linux")]
    wayland::ensure_nested_session();
    #[cfg(target_os = "linux")]
    wayland::overlay::set_config(cfg.clone());
    if cfg.enabled {
        overlay::init(cfg.clone());
        overlay::run_on_thread();
    }
    tools::build_registry_with_provider(compat, provider)
}

/// Standalone daemon startup recovery. Keep this out of registry construction:
/// read-only commands such as describe/list-tools must not mutate X11 devices.
#[cfg(target_os = "linux")]
pub fn recover_orphaned_mpx_devices() {
    input::reap_orphaned_master_pointers();
}

#[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));
    }
}