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): 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.mdx
index 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 &lt;output_dir&gt;/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 &lt;output_dir&gt;/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.mdx
index 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 &lt;output_dir&gt;/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 &lt;output_dir&gt;/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.mdx
index 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 &lt;output_dir&gt;/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 &lt;output_dir&gt;/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.json
index 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.py
index 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
@dataclass
class 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):
@dataclass
class 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 = reference
diff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/visual.rs
index 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.rs
index 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": false
diff --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.rs
index 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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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",
+ &current_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.rs
index 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.rs
new file mode 100644
index 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.rs
index 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.ts
index 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 = {
/**