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): polish CLI pipe, extension, schema, and output-path UX (#4210)
Francesco Bonacci70b87b4f26d8
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools-linux.mdx b/docs/content/docs/reference/cua-driver/mcp-tools-linux.mdxindex 8cf93d9af2..de38cd891f 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools-linux.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools-linux.mdx@@ -577,7 +577,7 @@ Turn folders are named `turn-00001/`, `turn-00002/`, etc. Turn numbering restar**Video is off by default.** Pass `record_video: true` to also capture the main display to `<output_dir>/recording.mp4` (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.-**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) so video inherits the daemon's Screen Recording grant — no extra TCC prompt, no ffmpeg subprocess. Requires macOS 15.0+.+**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) under the daemon's Screen Recording grant, with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 (Tahoe), the first direct capture can also show a one-time consent asking to let Cua Driver bypass the system private window picker and directly access your screen and audio; choose Allow, or run `cua-driver permissions grant` beforehand to answer it up front. The recorder captures screen video only and does not enable system-audio capture.**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / `x11grab` + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's `last_error` field carries the diagnostic.@@ -586,7 +586,7 @@ State persists for the life of the daemon; a restart resets to disabled with no**Arguments:**- `output_dir` (string, required): Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written.-- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (no extra TCC prompt, macOS 15.0+); on Windows + Linux it requires ffmpeg on PATH.+- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time direct screen-capture consent on first use (see `cua-driver permissions grant`). On Windows + Linux it requires ffmpeg on PATH.```json{"output_dir":"~/cua-trajectories/demo1"}diff --git a/docs/content/docs/reference/cua-driver/mcp-tools-windows.mdx b/docs/content/docs/reference/cua-driver/mcp-tools-windows.mdxindex 4eea00a269..2555ed3942 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools-windows.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools-windows.mdx@@ -669,7 +669,7 @@ Turn folders are named `turn-00001/`, `turn-00002/`, etc. Turn numbering restar**Video is off by default.** Pass `record_video: true` to also capture the main display to `<output_dir>/recording.mp4` (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.-**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) so video inherits the daemon's Screen Recording grant — no extra TCC prompt, no ffmpeg subprocess. Requires macOS 15.0+.+**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) under the daemon's Screen Recording grant, with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 (Tahoe), the first direct capture can also show a one-time consent asking to let Cua Driver bypass the system private window picker and directly access your screen and audio; choose Allow, or run `cua-driver permissions grant` beforehand to answer it up front. The recorder captures screen video only and does not enable system-audio capture.**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / `x11grab` + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's `last_error` field carries the diagnostic.@@ -678,7 +678,7 @@ State persists for the life of the daemon; a restart resets to disabled with no**Arguments:**- `output_dir` (string, required): Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written.-- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (no extra TCC prompt, macOS 15.0+); on Windows + Linux it requires ffmpeg on PATH.+- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time direct screen-capture consent on first use (see `cua-driver permissions grant`). On Windows + Linux it requires ffmpeg on PATH.```json{"output_dir":"~/cua-trajectories/demo1"}diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 850b93f743..0abb8ce7d9 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -627,7 +627,7 @@ Turn folders are named `turn-00001/`, `turn-00002/`, etc. Turn numbering restar**Video is off by default.** Pass `record_video: true` to also capture the main display to `<output_dir>/recording.mp4` (H.264 / 30 fps) for the lifetime of the session. The recording is torn down automatically when the MCP client disconnects.-**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) so video inherits the daemon's Screen Recording grant — no extra TCC prompt, no ffmpeg subprocess. Requires macOS 15.0+.+**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + SCRecordingOutput) under the daemon's Screen Recording grant, with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 (Tahoe), the first direct capture can also show a one-time consent asking to let Cua Driver bypass the system private window picker and directly access your screen and audio; choose Allow, or run `cua-driver permissions grant` beforehand to answer it up front. The recorder captures screen video only and does not enable system-audio capture.**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / `x11grab` + libx264). Requires ffmpeg on PATH (winget install Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or fails on startup the per-turn capture (screenshots + action.json) still runs and the session's `last_error` field carries the diagnostic.@@ -636,7 +636,7 @@ State persists for the life of the daemon; a restart resets to disabled with no**Arguments:**- `output_dir` (string, required): Absolute or ~-rooted directory where turn folders and (when enabled) the video file are written.-- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (no extra TCC prompt, macOS 15.0+); on Windows + Linux it requires ffmpeg on PATH.+- `record_video` (boolean, optional): Capture the main display to <output_dir>/recording.mp4. Default: false. Set to true to also capture the main display to recording.mp4 (otherwise only the per-turn screenshots + JSON are recorded). On macOS this uses native ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time direct screen-capture consent on first use (see `cua-driver permissions grant`). On Windows + Linux it requires ffmpeg on PATH.```json{"output_dir":"~/cua-trajectories/demo1"}diff --git a/libs/cua-driver/contract/manifest.json b/libs/cua-driver/contract/manifest.jsonindex f448282fb4..aa3e59fa27 100644--- a/libs/cua-driver/contract/manifest.json+++ b/libs/cua-driver/contract/manifest.json@@ -3054,7 +3054,7 @@},"input_schema": {"additionalProperties": false,- "description": "Transport-free request. Runtime use requires the future capture registry.",+ "description": "Parse one immutable screenshot capture. Pass the `capture_id` returned by\n`get_window_state` or `get_desktop_state`; the Driver capture registry\nresolves it to the exact pixels and action-coordinate transform.","properties": {"capture_id": {"minLength": 1,diff --git a/libs/cua-driver/python/src/cua_driver/_native_contract.py b/libs/cua-driver/python/src/cua_driver/_native_contract.pyindex 2cbdb0ec60..674ca47c45 100644--- a/libs/cua-driver/python/src/cua_driver/_native_contract.py+++ b/libs/cua-driver/python/src/cua_driver/_native_contract.py@@ -4869,7 +4869,9 @@ class _UniffiFfiConverterTypeParseVisualRegionsOptions(_UniffiConverterRustBuffe@dataclassclass ParseVisualRegionsInput:"""- Transport-free request. Runtime use requires the future capture registry.+ Parse one immutable screenshot capture. Pass the `capture_id` returned by+ `get_window_state` or `get_desktop_state`; the Driver capture registry+ resolves it to the exact pixels and action-coordinate transform."""def __init__(self, *, capture_id:str, options:ParseVisualRegionsOptions):self.capture_id = capture_id@@ -5035,7 +5037,7 @@ class _UniffiFfiConverterTypeVisualCaptureSource(_UniffiConverterRustBuffer):@dataclassclass VisualScreenshotReference:"""- Screenshot identity and geometry retained by the future capture registry.+ Screenshot identity and geometry retained by the Driver capture registry."""def __init__(self, *, reference:str, width:int, height:int, mime_type:str, sha256:typing.Optional[str]):self.reference = referencediff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rsindex a86d8b9d6f..9791f2a166 100644--- a/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rs+++ b/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rs@@ -3,12 +3,12 @@//! Model-neutral DTOs for parsing an immutable screenshot into visual regions.//!-//! This module is a transport-free public contract. It registers the callable-//! tool schema without implementing dispatch. A Driver-owned capture registry-//! must retain an immutable PNG together with its exact-//! target and screenshot-to-action transform for every `capture_id`. Current-//! `WindowStateOutput::snapshot_id` values do not retain screenshot pixels, and-//! `DesktopStateOutput` has no capture ID, so neither satisfies this contract.+//! This module is a transport-free public contract: it defines the callable+//! tool schema, and `cua-driver-core` implements dispatch. The Driver-owned+//! capture registry retains an immutable PNG together with its exact target and+//! screenshot-to-action transform for every `capture_id`. `get_window_state`+//! and `get_desktop_state` return such a `capture_id` with their screenshot; a+//! `snapshot_id` alone does not retain screenshot pixels.//!//! V1 deliberately refers to registry captures instead of accepting inline//! bytes or file paths. Existing MCP images carry base64 data in the envelope,@@ -80,7 +80,7 @@ pub enum VisualCaptureSource {},}-/// Screenshot identity and geometry retained by the future capture registry.+/// Screenshot identity and geometry retained by the Driver capture registry.#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, uniffi::Record)]pub struct VisualScreenshotReference {/// Opaque identity for these exact encoded pixels, such as a content digest.@@ -186,7 +186,9 @@ pub struct ParseVisualRegionsOptions {pub max_regions: Option<u32>,}-/// Transport-free request. Runtime use requires the future capture registry.+/// Parse one immutable screenshot capture. Pass the `capture_id` returned by+/// `get_window_state` or `get_desktop_state`; the Driver capture registry+/// resolves it to the exact pixels and action-coordinate transform.#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, uniffi::Record)]#[serde(deny_unknown_fields)]pub struct ParseVisualRegionsInput {diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/recording_tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/recording_tools.rsindex 43779ee71b..b6a6bcf277 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/recording_tools.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/recording_tools.rs@@ -69,9 +69,14 @@ impl Tool for StartRecordingTool {30 fps) for the lifetime of the session. The recording is torn \down automatically when the MCP client disconnects.\n\n\**macOS uses native ScreenCaptureKit** (daemon-owned SCStream + \- SCRecordingOutput) so video inherits the daemon's Screen \- Recording grant — no extra TCC prompt, no ffmpeg subprocess. \- Requires macOS 15.0+.\n\n\+ SCRecordingOutput) under the daemon's Screen Recording grant, \+ with no ffmpeg subprocess. Requires macOS 15.0+. On macOS 26 \+ (Tahoe), the first direct capture can also show a one-time \+ consent asking to let Cua Driver bypass the system private \+ window picker and directly access your screen and audio; \+ choose Allow, or run `cua-driver permissions grant` beforehand \+ to answer it up front. The recorder captures screen video only \+ and does not enable system-audio capture.\n\n\**Windows + Linux use an ffmpeg subprocess** (`gdigrab` / \`x11grab` + libx264). Requires ffmpeg on PATH (winget install \Gyan.FFmpeg / apt install ffmpeg); when ffmpeg is missing or \@@ -97,8 +102,10 @@ impl Tool for StartRecordingTool {Default: false. Set to true to also capture the main \display to recording.mp4 (otherwise only the per-turn \screenshots + JSON are recorded). On macOS this uses native \- ScreenCaptureKit (no extra TCC prompt, macOS 15.0+); on \- Windows + Linux it requires ffmpeg on PATH."+ ScreenCaptureKit (macOS 15.0+); macOS 26 can show a one-time \+ direct screen-capture consent on first use (see \+ `cua-driver permissions grant`). On Windows + Linux it \+ requires ffmpeg on PATH."}},"additionalProperties": falsediff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/session_manifest.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/session_manifest.rsindex 4fa445fb19..1d3b4c7994 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/session_manifest.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/session_manifest.rs@@ -1271,6 +1271,9 @@ fn canonical_manifest_path(path: &Path) -> Result<String, String> {}Ok(_) => return Err("path contains an unavailable filesystem entry".to_owned()),Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}+ Err(error) if error.kind() == std::io::ErrorKind::NotADirectory => {+ return Err("an ancestor of the path is not a directory".to_owned())+ }Err(error) => return Err(error.to_string()),}let name = existing@@ -1281,9 +1284,11 @@ fn canonical_manifest_path(path: &Path) -> Result<String, String> {.parent().ok_or_else(|| "path has no existing ancestor".to_owned())?;}- let metadata = std::fs::symlink_metadata(existing).map_err(|error| error.to_string())?;+ // Follow a symlinked deepest ancestor (macOS `/tmp` -> `/private/tmp`);+ // `canonicalize` below records its resolved target.+ let metadata = std::fs::metadata(existing).map_err(|error| error.to_string())?;if !metadata.is_dir() {- return Err("existing ancestor is not a directory".to_owned());+ return Err("deepest existing ancestor is not a directory".to_owned());}let mut canonical = std::fs::canonicalize(existing).map_err(|error| error.to_string())?;for component in suffix.into_iter().rev() {@@ -1721,6 +1726,31 @@ allow:.unwrap();}+ #[cfg(all(feature = "yaml", unix))]+ #[test]+ fn manifest_paths_resolve_a_symlinked_deepest_ancestor() {+ let root = tempfile::tempdir().unwrap();+ let target = root.path().join("private-tmp");+ std::fs::create_dir(&target).unwrap();+ let link = root.path().join("tmp");+ std::os::unix::fs::symlink(&target, &link).unwrap();+ assert_eq!(+ canonical_manifest_path(&link.join("out.png")).unwrap(),+ std::fs::canonicalize(&target)+ .unwrap()+ .join("out.png")+ .to_string_lossy()+ );+ let file = root.path().join("file");+ std::fs::write(&file, b"").unwrap();+ let file_link = root.path().join("file-link");+ std::os::unix::fs::symlink(&file, &file_link).unwrap();+ assert_eq!(+ canonical_manifest_path(&file_link.join("out.png")).unwrap_err(),+ "an ancestor of the path is not a directory"+ );+ }+#[cfg(feature = "yaml")]#[test]fn protected_resources_are_exactly_bounded_by_the_manifest() {diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rsindex 054d0ba938..b96bdc0d80 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs@@ -2556,7 +2556,12 @@ fn canonical_existing_file(raw: &str) -> Result<String, ToolResult> {/// The deepest existing ancestor is canonicalized first, so symlinked parents/// are captured in the approved identity. Only normal path components may be/// appended after that ancestor; lexical parent traversal never enters a-/// protected-resource digest.+/// protected-resource digest. The caller replaces the raw argument with this+/// canonical path, so the tool writes exactly the approved location.+///+/// A deepest existing ancestor that is itself a symbolic link to a directory+/// (macOS `/tmp` -> `/private/tmp`) is resolved like any other symlinked+/// parent. A link to a non-directory is refused.fn canonical_proposed_path(raw: &str) -> Result<String, ToolResult> {let path = expanded_path(raw)?;if path.exists() {@@ -2580,6 +2585,11 @@ fn canonical_proposed_path(raw: &str) -> Result<String, ToolResult> {))}Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}+ Err(error) if error.kind() == std::io::ErrorKind::NotADirectory => {+ return Err(protected_scope_refusal(+ "an ancestor of the output path is not a directory",+ ))+ }Err(_) => {return Err(protected_scope_refusal("the output path could not be inspected safely",@@ -2594,11 +2604,13 @@ fn canonical_proposed_path(raw: &str) -> Result<String, ToolResult> {.parent().ok_or_else(|| protected_scope_refusal("the output path has no existing ancestor"))?;}- let metadata = std::fs::symlink_metadata(existing)+ // Follow a symlinked ancestor: `exists()` above already resolved it, and+ // `canonicalize` below records its target in the approved identity.+ let metadata = std::fs::metadata(existing).map_err(|_| protected_scope_refusal("the output ancestor is unavailable"))?;if !metadata.is_dir() {return Err(protected_scope_refusal(- "the output path's existing ancestor is not a directory",+ "the output path's deepest existing ancestor is not a directory",));}let mut canonical = std::fs::canonicalize(existing)@@ -4546,6 +4558,55 @@ resources:assert_eq!(provider.requests.load(Ordering::SeqCst), 0);}+ #[cfg(unix)]+ #[test]+ fn proposed_output_scope_resolves_a_symlinked_deepest_ancestor() {+ // Mirrors macOS `/tmp/x.png`, where `/tmp` links to `/private/tmp`.+ let root = tempfile::tempdir().unwrap();+ let target = root.path().join("private-tmp");+ std::fs::create_dir(&target).unwrap();+ let link = root.path().join("tmp");+ std::os::unix::fs::symlink(&target, &link).unwrap();+ let proposed = link.join("x.png");++ let canonical = canonical_proposed_path(proposed.to_str().unwrap()).unwrap();++ assert_eq!(+ canonical,+ std::fs::canonicalize(&target)+ .unwrap()+ .join("x.png")+ .to_string_lossy()+ );+ assert!(!proposed.exists());+ // The same file already existing was always resolved; both agree.+ std::fs::write(target.join("x.png"), b"").unwrap();+ assert_eq!(+ canonical_proposed_path(proposed.to_str().unwrap()).unwrap(),+ canonical+ );+ }++ #[cfg(unix)]+ #[test]+ fn proposed_output_scope_refuses_a_symlinked_ancestor_that_is_not_a_directory() {+ let root = tempfile::tempdir().unwrap();+ let file = root.path().join("file");+ std::fs::write(&file, b"").unwrap();+ let link = root.path().join("link");+ std::os::unix::fs::symlink(&file, &link).unwrap();+ let proposed = link.join("x.png");++ let refusal = canonical_proposed_path(proposed.to_str().unwrap()).unwrap_err();++ let text = serde_json::to_string(&refusal).unwrap();+ assert!(+ text.contains("an ancestor of the output path is not a directory"),+ "{text}"+ );+ assert!(!file.with_file_name("x.png").exists());+ }+#[test]fn proposed_output_scope_canonicalizes_the_existing_ancestor_without_creating_output() {let root = tempfile::tempdir().unwrap();diff --git a/libs/cua-driver/rust/crates/cua-driver/src/broken_pipe.rs b/libs/cua-driver/rust/crates/cua-driver/src/broken_pipe.rsnew file mode 100644index 0000000000..0407ba354e--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/src/broken_pipe.rs@@ -0,0 +1,143 @@+//! Clean exit when a finite CLI command's reader closes its output early.+//!+//! The CLI prints through `println!`/`eprintln!`, which panic with+//! `failed printing to stdout: <io error>` when the reader of a pipe has gone+//! away (for example `cua-driver status | head -3`). Rust ignores `SIGPIPE`, so+//! the write returns `EPIPE` on Unix, and Windows reports `ERROR_NO_DATA` /+//! `ERROR_BROKEN_PIPE`; both map to [`std::io::ErrorKind::BrokenPipe`].+//!+//! Restoring the default `SIGPIPE` disposition process-wide would also kill+//! the CLI silently when an internal socket or worker pipe closes, hiding the+//! diagnostics those paths already report. Instead, finite commands install a+//! panic hook that recognises only a broken pipe on the process's own stdout or+//! stderr and terminates the way a conventional pipeline stage does: on Unix+//! the process dies from `SIGPIPE` (status 141 in shells), and on Windows it+//! exits with the same status code 141. Every other panic keeps the previous+//! hook's behavior.+//!+//! Long-lived transports (`mcp`, `serve`, and bare invocation, which runs MCP)+//! do not install the hook, so their existing per-task panic handling is+//! unchanged.++use std::io::ErrorKind;++/// Exit status a shell reports for a process terminated by `SIGPIPE`.+pub const BROKEN_PIPE_EXIT_CODE: i32 = 128 + 13;++/// Install the broken-pipe hook when argv names a finite command.+pub fn install_for_finite_command_from_argv() {+ let args: Vec<String> = std::env::args().skip(1).collect();+ if crate::cli::is_long_lived_transport_command(&args) {+ return;+ }+ let previous = std::panic::take_hook();+ std::panic::set_hook(Box::new(move |info| {+ let message = info+ .payload()+ .downcast_ref::<String>()+ .map(String::as_str)+ .or_else(|| info.payload().downcast_ref::<&str>().copied());+ if message.is_some_and(is_broken_pipe_print_panic) {+ terminate_for_broken_pipe();+ }+ previous(info);+ }));+}++/// True only for the standard library's stdout/stderr print panic whose+/// underlying OS error is a broken pipe on the current platform.+pub fn is_broken_pipe_print_panic(message: &str) -> bool {+ let Some(error) = message+ .strip_prefix("failed printing to stdout: ")+ .or_else(|| message.strip_prefix("failed printing to stderr: "))+ else {+ return false;+ };+ let Some(code) = error+ .trim_end()+ .strip_suffix(')')+ .and_then(|rest| rest.rsplit_once("(os error "))+ .and_then(|(_, code)| code.parse::<i32>().ok())+ else {+ return false;+ };+ std::io::Error::from_raw_os_error(code).kind() == ErrorKind::BrokenPipe+}++/// Map a child's exit status to the status a shell would report, so the+/// telemetry wrapper preserves a signal death such as `SIGPIPE` as `128 + n`+/// instead of collapsing it to a generic failure.+pub fn shell_exit_code(status: std::process::ExitStatus) -> i32 {+ if let Some(code) = status.code() {+ return code;+ }+ #[cfg(unix)]+ {+ use std::os::unix::process::ExitStatusExt;+ if let Some(signal) = status.signal() {+ return 128 + signal;+ }+ }+ 1+}++fn terminate_for_broken_pipe() -> ! {+ #[cfg(unix)]+ // SAFETY: restoring the default disposition and raising a signal on the+ // current process are async-signal-safe libc calls with no Rust invariants.+ unsafe {+ libc::signal(libc::SIGPIPE, libc::SIG_DFL);+ libc::raise(libc::SIGPIPE);+ }+ std::process::exit(BROKEN_PIPE_EXIT_CODE)+}++#[cfg(test)]+mod tests {+ use super::*;++ fn print_panic(stream: &str, error: std::io::Error) -> String {+ format!("failed printing to {stream}: {error}")+ }++ #[test]+ fn recognises_the_platform_broken_pipe_print_panic() {+ #[cfg(unix)]+ let codes = [libc::EPIPE];+ // ERROR_BROKEN_PIPE and ERROR_NO_DATA ("The pipe is being closed.").+ #[cfg(windows)]+ let codes = [109, 232];+ for code in codes {+ let error = std::io::Error::from_raw_os_error(code);+ assert!(is_broken_pipe_print_panic(&print_panic("stdout", error)));+ let error = std::io::Error::from_raw_os_error(code);+ assert!(is_broken_pipe_print_panic(&print_panic("stderr", error)));+ }+ }++ #[test]+ fn keeps_other_print_failures_and_panics_visible() {+ #[cfg(unix)]+ let other = libc::ENOSPC;+ #[cfg(windows)]+ let other = 112; // ERROR_DISK_FULL+ let error = std::io::Error::from_raw_os_error(other);+ assert!(!is_broken_pipe_print_panic(&print_panic("stdout", error)));+ let custom = std::io::Error::new(ErrorKind::BrokenPipe, "synthetic");+ assert!(!is_broken_pipe_print_panic(&print_panic("stdout", custom)));+ assert!(!is_broken_pipe_print_panic(+ "called `Result::unwrap()` on an `Err` value: Broken pipe (os error 32)"+ ));+ assert!(!is_broken_pipe_print_panic("failed printing to stdout"));+ }++ #[cfg(unix)]+ #[test]+ fn wrapper_reports_signal_deaths_like_a_shell() {+ use std::os::unix::process::ExitStatusExt;+ let status = std::process::ExitStatus::from_raw(libc::SIGPIPE);+ assert_eq!(shell_exit_code(status), BROKEN_PIPE_EXIT_CODE);+ let status = std::process::ExitStatus::from_raw(3 << 8);+ assert_eq!(shell_exit_code(status), 3);+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex 6b6034caa2..e785dbd032 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -302,6 +302,22 @@ fn positional_args(args: &[String]) -> Vec<&str> {positionals}+/// True when argv runs a long-lived transport rather than a finite command:+/// `mcp`, `serve`, or a bare invocation (which runs MCP). `--help` and+/// `--version` always print and exit, so they are finite.+pub fn is_long_lived_transport_command(args: &[String]) -> bool {+ if args+ .iter()+ .any(|arg| matches!(arg.as_str(), "--help" | "-h" | "--version" | "-V"))+ {+ return false;+ }+ matches!(+ positional_args(args).first().copied(),+ None | Some("mcp" | "serve")+ )+}+fn finite_command_name_from_args(args: &[String]) -> Option<&'static str> {if args.iter()@@ -4866,6 +4882,38 @@ mod tests {values.iter().map(|value| (*value).to_owned()).collect()}+ #[test]+ fn only_transports_skip_the_finite_broken_pipe_contract() {+ for transport in [+ &[][..],+ &["mcp"],+ &["serve"],+ &["serve", "--socket", "/tmp/s"],+ ] {+ assert!(+ is_long_lived_transport_command(&args(transport)),+ "{transport:?}"+ );+ }+ for finite in [+ &["status"][..],+ &["list-tools"],+ &["describe", "click"],+ &["dump-docs", "--type", "cli"],+ &["extension", "inspect", "cua-perception"],+ &["telemetry", "status"],+ &["click", "{}"],+ &["--help"],+ &["mcp", "--help"],+ &["--version"],+ ] {+ assert!(+ !is_long_lived_transport_command(&args(finite)),+ "{finite:?}"+ );+ }+ }+#[test]fn history_relaunch_preserves_authorization_mode_and_every_grant() {let grants = args(&["capability:a", "capability:b"]);diff --git a/libs/cua-driver/rust/crates/cua-driver/src/extension_manager.rs b/libs/cua-driver/rust/crates/cua-driver/src/extension_manager.rsindex bc5a895437..fe5659dcb2 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/extension_manager.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/extension_manager.rs@@ -1751,89 +1751,112 @@ fn print_preview(preview: &InstallReview, json: bool) -> Result<()> {if json {println!("{}", serde_json::to_string_pretty(&preview)?);} else {- println!("Extension: {} {}", preview.id, preview.version);- println!("Name: {}", preview.name);- println!("Trust: {}", trust_label(&preview.trust));- println!("Evidence class: {}", preview.evidence_class);- #[cfg(feature = "review-trust-root")]- if preview.trust == TrustClass::ReviewOnlyPublisherVerified {- println!("{REVIEW_TRUST_NOTICE}");- }- if let (Some(publisher), Some(key), Some(catalog), Some(expires)) = (- &preview.publisher_name,- &preview.publisher_key_id,- preview.catalog_version,- preview.catalog_expires_unix,- ) {- println!(- "Publisher signature: verified {} with key {} (catalog {}, expires {})",- publisher, key, catalog, expires- );- }- println!("Signing key status: {}", preview.signing_key_status);- if let Some(publisher_id) = &preview.publisher_id {- println!("Publisher ID: {publisher_id}");- }- if let Some(algorithm) = &preview.signing_key_algorithm {- println!("Signing key algorithm: {algorithm}");- }- println!("Artifact source: {}", preview.artifact_source);- println!("Destination: {}", preview.destination);- println!("Download size: {} bytes", preview.download_size);- println!("Installed size: {} bytes", preview.installed_size);- println!("License: {}", preview.license);- println!("Source: {}", preview.source);- println!(- "Corresponding source: {} @ {}",- preview.corresponding_source_uri, preview.corresponding_source_revision- );- if let Some(file) = &preview.corresponding_source.file {- println!(- "Corresponding source file: {} | SHA-256 {}",+ // Render first and print once so a closed stdout takes the same+ // broken-pipe path as every other CLI `print!`.+ let mut text = Vec::new();+ write_preview_text(&mut text, preview)?;+ print!("{}", String::from_utf8_lossy(&text));+ }+ Ok(())+}++/// Human-readable install review. The "no extension state was changed"+/// footer is only true for a preview that does not authorize mutation+/// (`inspect`); `install` and `update` go on to change state and print their+/// own result line instead.+fn write_preview_text(out: &mut impl Write, preview: &InstallReview) -> std::io::Result<()> {+ writeln!(out, "Extension: {} {}", preview.id, preview.version)?;+ writeln!(out, "Name: {}", preview.name)?;+ writeln!(out, "Trust: {}", trust_label(&preview.trust))?;+ writeln!(out, "Evidence class: {}", preview.evidence_class)?;+ #[cfg(feature = "review-trust-root")]+ if preview.trust == TrustClass::ReviewOnlyPublisherVerified {+ writeln!(out, "{REVIEW_TRUST_NOTICE}")?;+ }+ if let (Some(publisher), Some(key), Some(catalog), Some(expires)) = (+ &preview.publisher_name,+ &preview.publisher_key_id,+ preview.catalog_version,+ preview.catalog_expires_unix,+ ) {+ writeln!(+ out,+ "Publisher signature: verified {} with key {} (catalog {}, expires {})",+ publisher, key, catalog, expires+ )?;+ }+ writeln!(out, "Signing key status: {}", preview.signing_key_status)?;+ if let Some(publisher_id) = &preview.publisher_id {+ writeln!(out, "Publisher ID: {publisher_id}")?;+ }+ if let Some(algorithm) = &preview.signing_key_algorithm {+ writeln!(out, "Signing key algorithm: {algorithm}")?;+ }+ writeln!(out, "Artifact source: {}", preview.artifact_source)?;+ writeln!(out, "Destination: {}", preview.destination)?;+ writeln!(out, "Download size: {} bytes", preview.download_size)?;+ writeln!(out, "Installed size: {} bytes", preview.installed_size)?;+ writeln!(out, "License: {}", preview.license)?;+ writeln!(out, "Source: {}", preview.source)?;+ writeln!(+ out,+ "Corresponding source: {} @ {}",+ preview.corresponding_source_uri, preview.corresponding_source_revision+ )?;+ if let Some(file) = &preview.corresponding_source.file {+ writeln!(+ out,+ "Corresponding source file: {} | SHA-256 {}",+ file.path, file.sha256+ )?;+ }+ writeln!(out, "Provenance: {}", preview.provenance)?;+ for component in &preview.components {+ writeln!(+ out,+ "Component: {} {} | {} | {} @ {} | notice: {}",+ component.name,+ component.version,+ component.license,+ component.source_uri,+ component.source_revision,+ component.notice+ )?;+ if let Some(file) = &component.notice_file {+ writeln!(+ out,+ "Component notice file: {} | SHA-256 {}",file.path, file.sha256- );- }- println!("Provenance: {}", preview.provenance);- for component in &preview.components {- println!(- "Component: {} {} | {} | {} @ {} | notice: {}",- component.name,- component.version,- component.license,- component.source_uri,- component.source_revision,- component.notice- );- if let Some(file) = &component.notice_file {- println!(- "Component notice file: {} | SHA-256 {}",- file.path, file.sha256- );- }+ )?;}- for model in &preview.models {- println!(- "Model: {} @ {} | original {} | conversion {}",- model.path, model.revision, model.original_sha256, model.conversion_sha256- );- if let Some(file) = &model.license_file {- println!(- "Model license file: {} | SHA-256 {}",- file.path, file.sha256- );- }+ }+ for model in &preview.models {+ writeln!(+ out,+ "Model: {} @ {} | original {} | conversion {}",+ model.path, model.revision, model.original_sha256, model.conversion_sha256+ )?;+ if let Some(file) = &model.license_file {+ writeln!(+ out,+ "Model license file: {} | SHA-256 {}",+ file.path, file.sha256+ )?;}- println!("Target: {}", preview.target);- println!("Archive SHA-256: {}", preview.archive_sha256);- println!("Manifest SHA-256: {}", preview.manifest_sha256);- println!(- "Authorization: request={}, confirmation_required={}, confirmation_received={}, mutation_authorized={}",- preview.authorization.request,- preview.authorization.confirmation_required,- preview.authorization.confirmation_received,- preview.authorization.mutation_authorized,- );- println!("Preview complete; no extension state was changed.");+ }+ writeln!(out, "Target: {}", preview.target)?;+ writeln!(out, "Archive SHA-256: {}", preview.archive_sha256)?;+ writeln!(out, "Manifest SHA-256: {}", preview.manifest_sha256)?;+ writeln!(+ out,+ "Authorization: request={}, confirmation_required={}, confirmation_received={}, mutation_authorized={}",+ preview.authorization.request,+ preview.authorization.confirmation_required,+ preview.authorization.confirmation_received,+ preview.authorization.mutation_authorized,+ )?;+ if !preview.authorization.mutation_authorized {+ writeln!(out, "Preview complete; no extension state was changed.")?;}Ok(())}@@ -4803,6 +4826,51 @@ mod tests {0x7f, 0x60,];+ #[test]+ fn preview_footer_is_reserved_for_non_mutating_inspection() {+ let temp = TempDir::new().unwrap();+ let store = ExtensionStore::new(temp.path().join("extensions"));+ let entry = registry_entry(PERCEPTION_ID).unwrap();+ let archive = fixture_archive(+ temp.path(),+ "1.0.0",+ ¤t_target().unwrap(),+ 1,+ b"worker",+ );+ let source = InstallSource {+ archive,+ trust: TrustClass::DeveloperUnsignedLocal,+ catalog: None,+ signed_catalog: None,+ trust_update: None,+ };+ let inspected = inspect_without_mutation(entry, &source).unwrap();+ let render = |request| {+ let mut text = Vec::new();+ write_preview_text(+ &mut text,+ &install_review(entry, &store, &inspected, &source, request),+ )+ .unwrap();+ String::from_utf8(text).unwrap()+ };+ const FOOTER: &str = "Preview complete; no extension state was changed.";++ let inspect = render(InstallReviewRequest::CliInspect);+ assert!(inspect.contains("mutation_authorized=false"));+ assert!(inspect.trim_end().ends_with(FOOTER));+ for request in [+ InstallReviewRequest::CliInstall,+ InstallReviewRequest::CliUpdate,+ ] {+ let review = render(request);+ assert!(review.contains("mutation_authorized=true"));+ assert!(!review.contains(FOOTER), "{review}");+ }+ assert!(!store.extension_dir(PERCEPTION_ID).exists());+ }+fn acl_drift_error() -> anyhow::Error {anyhow!(WindowsAclDrift).context("extension Windows ACL grants access to untrusted principal in test fixture")diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rsindex 2dca194133..858057022c 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs@@ -18,6 +18,7 @@//! platform tool registry.mod autostart;+mod broken_pipe;mod bundle;mod check_update_tool;mod cli;@@ -131,7 +132,7 @@ fn maybe_wrap_finite_command() {let Ok(status) = status else {return;};- let exit_code = status.code().unwrap_or(1);+ let exit_code = broken_pipe::shell_exit_code(status);telemetry::spawn_cli_completion_worker(command_name,tool_name.as_deref(),@@ -509,6 +510,7 @@ fn main() {if telemetry::run_update_event_worker_if_requested() {return;}+ broken_pipe::install_for_finite_command_from_argv();maybe_wrap_finite_command();// ── CLI subcommand dispatch ──────────────────────────────────────────────@@ -918,6 +920,7 @@ fn main() -> anyhow::Result<()> {if telemetry::run_update_event_worker_if_requested() {return Ok(());}+ broken_pipe::install_for_finite_command_from_argv();maybe_wrap_finite_command();// ── CLI subcommand dispatch ──────────────────────────────────────────────diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/broken_pipe_cli_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/broken_pipe_cli_test.rsnew file mode 100644index 0000000000..d4e56930a5--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/tests/broken_pipe_cli_test.rs@@ -0,0 +1,64 @@+//! A finite CLI command whose reader closes early (`cua-driver ... | head`)+//! must stop like a normal pipeline stage instead of panicking with+//! `failed printing to stdout: Broken pipe`.++use std::process::{Command, ExitStatus, Stdio};+use tempfile::TempDir;++/// Shell-visible status for a process terminated by SIGPIPE; Windows uses the+/// same exit code.+const BROKEN_PIPE_EXIT_CODE: i32 = 141;++fn run_with_closed_stdout(wrapped_child: bool) -> (ExitStatus, String) {+ let home = TempDir::new().unwrap();+ let mut command = Command::new(env!("CARGO_BIN_EXE_cua-driver"));+ // `dump-docs` is desktop-free and prints far more than a pipe buffer, so+ // the write fails even if the reader closes after the first chunk.+ command+ .args(["dump-docs", "--pretty"])+ .env("CUA_DRIVER_RS_HOME", home.path())+ .env("CUA_DRIVER_TELEMETRY_HOME", home.path())+ .env("CUA_DRIVER_RS_TELEMETRY_ENABLED", "0")+ .stdin(Stdio::null())+ .stdout(Stdio::piped())+ .stderr(Stdio::piped());+ if wrapped_child {+ command.env("CUA_DRIVER_CLI_TELEMETRY_CHILD", "1");+ } else {+ command.env_remove("CUA_DRIVER_CLI_TELEMETRY_CHILD");+ }+ let mut child = command.spawn().expect("spawn cua-driver");+ drop(child.stdout.take());+ let output = child.wait_with_output().expect("wait for cua-driver");+ (+ output.status,+ String::from_utf8_lossy(&output.stderr).into_owned(),+ )+}++fn assert_quiet(stderr: &str) {+ assert!(+ !stderr.contains("panicked") && !stderr.contains("failed printing"),+ "closed stdout must not panic:\n{stderr}"+ );+}++#[test]+fn finite_command_stops_cleanly_when_its_reader_closes() {+ let (status, stderr) = run_with_closed_stdout(true);+ assert_quiet(&stderr);+ #[cfg(unix)]+ {+ use std::os::unix::process::ExitStatusExt;+ assert_eq!(status.signal(), Some(libc::SIGPIPE), "{status:?}");+ }+ #[cfg(windows)]+ assert_eq!(status.code(), Some(BROKEN_PIPE_EXIT_CODE), "{status:?}");+}++#[test]+fn telemetry_wrapper_reports_the_broken_pipe_status_like_a_shell() {+ let (status, stderr) = run_with_closed_stdout(false);+ assert_quiet(&stderr);+ assert_eq!(status.code(), Some(BROKEN_PIPE_EXIT_CODE), "{status:?}");+}diff --git a/libs/cua-driver/rust/crates/cua-driver/tests/extension_manager_cli_test.rs b/libs/cua-driver/rust/crates/cua-driver/tests/extension_manager_cli_test.rsindex 96673db6cb..bc464ac78d 100644--- a/libs/cua-driver/rust/crates/cua-driver/tests/extension_manager_cli_test.rs+++ b/libs/cua-driver/rust/crates/cua-driver/tests/extension_manager_cli_test.rs@@ -307,6 +307,23 @@ fn developer_lifecycle_is_explicit_previewed_and_removable() {assert_eq!(preview["mutation_performed"], false);assert!(!home.join("extensions/cua-perception").exists());+ let inspect_text = run(+ &home,+ &[+ "extension",+ "inspect",+ "cua-perception",+ "--archive",+ archive.to_str().unwrap(),+ "--allow-unsigned-local",+ ],+ );+ assert!(inspect_text.status.success());+ assert!(String::from_utf8_lossy(&inspect_text.stdout)+ .trim_end()+ .ends_with("Preview complete; no extension state was changed."));+ assert!(!home.join("extensions/cua-perception").exists());+let install = run(&home,&[@@ -331,6 +348,11 @@ fn developer_lifecycle_is_explicit_previewed_and_removable() {assert!(install_stdout.contains("Model: models/parser.bin @ model-v1"));assert!(install_stdout.contains("Model license file: LICENSES/model.txt"));assert!(install_stdout.contains("mutation_authorized=true"));+ assert!(install_stdout.contains("Installed cua-perception 1.2.3 at "));+ assert!(+ !install_stdout.contains("no extension state was changed"),+ "install must not claim that nothing changed:\n{install_stdout}"+ );let status = run(&home,diff --git a/libs/cua-driver/typescript/src/native/cua_driver_contract.ts b/libs/cua-driver/typescript/src/native/cua_driver_contract.tsindex 604c832d08..4e34538e27 100644--- a/libs/cua-driver/typescript/src/native/cua_driver_contract.ts+++ b/libs/cua-driver/typescript/src/native/cua_driver_contract.ts@@ -3378,7 +3378,9 @@ const FfiConverterTypeParseVisualRegionsOptions = (() => {})();/**- * Transport-free request. Runtime use requires the future capture registry.+ * Parse one immutable screenshot capture. Pass the `capture_id` returned by+ * `get_window_state` or `get_desktop_state`; the Driver capture registry+ * resolves it to the exact pixels and action-coordinate transform.*/export type ParseVisualRegionsInput = {captureId: string,@@ -3569,7 +3571,7 @@ const FfiConverterTypeVisualCaptureSource = (() => {})();/**- * Screenshot identity and geometry retained by the future capture registry.+ * Screenshot identity and geometry retained by the Driver capture registry.*/export type VisualScreenshotReference = {/**