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): accept host identity in embedded health check (#2170)
injaneity8a3d79aa7944
diff --git a/docs/content/docs/reference/cua-driver/embedding.mdx b/docs/content/docs/reference/cua-driver/embedding.mdxindex 33635588fc..2a1d01d6bc 100644--- a/docs/content/docs/reference/cua-driver/embedding.mdx+++ b/docs/content/docs/reference/cua-driver/embedding.mdx@@ -89,7 +89,7 @@ cua-driver mcp --embedded --socket /tmp/yourapp-cua.sock \--host-bundle-id com.yourco.yourapp```-You can pass `--embedded --host-bundle-id com.yourco.yourapp` to `serve` instead of the environment variables. Only the exact value `CUA_DRIVER_EMBEDDED=1` enables environment-based embedded mode. The host bundle id is an advisory label echoed in `check_permissions`; trust still comes from macOS's responsibility chain.+You can pass `--embedded --host-bundle-id com.yourco.yourapp` to `serve` instead of the environment variables. Only the exact value `CUA_DRIVER_EMBEDDED=1` enables environment-based embedded mode. The host bundle id declares the expected host: `health_report` compares it with the daemon's parent application, while trust still comes from macOS's responsibility chain.## Node and Electron hosts@@ -151,6 +151,8 @@ If macOS grants are added after the daemon has started, restart the daemon so TC`--embedded` does not transfer a GUI app's grants to the driver; it only keeps the daemon inside its spawner's macOS responsibility chain. If a separate gateway or Node process spawns the daemon, the daemon inherits the gateway's identity, not the app's. Spawn `cua-driver serve --embedded` from the app process.+Call `health_report` with `{"include":["bundle_identity"]}` after connecting. The check passes only when macOS can resolve the direct parent as an application and, when configured, its observed bundle identifier matches `CUA_DRIVER_HOST_BUNDLE_ID`.+Normal OpenClaw gateway and Hermes YAML MCP configurations remain standalone integrations; do not set embedded mode merely because one of those agents is the client. A signed Node or Electron desktop host may use `@trycua/cua-driver/embedded`, but only its permission-owning app process may start the daemon. The MCP client can then launch the proxy described by `connection.mcp`.```textdiff --git a/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md b/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.mdindex 8bb789d3dc..f21d82cbff 100644--- a/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md+++ b/libs/cua-driver/rust/Skills/cua-driver/EMBEDDING.md@@ -250,11 +250,12 @@ gateway / node daemon YourApp.app--socket <private-path>```-Note `check_permissions` cannot detect this: `source.attribution` reports-`host` whenever `CUA_DRIVER_EMBEDDED=1` is set, even if a gateway spawned-the driver. The symptoms are grant booleans that track the _gateway's_ TCC-state and prompts/Settings entries naming the gateway process; see-Troubleshooting below.+`health_report(include=["bundle_identity"])` detects this wiring error by+resolving the daemon's direct parent through macOS. It fails when the parent+is not an identifiable app or when its observed bundle identifier differs+from `CUA_DRIVER_HOST_BUNDLE_ID`. `check_permissions.source.attribution`+still describes the configured mode; use the two reports together when+diagnosing embedding.## Reading `check_permissions` from the host@@ -441,12 +442,29 @@ _ = readMessage()send(["jsonrpc": "2.0", "method": "notifications/initialized"])log("embedded cua-driver daemon + proxy started (\(driverPath)) — no driver prompt should have appeared")-// 4. check_permissions must report attribution "host" and never prompt.+// 4. health_report must observe this actual parent app, and+// check_permissions must report host attribution and matching TCC results.+let health = call("health_report", ["include": ["bundle_identity"]])+let healthStructured = health["structuredContent"] as? [String: Any] ?? [:]+let healthChecks = healthStructured["checks"] as? [[String: Any]] ?? []+let identity = healthChecks.first { $0["name"] as? String == "bundle_identity" } ?? [:]+let identityData = identity["data"] as? [String: Any] ?? [:]+let hostBundleId = Bundle.main.bundleIdentifier ?? ""+let identityOk = identity["status"] as? String == "pass" &&+ identityData["bundle_identifier"] as? String == hostBundleId &&+ identityData["identity_source"] as? String == "parent_application" &&+ (identityData["parent_process_id"] as? Int) == Int(ProcessInfo.processInfo.processIdentifier)+log("health_report — bundle_identity: \(identity["status"] ?? "?"), " ++ "observed host: \(identityData["bundle_identifier"] ?? "?") (want: \(hostBundleId))")+let perms = call("check_permissions")let structured = perms["structuredContent"] as? [String: Any] ?? [:]let source = structured["source"] as? [String: Any] ?? [:]let attribution = source["attribution"] as? String ?? "?"+let permissionsMatchHost = structured["accessibility"] as? Bool == ax &&+ structured["screen_recording"] as? Bool == srlog("check_permissions — attribution: \(attribution) (want: host), " ++ "TCC matches host: \(permissionsMatchHost), " +"capturable: \(structured["screen_recording_capturable"] ?? "?")")// 5. Background AX read + window screenshot — proves both grants@@ -477,7 +495,8 @@ let cursorOk = (cursor1["isError"] as? Bool) != true &&(cursor2["isError"] as? Bool) != truelog("move_cursor — \(cursorOk ? "ok" : "FAILED")")-let pass = attribution == "host" && !images.isEmpty && hasTree && cursorOk+let pass = identityOk && attribution == "host" && permissionsMatchHost &&+ !images.isEmpty && hasTree && cursorOklog(pass ? "DEMO COMPLETE: PASS" : "DEMO COMPLETE: FAIL")driver.terminate()daemon.terminate()diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rsindex 13f486c502..e4326c37d2 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/health_report.rs@@ -95,8 +95,14 @@ pub struct CheckData {#[serde(skip_serializing_if = "Option::is_none")]pub bundle_identifier: Option<String>,#[serde(skip_serializing_if = "Option::is_none")]+ pub configured_bundle_identifier: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]pub executable_path: Option<String>,#[serde(skip_serializing_if = "Option::is_none")]+ pub identity_source: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ pub parent_process_id: Option<u32>,+ #[serde(skip_serializing_if = "Option::is_none")]pub os_version: Option<String>,#[serde(skip_serializing_if = "Option::is_none")]pub architecture: Option<String>,@@ -112,7 +118,10 @@ impl CheckData {/// serialized as `{}`.pub fn is_empty(&self) -> bool {self.bundle_identifier.is_none()+ && self.configured_bundle_identifier.is_none()&& self.executable_path.is_none()+ && self.identity_source.is_none()+ && self.parent_process_id.is_none()&& self.os_version.is_none()&& self.architecture.is_none()&& self.display_count.is_none()diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rsindex 1bbdb378ae..6bbad0c6cf 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/health_report.rs@@ -110,13 +110,27 @@ pub(crate) fn check_bundle_identity() -> CheckEntry {.and_then(|p| p.to_str().map(str::to_owned)).unwrap_or_default();- let is_correct = bid.as_deref() == Some(CANONICAL_BUNDLE_ID);+ if cua_driver_core::embedded_mode() {+ let parent_process_id = unsafe { libc::getppid() } as u32;+ let observed_host_bundle_id = application_bundle_identifier_for_pid(parent_process_id);+ let configured_host_bundle_id = std::env::var(cua_driver_core::HOST_BUNDLE_ID_ENV)+ .ok()+ .filter(|id| !id.trim().is_empty());+ return check_embedded_bundle_identity(+ observed_host_bundle_id,+ configured_host_bundle_id,+ parent_process_id,+ exe,+ );+ }+let data = CheckData {bundle_identifier: bid.clone(),executable_path: if exe.is_empty() { None } else { Some(exe) },+ identity_source: Some("current_process".to_owned()),..Default::default()};- if is_correct {+ if bid.as_deref() == Some(CANONICAL_BUNDLE_ID) {return CheckEntry::pass(NAME_BUNDLE_IDENTITY,format!("Bundle is {CANONICAL_BUNDLE_ID}."),@@ -140,8 +154,56 @@ pub(crate) fn check_bundle_identity() -> CheckEntry {),),};+CheckEntry::fail(NAME_BUNDLE_IDENTITY, message, hint).with_data(data)}+fn check_embedded_bundle_identity(+ observed_host_bundle_id: Option<String>,+ configured_host_bundle_id: Option<String>,+ parent_process_id: u32,+ executable_path: String,+) -> CheckEntry {+ let data = CheckData {+ bundle_identifier: observed_host_bundle_id.clone(),+ configured_bundle_identifier: configured_host_bundle_id.clone(),+ executable_path: if executable_path.is_empty() {+ None+ } else {+ Some(executable_path)+ },+ identity_source: Some("parent_application".to_owned()),+ parent_process_id: Some(parent_process_id),+ ..Default::default()+ };++ let Some(observed) = observed_host_bundle_id else {+ return CheckEntry::fail(+ NAME_BUNDLE_IDENTITY,+ "Embedded mode is set, but the parent process is not an identifiable macOS application.",+ "Spawn `cua-driver serve --embedded` directly from the signed host app process. Do not launch it through a shell, gateway, `open`, or NSWorkspace.",+ )+ .with_data(data);+ };++ if let Some(configured) = configured_host_bundle_id {+ if configured != observed {+ return CheckEntry::fail(+ NAME_BUNDLE_IDENTITY,+ format!(+ "Observed host bundle is {observed}, but the configured host bundle is {configured}."+ ),+ "Spawn the embedded daemon directly from the configured host application, or correct CUA_DRIVER_HOST_BUNDLE_ID.",+ )+ .with_data(data);+ }+ }++ CheckEntry::pass(+ NAME_BUNDLE_IDENTITY,+ format!("Embedded daemon is directly hosted by {observed}."),+ )+ .with_data(data)+}fn check_tcc_accessibility() -> CheckEntry {// Reuse the shared probe — do not duplicate AXIsProcessTrusted.@@ -216,13 +278,43 @@ fn check_screen_capture_capability() -> CheckEntry {// ── Helpers ──────────────────────────────────────────────────────────────────+fn application_bundle_identifier_for_pid(pid: u32) -> Option<String> {+ use core_foundation::url::kCFURLPOSIXPathStyle;+ use security_framework::os::macos::code_signing::{Flags, GuestAttributes, SecCode};++ let mut attributes = GuestAttributes::new();+ attributes.set_pid(pid as libc::pid_t);+ let code = SecCode::copy_guest_with_attribues(None, &attributes, Flags::NONE).ok()?;+ let url = code.path(Flags::NONE).ok()?;+ let path = std::path::PathBuf::from(url.get_file_system_path(kCFURLPOSIXPathStyle).to_string());+ let bundle_path = path+ .ancestors()+ .find(|candidate| candidate.extension().is_some_and(|ext| ext == "app"))?;+ let bundle_url = core_foundation::url::CFURL::from_path(bundle_path, true)?;+ let bundle = core_foundation::bundle::CFBundle::new(bundle_url)?;+ bundle_identifier(&bundle)+}++fn bundle_identifier(bundle: &core_foundation::bundle::CFBundle) -> Option<String> {+ use core_foundation::base::TCFType;+ use core_foundation::string::CFString;++ unsafe {+ let id_ref = core_foundation::bundle::CFBundleGetIdentifier(bundle.as_concrete_TypeRef());+ if id_ref.is_null() {+ return None;+ }+ let id = CFString::wrap_under_get_rule(id_ref).to_string();+ (!id.is_empty()).then_some(id)+ }+}+/// Read the running process's `CFBundleIdentifier` via CoreFoundation./// Returns `None` when the process has no associated bundle (e.g./// running the bare binary outside `CuaDriver.app`).fn current_bundle_identifier() -> Option<String> {use core_foundation::base::TCFType;use core_foundation::bundle::{CFBundle, CFBundleGetMainBundle};- use core_foundation::string::CFString;unsafe {let raw = CFBundleGetMainBundle();@@ -233,17 +325,7 @@ fn current_bundle_identifier() -> Option<String> {// without retaining and read the bundle identifier. `bundle`// intentionally doesn't drop the underlying CF object.let bundle = CFBundle::wrap_under_get_rule(raw);- let id_ref = core_foundation::bundle::CFBundleGetIdentifier(bundle.as_concrete_TypeRef());- if id_ref.is_null() {- return None;- }- let id = CFString::wrap_under_get_rule(id_ref);- let s = id.to_string();- if s.is_empty() {- None- } else {- Some(s)- }+ bundle_identifier(&bundle)}}@@ -282,6 +364,26 @@ mod tests {use cua_driver_core::tool::Tool;use std::sync::Arc;+ fn env_lock() -> std::sync::MutexGuard<'static, ()> {+ crate::permissions::test_env_lock()+ }++ fn swap_env(var: &str, value: Option<&str>) -> Option<std::ffi::OsString> {+ let original = std::env::var_os(var);+ match value {+ Some(v) => std::env::set_var(var, v),+ None => std::env::remove_var(var),+ }+ original+ }++ fn restore_env(var: &str, original: Option<std::ffi::OsString>) {+ match original {+ Some(value) => std::env::set_var(var, value),+ None => std::env::remove_var(var),+ }+ }+#[test]fn binary_version_always_passes() {let entry = check_binary_version();@@ -316,6 +418,9 @@ mod tests {#[test]fn bundle_identity_in_test_host_fails_with_full_shape() {+ let _guard = env_lock();+ let embedded = swap_env(cua_driver_core::EMBEDDED_ENV, None);+// The Rust test binary runs outside CuaDriver.app, so its// bundle id is either absent or not com.trycua.driver. Either// way the documented fail-mode shape applies: message + hint@@ -342,6 +447,58 @@ mod tests {data.executable_path.is_some(),"executable_path must be set so consumers can identify the wrong binary");++ restore_env(cua_driver_core::EMBEDDED_ENV, embedded);+ }++ #[test]+ fn embedded_bundle_identity_passes_for_observed_host() {+ let entry = check_embedded_bundle_identity(+ Some("com.example.host".to_owned()),+ Some("com.example.host".to_owned()),+ 1234,+ "/usr/local/bin/cua-driver".to_owned(),+ );+ assert_eq!(entry.status, CheckStatus::Pass);+ assert!(entry.message.contains("com.example.host"));+ assert!(entry.hint.is_none());+ let data = entry.data.expect("diagnostic data expected");+ assert_eq!(data.bundle_identifier.as_deref(), Some("com.example.host"));+ assert_eq!(+ data.configured_bundle_identifier.as_deref(),+ Some("com.example.host")+ );+ assert_eq!(data.identity_source.as_deref(), Some("parent_application"));+ assert_eq!(data.parent_process_id, Some(1234));+ }++ #[test]+ fn embedded_bundle_identity_fails_without_observable_host() {+ let entry = check_embedded_bundle_identity(+ None,+ Some("com.example.host".to_owned()),+ 1234,+ "/usr/local/bin/cua-driver".to_owned(),+ );+ assert_eq!(entry.status, CheckStatus::Fail);+ assert!(entry+ .message+ .contains("not an identifiable macOS application"));+ assert!(entry.hint.is_some());+ }++ #[test]+ fn embedded_bundle_identity_fails_on_configured_host_mismatch() {+ let entry = check_embedded_bundle_identity(+ Some("com.example.gateway".to_owned()),+ Some("com.example.host".to_owned()),+ 1234,+ "/usr/local/bin/cua-driver".to_owned(),+ );+ assert_eq!(entry.status, CheckStatus::Fail);+ assert!(entry.message.contains("com.example.gateway"));+ assert!(entry.message.contains("com.example.host"));+ assert!(entry.hint.is_some());}// End-to-end through the dispatcher — checks every macOS canonicaldiff --git a/libs/cua-driver/rust/examples/embedded-host-macos/ExampleAgentHarness.swift b/libs/cua-driver/rust/examples/embedded-host-macos/ExampleAgentHarness.swiftindex 9cb660a41b..89055d6748 100644--- a/libs/cua-driver/rust/examples/embedded-host-macos/ExampleAgentHarness.swift+++ b/libs/cua-driver/rust/examples/embedded-host-macos/ExampleAgentHarness.swift@@ -122,12 +122,29 @@ _ = readMessage()send(["jsonrpc": "2.0", "method": "notifications/initialized"])log("embedded cua-driver daemon + proxy started (\(driverPath)) — no driver prompt should have appeared")-// 4. check_permissions must report attribution "host" and never prompt.+// 4. health_report must observe this actual parent app, and+// check_permissions must report host attribution and matching TCC results.+let health = call("health_report", ["include": ["bundle_identity"]])+let healthStructured = health["structuredContent"] as? [String: Any] ?? [:]+let healthChecks = healthStructured["checks"] as? [[String: Any]] ?? []+let identity = healthChecks.first { $0["name"] as? String == "bundle_identity" } ?? [:]+let identityData = identity["data"] as? [String: Any] ?? [:]+let hostBundleId = Bundle.main.bundleIdentifier ?? ""+let identityOk = identity["status"] as? String == "pass" &&+ identityData["bundle_identifier"] as? String == hostBundleId &&+ identityData["identity_source"] as? String == "parent_application" &&+ (identityData["parent_process_id"] as? Int) == Int(ProcessInfo.processInfo.processIdentifier)+log("health_report — bundle_identity: \(identity["status"] ?? "?"), " ++ "observed host: \(identityData["bundle_identifier"] ?? "?") (want: \(hostBundleId))")+let perms = call("check_permissions")let structured = perms["structuredContent"] as? [String: Any] ?? [:]let source = structured["source"] as? [String: Any] ?? [:]let attribution = source["attribution"] as? String ?? "?"+let permissionsMatchHost = structured["accessibility"] as? Bool == ax &&+ structured["screen_recording"] as? Bool == srlog("check_permissions — attribution: \(attribution) (want: host), " ++ "TCC matches host: \(permissionsMatchHost), " +"capturable: \(structured["screen_recording_capturable"] ?? "?")")// 5. Background AX read + window screenshot — proves both grants@@ -158,7 +175,8 @@ let cursorOk = (cursor1["isError"] as? Bool) != true &&(cursor2["isError"] as? Bool) != truelog("move_cursor — \(cursorOk ? "ok" : "FAILED")")-let pass = attribution == "host" && !images.isEmpty && hasTree && cursorOk+let pass = identityOk && attribution == "host" && permissionsMatchHost &&+ !images.isEmpty && hasTree && cursorOklog(pass ? "DEMO COMPLETE: PASS" : "DEMO COMPLETE: FAIL")driver.terminate()daemon.terminate()