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.

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.mdx
index 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.json
index 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.mdx
new file mode 100644
index 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.lock
index 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.md
index 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-specific
launch 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.rs
new file mode 100644
index 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.rs
index 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.rs
index 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(&reg);
return;
}
cli::Command::Describe(name) => {
- let reg = Arc::new(platform_macos::register_tools());
+ let reg = Arc::new(build_macos_registry());
cli::run_describe(&reg, &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(&reg, 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(&reg, 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.rs
index 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, &current))
+ .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]