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
feat(cua-driver-rs): check-update CLI verb + check_for_update MCP tool (#1734)
Francesco Bonacci7d893ce827fe
diff --git a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx b/docs/content/docs/cua-driver/guide/getting-started/installation.mdxindex a27f86b294..6a1ae74fc9 100644--- a/docs/content/docs/cua-driver/guide/getting-started/installation.mdx+++ b/docs/content/docs/cua-driver/guide/getting-started/installation.mdx@@ -659,3 +659,5 @@ It also doesn't auto-edit `%USERPROFILE%\.claude.json` — the closing message p**Daemon won't start** — another daemon may already be bound to the socket. Check with `cua-driver status` and stop it with `cua-driver stop`. For stale lock files after a crash, the daemon's own probe detects those and proceeds.Ready to drive an app? Head to the [Quickstart](/cua-driver/guide/getting-started/quickstart).++After install, see [Updating](/cua-driver/guide/getting-started/updating) for how to check for and apply new releases.diff --git a/docs/content/docs/cua-driver/guide/getting-started/meta.json b/docs/content/docs/cua-driver/guide/getting-started/meta.jsonindex 2865dc2fed..5ee98b9fea 100644--- a/docs/content/docs/cua-driver/guide/getting-started/meta.json+++ b/docs/content/docs/cua-driver/guide/getting-started/meta.json@@ -3,5 +3,5 @@"description": "Get up and running with Cua Driver","icon": "Rocket","defaultOpen": true,- "pages": ["introduction", "installation", "quickstart", "windows-ssh", "linux", "autostart", "pip-preview", "integrations", "swift-integration", "process-model", "comparison", "faq"]+ "pages": ["introduction", "installation", "updating", "quickstart", "windows-ssh", "linux", "autostart", "pip-preview", "integrations", "swift-integration", "process-model", "comparison", "faq"]}diff --git a/docs/content/docs/cua-driver/guide/getting-started/updating.mdx b/docs/content/docs/cua-driver/guide/getting-started/updating.mdxnew file mode 100644index 0000000000..043c3c0cad--- /dev/null+++ b/docs/content/docs/cua-driver/guide/getting-started/updating.mdx@@ -0,0 +1,179 @@+---+title: Updating+description: Check whether a newer cua-driver release is available, then apply it on your terms — from the CLI, an MCP client, or a script.+---++import { Callout } from 'fumadocs-ui/components/callout';++cua-driver ships three update surfaces, all reading from the same GitHub releases endpoint and 20-hour on-disk cache:++| Surface | Verb | Use case |+| --- | --- | --- |+| Passive banner | (automatic) | Friendly nudge on every `mcp` / `serve` / `doctor` start. |+| CLI check | `cua-driver check-update` | Human-readable "am I outdated?" probe. |+| Scripted check | `cua-driver check-update --json` | Hermes / CI / wrapper scripts. Same payload as the `check_for_update` MCP tool. |+| MCP tool | `check_for_update` | Agents that want to ask programmatically, without spawning a subprocess. |+| Apply | `cua-driver update --apply` | Download and install the latest release. |++`check-update` and `check_for_update` are **read-only** — they never modify your install. Apply is a separate step on purpose.++## The launch-time banner++Every `cua-driver mcp` / `cua-driver serve` / `cua-driver doctor` invocation kicks off a non-blocking GitHub poll. If a strictly-newer release is found and you haven't dismissed it, a two-line banner lands on stderr (gh-CLI style):++```+✨ cua-driver v0.3.2 is available (you have v0.3.1).+ Update with: cua-driver update+ Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2+```++The check is cached for 20 hours, runs on a background task, and never blocks startup. To disable it set `CUA_DRIVER_RS_UPDATE_CHECK=false` in the environment, or persist the choice with:++```bash+cua-driver config set update_check_enabled false+```++## `cua-driver check-update` — human path++A pure check, never installs. Prints a short summary and exits.++```bash+$ cua-driver check-update+Current: 0.3.1+Latest: 0.3.2++Update available. Run `cua-driver update --apply` to install.+Release notes: https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2+```++When you're on the latest release:++```bash+$ cua-driver check-update+Current: 0.3.1+Latest: 0.3.1++You're on the latest release.+```++### Flags++- `--json` — emit a machine-readable JSON payload (see below).+- `--no-cache` — skip the 20h on-disk cache and force a fresh GitHub round-trip. Useful when iterating right after a release.++### Exit codes++- `0` — the check itself succeeded. The `update_available` field in the JSON payload carries the "is it outdated?" signal.+- `1` — the check failed (network down, GitHub 5xx, parse error). The text path prints a one-line reason; the JSON path puts it in the `error` field.++The non-zero-on-outdated convention (à la `brew outdated`) is intentionally not used — it conflicts with every shell script's "non-zero means error" assumption. Hermes parses JSON; humans read text; the signal lives in the payload.++## `cua-driver check-update --json` — scripted path++Same check, JSON output. Use this when wiring cua-driver updates into Hermes, CI, or any wrapper script.++```bash+$ cua-driver check-update --json+{+ "current_version": "0.3.1",+ "latest_version": "0.3.2",+ "update_available": true,+ "source": "github_releases",+ "checked_at": "2026-05-27T14:30:00Z",+ "cache_hit": false,+ "install_command": "curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash -s -- install --backend=rust",+ "release_notes_url": "https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2",+ "error": null+}+```++When you're up to date, `install_command` and `release_notes_url` are `null`:++```bash+$ cua-driver check-update --json+{+ "current_version": "0.3.1",+ "latest_version": "0.3.1",+ "update_available": false,+ "source": "github_releases",+ "checked_at": "2026-05-27T14:30:00Z",+ "cache_hit": true,+ "install_command": null,+ "release_notes_url": null,+ "error": null+}+```++### JSON schema++| Field | Type | Notes |+| --- | --- | --- |+| `current_version` | string | The running binary's `CARGO_PKG_VERSION`. |+| `latest_version` | string \| null | Highest non-draft non-prerelease `cua-driver-rs-v*` tag on GitHub. `null` if the fetch failed and no cache exists. |+| `update_available` | bool | `latest > current` under strict semver. `false` when `latest_version` is `null`. |+| `source` | string | Always `"github_releases"` today. Pinned so future alternate sources can be slotted in without breaking consumers. |+| `checked_at` | string | ISO-8601 UTC timestamp of this check (not the cached fetch). |+| `cache_hit` | bool | `true` when we short-circuited via the cache, `false` when we hit GitHub. |+| `install_command` | string \| null | Shell one-liner to apply the update. `null` when up-to-date or the check failed. |+| `release_notes_url` | string \| null | Release notes page on GitHub. `null` when up-to-date or the check failed. |+| `error` | string \| null | Human-readable reason when the fetch failed and no cache was available. |++### Example consumer snippet (bash)++```bash+if cua-driver check-update --json | jq -e '.update_available' > /dev/null; then+ echo "cua-driver is outdated — applying update"+ cua-driver update --apply+fi+```++## `check_for_update` — MCP tool++Same payload, surfaced over MCP so agents can probe without spawning a subprocess. Input schema is empty.++```bash+$ cua-driver call check_for_update '{}'+{+ "current_version": "0.3.1",+ "latest_version": "0.3.2",+ "update_available": true,+ "source": "github_releases",+ "checked_at": "2026-05-27T14:30:00Z",+ "cache_hit": false,+ "install_command": "curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash -s -- install --backend=rust",+ "release_notes_url": "https://github.com/trycua/cua/releases/tag/cua-driver-rs-v0.3.2",+ "error": null+}+```++The tool is registered as `read_only`, `idempotent`, and `open_world` (the network can change the answer between calls). MCP clients see both a human summary in `content[0].text` and the JSON above in `structuredContent`.++<Callout>+The MCP tool intentionally has no `apply` variant. Installing over MCP would force a self-replacement of the running MCP server — a UX boundary we want explicit. If your agent needs to apply, shell out to `cua-driver update --apply` or run the `install_command` from the payload.+</Callout>++## `cua-driver update --apply` — installing++When you're ready to install, `update --apply` delegates to the canonical installer script (the same one the docs print as the one-liner):++```bash+$ cua-driver update --apply+Current version: 0.3.1+Checking for updates…+New version available: 0.3.2+Downloading and installing cua-driver 0.3.2…+Installed cua-driver 0.3.2.+```++If a daemon was already running, restart it to pick up the new binary:++```bash+cua-driver stop && cua-driver serve+```++`update` (without `--apply`) keeps the existing "check + suggest" text behaviour intact for backward compat. Add `--json` to either form for a structured payload — handy when the calling script wants to log the version it just installed.++```bash+$ cua-driver update --json | jq '.update_available'+true+```diff --git a/libs/cua-driver/rust/Cargo.lock b/libs/cua-driver/rust/Cargo.lockindex b2069f67ca..a3bc25f107 100644--- a/libs/cua-driver/rust/Cargo.lock+++ b/libs/cua-driver/rust/Cargo.lock@@ -276,7 +276,7 @@ dependencies = [[[package]]name = "cua-driver"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","async-trait",@@ -306,7 +306,7 @@ dependencies = [[[package]]name = "cua-driver-core"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","async-trait",@@ -321,7 +321,7 @@ dependencies = [[[package]]name = "cua-driver-uia"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","cua-driver-core",@@ -336,7 +336,7 @@ dependencies = [[[package]]name = "cursor-overlay"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","image",@@ -489,7 +489,7 @@ checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"[[package]]name = "focus-monitor-win"-version = "0.2.18"+version = "0.3.1"dependencies = ["windows 0.58.0",]@@ -1193,7 +1193,7 @@ checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"[[package]]name = "pip-preview"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","serde_json",@@ -1208,7 +1208,7 @@ checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"[[package]]name = "platform-linux"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","async-trait",@@ -1229,7 +1229,7 @@ dependencies = [[[package]]name = "platform-macos"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","async-trait",@@ -1261,7 +1261,7 @@ dependencies = [[[package]]name = "platform-windows"-version = "0.2.18"+version = "0.3.1"dependencies = ["anyhow","async-trait",diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.mdindex 215352f200..13d4f2b906 100644--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md@@ -107,6 +107,7 @@ Tool names are `snake_case`, management subcommands are- `cua-driver stop` / `status`- `cua-driver list-tools`, `describe <tool>`- `cua-driver recording start|stop|status` — see `RECORDING.md`+- `cua-driver check-update [--json] [--no-cache]` — read-only "is a newer release available?" probe. Same payload as the `check_for_update` MCP tool; pair with `cua-driver update --apply` to install.Canonical multi-step workflow (example shape — platform-specificlaunch idioms in the per-OS companion file):diff --git a/libs/cua-driver/rust/crates/cua-driver/src/check_update_tool.rs b/libs/cua-driver/rust/crates/cua-driver/src/check_update_tool.rsnew file mode 100644index 0000000000..3cd682b05a--- /dev/null+++ b/libs/cua-driver/rust/crates/cua-driver/src/check_update_tool.rs@@ -0,0 +1,94 @@+//! `check_for_update` MCP tool — programmatic mirror of+//! `cua-driver check-update`.+//!+//! Lives in the `cua-driver` binary crate (not in `cua-driver-core` or the+//! per-platform `tools/` modules) for one reason: the implementation calls+//! into `version_check`, which pulls `ureq` + rustls. Putting that crypto+//! stack into `cua-driver-core` would propagate it into every platform+//! crate's dep graph and break cross-target builds from macOS host (ring's+//! C bits can't find MSVC headers without an MSVC toolchain installed).+//! Keeping it here, behind a thin registry-injection seam, means+//! `cua-driver` keeps its existing dep footprint while every platform's+//! tool table still exposes the new MCP tool.+//!+//! Registered by [`register_into`] from `main.rs` immediately after the+//! per-platform `register_tools()` call, so the result is identical to+//! the per-platform tools registering it themselves.++use async_trait::async_trait;+use serde_json::Value;++use cua_driver_core::{+ protocol::ToolResult,+ tool::{Tool, ToolDef, ToolRegistry},+};++pub struct CheckForUpdateTool;++static DEF: std::sync::OnceLock<ToolDef> = std::sync::OnceLock::new();++fn def() -> &'static ToolDef {+ DEF.get_or_init(|| ToolDef {+ name: "check_for_update".into(),+ description:+ "Check whether a newer cua-driver-rs release is available on GitHub. \+ Returns the current and latest versions, an `update_available` boolean, \+ the install one-liner, and the release notes URL. Read-only — never \+ installs. Mirror of `cua-driver check-update --json`."+ .into(),+ input_schema: serde_json::json!({+ "type": "object",+ "properties": {},+ "additionalProperties": false+ }),+ read_only: true,+ destructive: false,+ idempotent: true,+ // The check hits GitHub over the network, so the response can+ // change between invocations even though the tool is read-only+ // from the caller's perspective.+ open_world: true,+ })+}++#[async_trait]+impl Tool for CheckForUpdateTool {+ fn def(&self) -> &ToolDef {+ def()+ }++ async fn invoke(&self, _args: Value) -> ToolResult {+ // The fetch hits the network with a 4s timeout — run on a+ // blocking pool so the MCP server's tokio runtime keeps+ // multiplexing other tool calls during the round-trip.+ let state = tokio::task::spawn_blocking(|| {+ crate::version_check::check_update_state(false)+ })+ .await+ .expect("version_check::check_update_state never panics");++ let summary = if let Some(err) = &state.error {+ format!("Update check failed: {err}")+ } else if state.update_available {+ let latest = state.latest_version.as_deref().unwrap_or("?");+ format!(+ "Update available: cua-driver {latest} (you have {}).",+ state.current_version+ )+ } else {+ format!("Up to date (cua-driver {}).", state.current_version)+ };++ let structured = serde_json::to_value(&state)+ .unwrap_or_else(|_| serde_json::json!({}));++ ToolResult::text(summary).with_structured(structured)+ }+}++/// Register the `check_for_update` tool into a freshly-built platform+/// registry. Call site lives in `main.rs`; this keeps the per-platform+/// `register_tools()` signature untouched.+pub fn register_into(registry: &mut ToolRegistry) {+ registry.register(Box::new(CheckForUpdateTool));+}diff --git a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs b/libs/cua-driver/rust/crates/cua-driver/src/cli.rsindex 88c3f338c2..32d4844b38 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/cli.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/cli.rs@@ -64,7 +64,13 @@ pub enum Command {Status { socket: Option<String> },Recording { subcommand: String, args: Vec<String>, socket: Option<String> },DumpDocs { pretty: bool, doc_type: String },- Update { apply: bool },+ Update { apply: bool, json: bool },+ /// `cua-driver check-update [--json] [--no-cache]` — pure check verb.+ /// Never installs; the apply path stays on `update --apply` so the+ /// "did anything change on disk?" question is unambiguous from argv.+ /// Mirror of the `check_for_update` MCP tool — both routes share+ /// `crate::version_check::check_update_state`.+ CheckUpdate { json: bool, no_cache: bool },Doctor { json: bool },Diagnose,Config {@@ -131,7 +137,17 @@ pub fn parse_command() -> Command {if args.iter().any(|a| a == "--help" || a == "-h") {println!("cua-driver {} — cross-platform computer-use automation driver", env!("CARGO_PKG_VERSION"));println!("Usage: cua-driver [SUBCOMMAND] [OPTIONS]");- println!("Subcommands: mcp, list-tools, describe, call, serve, stop, status, config, recording, update, doctor, diagnose, autostart, skills");+ println!("Subcommands: mcp, list-tools, describe, call, serve, stop, status, config, recording, update, check-update, doctor, diagnose, autostart, skills");+ println!();+ println!("Updating cua-driver:");+ println!(" cua-driver check-update Ask GitHub whether a newer release is available. Read-only.");+ println!(" Default output is human-friendly text.");+ println!(" --json Emit a machine-readable JSON payload (same shape as the");+ println!(" check_for_update MCP tool). Hermes branches on update_available.");+ println!(" --no-cache Skip the 20h on-disk cache and force a fresh GitHub round-trip.");+ println!(" cua-driver update Same check as above, then suggest --apply if outdated.");+ println!(" --apply Download + install the latest release via the canonical installer.");+ println!(" --json Emit the structured check payload (does not change --apply behaviour).");println!();println!("autostart options (Windows-only today):");println!(" cua-driver autostart enable Register a logon Scheduled Task so serve starts at every interactive logon.");@@ -246,7 +262,13 @@ pub fn parse_command() -> Command {}Some("update") => {let apply = args.iter().any(|a| a == "--apply");- Command::Update { apply }+ let json = args.iter().any(|a| a == "--json");+ Command::Update { apply, json }+ }+ Some("check-update") => {+ let json = args.iter().any(|a| a == "--json");+ let no_cache = args.iter().any(|a| a == "--no-cache");+ Command::CheckUpdate { json, no_cache }}Some("doctor") => {// `--json` switches to machine-readable output for scripting.@@ -1279,10 +1301,30 @@ fn run_recording_render(args: &[String]) {/// tag filtering and HTTP semantics. `--apply` delegates to the canonical/// installer script — see [`crate::updater`] for why we go through the script/// instead of re-implementing the asset resolution + atomic swap + GC in Rust.-pub fn run_update_cmd(apply: bool) {+pub fn run_update_cmd(apply: bool, json: bool) {+ // `--json` short-circuits the text path entirely so scripted callers+ // get a parseable payload regardless of `--apply`. The check itself+ // routes through the same `check_update_state` the `check-update`+ // verb and the MCP tool use, so all three surfaces agree.+ if json {+ let state = crate::version_check::check_update_state(false);+ let val = serde_json::to_value(&state)+ .unwrap_or_else(|_| serde_json::json!({}));+ let pretty = serde_json::to_string_pretty(&val).unwrap_or_else(|_| val.to_string());+ println!("{pretty}");+ // `--apply` still installs when JSON is on — the JSON is just the+ // pre-install snapshot. Returning here when apply is false keeps+ // the existing "check + suggest" behaviour off the JSON path.+ if !apply {+ return;+ }+ }+let current = env!("CARGO_PKG_VERSION");- println!("Current version: {current}");- println!("Checking for updates…");+ if !json {+ println!("Current version: {current}");+ println!("Checking for updates…");+ }let latest = crate::version_check::fetch_latest_version();match latest {@@ -1291,30 +1333,42 @@ pub fn run_update_cmd(apply: bool) {// the CLI surface — pass it through so the user can see why// (timeout, parse error, etc.) instead of just "unreachable".tracing::debug!(target: "cua_driver::update", "fetch failed: {e}");- println!("Could not reach GitHub — check your connection and try again.");+ if !json {+ println!("Could not reach GitHub — check your connection and try again.");+ }process::exit(1);}Ok(v) if !crate::version_check::is_newer(&v, current) => {- println!("Already up to date.");+ if !json {+ println!("Already up to date.");+ }}Ok(v) => {- println!("New version available: {v}");+ if !json {+ println!("New version available: {v}");+ }if !apply {- println!();- println!("Run with --apply to download and install it:");- println!(" cua-driver update --apply");- println!();- println!("Or reinstall directly:");- println!(" {}", crate::updater::manual_install_one_liner());+ if !json {+ println!();+ println!("Run with --apply to download and install it:");+ println!(" cua-driver update --apply");+ println!();+ println!("Or reinstall directly:");+ println!(" {}", crate::updater::manual_install_one_liner());+ }return;}- println!("Downloading and installing cua-driver {v}…");+ if !json {+ println!("Downloading and installing cua-driver {v}…");+ }let daemon_was_running = crate::updater::daemon_is_running();match crate::updater::run_install_script(&v) {Ok(s) if s.success() => {- println!("Installed cua-driver {v}.");+ if !json {+ println!("Installed cua-driver {v}.");+ }if daemon_was_running {// The atomic swap (symlink retarget / junction flip)// means the running daemon kept executing the old@@ -1345,6 +1399,61 @@ pub fn run_update_cmd(apply: bool) {}}+/// `cua-driver check-update [--json] [--no-cache]` — pure check, never installs.+///+/// Mirror of the `check_for_update` MCP tool. Both routes call into+/// [`crate::version_check::check_update_state`] so the CLI and MCP+/// surfaces never disagree on which release is "latest".+///+/// Exit codes (mirror `brew outdated` / `npm outdated`):+/// * `0` — the check itself succeeded (regardless of `update_available`)+/// * `1` — the check failed (network down, parse error, GitHub 5xx)+///+/// We deliberately do NOT use a non-zero exit to mean "outdated" — that+/// would conflict with every shell script's "non-zero means error"+/// assumption. Hermes parses JSON; humans read text; the signal lives in+/// the payload.+pub fn run_check_update_cmd(json: bool, no_cache: bool) {+ let state = crate::version_check::check_update_state(no_cache);++ if json {+ let val = serde_json::to_value(&state).unwrap_or_else(|_| serde_json::json!({}));+ let pretty = serde_json::to_string_pretty(&val).unwrap_or_else(|_| val.to_string());+ println!("{pretty}");+ } else {+ println!("Current: {}", state.current_version);+ match (&state.latest_version, &state.error) {+ (Some(latest), _) => {+ println!("Latest: {latest}");+ if state.update_available {+ println!();+ println!("Update available. Run `cua-driver update --apply` to install.");+ if let Some(url) = &state.release_notes_url {+ println!("Release notes: {url}");+ }+ } else {+ println!();+ println!("You're on the latest release.");+ }+ }+ (None, Some(err)) => {+ println!("Latest: <unavailable>");+ println!();+ println!("Could not reach GitHub: {err}");+ }+ (None, None) => {+ // Network failed AND no cache existed — `error` should be set;+ // fall through with a generic message in case it isn't.+ println!("Latest: <unavailable>");+ }+ }+ }++ if state.error.is_some() && state.latest_version.is_none() {+ process::exit(1);+ }+}+/// Output documentation as JSON. `doc_type` is one of:/// - `"mcp"` — only MCP tool docs (`{version, tools: [...]}`)/// - `"cli"` — CLI docs (stub on Rust — Swift extracts via swift-argument-parser@@ -1959,6 +2068,7 @@ pub fn telemetry_entry_event(cmd: &Command) -> Option<String> {Command::Config { .. } => event::CONFIG.to_owned(),Command::DumpDocs { .. } => "cua_driver_dump_docs".to_owned(),Command::Update { .. } => "cua_driver_update".to_owned(),+ Command::CheckUpdate { .. } => "cua_driver_check_update".to_owned(),Command::Doctor { .. } => "cua_driver_doctor".to_owned(),Command::Diagnose => "cua_driver_diagnose".to_owned(),// Per-subcommand event so dashboards can split enable / disable /diff --git a/libs/cua-driver/rust/crates/cua-driver/src/main.rs b/libs/cua-driver/rust/crates/cua-driver/src/main.rsindex 28a177f002..02bd81d4f6 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/main.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/main.rs@@ -32,6 +32,7 @@ mod proxy;mod serve;mod skills;mod telemetry;+mod check_update_tool;mod updater;mod version_check;@@ -139,6 +140,26 @@ fn maybe_init_pip() {}}+// ── Registry helpers (macOS) ─────────────────────────────────────────────++/// Build the macOS tool registry and inject the platform-agnostic+/// `check_for_update` tool. Wrapper lives in the binary crate so the+/// `cua-driver-core` graph (shared with every `platform-*` crate) stays+/// free of the `ureq` + rustls + ring deps that the check tool needs.+#[cfg(target_os = "macos")]+fn build_macos_registry() -> cua_driver_core::tool::ToolRegistry {+ let mut r = platform_macos::register_tools();+ check_update_tool::register_into(&mut r);+ r+}++#[cfg(target_os = "macos")]+fn build_macos_registry_with_compat(compat: bool) -> cua_driver_core::tool::ToolRegistry {+ let mut r = platform_macos::register_tools_with_compat(compat);+ check_update_tool::register_into(&mut r);+ r+}+// ── macOS entry-point ─────────────────────────────────────────────────────#[cfg(target_os = "macos")]@@ -161,12 +182,12 @@ fn main() {return;}cli::Command::ListTools => {- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());cli::run_list_tools(®);return;}cli::Command::Describe(name) => {- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());cli::run_describe(®, &name);return;}@@ -198,7 +219,7 @@ fn main() {cua_driver_core::video::set_video_backend_factory(Box::new(platform_macos::video_sckit::SckitVideoBackendFactory),);- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());reg.init_self_weak();cli::run_call(reg, &tool, json_args, screenshot_out_file, socket);return;@@ -253,7 +274,7 @@ fn main() {None => pip_preview::PipConfig::from_args(),};maybe_init_pip();- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());reg.init_self_weak();let sp = socket.unwrap_or_else(serve::default_socket_path);let pid_path = serve::default_pid_file_path();@@ -296,12 +317,16 @@ fn main() {return;}cli::Command::DumpDocs { pretty, doc_type } => {- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());cli::run_dump_docs_with_type(®, pretty, &doc_type);return;}- cli::Command::Update { apply } => {- cli::run_update_cmd(apply);+ cli::Command::Update { apply, json } => {+ cli::run_update_cmd(apply, json);+ return;+ }+ cli::Command::CheckUpdate { json, no_cache } => {+ cli::run_check_update_cmd(json, no_cache);return;}cli::Command::Doctor { json } => {@@ -316,7 +341,7 @@ fn main() {return;}cli::Command::Diagnose => {- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());cli::run_diagnose_cmd(reg);return;}@@ -329,7 +354,7 @@ fn main() {return;}cli::Command::Config { subcommand, key, value, socket } => {- let reg = Arc::new(platform_macos::register_tools());+ let reg = Arc::new(build_macos_registry());reg.init_self_weak();cli::run_config_cmd(reg, subcommand.as_deref(), key.as_deref(), value.as_deref(), socket.as_deref());return;@@ -418,7 +443,7 @@ fn main() {let compat = CLAUDE_CODE_COMPAT.load(Ordering::SeqCst);rt.block_on(async move {// Register tools; overlay init has already happened above.- let registry = Arc::new(platform_macos::register_tools_with_compat(compat));+ let registry = Arc::new(build_macos_registry_with_compat(compat));// Wire up replay tool's back-reference to the registry.registry.init_self_weak();if let Err(e) = cua_driver_core::server::run(registry).await {@@ -527,8 +552,12 @@ fn main() -> anyhow::Result<()> {cli::run_dump_docs_with_type(®, pretty, &doc_type);return Ok(());}- cli::Command::Update { apply } => {- cli::run_update_cmd(apply);+ cli::Command::Update { apply, json } => {+ cli::run_update_cmd(apply, json);+ return Ok(());+ }+ cli::Command::CheckUpdate { json, no_cache } => {+ cli::run_check_update_cmd(json, no_cache);return Ok(());}cli::Command::Doctor { json } => {@@ -653,7 +682,7 @@ fn build_registry(cursor_cfg: cursor_overlay::CursorConfig) -> cua_driver_core::cua_driver_core::video::set_video_backend_factory(Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),);- platform_windows::register_tools_with_cursor(cursor_cfg, compat)+ { let mut r = platform_windows::register_tools_with_cursor(cursor_cfg, compat); check_update_tool::register_into(&mut r); r }}#[cfg(target_os = "linux")]{@@ -675,7 +704,7 @@ fn build_registry(cursor_cfg: cursor_overlay::CursorConfig) -> cua_driver_core::cua_driver_core::video::set_video_backend_factory(Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),);- platform_linux::register_tools_with_cursor(cursor_cfg, compat)+ { let mut r = platform_linux::register_tools_with_cursor(cursor_cfg, compat); check_update_tool::register_into(&mut r); r }}#[cfg(not(any(target_os = "windows", target_os = "linux")))]{@@ -718,7 +747,14 @@ fn build_registry_no_cursor() -> cua_driver_core::tool::ToolRegistry {cua_driver_core::video::set_video_backend_factory(Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),);- platform_windows::register_tools_with_cursor(cursor_overlay::CursorConfig { enabled: false, ..Default::default() }, compat)+ {+ let mut r = platform_windows::register_tools_with_cursor(+ cursor_overlay::CursorConfig { enabled: false, ..Default::default() },+ compat,+ );+ check_update_tool::register_into(&mut r);+ r+ }}#[cfg(target_os = "linux")]{@@ -740,7 +776,14 @@ fn build_registry_no_cursor() -> cua_driver_core::tool::ToolRegistry {cua_driver_core::video::set_video_backend_factory(Box::new(cua_driver_core::video_ffmpeg::FfmpegVideoBackendFactory),);- platform_linux::register_tools_with_cursor(cursor_overlay::CursorConfig { enabled: false, ..Default::default() }, compat)+ {+ let mut r = platform_linux::register_tools_with_cursor(+ cursor_overlay::CursorConfig { enabled: false, ..Default::default() },+ compat,+ );+ check_update_tool::register_into(&mut r);+ r+ }}#[cfg(not(any(target_os = "windows", target_os = "linux")))]{diff --git a/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs b/libs/cua-driver/rust/crates/cua-driver/src/version_check.rsindex 73db9e7280..6f266a85f0 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/version_check.rs@@ -60,7 +60,7 @@ const HTTP_TIMEOUT_SECONDS: u64 = 4;/// Tag-name prefix used by the Rust-port releases on the trycua/cua repo./// Releases tagged with anything else (e.g. the Swift port's/// `cua-driver-v*`) are filtered out so we never recommend the wrong binary.-pub(crate) const RELEASE_TAG_PREFIX: &str = "cua-driver-rs-v";+pub const RELEASE_TAG_PREFIX: &str = "cua-driver-rs-v";/// GitHub releases API endpoint. Paginates newest-first; 40 entries is/// plenty of headroom past the most recent stable release even when@@ -106,6 +106,146 @@ pub fn maybe_announce_update() {}}+/// Structured snapshot returned by [`check_update_state`] — the canonical+/// payload behind both `cua-driver check-update --json` and the+/// `check_for_update` MCP tool. Hermes branches on `update_available`.+///+/// Fields mirror the JSON schema documented in the user-facing+/// `getting-started/updating` page; field names use snake_case so a+/// serde-default JSON serialise round-trips cleanly into typed consumers+/// without a Deserialize impl on their side.+#[derive(serde::Serialize, Debug, Clone)]+pub struct UpdateState {+ pub current_version: String,+ /// `None` when the network fetch failed and no usable cache existed —+ /// the `error` field carries the human-readable reason.+ pub latest_version: Option<String>,+ pub update_available: bool,+ /// Always `"github_releases"` today. A constant on the wire so future+ /// alternate sources (private registries, mirrors) can be slotted in+ /// without breaking existing consumers that key off this string.+ pub source: &'static str,+ /// ISO-8601 UTC timestamp of when this check ran (NOT when the cached+ /// result was originally fetched — see `cache_hit`).+ pub checked_at: String,+ /// `true` when we short-circuited via the on-disk cache (no network+ /// round-trip this invocation). `false` when we actually hit GitHub.+ pub cache_hit: bool,+ /// Shell one-liner to apply the update. `None` when already up-to-date+ /// or the check failed.+ pub install_command: Option<String>,+ /// URL of the release notes page on GitHub. `None` when already+ /// up-to-date or the check failed.+ pub release_notes_url: Option<String>,+ /// Human-readable error string when the network fetch failed AND no+ /// cache was available. `None` on success / cache fallback.+ pub error: Option<String>,+}++/// Build the canonical install one-liner for the current target.+///+/// Lives here (rather than in the `cua-driver` crate's `updater.rs`) so the+/// MCP tool in this crate doesn't pull a circular dep. Both call sites+/// emit the same string — the canonical install URL and the same+/// `--backend=rust` flag the docs print.+fn install_one_liner() -> String {+ #[cfg(windows)]+ {+ "irm https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.ps1 | iex".to_owned()+ }+ #[cfg(not(windows))]+ {+ "curl -fsSL https://raw.githubusercontent.com/trycua/cua/main/libs/cua-driver/scripts/install.sh | bash -s -- install --backend=rust".to_owned()+ }+}++/// Run a check and return a structured result.+///+/// Drives the same fetch + cache primitives the launch-time banner uses,+/// so the two paths never disagree on which tag is "latest". Respects the+/// 20-hour `CACHE_REFRESH_SECONDS` unless `no_cache=true`, which forces a+/// fresh GitHub round-trip (and rewrites the cache on success).+///+/// Never panics, never returns an error type — fetch failures land in+/// `UpdateState.error` with a non-empty `current_version` so consumers+/// always get a well-formed payload they can branch on.+pub fn check_update_state(no_cache: bool) -> UpdateState {+ let current = env!("CARGO_PKG_VERSION").to_owned();+ let now = unix_now();+ let checked_at = iso8601(now);++ let cached = read_cache().unwrap_or_default();+ let cache_fresh = cached+ .last_checked_unix+ .map(|t| now.saturating_sub(t) < CACHE_REFRESH_SECONDS)+ .unwrap_or(false);++ // Honour the cache unless caller explicitly asked us to bypass it.+ // Mirrors `npm outdated --no-cache` / `brew update --force` semantics.+ let use_cache = !no_cache && cache_fresh && cached.latest_version.is_some();++ let (latest, cache_hit, fetch_error) = if use_cache {+ (cached.latest_version.clone(), true, None)+ } else {+ match fetch_latest_version() {+ Ok(v) => {+ // Persist on success so the next launch can reuse the answer.+ let new_cache = VersionCache {+ last_checked_unix: Some(now),+ last_checked_at: Some(checked_at.clone()),+ latest_version: Some(v.clone()),+ dismissed_versions: cached.dismissed_versions.clone(),+ };+ if let Err(e) = write_cache(&new_cache) {+ tracing::debug!(target: "cua_driver::version_check",+ "failed to write cache: {e}");+ }+ (Some(v), false, None)+ }+ Err(e) => {+ // Network failure — fall back to whatever the cache holds+ // (better a slightly-stale answer than nothing). The error+ // surfaces only when no cache is available.+ tracing::debug!(target: "cua_driver::version_check",+ "fetch failed: {e}");+ match cached.latest_version.clone() {+ Some(v) => (Some(v), true, None),+ None => (None, false, Some(e)),+ }+ }+ }+ };++ let update_available = latest+ .as_deref()+ .map(|l| is_newer(l, ¤t))+ .unwrap_or(false);++ let (install_command, release_notes_url) = if update_available {+ let l = latest.as_deref().unwrap_or("");+ (+ Some(install_one_liner()),+ Some(format!(+ "https://github.com/trycua/cua/releases/tag/{RELEASE_TAG_PREFIX}{l}"+ )),+ )+ } else {+ (None, None)+ };++ UpdateState {+ current_version: current,+ latest_version: latest,+ update_available,+ source: "github_releases",+ checked_at,+ cache_hit,+ install_command,+ release_notes_url,+ error: fetch_error,+ }+}+/// Mark `version` as dismissed so the banner stops nagging the user about/// this specific release. They will see the next banner the moment a/// strictly-newer tag ships.@@ -347,12 +487,16 @@ fn cache_path() -> Option<PathBuf> {////// - tags that don't start with `cua-driver-rs-v` (Swift port releases)/// - draft releases (`"draft": true`)-/// - pre-releases (`"prerelease": true`)+///+/// Pre-releases (`"prerelease": true`) are NOT filtered — cua-driver-rs+/// is pre-1.0 and the CD pipeline marks every release `prerelease=true`+/// by convention. Stripping them out left the check finding zero+/// candidates.////// Returns the bare version string (e.g. `"0.1.4"`) on success, or a/// human-readable error string on failure. The caller is expected to/// downgrade errors to `tracing::debug!`.-pub(crate) fn fetch_latest_version() -> Result<String, String> {+pub fn fetch_latest_version() -> Result<String, String> {let agent = ureq::Agent::config_builder().timeout_global(Some(std::time::Duration::from_secs(HTTP_TIMEOUT_SECONDS))).build()@@ -374,9 +518,10 @@ pub(crate) fn fetch_latest_version() -> Result<String, String> {.ok_or_else(|| "no matching cua-driver-rs-v* release in response".to_owned())}-/// Pull the highest non-draft non-prerelease `cua-driver-rs-v*` tag out-/// of the parsed releases response. Split out so unit tests can feed in-/// canned JSON without hitting the network.+/// Pull the highest non-draft `cua-driver-rs-v*` tag out of the parsed+/// releases response. Split out so unit tests can feed in canned JSON+/// without hitting the network. Pre-release flag is intentionally+/// ignored — see `fetch_latest_version` doc-comment.pub(crate) fn pick_latest_release(body: &serde_json::Value) -> Option<String> {let releases = body.as_array()?;let mut versions: Vec<semver::Version> = releases@@ -387,9 +532,6 @@ pub(crate) fn pick_latest_release(body: &serde_json::Value) -> Option<String> {if r.get("draft").and_then(|d| d.as_bool()).unwrap_or(false) {return None;}- if r.get("prerelease").and_then(|p| p.as_bool()).unwrap_or(false) {- return None;- }semver::Version::parse(bare).ok()}).collect();@@ -796,13 +938,17 @@ mod tests {}#[test]- fn pick_latest_release_skips_drafts_and_prereleases() {+ fn pick_latest_release_skips_drafts_but_accepts_prereleases() {+ // Drafts are always skipped. Pre-releases are accepted — every+ // cua-driver-rs release on `trycua/cua` is published as a+ // pre-release while the project is pre-1.0, so filtering them+ // out left the check finding zero candidates.let body = serde_json::json!([{"tag_name": "cua-driver-rs-v0.2.0", "draft": true, "prerelease": false},{"tag_name": "cua-driver-rs-v0.1.5", "draft": false, "prerelease": true},{"tag_name": "cua-driver-rs-v0.1.4", "draft": false, "prerelease": false},]);- assert_eq!(pick_latest_release(&body).as_deref(), Some("0.1.4"));+ assert_eq!(pick_latest_release(&body).as_deref(), Some("0.1.5"));}#[test]