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): restore embedded-host builds on macOS and Linux (#3687)

Anthony2dbc1c2cfbee
diff --git a/.github/workflows/ci-rust-linux.yml b/.github/workflows/ci-rust-linux.yml
index 860e82afc6..d9e3749a40 100644
--- a/.github/workflows/ci-rust-linux.yml
+++ b/.github/workflows/ci-rust-linux.yml
@@ -3,6 +3,7 @@ name: "CI: Rust Linux unit"
on:
pull_request:
paths:
+ - "libs/cua-driver/rust/crates/cua-driver-sdk/**"
- "libs/cua-driver/rust/.cargo/**"
- "libs/cua-driver/rust/Cargo.toml"
- "libs/cua-driver/rust/Cargo.lock"
@@ -23,6 +24,7 @@ on:
push:
branches: [main]
paths:
+ - "libs/cua-driver/rust/crates/cua-driver-sdk/**"
- "libs/cua-driver/rust/.cargo/**"
- "libs/cua-driver/rust/Cargo.toml"
- "libs/cua-driver/rust/Cargo.lock"
@@ -129,6 +131,9 @@ jobs:
- name: Run Linux Rust tests
working-directory: libs/cua-driver/rust
run: cargo test -p cua-driver -p cua-driver-contract -p cua-driver-core -p cua-driver-testkit -p cursor-overlay -p cursor-theme-cli -p platform-linux --all-targets --locked
+ - name: Compile and link an async-io embedded host
+ working-directory: libs/cua-driver/rust
+ run: cargo test -p cua-driver-sdk --test async_io_embedding --locked
- name: Verify final-frame extraction without a desktop
working-directory: libs/cua-driver/rust
run: |
diff --git a/libs/cua-driver/rust/Cargo.lock b/libs/cua-driver/rust/Cargo.lock
index 544b50af01..1f4c36cfba 100644
--- a/libs/cua-driver/rust/Cargo.lock
+++ b/libs/cua-driver/rust/Cargo.lock
@@ -27,6 +27,7 @@ dependencies = [
"cfg-if",
"cipher 0.4.4",
"cpufeatures 0.2.17",
+ "zeroize",
]
[[package]]
@@ -185,7 +186,6 @@ dependencies = [
"getrandom 0.4.2",
"serde",
"serde_repr",
- "tokio",
"zbus",
]
@@ -282,6 +282,17 @@ dependencies = [
"slab",
]
+[[package]]
+name = "async-fs"
+version = "2.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8034a681df4aed8b8edbd7fbe472401ecf009251c8b40556b304567052e294c5"
+dependencies = [
+ "async-lock",
+ "blocking",
+ "futures-lite",
+]
+
[[package]]
name = "async-io"
version = "2.6.0"
@@ -826,6 +837,7 @@ checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
dependencies = [
"crypto-common 0.1.7",
"inout 0.1.4",
+ "zeroize",
]
[[package]]
@@ -1241,6 +1253,7 @@ dependencies = [
"cua-driver-contract",
"cua-driver-core",
"cursor-overlay",
+ "oo7",
"platform-linux",
"platform-macos",
"platform-windows",
@@ -2364,6 +2377,12 @@ dependencies = [
"windows-link 0.2.1",
]
+[[package]]
+name = "libm"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981"
+
[[package]]
name = "libredox"
version = "0.1.17"
@@ -2449,6 +2468,16 @@ dependencies = [
"regex-automata",
]
+[[package]]
+name = "md-5"
+version = "0.10.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
+dependencies = [
+ "cfg-if",
+ "digest",
+]
+
[[package]]
name = "memchr"
version = "2.8.0"
@@ -2643,6 +2672,23 @@ dependencies = [
"num-traits",
]
+[[package]]
+name = "num-bigint-dig"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7f9a86e097b0d187ad0e65667c2f58b9254671e86e7dbb78036b16692eae099"
+dependencies = [
+ "libm",
+ "num-integer",
+ "num-iter",
+ "num-traits",
+ "once_cell",
+ "rand 0.9.5",
+ "serde",
+ "smallvec",
+ "zeroize",
+]
+
[[package]]
name = "num-cmp"
version = "0.1.0"
@@ -3002,6 +3048,41 @@ version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+[[package]]
+name = "oo7"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78f2bfed90f1618b4b48dcad9307f25e14ae894e2949642c87c351601d62cebd"
+dependencies = [
+ "aes",
+ "ashpd",
+ "async-fs",
+ "async-io",
+ "async-lock",
+ "blocking",
+ "cbc",
+ "cipher 0.4.4",
+ "digest",
+ "endi",
+ "futures-lite",
+ "futures-util",
+ "getrandom 0.4.2",
+ "hkdf",
+ "hmac",
+ "md-5",
+ "num",
+ "num-bigint-dig",
+ "pbkdf2",
+ "serde",
+ "serde_bytes",
+ "sha2",
+ "subtle",
+ "zbus",
+ "zbus_macros",
+ "zeroize",
+ "zvariant",
+]
+
[[package]]
name = "openssl"
version = "0.10.80"
@@ -3106,6 +3187,16 @@ dependencies = [
"windows-link 0.2.1",
]
+[[package]]
+name = "pbkdf2"
+version = "0.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8ed6a7761f76e3b9f92dfb0a60a6a6477c61024b775147ff0973a02653abaf2"
+dependencies = [
+ "digest",
+ "hmac",
+]
+
[[package]]
name = "percent-encoding"
version = "2.3.2"
@@ -3487,10 +3578,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5ca0ecfa931c29007047d1bc58e623ab12e5590e8c7cc53200d5202b69266d8a"
dependencies = [
"libc",
- "rand_chacha",
+ "rand_chacha 0.3.1",
"rand_core 0.6.4",
]
+[[package]]
+name = "rand"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41"
+dependencies = [
+ "rand_chacha 0.9.0",
+ "rand_core 0.9.5",
+]
+
[[package]]
name = "rand"
version = "0.10.2"
@@ -3512,6 +3613,16 @@ dependencies = [
"rand_core 0.6.4",
]
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core 0.9.5",
+]
+
[[package]]
name = "rand_core"
version = "0.6.4"
@@ -3521,6 +3632,15 @@ dependencies = [
"getrandom 0.2.17",
]
+[[package]]
+name = "rand_core"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
[[package]]
name = "rand_core"
version = "0.10.1"
@@ -3886,6 +4006,16 @@ dependencies = [
"serde_derive",
]
+[[package]]
+name = "serde_bytes"
+version = "0.11.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a5d440709e79d88e51ac01c4b72fc6cb7314017bb7da9eeff678aa94c10e3ea8"
+dependencies = [
+ "serde",
+ "serde_core",
+]
+
[[package]]
name = "serde_core"
version = "1.0.228"
@@ -6117,6 +6247,7 @@ dependencies = [
"endi",
"enumflags2",
"serde",
+ "serde_bytes",
"winnow 1.0.3",
"zvariant_derive",
"zvariant_utils",
diff --git a/libs/cua-driver/rust/crates/cua-driver-sdk/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver-sdk/Cargo.toml
index 24d6d1f247..d7b4cc762f 100644
--- a/libs/cua-driver/rust/crates/cua-driver-sdk/Cargo.toml
+++ b/libs/cua-driver/rust/crates/cua-driver-sdk/Cargo.toml
@@ -34,6 +34,9 @@ platform-windows = { path = "../platform-windows" }
[target.'cfg(target_os = "linux")'.dependencies]
platform-linux = { path = "../platform-linux" }
+[target.'cfg(target_os = "linux")'.dev-dependencies]
+oo7 = { version = "=0.6.0", default-features = false, features = ["async-std", "native_crypto"] }
+
[features]
default = []
portal-input = ["platform-linux/portal-input"]
diff --git a/libs/cua-driver/rust/crates/cua-driver-sdk/tests/README.md b/libs/cua-driver/rust/crates/cua-driver-sdk/tests/README.md
new file mode 100644
index 0000000000..9c981c1f7d
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-sdk/tests/README.md
@@ -0,0 +1,25 @@
+# SDK integration tests
+
+## Linux async-io embedding
+
+`async_io_embedding.rs` compiles and links the native SDK alongside the
+Linux-only dev dependency `oo7 0.6.0`, with its `async-std` and `native_crypto`
+features. That dependency path selects ashpd's `async-io` backend, reproducing
+the feature-unification constraint of an async-io embedding host without
+requiring the complete downstream application.
+
+From `libs/cua-driver/rust` on Linux:
+
+```bash
+cargo test -p cua-driver-sdk --test async_io_embedding --locked
+```
+
+The test references SDK and oo7 types without opening a keyring, desktop session,
+or portal. Successful compilation and linking are the regression oracle; this
+is not evidence of full GPUI/Maple behavior or portal delivery. The Linux unit
+workflow runs it explicitly. Other platforms do not build the Linux-only dev
+dependency or run this test.
+
+Restoring only platform-linux's former `ashpd/tokio` selection makes compilation
+fail with `You can't enable both async-io & tokio features at once`. Restoring
+the candidate's `async-io` selection makes it build again.
diff --git a/libs/cua-driver/rust/crates/cua-driver-sdk/tests/async_io_embedding.rs b/libs/cua-driver/rust/crates/cua-driver-sdk/tests/async_io_embedding.rs
new file mode 100644
index 0000000000..be6b488f7d
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver-sdk/tests/async_io_embedding.rs
@@ -0,0 +1,10 @@
+#![cfg(target_os = "linux")]
+
+#[test]
+fn sdk_and_async_io_keyring_link_together() {
+ println!(
+ "sdk driver handle: {} bytes",
+ std::mem::size_of::<cua_driver_sdk::CuaDriver>()
+ );
+ println!("oo7 keyring: {} bytes", std::mem::size_of::<oo7::Keyring>());
+}
diff --git a/libs/cua-driver/rust/crates/cua-driver/build.rs b/libs/cua-driver/rust/crates/cua-driver/build.rs
index a47b84cc64..cc2f15a003 100644
--- a/libs/cua-driver/rust/crates/cua-driver/build.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/build.rs
@@ -25,18 +25,11 @@ fn main() {
}
fn emit_sdk_framework_search_path() {
- let sdk_root = std::env::var("SDKROOT").unwrap_or_else(|_| {
- std::process::Command::new("xcrun")
- .args(["--sdk", "macosx", "--show-sdk-path"])
- .output()
- .ok()
- .and_then(|out| String::from_utf8(out.stdout).ok())
- .map(|out| out.trim().to_owned())
- .unwrap_or_default()
- });
-
- if !sdk_root.is_empty() {
- println!("cargo:rustc-link-search=framework={sdk_root}/System/Library/Frameworks");
+ if let Some(sdk_root) = active_macos_sdk_root() {
+ println!(
+ "cargo:rustc-link-search=framework={}",
+ sdk_root.join("System/Library/Frameworks").display()
+ );
}
}
@@ -49,6 +42,16 @@ fn emit_swift_runtime_link_args() {
let mut dirs = BTreeSet::new();
+ // `swiftc` links against the SDK's Swift TBDs on current Xcode releases.
+ // The toolchain runtime directories below contain compatibility libraries,
+ // but are not guaranteed to contain the full Swift runtime surface.
+ if let Some(sdk_root) = active_macos_sdk_root() {
+ let sdk_swift_dir = sdk_root.join("usr/lib/swift");
+ if sdk_swift_dir.is_dir() {
+ println!("cargo:rustc-link-search=native={}", sdk_swift_dir.display());
+ }
+ }
+
if let Ok(out) = std::process::Command::new("xcode-select")
.arg("-p")
.output()
@@ -91,3 +94,19 @@ fn emit_swift_runtime_link_args() {
}
}
}
+
+fn active_macos_sdk_root() -> Option<std::path::PathBuf> {
+ std::env::var_os("SDKROOT")
+ .map(std::path::PathBuf::from)
+ .filter(|path| path.is_dir())
+ .or_else(|| {
+ let out = std::process::Command::new("xcrun")
+ .args(["--sdk", "macosx", "--show-sdk-path"])
+ .output()
+ .ok()?;
+ out.status
+ .success()
+ .then(|| std::path::PathBuf::from(String::from_utf8_lossy(&out.stdout).trim()))
+ .filter(|path| path.is_dir())
+ })
+}
diff --git a/libs/cua-driver/rust/crates/platform-linux/Cargo.toml b/libs/cua-driver/rust/crates/platform-linux/Cargo.toml
index 176bf349c7..f1a3d305b4 100644
--- a/libs/cua-driver/rust/crates/platform-linux/Cargo.toml
+++ b/libs/cua-driver/rust/crates/platform-linux/Cargo.toml
@@ -62,12 +62,14 @@ wayland-protocols = { version = "0.32", features = ["client", "staging", "unstab
# xdg-desktop-portal client: display-screenshot tier
# (org.freedesktop.portal.Screenshot), per-window ScreenCast
# (org.freedesktop.portal.ScreenCast), and the libei input session
-# (org.freedesktop.portal.RemoteDesktop.ConnectToEIS). `tokio` shares the
-# driver's async runtime.
+# (org.freedesktop.portal.RemoteDesktop.ConnectToEIS). ashpd allows exactly
+# one async backend, and gpui's Linux port selects `async-io` through oo7,
+# so an app embedding both must use it here too; zbus keeps running on
+# tokio when both of its backends are enabled.
#
# ashpd's RemoteDesktop feature is pure Rust. Only our ScreenCast frame reader
# pulls pipewire-rs/libspa, whose headers are newer than Debian bullseye.
-ashpd = { version = "0.13", default-features = false, features = ["tokio", "screenshot"] }
+ashpd = { version = "0.13", default-features = false, features = ["async-io", "screenshot"] }
# zbus is pulled transitively via ashpd + atspi but declared directly so
# the portal-probe path in wayland::portal_screenshot can talk to the
# session bus without going through ashpd's higher-level builders.
diff --git a/libs/cua-driver/rust/crates/platform-macos/Cargo.toml b/libs/cua-driver/rust/crates/platform-macos/Cargo.toml
index 5a18e6a516..96196ad6c1 100644
--- a/libs/cua-driver/rust/crates/platform-macos/Cargo.toml
+++ b/libs/cua-driver/rust/crates/platform-macos/Cargo.toml
@@ -74,3 +74,7 @@ futures-util = "0.3"
[dev-dependencies]
tempfile = "3"
+
+[[test]]
+name = "embedded_menu_restore"
+harness = false
diff --git a/libs/cua-driver/rust/crates/platform-macos/build.rs b/libs/cua-driver/rust/crates/platform-macos/build.rs
index 3e1a1e3e31..da59f3b2ee 100644
--- a/libs/cua-driver/rust/crates/platform-macos/build.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/build.rs
@@ -12,27 +12,6 @@ fn main() {
println!("cargo:rustc-link-lib=framework=QuartzCore");
println!("cargo:rustc-link-lib=framework=CoreGraphics");
- // Point the linker at the SDK's system sub-library directory so
- // `#[link(name = "dispatch", kind = "dylib")]` can find libdispatch.tbd.
- // The path is stable across Xcode / CLT installs; SDKROOT takes precedence
- // if set (Xcode builds set it automatically).
- let sdk_root = std::env::var("SDKROOT").unwrap_or_else(|_| {
- // Fall back to the active CLT SDK.
- let out = std::process::Command::new("xcrun")
- .args(["--sdk", "macosx", "--show-sdk-path"])
- .output()
- .ok()
- .and_then(|o| String::from_utf8(o.stdout).ok())
- .unwrap_or_default();
- out.trim().to_owned()
- });
-
- if !sdk_root.is_empty() {
- println!("cargo:rustc-link-search={sdk_root}/usr/lib/system");
- println!("cargo:rustc-link-search={sdk_root}/usr/lib");
- println!("cargo:rustc-link-search=framework={sdk_root}/System/Library/Frameworks");
- }
-
// The ScreenCaptureKit bindings pull in Swift runtime libraries such as
// libswift_Concurrency.dylib. The cua-driver binary emits these rpaths in
// its own build.rs, but platform-macos' unit-test binary is linked from
@@ -49,6 +28,16 @@ fn emit_swift_runtime_link_args() {
let mut dirs = BTreeSet::new();
+ // `swiftc` links against the SDK's Swift TBDs on current Xcode releases.
+ // The toolchain runtime directories below contain compatibility libraries,
+ // but are not guaranteed to contain the full Swift runtime surface.
+ if let Some(sdk_root) = active_macos_sdk_root() {
+ let sdk_swift_dir = sdk_root.join("usr/lib/swift");
+ if sdk_swift_dir.is_dir() {
+ println!("cargo:rustc-link-search=native={}", sdk_swift_dir.display());
+ }
+ }
+
if let Ok(out) = Command::new("xcode-select").arg("-p").output() {
if out.status.success() {
let xcode_path = String::from_utf8_lossy(&out.stdout).trim().to_string();
@@ -88,3 +77,19 @@ fn emit_swift_runtime_link_args() {
}
}
}
+
+fn active_macos_sdk_root() -> Option<std::path::PathBuf> {
+ std::env::var_os("SDKROOT")
+ .map(std::path::PathBuf::from)
+ .filter(|path| path.is_dir())
+ .or_else(|| {
+ let out = std::process::Command::new("xcrun")
+ .args(["--sdk", "macosx", "--show-sdk-path"])
+ .output()
+ .ok()?;
+ out.status
+ .success()
+ .then(|| std::path::PathBuf::from(String::from_utf8_lossy(&out.stdout).trim()))
+ .filter(|path| path.is_dir())
+ })
+}
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
index b83e632f37..78981e9cc8 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/apps/mod.rs
@@ -276,7 +276,7 @@ struct FinderFolderRequest {
tx: SyncSender<Result<(), String>>,
}
-#[link(name = "dispatch", kind = "dylib")]
+#[link(name = "System", kind = "framework")]
extern "C" {
static _dispatch_main_q: u8;
fn dispatch_async_f(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs
index abc10c7fe6..5d74dddf50 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/cursor/overlay.rs
@@ -960,7 +960,7 @@ fn dispatch_set_layer_contents(layer_ptr: usize, pixmap: tiny_skia::Pixmap) {
// symbol is `_dispatch_main_q`, a *struct* (not a pointer).
// We declare it as `u8` (opaque placeholder) and take its ADDRESS to
// obtain the `dispatch_queue_t` (pointer to the struct).
- #[link(name = "dispatch", kind = "dylib")]
+ #[link(name = "System", kind = "framework")]
extern "C" {
// Opaque placeholder — we only ever take &_dispatch_main_q, never read it.
static _dispatch_main_q: u8;
@@ -1005,7 +1005,7 @@ fn dispatch_set_layer_contents(layer_ptr: usize, pixmap: tiny_skia::Pixmap) {
fn dispatch_order_front(win_ptr: usize) {
use std::ffi::c_void;
- #[link(name = "dispatch", kind = "dylib")]
+ #[link(name = "System", kind = "framework")]
extern "C" {
static _dispatch_main_q: u8;
fn dispatch_async_f(
@@ -1069,7 +1069,7 @@ fn target_is_frontmost_visible_window(
fn dispatch_pin_above(win_ptr: usize, target_wid: u64) {
use std::ffi::c_void;
- #[link(name = "dispatch", kind = "dylib")]
+ #[link(name = "System", kind = "framework")]
extern "C" {
static _dispatch_main_q: u8;
fn dispatch_async_f(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/pip/mod.rs b/libs/cua-driver/rust/crates/platform-macos/src/pip/mod.rs
index bf873a403f..587fa0fc03 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/pip/mod.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/pip/mod.rs
@@ -86,7 +86,7 @@ static HANDLES: Mutex<Option<NativeHandles>> = Mutex::new(None);
// ── libdispatch glue — same shape as cursor::overlay ──────────────────────
-#[link(name = "dispatch", kind = "dylib")]
+#[link(name = "System", kind = "framework")]
extern "C" {
static _dispatch_main_q: u8;
fn dispatch_async_f(
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
index 6d01dc1b52..ff2f7d4507 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/invoke_menu.rs
@@ -10,7 +10,15 @@ use cua_driver_core::{
tool::{Tool, ToolDef},
};
use serde_json::Value;
-use std::time::Duration;
+use std::{
+ ffi::c_void,
+ sync::{
+ atomic::{AtomicBool, Ordering},
+ mpsc::{self, SyncSender},
+ Arc,
+ },
+ time::Duration,
+};
use crate::ax::bindings::{
ax_get_window_id, copy_action_names, copy_ax_windows, copy_bool_attr, copy_children,
@@ -21,6 +29,7 @@ use crate::ax::bindings::{
pub struct InvokeMenuTool;
const AX_MESSAGING_TIMEOUT_SECONDS: f32 = 2.0;
+const MAIN_QUEUE_TIMEOUT: Duration = Duration::from_secs(5);
unsafe fn set_messaging_timeout(element: AXUIElementRef) {
let _ = AXUIElementSetMessagingTimeout(element, AX_MESSAGING_TIMEOUT_SECONDS);
@@ -194,18 +203,7 @@ unsafe fn invoke_path(pid: i32, path: &[String]) -> Result<(), String> {
/// disabled even though the application itself is frontmost. Raise and mark
/// only the requested AX window, then require an exact focused-window readback
/// before menu resolution proceeds.
-fn focus_exact_window(pid: i32, window_id: u32) -> Result<(), String> {
- let native_key_requested = crate::input::skylight::make_exact_window_key(pid, window_id);
- if !native_key_requested
- && crate::apps::frontmost_pid() != Some(pid)
- && !crate::apps::activate_pid(pid)
- {
- return Err("invoke_menu: target application could not be activated".into());
- }
- if !native_key_requested {
- std::thread::sleep(Duration::from_millis(120));
- }
-
+fn focus_ax_window(pid: i32, window_id: u32) -> Result<(), String> {
unsafe {
let app = AXUIElementCreateApplication(pid);
if app.is_null() {
@@ -237,6 +235,88 @@ fn focus_exact_window(pid: i32, window_id: u32) -> Result<(), String> {
let _ = set_bool_attr_true(target, "AXFocused");
CFRelease(target as CFTypeRef);
}
+ Ok(())
+}
+
+struct AxWindowFocusRequest {
+ pid: i32,
+ window_id: u32,
+ tx: SyncSender<Result<(), String>>,
+ cancelled: Arc<AtomicBool>,
+}
+
+#[link(name = "System", kind = "framework")]
+extern "C" {
+ static _dispatch_main_q: u8;
+ fn dispatch_async_f(
+ queue: *const c_void,
+ context: *mut c_void,
+ work: unsafe extern "C" fn(*mut c_void),
+ );
+}
+
+unsafe extern "C" fn focus_ax_window_on_main(context: *mut c_void) {
+ let request = unsafe { Box::from_raw(context.cast::<AxWindowFocusRequest>()) };
+ if request.cancelled.load(Ordering::Acquire) {
+ return;
+ }
+ let result = focus_ax_window(request.pid, request.window_id);
+ let _ = request.tx.send(result);
+}
+
+fn focus_ax_window_with_thread_affinity(pid: i32, window_id: u32) -> Result<(), String> {
+ let is_main_thread = objc2_foundation::MainThreadMarker::new().is_some();
+ if pid != std::process::id() as i32 || is_main_thread {
+ return focus_ax_window(pid, window_id);
+ }
+
+ // AX actions against another process execute in that process. An embedded
+ // driver targeting its own window is different: AppKit services AXRaise
+ // in this process, and window ordering is main-thread-only. Queue just the
+ // self-process AX mutation onto AppKit's main queue, then return to the
+ // blocking worker for readiness polling and menu traversal.
+ let (tx, rx) = mpsc::sync_channel(1);
+ let cancelled = Arc::new(AtomicBool::new(false));
+ let request = Box::new(AxWindowFocusRequest {
+ pid,
+ window_id,
+ tx,
+ cancelled: Arc::clone(&cancelled),
+ });
+ unsafe {
+ let main_queue = &raw const _dispatch_main_q as *const c_void;
+ dispatch_async_f(
+ main_queue,
+ Box::into_raw(request).cast::<c_void>(),
+ focus_ax_window_on_main,
+ );
+ }
+ match rx.recv_timeout(MAIN_QUEUE_TIMEOUT) {
+ Ok(result) => result,
+ Err(error) => {
+ // If AppKit never serviced the request, prevent a stale focus
+ // change from firing after this tool call has already failed.
+ cancelled.store(true, Ordering::Release);
+ Err(format!(
+ "invoke_menu: failed waiting for the embedded host window on the AppKit main queue: {error}"
+ ))
+ }
+ }
+}
+
+fn focus_exact_window(pid: i32, window_id: u32) -> Result<(), String> {
+ let native_key_requested = crate::input::skylight::make_exact_window_key(pid, window_id);
+ if !native_key_requested
+ && crate::apps::frontmost_pid() != Some(pid)
+ && !crate::apps::activate_pid(pid)
+ {
+ return Err("invoke_menu: target application could not be activated".into());
+ }
+ if !native_key_requested {
+ std::thread::sleep(Duration::from_millis(120));
+ }
+
+ focus_ax_window_with_thread_affinity(pid, window_id)?;
// AXFocusedWindow can lead AppKit's native `isKeyWindow` state while the
// WindowServer activation is still settling. Menu validation observes the
diff --git a/libs/cua-driver/rust/crates/platform-macos/tests/README.md b/libs/cua-driver/rust/crates/platform-macos/tests/README.md
new file mode 100644
index 0000000000..7eaff1a5cf
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-macos/tests/README.md
@@ -0,0 +1,79 @@
+# Embedded menu restoration regression
+
+`embedded_menu_restore` runs AppKit on the process main thread and embeds the
+real platform tool registry on a background Tokio worker. It launches a second
+native process, invokes its Window > Minimize command, and verifies:
+
+- the target process independently observes native minimization;
+- the host becomes frontmost again;
+- the host's original window is natively key; and
+- its other window is not key.
+
+The test does not accept the tool response as proof of restoration. It has
+bounded readiness and completion deadlines. It exercises the embedded platform
+implementation, not the public SDK authorization/lifecycle boundary.
+
+## Build and authorize
+
+From the repository root, build an independently identified fixture application:
+
+```bash
+bash scripts/ci/macos/build-embedded-menu-fixture.sh \
+ "$HOME/Applications/CuaEmbeddedMenuFixture.app" \
+ com.trycua.tests.embedded-menu-fixture
+```
+
+The builder refuses to overwrite an existing application. It uses an ad-hoc
+signature; preserve the built bytes after authorization. Rebuilding can invalidate
+that authorization. Do not borrow the installed CuaDriver application's identity
+or modify TCC databases.
+
+In a logged-in Aqua session, request Accessibility through the normal macOS flow:
+
+```bash
+open -W -n "$HOME/Applications/CuaEmbeddedMenuFixture.app" \
+ --args --request-accessibility --report /tmp/embedded-menu-permission.txt
+```
+
+The permission mode waits up to 180 seconds for human approval and does not run
+the regression. If it expires, grant access in System Settings before rerunning.
+
+## Run the foreground regression
+
+```bash
+open -W -n "$HOME/Applications/CuaEmbeddedMenuFixture.app" \
+ --args --run-gui --report /tmp/embedded-menu-result.txt
+```
+
+Run one fixture at a time. This intentionally foregrounds the fixture: a
+background launcher that suppresses activation interferes with the test's
+preconditions. Direct execution of the executable may also have different TCC
+attribution from a LaunchServices application launch.
+
+Require the report to contain exactly `passed`. A native abort can leave it at
+`running`, so the exit status of `open` alone is not acceptance evidence. Rust
+panics write `failed` with their diagnostic. Without either explicit mode, the
+test executable prints a skip, allowing ordinary Cargo test/compile jobs to run
+without a desktop or permission prompt.
+
+## Negative control
+
+In an isolated checkout, change only the call inside `focus_exact_window` from
+`focus_ax_window_with_thread_affinity(pid, window_id)` to
+`focus_ax_window(pid, window_id)`. Package that build under a different test
+bundle identifier and obtain its own normal Accessibility grant. Restore the
+source mutation before returning to the candidate.
+
+On macOS Tahoe, the control traps during restoration with
+`Must only be used from the main thread`. Its crash stack includes
+`NSWindow makeKeyAndOrderFront:`, `NSResponder accessibilityPerformRaise`,
+`AXUIElementPerformAction`, `focus_ax_window`, and the menu restoration closure
+on a Tokio blocking worker. A missing permission or failed initial focus
+precondition does not count as this negative control.
+
+An aborted parent cannot clean up its target child; the child exits after its
+bounded 45-second lifetime. Wait for that exit before the next run.
+
+This focused regression supplements, rather than replaces, the complete
+canonical desktop suite described in
+[`test-harnesses-guide.md`](../../../../docs/test-harnesses-guide.md).
diff --git a/libs/cua-driver/rust/crates/platform-macos/tests/embedded_menu_restore.rs b/libs/cua-driver/rust/crates/platform-macos/tests/embedded_menu_restore.rs
new file mode 100644
index 0000000000..cb4675b8e4
--- /dev/null
+++ b/libs/cua-driver/rust/crates/platform-macos/tests/embedded_menu_restore.rs
@@ -0,0 +1,280 @@
+#[cfg(not(target_os = "macos"))]
+fn main() {}
+
+#[cfg(target_os = "macos")]
+fn main() {
+ let args: Vec<String> = std::env::args().collect();
+ let request = args.iter().any(|arg| arg == "--request-accessibility");
+ if !request && !args.iter().any(|arg| arg == "--run-gui") {
+ println!("embedded_menu_restore: skipped; pass --run-gui in a TCC-authorized Aqua session");
+ return;
+ }
+ let report = args
+ .windows(2)
+ .find(|pair| pair[0] == "--report")
+ .map(|pair| &pair[1]);
+ if let Some(path) = report {
+ std::fs::write(path, "running\n").unwrap();
+ }
+ let result = std::panic::catch_unwind(|| {
+ if request {
+ native::request_accessibility();
+ } else {
+ native::run();
+ }
+ });
+ if let Some(path) = report {
+ let status = match &result {
+ Ok(()) => "passed\n".to_owned(),
+ Err(error) => format!(
+ "failed: {}\n",
+ error
+ .downcast_ref::<String>()
+ .map(String::as_str)
+ .or_else(|| error.downcast_ref::<&str>().copied())
+ .unwrap_or("non-string panic")
+ ),
+ };
+ std::fs::write(path, status).unwrap();
+ }
+ if let Err(error) = result {
+ std::panic::resume_unwind(error);
+ }
+}
+
+#[cfg(target_os = "macos")]
+mod native {
+ use objc2::runtime::AnyObject;
+ use objc2::{class, msg_send, sel};
+ use objc2_foundation::{MainThreadMarker, NSPoint, NSRect, NSSize, NSString};
+ use std::path::Path;
+ use std::process::{Child, Command};
+ use std::sync::mpsc;
+ use std::time::{Duration, Instant};
+
+ struct Fixture(Child);
+
+ impl Drop for Fixture {
+ fn drop(&mut self) {
+ let _ = self.0.kill();
+ let _ = self.0.wait();
+ }
+ }
+
+ unsafe fn window(title: &str, x: f64) -> *mut AnyObject {
+ let allocated: *mut AnyObject = msg_send![class!(NSWindow), alloc];
+ let window: *mut AnyObject = msg_send![allocated,
+ initWithContentRect: NSRect::new(NSPoint::new(x, 200.0), NSSize::new(360.0, 240.0))
+ styleMask: 15u64
+ backing: 2u64
+ defer: false
+ ];
+ assert!(!window.is_null());
+ let _: () = msg_send![window, setReleasedWhenClosed: false];
+ let _: () = msg_send![window, setTitle: &*NSString::from_str(title)];
+ let _: () = msg_send![window, makeKeyAndOrderFront: std::ptr::null::<AnyObject>()];
+ window
+ }
+
+ unsafe fn pump(app: *mut AnyObject) {
+ let until: *mut AnyObject =
+ msg_send![class!(NSDate), dateWithTimeIntervalSinceNow: 0.01f64];
+ let event: *mut AnyObject = msg_send![app,
+ nextEventMatchingMask: u64::MAX
+ untilDate: until
+ inMode: &*NSString::from_str("kCFRunLoopDefaultMode")
+ dequeue: true
+ ];
+ if !event.is_null() {
+ let _: () = msg_send![app, sendEvent: event];
+ }
+ let _: () = msg_send![app, updateWindows];
+ }
+
+ unsafe fn install_menu(app: *mut AnyObject) {
+ let menu: *mut AnyObject = msg_send![class!(NSMenu), new];
+ let application_item: *mut AnyObject = msg_send![class!(NSMenuItem), new];
+ let application_menu: *mut AnyObject = msg_send![class!(NSMenu), new];
+ let _: () = msg_send![application_item, setSubmenu: application_menu];
+ let _: () = msg_send![menu, addItem: application_item];
+ let root: *mut AnyObject = msg_send![class!(NSMenuItem), new];
+ let _: () = msg_send![root, setTitle: &*NSString::from_str("Window")];
+ let submenu: *mut AnyObject = msg_send![class!(NSMenu), new];
+ let _: () = msg_send![submenu, setTitle: &*NSString::from_str("Window")];
+ let allocated: *mut AnyObject = msg_send![class!(NSMenuItem), alloc];
+ let item: *mut AnyObject = msg_send![allocated,
+ initWithTitle: &*NSString::from_str("Minimize")
+ action: sel!(performMiniaturize:)
+ keyEquivalent: &*NSString::from_str("")
+ ];
+ let _: () = msg_send![submenu, addItem: item];
+ let _: () = msg_send![root, setSubmenu: submenu];
+ let _: () = msg_send![menu, addItem: root];
+ let _: () = msg_send![app, setMainMenu: menu];
+ }
+
+ unsafe fn child(app: *mut AnyObject, directory: &Path) {
+ install_menu(app);
+ let target = window("embedded menu target", 650.0);
+ let _: () = msg_send![app, activateIgnoringOtherApps: true];
+ let wid: i64 = msg_send![target, windowNumber];
+ std::fs::write(directory.join("window.pending"), wid.to_string()).unwrap();
+ std::fs::rename(directory.join("window.pending"), directory.join("window")).unwrap();
+ let deadline = Instant::now() + Duration::from_secs(45);
+ while Instant::now() < deadline {
+ pump(app);
+ let minimized: bool = msg_send![target, isMiniaturized];
+ if minimized && !directory.join("minimized").exists() {
+ std::fs::write(directory.join("minimized"), "true").unwrap();
+ }
+ }
+ }
+
+ pub fn request_accessibility() {
+ use core_foundation::{
+ base::TCFType, boolean::CFBoolean, dictionary::CFDictionary, string::CFString,
+ };
+ let _main =
+ MainThreadMarker::new().expect("permission request must run on the main thread");
+ unsafe {
+ let app: *mut AnyObject = msg_send![class!(NSApplication), sharedApplication];
+ let _: bool = msg_send![app, setActivationPolicy: 0i64];
+ let _: () = msg_send![app, finishLaunching];
+ let options = CFDictionary::from_CFType_pairs(&[(
+ CFString::new("AXTrustedCheckOptionPrompt"),
+ CFBoolean::true_value(),
+ )]);
+ platform_macos::ax::bindings::AXIsProcessTrustedWithOptions(
+ options.as_concrete_TypeRef(),
+ );
+ let deadline = Instant::now() + Duration::from_secs(180);
+ while !platform_macos::ax::bindings::AXIsProcessTrusted() {
+ assert!(
+ Instant::now() < deadline,
+ "Accessibility authorization was not granted"
+ );
+ pump(app);
+ }
+ }
+ }
+
+ pub fn run() {
+ let _main = MainThreadMarker::new().expect("fixture must own the AppKit main thread");
+ unsafe {
+ let app: *mut AnyObject = msg_send![class!(NSApplication), sharedApplication];
+ let _: bool = msg_send![app, setActivationPolicy: 0i64];
+ let _: () = msg_send![app, finishLaunching];
+ if let Some(directory) = std::env::var_os("CUA_EMBEDDED_MENU_CHILD") {
+ child(app, Path::new(&directory));
+ return;
+ }
+ assert!(
+ platform_macos::ax::bindings::AXIsProcessTrusted(),
+ "Accessibility permission is required for this test executable"
+ );
+ let directory = tempfile::tempdir().unwrap();
+ let mut fixture = Fixture(
+ Command::new(std::env::current_exe().unwrap())
+ .arg("--run-gui")
+ .env("CUA_EMBEDDED_MENU_CHILD", directory.path())
+ .spawn()
+ .unwrap(),
+ );
+ let deadline = Instant::now() + Duration::from_secs(10);
+ while !directory.path().join("window").exists() {
+ assert!(
+ fixture.0.try_wait().unwrap().is_none(),
+ "target fixture exited"
+ );
+ assert!(
+ Instant::now() < deadline,
+ "target fixture did not publish a window"
+ );
+ pump(app);
+ }
+ let target_wid: u32 = std::fs::read_to_string(directory.path().join("window"))
+ .unwrap()
+ .parse()
+ .unwrap();
+ let original = window("embedded host original", 100.0);
+ let distractor = window("embedded host distractor", 200.0);
+ let _: () = msg_send![original, makeKeyAndOrderFront: std::ptr::null::<AnyObject>()];
+ let _: () = msg_send![app, activateIgnoringOtherApps: true];
+ let original_wid: i64 = msg_send![original, windowNumber];
+ let deadline = Instant::now() + Duration::from_secs(5);
+ let mut stable_since = None;
+ loop {
+ pump(app);
+ let key: bool = msg_send![original, isKeyWindow];
+ let ready = key
+ && platform_macos::apps::frontmost_pid() == Some(std::process::id() as i32)
+ && platform_macos::ax::bindings::focused_window_id_of_pid(
+ std::process::id() as i32
+ ) == Some(original_wid as u32);
+ if ready {
+ if stable_since.get_or_insert_with(Instant::now).elapsed()
+ >= Duration::from_millis(300)
+ {
+ break;
+ }
+ } else {
+ stable_since = None;
+ }
+ assert!(
+ Instant::now() < deadline,
+ "host precondition: exact original window never became key"
+ );
+ }
+ let target_pid = fixture.0.id();
+ let (tx, rx) = mpsc::channel();
+ let worker = std::thread::spawn(move || {
+ let runtime = tokio::runtime::Runtime::new().unwrap();
+ let registry = platform_macos::register_tools();
+ let result = runtime.block_on(registry.invoke(
+ "invoke_menu",
+ serde_json::json!({
+ "pid": target_pid,
+ "window_id": target_wid,
+ "path": ["Window", "Minimize"]
+ }),
+ ));
+ tx.send(result).unwrap();
+ });
+ let deadline = Instant::now() + Duration::from_secs(25);
+ let result = loop {
+ pump(app);
+ match rx.try_recv() {
+ Ok(result) => break result,
+ Err(mpsc::TryRecvError::Disconnected) => panic!("embedded worker failed"),
+ Err(mpsc::TryRecvError::Empty) => {}
+ }
+ assert!(Instant::now() < deadline, "embedded invoke_menu timed out");
+ };
+ worker.join().unwrap();
+ assert!(
+ !result.is_error.unwrap_or(false),
+ "invoke_menu failed: {result:?}"
+ );
+ let deadline = Instant::now() + Duration::from_secs(3);
+ loop {
+ pump(app);
+ let key: bool = msg_send![original, isKeyWindow];
+ let other_key: bool = msg_send![distractor, isKeyWindow];
+ if key
+ && !other_key
+ && platform_macos::apps::frontmost_pid() == Some(std::process::id() as i32)
+ && directory.path().join("minimized").exists()
+ {
+ break;
+ }
+ assert!(
+ Instant::now() < deadline,
+ "menu did not minimize the target and restore the exact native host key window"
+ );
+ }
+ println!(
+ "embedded_menu_restore: passed (target minimized; exact host window restored)"
+ );
+ }
+ }
+}
diff --git a/scripts/ci/macos/build-embedded-menu-fixture.sh b/scripts/ci/macos/build-embedded-menu-fixture.sh
new file mode 100644
index 0000000000..1d9aa119eb
--- /dev/null
+++ b/scripts/ci/macos/build-embedded-menu-fixture.sh
@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+APP="${1:?usage: build-embedded-menu-fixture.sh /absolute/path/Fixture.app unique.bundle.id}"
+BUNDLE_ID="${2:?supply a unique test bundle identifier}"
+[[ "$APP" = /*.app ]] || { printf '%s\n' 'app path must be absolute and end in .app' >&2; exit 1; }
+[[ ! -e "$APP" ]] || { printf '%s\n' 'choose a new app path; existing apps are not overwritten' >&2; exit 1; }
+BUILD_LOG="$(mktemp)"
+trap 'rm -f "$BUILD_LOG"' EXIT
+
+cargo test --manifest-path "$ROOT/libs/cua-driver/rust/Cargo.toml" \
+ -p platform-macos --test embedded_menu_restore --locked --no-run \
+ --message-format=json > "$BUILD_LOG"
+
+python3 - "$BUILD_LOG" "$APP" "$BUNDLE_ID" <<'PY'
+import json
+import pathlib
+import plistlib
+import shutil
+import sys
+
+log, destination, identifier = sys.argv[1:]
+artifacts = [json.loads(line) for line in pathlib.Path(log).read_text().splitlines() if line.startswith("{")]
+executables = [item["executable"] for item in artifacts
+ if item.get("reason") == "compiler-artifact"
+ and item.get("target", {}).get("name") == "embedded_menu_restore"
+ and item.get("executable")]
+assert len(executables) == 1, executables
+app = pathlib.Path(destination)
+(app / "Contents" / "MacOS").mkdir(parents=True)
+shutil.copy2(executables[0], app / "Contents" / "MacOS" / "embedded_menu_restore")
+with (app / "Contents" / "Info.plist").open("wb") as output:
+ plistlib.dump({
+ "CFBundleIdentifier": identifier,
+ "CFBundleName": app.stem,
+ "CFBundleDisplayName": app.stem,
+ "CFBundleExecutable": "embedded_menu_restore",
+ "CFBundlePackageType": "APPL",
+ "CFBundleVersion": "1",
+ "CFBundleShortVersionString": "1.0",
+ "NSHighResolutionCapable": True,
+ }, output)
+PY
+
+codesign --force --sign - --identifier "$BUNDLE_ID" "$APP"
+codesign --verify --strict "$APP"
+printf 'fixture app: %s\nbundle identifier: %s\n' "$APP" "$BUNDLE_ID"