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): honor --pid-file in cua-driver status (#5246)

injaneitybab00b7b4039
diff --git a/.github/workflows/ci-rust-macos.yml b/.github/workflows/ci-rust-macos.yml
index 703facef2e..26db08a86f 100644
--- a/.github/workflows/ci-rust-macos.yml
+++ b/.github/workflows/ci-rust-macos.yml
@@ -77,14 +77,14 @@ jobs:
- name: Run cua-driver-core unit tests on macOS
working-directory: libs/cua-driver/rust
run: cargo test --locked -p cua-driver-core --lib
- - name: Run macOS protocol schema contract
+ - name: Run macOS protocol schema and status pid-file contracts
working-directory: libs/cua-driver/rust
env:
CUA_TEST_REQUIRE_DRIVER_BIN: "1"
CUA_TEST_DRIVER_STDERR: "1"
run: |
cargo build --locked -p cua-driver
- cargo test --locked -p cua-driver --test protocol_schema_test
+ cargo test --locked -p cua-driver --test protocol_schema_test --test status_pid_file_cli_test
# Desktop E2E suites are #[ignore] and run in the Lume harness. Their
# hermetic oracle and parser tests run here as a whole crate, including
# the macOS-gated ones that have no other runner: the harness's FIFO
diff --git a/.github/workflows/ci-rust-windows.yml b/.github/workflows/ci-rust-windows.yml
index 94c174b7b3..948a7c3b15 100644
--- a/.github/workflows/ci-rust-windows.yml
+++ b/.github/workflows/ci-rust-windows.yml
@@ -143,9 +143,9 @@ jobs:
- name: Run named-pipe readiness regression
working-directory: libs/cua-driver/rust
run: cargo test -p cua-driver-testkit stalled_pipe_attempt_is_bounded_and_does_not_block_the_next_probe --lib --locked
- - name: Run named-pipe instance recovery regression
+ - name: Run named-pipe instance recovery and status pid-file regressions
working-directory: libs/cua-driver/rust
- run: cargo test -p cua-driver --test named_pipe_instance_recovery_test --locked -- --nocapture
+ run: cargo test -p cua-driver --test named_pipe_instance_recovery_test --test status_pid_file_cli_test --locked -- --nocapture
- name: Run cross-platform cursor renderer unit tests
working-directory: libs/cua-driver/rust
run: |
diff --git a/docs/content/docs/cua-driver/reference/cli/daemon.mdx b/docs/content/docs/cua-driver/reference/cli/daemon.mdx
index 3a2dc9ee4e..22457659a6 100644
--- a/docs/content/docs/cua-driver/reference/cli/daemon.mdx
+++ b/docs/content/docs/cua-driver/reference/cli/daemon.mdx
@@ -39,7 +39,7 @@ cua-driver serve [OPTIONS]
| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| <span id="cua-driver-serve--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-serve--pid-file"></span>`--pid-file` | path | | Override the pid-file path on Unix targets. |
+| <span id="cua-driver-serve--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
| <span id="cua-driver-serve--permission-mode"></span>`--permission-mode` | string | `standard` | Immutable agent authorization mode: standard, bounded, or unrestricted. |
| <span id="cua-driver-serve--grant"></span>`--grant` | string | | Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile. |
| <span id="cua-driver-serve--capability-manifest"></span>`--capability-manifest` | path | | Optional narrow-only tool/resource ceiling; required in bounded mode. |
@@ -105,7 +105,7 @@ cua-driver status [OPTIONS]
| Flag | Type | Default | Description |
| --- | --- | --- | --- |
| <span id="cua-driver-status--socket"></span>`--socket` | string | | Override the daemon socket or named-pipe path. |
-| <span id="cua-driver-status--pid-file"></span>`--pid-file` | path | | Override the pid-file path on Unix targets. |
+| <span id="cua-driver-status--pid-file"></span>`--pid-file` | path | | Override the pid-file path. |
**Examples**
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
index 42eff1458e..ed11236d5b 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs
@@ -89,6 +89,7 @@ pub enum Command {
},
Status {
socket: Option<String>,
+ pid_file: Option<String>,
},
/// `cua-driver sessions list [--json]` — content-free operator view of
/// the live sessions owned by the selected daemon runtime.
@@ -880,7 +881,10 @@ pub fn parse_command() -> Command {
all,
}
}
- Some("status") => Command::Status { socket },
+ Some("status") => Command::Status {
+ socket,
+ pid_file: flag_value(&args, "--pid-file"),
+ },
Some("sessions") => {
let subcommand = pos.next().unwrap_or("list");
if subcommand != "list" {
@@ -4376,7 +4380,7 @@ fn cli_docs_literal() -> serde_json::Value {
"arguments": no_args,
"options": [
{"name":"socket","short_name":null,"help":"Override the daemon socket or named-pipe path.","type":"String","default_value":null,"is_optional":true},
- {"name":"pid-file","short_name":null,"help":"Override the pid-file path on Unix targets.","type":"Path","default_value":null,"is_optional":true},
+ {"name":"pid-file","short_name":null,"help":"Override the pid-file path.","type":"Path","default_value":null,"is_optional":true},
{"name":"permission-mode","short_name":null,"help":"Immutable agent authorization mode: standard, bounded, or unrestricted.","type":"String","default_value":"standard","is_optional":true},
{"name":"grant","short_name":null,"help":"Pre-authorize a residual standard-mode boundary. Repeatable; supported value: existing-profile.","type":"String","default_value":null,"is_optional":true,"is_repeatable":true},
{"name":"capability-manifest","short_name":null,"help":"Optional narrow-only tool/resource ceiling; required in bounded mode.","type":"Path","default_value":null,"is_optional":true},
@@ -4435,7 +4439,7 @@ fn cli_docs_literal() -> serde_json::Value {
"arguments": no_args,
"options": [
{"name":"socket","short_name":null,"help":"Override the daemon socket or named-pipe path.","type":"String","default_value":null,"is_optional":true},
- {"name":"pid-file","short_name":null,"help":"Override the pid-file path on Unix targets.","type":"Path","default_value":null,"is_optional":true}
+ {"name":"pid-file","short_name":null,"help":"Override the pid-file path.","type":"Path","default_value":null,"is_optional":true}
],
"flags": no_flags,
"subcommands": no_subcommands
diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
index ca22070776..88e78472ec 100644
--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs
+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs
@@ -780,9 +780,9 @@ fn main() {
let sp = socket.unwrap_or_else(serve::default_socket_path);
serve::run_revoke_cmd(&sp, session.as_deref(), all);
}
- cli::Command::Status { socket } => {
+ cli::Command::Status { socket, pid_file } => {
let sp = socket.unwrap_or_else(serve::default_socket_path);
- let pid_path = serve::default_pid_file_path();
+ let pid_path = pid_file.unwrap_or_else(serve::default_pid_file_path);
serve::run_status_cmd(&sp, &pid_path);
}
cli::Command::Sessions { json, socket } => {
@@ -1078,9 +1078,9 @@ fn main() -> anyhow::Result<()> {
serve::run_revoke_cmd(&sp, session.as_deref(), all);
Ok(())
}
- cli::Command::Status { socket } => {
+ cli::Command::Status { socket, pid_file } => {
let sp = socket.unwrap_or_else(serve::default_socket_path);
- let pid_path = serve::default_pid_file_path();
+ let pid_path = pid_file.unwrap_or_else(serve::default_pid_file_path);
serve::run_status_cmd(&sp, &pid_path);
Ok(())
}
diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/status_pid_file_cli_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/status_pid_file_cli_test.rs
new file mode 100644
index 0000000000..48e800311a
--- /dev/null
+++ b/libs/cua-driver/rust/crates/cua-driver/tests/status_pid_file_cli_test.rs
@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Cua AI, Inc.
+
+#![cfg(any(unix, target_os = "windows"))]
+
+use cua_driver_testkit::{spawn_in_job, ChildReaper};
+use std::path::Path;
+use std::process::{Child, Command, Output, Stdio};
+use std::time::{Duration, Instant};
+
+const BOUND: Duration = Duration::from_secs(10);
+const PROBE_BOUND: Duration = Duration::from_secs(2);
+
+fn driver(home: &Path, args: &[&str]) -> Command {
+ let mut command = Command::new(env!("CARGO_BIN_EXE_cua-driver"));
+ command
+ .args(args)
+ .stdin(Stdio::null())
+ .env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "false")
+ .env("HOME", home)
+ .env("USERPROFILE", home)
+ .env("LOCALAPPDATA", home)
+ .env("XDG_STATE_HOME", home)
+ .env("CUA_DRIVER_HOME", home)
+ .env("CUA_DRIVER_LOCAL_HOME", home)
+ .env("CUA_DRIVER_RS_HOME", home);
+ command
+}
+
+fn run_status(home: &Path, args: &[&str], limit: Duration) -> Option<Output> {
+ let mut command = driver(home, args);
+ command.stdout(Stdio::piped()).stderr(Stdio::piped());
+ let mut child = spawn_in_job(&mut command).expect("spawn cua-driver status");
+ let deadline = Instant::now() + limit;
+ loop {
+ if child.try_wait().expect("poll cua-driver status").is_some() {
+ return Some(child.wait_with_output().expect("collect status output"));
+ }
+ if Instant::now() >= deadline {
+ let _ = child.kill();
+ let _ = child.wait();
+ return None;
+ }
+ std::thread::sleep(Duration::from_millis(20));
+ }
+}
+
+fn status_pid(home: &Path, args: &[&str]) -> String {
+ let output = run_status(home, args, BOUND)
+ .unwrap_or_else(|| panic!("status {args:?} did not finish within {BOUND:?}"));
+ let stdout = String::from_utf8_lossy(&output.stdout);
+ assert!(
+ output.status.success(),
+ "status {args:?} failed: {stdout}{}",
+ String::from_utf8_lossy(&output.stderr)
+ );
+ stdout
+ .lines()
+ .find_map(|line| line.trim().strip_prefix("pid: "))
+ .unwrap_or_else(|| panic!("status {args:?} printed no pid line: {stdout}"))
+ .to_owned()
+}
+
+fn wait_until_ready(
+ daemon: &mut Child,
+ home: &Path,
+ socket: &str,
+ pid_file: &str,
+) -> Result<String, String> {
+ let deadline = Instant::now() + BOUND;
+ loop {
+ if let Ok(Some(status)) = daemon.try_wait() {
+ return Err(format!(
+ "daemon exited before becoming ready: {status}. \
+ Set CUA_TEST_DRIVER_STDERR=1 to inherit daemon stderr."
+ ));
+ }
+ let written = std::fs::read_to_string(pid_file).unwrap_or_default();
+ let reachable = run_status(home, &["status", "--socket", socket], PROBE_BOUND)
+ .is_some_and(|output| output.status.success());
+ if reachable && !written.trim().is_empty() {
+ return Ok(written.trim().to_owned());
+ }
+ if Instant::now() >= deadline {
+ return Err(format!(
+ "daemon did not become ready within {BOUND:?} (process still running). \
+ Set CUA_TEST_DRIVER_STDERR=1 to inherit daemon stderr."
+ ));
+ }
+ std::thread::sleep(Duration::from_millis(50));
+ }
+}
+
+#[test]
+fn status_reports_the_pid_stored_in_the_file_named_by_pid_file() {
+ let home = tempfile::tempdir().unwrap();
+ #[cfg(unix)]
+ let endpoint_dir = tempfile::Builder::new()
+ .prefix("cua-status-")
+ .tempdir_in("/tmp")
+ .unwrap();
+ #[cfg(unix)]
+ let socket = endpoint_dir.path().join("d.sock").display().to_string();
+ #[cfg(target_os = "windows")]
+ let socket = format!(r"\\.\pipe\cua-status-pid-file-{}", std::process::id());
+
+ let daemon_pid_file = home.path().join("daemon.pid").display().to_string();
+ let other_pid_file = home.path().join("other.pid").display().to_string();
+
+ let mut serve = driver(
+ home.path(),
+ &[
+ "serve",
+ "--socket",
+ &socket,
+ "--pid-file",
+ &daemon_pid_file,
+ "--no-overlay",
+ "--no-permissions-gate",
+ ],
+ );
+ serve
+ .stdout(Stdio::null())
+ .stderr(if std::env::var_os("CUA_TEST_DRIVER_STDERR").is_some() {
+ Stdio::inherit()
+ } else {
+ Stdio::null()
+ });
+ let mut reaper = ChildReaper::new();
+ let mut daemon = spawn_in_job(&mut serve).expect("spawn source-built daemon");
+ let ready = wait_until_ready(&mut daemon, home.path(), &socket, &daemon_pid_file);
+ reaper.push(daemon);
+ let daemon_pid = ready.unwrap_or_else(|error| panic!("{error}"));
+
+ assert_eq!(
+ status_pid(
+ home.path(),
+ &[
+ "status",
+ "--socket",
+ &socket,
+ "--pid-file",
+ &daemon_pid_file
+ ],
+ ),
+ daemon_pid,
+ );
+ assert_eq!(
+ status_pid(
+ home.path(),
+ &[
+ &format!("--pid-file={daemon_pid_file}"),
+ "status",
+ "--socket",
+ &socket,
+ ],
+ ),
+ daemon_pid,
+ );
+
+ let this_process = std::process::id().to_string();
+ assert_ne!(this_process, daemon_pid);
+ std::fs::write(&other_pid_file, &this_process).unwrap();
+ assert_eq!(
+ status_pid(
+ home.path(),
+ &["status", "--socket", &socket, "--pid-file", &other_pid_file],
+ ),
+ this_process,
+ );
+
+ assert_eq!(
+ status_pid(home.path(), &["status", "--socket", &socket]),
+ "unknown (no pid file)",
+ );
+}
diff --git a/scripts/docs-generators/cli-specs/cua-driver.json b/scripts/docs-generators/cli-specs/cua-driver.json
index 56b6a800dd..6ef809d31a 100644
--- a/scripts/docs-generators/cli-specs/cua-driver.json
+++ b/scripts/docs-generators/cli-specs/cua-driver.json
@@ -265,7 +265,7 @@
},
{
"default_value": null,
- "help": "Override the pid-file path on Unix targets.",
+ "help": "Override the pid-file path.",
"is_optional": true,
"name": "pid-file",
"short_name": null,
@@ -461,7 +461,7 @@
},
{
"default_value": null,
- "help": "Override the pid-file path on Unix targets.",
+ "help": "Override the pid-file path.",
"is_optional": true,
"name": "pid-file",
"short_name": null,