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): run_script on by default, with an operator opt-out (#4936)
Francesco Bonacci815dfd96a10c
diff --git a/.github/scripts/cua-driver-mcp-compat/expected-tools.json b/.github/scripts/cua-driver-mcp-compat/expected-tools.jsonindex 7ab2ed1bbc..163c008b8e 100644--- a/.github/scripts/cua-driver-mcp-compat/expected-tools.json+++ b/.github/scripts/cua-driver-mcp-compat/expected-tools.json@@ -51,6 +51,7 @@"press_key","replay_trajectory","right_click",+ "run_script","run_steps","scroll","set_agent_cursor_enabled",diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.pyindex 17fdec3ce4..861a14dec4 100644--- a/.github/scripts/tests/test_cua_driver_release_wiring.py+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py@@ -1042,7 +1042,7 @@ fiself.assertEqual(len(expected["baseTools"]), len(set(expected["baseTools"])))- self.assertEqual(len(expected["baseTools"]), 59)+ self.assertEqual(len(expected["baseTools"]), 60)self.assertEqual(expected["outputSchemaCountByPlatform"],{"darwin": 35, "linux": 39, "win32": 35},diff --git a/.github/workflows/smoke-cua-driver-live.yml b/.github/workflows/smoke-cua-driver-live.ymlindex e10a606ff8..dba9d36970 100644--- a/.github/workflows/smoke-cua-driver-live.yml+++ b/.github/workflows/smoke-cua-driver-live.yml@@ -3,7 +3,7 @@ name: "Smoke: Cua Driver live agent loop"# Builds cua-driver from the checked-out commit and drives a real GUI window on# Windows and on Linux (Xvfb): the lean get_window_state default and# full_output, `since` diffs, act-by-element_token (with and without pid),-# run_steps, and set_value on combo boxes (background, foreground and an+# run_steps, run_script, and set_value on combo boxes (background, foreground and an# unknown option). The checks live in scripts/ci/cua-driver-live-smoke/smoke.py.on:@@ -14,6 +14,8 @@ on:- "scripts/ci/cua-driver-live-smoke/**"- "libs/cua-driver/rust/crates/cua-driver-core/src/window_state_view.rs"- "libs/cua-driver/rust/crates/cua-driver-core/src/batch_tools.rs"+ - "libs/cua-driver/rust/crates/cua-driver-core/src/script_tool.rs"+ - "libs/cua-driver/rust/crates/cua-driver-core/src/script_tool/**"- "libs/cua-driver/rust/crates/cua-driver-core/src/element_token.rs"- "libs/cua-driver/rust/crates/cua-driver-core/src/snapshot_store.rs"- "libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs"diff --git a/docs/content/docs/cua-driver/guides/operate.mdx b/docs/content/docs/cua-driver/guides/operate.mdxindex 0be1d92c06..9ab58e7d4e 100644--- a/docs/content/docs/cua-driver/guides/operate.mdx+++ b/docs/content/docs/cua-driver/guides/operate.mdx@@ -221,6 +221,13 @@ instead of `null`, and the always-empty `windows: []` is gone. The typed SDKsalready treat them as optional. For an app's windows, call`list_windows({app: "Name"})`.+`tools/list` also grows by one: `run_script` (sandboxed JavaScript that drives+the driver's own tools in one call) is on by default. Client allowlists and+tool-count checks need the new name. Turn it off with+`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in+`~/.cua-driver/config.json`; the old opt-in `CUA_DRIVER_EXPERIMENTAL_SCRIPT=1`+is no longer needed and is ignored.+### Before updating to token-only element targetingReleases that include [#3873](https://github.com/trycua/cua/pull/3873) addressdiff --git a/docs/content/docs/cua-driver/reference/index.mdx b/docs/content/docs/cua-driver/reference/index.mdxindex af25779160..59fd59d3e3 100644--- a/docs/content/docs/cua-driver/reference/index.mdx+++ b/docs/content/docs/cua-driver/reference/index.mdx@@ -38,7 +38,7 @@ description: "Every cua-driver command and every MCP tool on macOS, Linux and Wi| [Typing tools](/cua-driver/reference/mcp-tools/keyboard) | Type text into a field or window. 1 tools. || [Key and shortcut tools](/cua-driver/reference/mcp-tools/keys-and-shortcuts) | Press keys and keyboard shortcuts. 2 tools. || [Value and clipboard tools](/cua-driver/reference/mcp-tools/values-and-clipboard) | Set element values and read or write the clipboard. 3 tools. |-| [Batch tool](/cua-driver/reference/mcp-tools/batch) | Run several action tools in one call. 1 tools. |+| [Batch and script tools](/cua-driver/reference/mcp-tools/batch) | Run several action tools, or a script that drives them, in one call. 2 tools. || [Page tools](/cua-driver/reference/mcp-tools/page) | Read and act on web pages, and prepare and navigate browsers. 4 tools. || [Browser input tools](/cua-driver/reference/mcp-tools/browser-input) | Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads. 6 tools. || [Session tools](/cua-driver/reference/mcp-tools/sessions) | Start, escalate, inspect and end lifecycle sessions. 6 tools. |diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdxindex dc09f264d3..fcb71e5808 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/batch.mdx@@ -1,6 +1,6 @@----title: "Batch tool"-description: "Run several action tools in one call."+title: "Batch and script tools"+description: "Run several action tools, or a script that drives them, in one call."---{/*@@ -10,6 +10,23 @@ description: "Run several action tools in one call."Version: 0.34.0*/}+| Tool | Description | Platforms |+| --- | --- | --- |+| [`run_steps`](#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |+| [`run_script`](#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |++Use `run_steps` for a fixed list of actions you have already decided. Use `run_script` when the flow needs+logic between actions (a loop over rows, a branch on what the app shows, a retry): it runs a JavaScript+program over the driver's own tools in one call and returns only its result. Every driver call either+tool makes passes the same session, permission and approval checks as a direct call.++`run_script` runs in a QuickJS sandbox with no filesystem, network, process, timers or environment.+Limits: `timeout_ms` (default 30 s, max 120 s), `max_calls` (default 100, max 500), a 32 MiB heap and+a 64 KiB script. It is on by default. Whoever runs the driver turns it off with+`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json`+(`CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work); `set_config` cannot+change it.+Served by `cua-driver mcp`; see [MCP tools](/cua-driver/reference/mcp-tools) for every tool.## `run_steps`@@ -45,3 +62,41 @@ Effect: destructive. Platforms: macOS, Linux, Windows.```json{"steps":[{"tool":"click"}]}```++## `run_script`++Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.++The script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:+- `await cua.getApp("TextEdit" | "com.apple.TextEdit" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)+- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`+- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:"latest"})+- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)+- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)+- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey("return" | "cmd+s", t?), hotkey(["cmd","s"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])+where a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.+- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.+A failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.++Limits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.++Example:+const app = await cua.getApp("Calculator");+for (const key of ["7", "multiply", "6", "equals"]) await app.click({role: "button", name: key});+const [display] = await app.query({role: "statictext"});+return display.value;.++Effect: destructive. Platforms: macOS, Linux, Windows.++| Parameter | Type | Default | Description |+| --- | --- | --- | --- |+| <span id="run_script--max_calls"></span>`max_calls` | `integer` | | Most driver calls the script may make. Default 100. Range: 1 to 500. |+| <span id="run_script--script"></span>`script` | `string` | required | JavaScript: the body of an async function. `return` the result. |+| <span id="run_script--session"></span>`session` | `string` | | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. |+| <span id="run_script--timeout_ms"></span>`timeout_ms` | `integer` | | Wall-time limit. Default 30000. Range: 100 to 120000. |++**Example arguments**++```json+{"script":"<script>"}+```diff --git a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdxindex c2bed84ade..71658e63fc 100644--- a/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx+++ b/docs/content/docs/cua-driver/reference/mcp-tools/index.mdx@@ -143,13 +143,14 @@ Set element values and read or write the clipboard. [Reference](/cua-driver/refe| <span id="clipboard_read"></span>[`clipboard_read`](/cua-driver/reference/mcp-tools/values-and-clipboard#clipboard_read) | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows || <span id="clipboard_write"></span>[`clipboard_write`](/cua-driver/reference/mcp-tools/values-and-clipboard#clipboard_write) | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |-## Batch tool+## Batch and script tools-Run several action tools in one call. [Reference](/cua-driver/reference/mcp-tools/batch).+Run several action tools, or a script that drives them, in one call. [Reference](/cua-driver/reference/mcp-tools/batch).| Tool | Description | Platforms || --- | --- | --- || <span id="run_steps"></span>[`run_steps`](/cua-driver/reference/mcp-tools/batch#run_steps) | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with `observe`) get what changed in the same response. | macOS, Linux, Windows |+| <span id="run_script"></span>[`run_script`](/cua-driver/reference/mcp-tools/batch#run_script) | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |## Page toolsdiff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.mdindex 2efe588936..5784cf1ba8 100644--- a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md+++ b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md@@ -109,6 +109,7 @@ is safe even for apps that normally foreground on media-load| Enumerate an app's windows | `list_windows({pid})`: or read the `windows` array `launch_app` already returns | `osascript 'every window of app …'` || Move or resize one exact window | `set_window_frame({pid, window_id, x, y, width, height})` | `osascript` position/size writes or title-bar dragging || Click / type / scroll / keys | `click`, `type_text`, `scroll`, `press_key`, `hotkey` | `osascript`, `cliclick`, raw `CGEvent`, `open <url>` |+| Loop, branch or retry over app actions | `run_script({script})` (sandboxed JavaScript over the `cua` API, one call); `run_steps` for a fixed list | an AppleScript or shell loop around `osascript` or `cua-driver` calls || Drag / drag-and-drop / marquee select | `drag({pid, window_id, from_x, from_y, to_x, to_y, delivery_mode:"foreground"})` (pixel-only and foreground-only: macOS AX has no semantic drag, and there is no background drag) | `cliclick dd:`, `osascript drag` || Screenshot | `get_window_state` (window) or authorized `get_desktop_state` (desktop) | `screencapture` || Quit an app | ask the user first, then `hotkey({pid, keys:["cmd","q"]})` | `kill`, `killall`, `pkill` |diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.mdindex 2dfd3a8998..1477a2c0dc 100644--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md@@ -39,7 +39,7 @@ The MCP server instructions carry the same rules, so they apply even when this f1. Start with a targeted read: `get_window_state({pid, window_id, query:"Save"})` returns about 2K chars where a full snapshot is about 42K. Bound large trees with `max_elements` / `max_depth`. Widen only if the target is missing.2. Act by `element_token`: row `[N]` of a read is `<snapshot_id>:N` (for example `"s0000002a:11"`, not `"11"`). Use pixels only for surfaces missing from the tree.-3. Act through `run_steps` with `observe:true`, even for a single step. It runs the steps, stops at the first failure, and returns only what changed since your last read, so you do not need a separate read after acting; see [Workflow](WORKFLOW.md#batch-known-actions).+3. Act through `run_steps` with `observe:true`, even for a single step. It runs the steps, stops at the first failure, and returns only what changed since your last read, so you do not need a separate read after acting; see [Workflow](WORKFLOW.md#batch-known-actions). When the flow needs logic between actions (a loop, a branch on what the app shows, a retry), write it as one `run_script` instead; see [Workflow](WORKFLOW.md#script-a-flow).4. To re-read a window, pass `since:"latest"`: you get the changed rows, not the whole tree. To just look, use `include_accessibility_tree:false` where advertised (it keeps the current tokens valid). Do not use `max_elements:1` or a junk `query` to get a picture.5. Verify at checkpoints (after a meaningful state change, before finishing), not after every action. One `verify_state` or one targeted `get_window_state` is usually enough.@@ -53,6 +53,7 @@ The MCP server instructions carry the same rules, so they apply even when this f| Observe one window | `get_window_state({pid, window_id, query})` | [Workflow](WORKFLOW.md) || Act on a control | `click` / `type_text` with a fresh `element_token` and exact window target | [Workflow](WORKFLOW.md) || Act and see what changed in one call | `run_steps({steps:[{tool,args},...], observe:true})`; stops at the first failure | [Workflow](WORKFLOW.md#batch-known-actions) |+| Loop, branch or retry in one call | `run_script({script})`: JavaScript over the `cua` API, sandboxed, time and call limits | [Workflow](WORKFLOW.md#script-a-flow) || Use pixels when semantics cannot reach it | Fresh target screenshot, then `x,y` on the same target | [Workflow](WORKFLOW.md) || Verify the outcome | `verify_state({pid, window_id, expect})` or a fresh snapshot read by the agent | [Workflow](WORKFLOW.md) || Operate the authorized desktop | `get_desktop_state` → input with `target:{kind:"desktop",display_id:"primary"}` → `get_desktop_state` | [Workflow](WORKFLOW.md), [Linux](LINUX.md) on Wayland |diff --git a/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md b/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.mdindex 575a9f8dd2..87b5e82f4d 100644--- a/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md+++ b/libs/cua-driver/rust/Skills/cua-driver/WORKFLOW.md@@ -98,6 +98,20 @@ cua-driver run_steps '{"session":"run-1","steps":[- `observe` is optional and reads once, after the last executed step (also after a failure). Pass `true` or `get_window_state` arguments; `pid`/`window_id` come from the last step that names both. Defaults: `since:"latest"` (only what changed since your last read of that window with the same view; a full read if there is none), `include_screenshot:false`, `max_elements:250`. Pass `include_screenshot:true` to see the window, or `since:null` for a full read. Omit `observe` to read nothing.- Read `steps[].ok` and `failed_step`. Steps before a failure did run and are not rolled back; steps after it did not. Observe before repairing, as for a single `unverifiable` action. When a step fails because another window of the app holds focus (a dialog opened mid-batch), the end read is of that window, even without `observe`; when a pixel step names a window with no screenshot yet, the end read includes its screenshot. A step refused because its app ignores background input (Electron, LibreOffice) says how to re-send it; set `foreground_fallback:true` on `run_steps` to retry such steps once in the foreground (the window is activated and the pointer may move).+## Script a flow++Use `run_script` when the flow needs logic between actions: a loop over rows, a branch on what the app shows, a retry, or a value read in one window and typed into another. The script is JavaScript, the body of an async function; it runs in ONE call and only its `return` value, console output and a per-call log come back. Use `run_steps` for a fixed list of steps you have already decided, and plain calls when the next step needs your judgement.++```bash+cua-driver run_script '{"session":"run-1","script":"const app = await cua.getApp(\"Calculator\"); for (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key}); const [display] = await app.query({role: \"statictext\"}); return display.value;"}'+```++- The only API is `cua`: `getApp`, `launch`, `listApps`, `listWindows`, `sleep`, and on an app `getState`, `query`, `waitFor`, `verify` and the actions (`click`, `typeText`, `pressKey`, `setValue`, `scroll`, `drag`, ...). A target is `{role, name, nth?}` (found fresh, waits up to 3 s), an `element_token`, or `[x, y]` window pixels. `describe run_script` lists the full API.+- A failed driver call throws; catch it to recover. An uncaught error names the script line, the call and the reason.+- Every driver call passes the same session, permission, capability-manifest and approval checks as a direct call, so a script grants nothing the same direct calls lack. It cannot call `run_steps`, `run_script`, `set_config` or tools outside its allowlist.+- Sandbox: QuickJS with no filesystem, network, process, timers or environment. Limits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), a 32 MiB heap, a bounded stack, and a 64 KiB script. The script stops when the request is cancelled.+- `run_script` is on by default. Whoever runs the driver can turn it off with `CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json` (the older `CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work). `set_config` cannot change it. When it is off, it is not in `tools/list`.+## Pixel coordinatesGround window actions on the PNG from that exact `get_window_state`; ground desktop actions on `get_desktop_state`. Origins are top-left, increasing downward. The driver handles its own window capture scaling; do not add window offsets to window-local input.diff --git a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.tomlindex 55cfbc9b26..de9e618d6b 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml+++ b/libs/cua-driver/rust/crates/cua-driver-core/Cargo.toml@@ -9,9 +9,10 @@ publish = falsedefault = ["yaml", "rego", "script"]yaml = ["dep:regex"]rego = ["dep:regorus"]-# Experimental `run_script` tool: an embedded QuickJS engine (rquickjs and-# quickjs-ng, both MIT). Compiled in by default; the tool itself is only-# registered when the operator opts in at runtime.+# `run_script` tool: an embedded QuickJS engine (rquickjs and quickjs-ng,+# both MIT). Compiled in by default on every platform, and the tool is+# offered unless the operator turns it off at runtime. Without this feature+# the tool is not offered at all.script = ["dep:rquickjs"][dependencies]diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rsindex ebb01588d1..e8cff5cdeb 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/protocol.rs@@ -378,6 +378,17 @@ fn agent_instructions() -> String {)};+ // Only point at run_script when this driver offers it.+ #[cfg(feature = "script")]+ let script_enabled = crate::script_tool::enabled();+ #[cfg(not(feature = "script"))]+ let script_enabled = false;+ let script_line = if script_enabled {+ " Loops, branches or retries: one `run_script` call (sandboxed JavaScript)."+ } else {+ ""+ };+format!(r#"cua-driver: background GUI automation. No shell: for non-GUI outcomes use an app API/SDK, CLI or filesystem and read the result back there.@@ -385,7 +396,7 @@ Efficient loop:1. `list_windows({{app:"Name"}})` or `launch_app` for `pid` and `window_id`. Unfiltered `list_windows`/`list_apps` list the whole host.2. Read narrowly: `get_window_state` with `query:"Save"` (or `max_elements`). Re-read with `since:"latest"` for only what changed. For just a picture, `include_accessibility_tree:false` (tokens stay valid).3. Act by `element_token` ({tree_kind}): row `[N]` is `<snapshot_id>:N`. Pixel `x,y` only for surfaces missing from the tree.-4. Act through `run_steps({{steps:[{{tool,args}}],observe:true}})`, even for one step: it stops at the first failure and returns what changed, so no separate re-read.+4. Act through `run_steps({{steps:[{{tool,args}}],observe:true}})`, even for one step: it stops at the first failure and returns what changed, so no separate re-read.{script_line}5. Verify at checkpoints, not after every action: `verify_state(pid, window_id, expect)`. `unknown` and `effect:"unverifiable"` are not success.Use the narrowest semantic route first: `set_window_frame` plus `list_windows` for geometry, typed browser tools for pages, clipboard tools for the clipboard. Stay in the background; `delivery_mode:"foreground"` only if refused or unverifiable.@@ -500,6 +511,10 @@ mod agent_instruction_tests {instructions.find("Read narrowly") < instructions.find("Act by `element_token`"),"the targeted read must precede acting");+ #[cfg(feature = "script")]+ if crate::script_tool::enabled() {+ assert!(instructions.contains("one `run_script` call"));+ }assert!(instructions.split_whitespace().count() <= 200,"initialize instructions should stay within the documented context budget"diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool.rsindex d5b0f569ec..b465d07c82 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool.rs@@ -1,10 +1,12 @@-//! `run_script` (experimental): run a model-written JavaScript program that-//! drives the computer through Cua Driver's own actions and reads.+//! `run_script`: run a model-written JavaScript program that drives the+//! computer through Cua Driver's own actions and reads.//!-//! Off by default. It is registered only when the person running the driver-//! opts in, with `CUA_DRIVER_EXPERIMENTAL_SCRIPT=1` or-//! `"experimental_script": true` in `~/.cua-driver/config.json`.-//! `set_config` cannot write that key, so a model cannot turn it on.+//! On by default wherever the engine is compiled in (the `script` feature,+//! default on macOS, Windows and Linux). The person running the driver turns+//! it off with `CUA_DRIVER_DISABLE_RUN_SCRIPT=1`, `CUA_DRIVER_EXPERIMENTAL_SCRIPT=0`,+//! or `"disable_run_script": true` / `"experimental_script": false` in+//! `~/.cua-driver/config.json`. `set_config` cannot write those keys, so a+//! model cannot turn it on or off.//!//! The script runs in an embedded QuickJS engine ([`engine`]) on its own//! thread, with no filesystem, network, process or environment access. Its@@ -42,10 +44,16 @@ mod engine;use engine::{FailureKind, HostCall, HostError, Limits};pub const RUN_SCRIPT_TOOL: &str = "run_script";-/// Environment switch that registers the tool.-pub const ENABLE_ENV: &str = "CUA_DRIVER_EXPERIMENTAL_SCRIPT";-/// `~/.cua-driver/config.json` key that registers the tool.-pub const ENABLE_CONFIG_KEY: &str = "experimental_script";+/// Environment switch that turns the tool off when set to `1`.+pub const DISABLE_ENV: &str = "CUA_DRIVER_DISABLE_RUN_SCRIPT";+/// `~/.cua-driver/config.json` key that turns the tool off when `true`.+pub const DISABLE_CONFIG_KEY: &str = "disable_run_script";+/// Legacy opt-in switch from when the tool was off by default. `0` still+/// turns the tool off; `1` changes nothing.+pub const LEGACY_ENV: &str = "CUA_DRIVER_EXPERIMENTAL_SCRIPT";+/// Legacy `~/.cua-driver/config.json` key. `false` turns the tool off;+/// `true` changes nothing.+pub const LEGACY_CONFIG_KEY: &str = "experimental_script";pub const DEFAULT_TIMEOUT_MS: u64 = 30_000;pub const MAX_TIMEOUT_MS: u64 = 120_000;@@ -71,8 +79,14 @@ const READ_TOOLS: &[&str] = &["zoom",];-/// Whether the person running the driver opted in.+/// Whether the tool is offered: yes, unless the person running the driver+/// turned it off.pub fn enabled() -> bool {+ disabled_by().is_none()+}++/// The setting that turned the tool off, if any.+pub fn disabled_by() -> Option<String> {let config = std::env::var_os("HOME").or_else(|| std::env::var_os("USERPROFILE")).map(|home| {@@ -80,22 +94,46 @@ pub fn enabled() -> bool {.join(".cua-driver").join("config.json")});- enabled_from(std::env::var(ENABLE_ENV).ok().as_deref(), config.as_deref())+ disabled_from(+ std::env::var(DISABLE_ENV).ok().as_deref(),+ std::env::var(LEGACY_ENV).ok().as_deref(),+ config.as_deref(),+ )}-/// The environment variable wins; otherwise the config file decides.-fn enabled_from(env: Option<&str>, config: Option<&std::path::Path>) -> bool {- if let Some(value) = env {- return matches!(- value.trim().to_ascii_lowercase().as_str(),- "1" | "true" | "yes" | "on"- );+/// Any opt-out wins; nothing turns the tool on that an opt-out turned off.+fn disabled_from(+ disable_env: Option<&str>,+ legacy_env: Option<&str>,+ config: Option<&std::path::Path>,+) -> Option<String> {+ let flag = |value: &str| -> Option<bool> {+ match value.trim().to_ascii_lowercase().as_str() {+ "1" | "true" | "yes" | "on" => Some(true),+ "0" | "false" | "no" | "off" => Some(false),+ _ => None,+ }+ };+ if disable_env.and_then(flag) == Some(true) {+ return Some(format!("{DISABLE_ENV}=1"));+ }+ if legacy_env.and_then(flag) == Some(false) {+ return Some(format!("{LEGACY_ENV}=0"));}- config+ let config_value = config.and_then(|path| std::fs::read_to_string(path).ok())- .and_then(|text| serde_json::from_str::<Value>(&text).ok())- .and_then(|config| config.get(ENABLE_CONFIG_KEY).and_then(Value::as_bool))- .unwrap_or(false)+ .and_then(|text| serde_json::from_str::<Value>(&text).ok())?;+ if config_value+ .get(DISABLE_CONFIG_KEY)+ .and_then(Value::as_bool)+ == Some(true)+ {+ return Some(format!("\"{DISABLE_CONFIG_KEY}\": true in config.json"));+ }+ if config_value.get(LEGACY_CONFIG_KEY).and_then(Value::as_bool) == Some(false) {+ return Some(format!("\"{LEGACY_CONFIG_KEY}\": false in config.json"));+ }+ None}pub struct RunScriptTool {@@ -125,10 +163,10 @@ impl Tool for RunScriptTool {fn def(&self) -> &ToolDef {DEF.get_or_init(|| ToolDef {name: RUN_SCRIPT_TOOL.into(),- description: "EXPERIMENTAL. Run a JavaScript program that drives apps through Cua \- Driver, in ONE call: loops, conditions, reads and checks between actions, and \- only the result comes back. Use it for a multi-step flow you can write down; \- use run_steps for a fixed list of steps.\n\n\+ description: "Run a JavaScript program that drives apps through Cua Driver, in ONE \+ call: loops, conditions, reads and checks between actions, and only the result \+ comes back. Use it when the flow needs logic (a loop over rows, a branch on what \+ the app shows, a retry); use run_steps for a fixed list of steps.\n\n\The script is the body of an async function: use `await`, and `return` a JSON \value. It runs in a sandbox with no filesystem, network, process, timers or \environment; the only API is `cua`:\n\diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool/tests.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool/tests.rsindex bced2f9b81..710ec10928 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool/tests.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/script_tool/tests.rs@@ -433,30 +433,77 @@ async fn bad_requests_are_rejected_before_running() {}#[test]-fn the_tool_is_off_unless_the_operator_opts_in() {+fn the_tool_is_on_unless_the_operator_turns_it_off() {+ use super::disabled_from as off;let dir = tempfile::tempdir().unwrap();let config = dir.path().join("config.json");- assert!(!super::enabled_from(None, None), "off by default");- assert!(!super::enabled_from(None, Some(&config)), "no config file");+ assert_eq!(off(None, None, None), None, "on by default");+ assert_eq!(off(None, None, Some(&config)), None, "no config file");+ std::fs::write(&config, "not json").unwrap();+ assert_eq!(off(None, None, Some(&config)), None, "unreadable config");std::fs::write(&config, r#"{"experimental_pip": true}"#).unwrap();- assert!(!super::enabled_from(None, Some(&config)));+ assert_eq!(off(None, None, Some(&config)), None, "other keys");++ // The opt-outs.+ assert!(off(Some("1"), None, None)+ .unwrap()+ .contains("CUA_DRIVER_DISABLE_RUN_SCRIPT"));+ assert!(off(Some(" TRUE "), None, None).is_some());+ assert_eq!(off(Some("0"), None, None), None);+ assert_eq!(off(Some("maybe"), None, None), None);+ std::fs::write(&config, r#"{"disable_run_script": true}"#).unwrap();+ assert!(off(None, None, Some(&config))+ .unwrap()+ .contains("disable_run_script"));+ std::fs::write(&config, r#"{"disable_run_script": false}"#).unwrap();+ assert_eq!(off(None, None, Some(&config)), None);+ std::fs::write(&config, r#"{"experimental_script": false}"#).unwrap();+ assert!(off(None, None, Some(&config))+ .unwrap()+ .contains("experimental_script"));+}++#[test]+fn the_legacy_opt_in_flag_can_only_turn_the_tool_off() {+ use super::disabled_from as off;+ let dir = tempfile::tempdir().unwrap();+ let config = dir.path().join("config.json");+ // `=1` and `true` were the old opt-in: now they change nothing.+ assert_eq!(off(None, Some("1"), None), None);std::fs::write(&config, r#"{"experimental_script": true}"#).unwrap();- assert!(super::enabled_from(None, Some(&config)), "config opt-in");- assert!(- !super::enabled_from(Some("0"), Some(&config)),- "the environment wins"- );- assert!(super::enabled_from(Some("1"), None));- assert!(super::enabled_from(Some(" TRUE "), None));- assert!(!super::enabled_from(Some("maybe"), None));+ assert_eq!(off(None, None, Some(&config)), None);+ // ...and they do not override an opt-out.+ assert!(off(Some("1"), Some("1"), Some(&config)).is_some());+ std::fs::write(+ &config,+ r#"{"experimental_script": true, "disable_run_script": true}"#,+ )+ .unwrap();+ assert!(off(None, Some("1"), Some(&config)).is_some());+ std::fs::write(&config, r#"{"experimental_script": false}"#).unwrap();+ assert!(off(None, Some("1"), Some(&config)).is_some());+ // `=0` turns it off, even over a config opt-in.+ std::fs::write(&config, r#"{"experimental_script": true}"#).unwrap();+ assert!(off(None, Some("0"), Some(&config))+ .unwrap()+ .contains("CUA_DRIVER_EXPERIMENTAL_SCRIPT=0"));+ assert!(off(None, Some("false"), None).is_some());}#[test]-fn an_unflagged_registry_does_not_offer_the_tool() {+fn a_default_registry_offers_the_tool() {let mut registry = ToolRegistry::new();registry.register_session_tools();- // The flag is off in the test environment unless someone set it.- if !super::enabled() {+ // On unless whoever runs the tests turned it off.+ if super::enabled() {+ assert!(registry.get_def(super::RUN_SCRIPT_TOOL).is_some());+ let listed = registry.tools_list();+ assert!(listed["tools"]+ .as_array()+ .unwrap()+ .iter()+ .any(|tool| tool["name"] == super::RUN_SCRIPT_TOOL));+ } else {assert!(registry.get_def(super::RUN_SCRIPT_TOOL).is_none());}assert!(registrydiff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rsindex 37ac515d5e..4f8a635c04 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@@ -1330,14 +1330,17 @@ impl ToolRegistry {self.register(Box::new(crate::batch_tools::RunStepsTool::new(self.replay_registry.clone(),)));- // Experimental and opt-in: only when the operator turned it on.+ // On by default; the operator can turn it off (see script_tool).#[cfg(feature = "script")]- if crate::script_tool::enabled() {- self.register_script_tool();+ match crate::script_tool::disabled_by() {+ None => self.register_script_tool(),+ Some(setting) => tracing::debug!("run_script not offered: turned off by {setting}"),}+ #[cfg(not(feature = "script"))]+ tracing::debug!("run_script not offered: built without the `script` engine feature");}- /// Register the experimental `run_script` tool, which, like+ /// Register the `run_script` tool, which, like/// `run_steps`, re-enters this registry for every driver call.#[cfg(feature = "script")]pub fn register_script_tool(&mut self) {diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rsindex 9c451e3c77..ec65c58403 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_config.rs@@ -99,6 +99,22 @@ impl Tool for SetConfigTool {"replacement": "action.target",}));}+ // Whether run_script is offered is the operator's choice, made in+ // config.json or the environment; a model cannot change it.+ if let Some(key) = args+ .get("key")+ .and_then(Value::as_str)+ .filter(|key| matches!(*key, "disable_run_script" | "experimental_script"))+ {+ return ToolResult::error(format!(+ "config key '{key}' is set by whoever runs cua-driver, in \+ ~/.cua-driver/config.json or the environment, not through set_config"+ ))+ .with_structured(serde_json::json!({+ "code": "config_key_operator_only",+ "key": key,+ }));+ }// The daemon injects `_session_id` for non-anonymous MCP sessions.// Absent => anonymous/global session (CLI one-shot, legacy proxy) =>// today's behavior: write the shared global DriverConfig + persist todiff --git a/scripts/ci/cua-driver-live-smoke/smoke.py b/scripts/ci/cua-driver-live-smoke/smoke.pyindex bd221d857d..f9c5476506 100644--- a/scripts/ci/cua-driver-live-smoke/smoke.py+++ b/scripts/ci/cua-driver-live-smoke/smoke.py@@ -8,6 +8,7 @@ fixture window (GTK3 on Linux, WinForms on Windows) and checks:* the act-by-element_token loop (snapshot, click a token, fresh snapshot),* `since` (a diff against an earlier snapshot, and `no change`),* run_steps (one batch with an end-of-batch observation),+ * run_script (listed by default; a script loop clicks by token; no I/O),* set_value on a drop-down combo box and on an editable combo box,* display_only previews (and plain screenshot-only reads) keep the agent'selement tokens valid.@@ -414,6 +415,9 @@ def run_checks(smoke):# 7c. The pre-0.35 name run_actions still runs, unlisted, with a note.renamed_tool_alias_check(smoke)+ # 7d. run_script is on by default: listed, runs a loop, has no I/O.+ run_script_check(smoke)+# 8. The drop-down combo with delivery_mode foreground (last because a# broken route may leave a popup open), then a click by token must still# land, which it does not while a popup holds the pointer grab.@@ -636,6 +640,45 @@ def renamed_tool_alias_check(smoke):smoke.record(check, "fail" if problems else "pass", "; ".join(problems) or "listed: run_steps only; run_actions ran with the note")+def run_script_check(smoke):+ """run_script is listed by default, a script clicks Increment twice in a+ loop, and the sandbox has no require, process or fetch."""+ check = "run_script: listed by default, loop of clicks, sandboxed"+ problems = []+ listed = smoke.mcp.request("tools/list", {})+ names = {t.get("name") for t in (listed.get("result") or {}).get("tools") or []}+ if "run_script" not in names:+ problems.append("tools/list lacks run_script")++ state = smoke.read()+ before = count_value(tree(state))+ increment = find_row(tree(state), BUTTON, "Increment")+ if before is None or increment is None:+ problems.append("fixture Increment row or Count label not found")+ else:+ script = (+ f"const app = await cua.getApp({{pid: {smoke.pid}, windowId: {smoke.window_id}}});\n"+ f"for (let i = 0; i < 2; i++) await app.click({json.dumps(token(state, increment))});\n"+ "return {sandbox: [typeof require, typeof process, typeof fetch].join(',')};"+ )+ ran = smoke.call("run_script", {"script": script, "timeout_ms": 30000})+ value = (ran.structured or {}).get("value") or {}+ if ran.is_error:+ problems.append(f"run_script -> {ran.text[:600]!r}")+ elif value.get("sandbox") != "undefined,undefined,undefined":+ problems.append(f"sandbox exposes {value.get('sandbox')!r}")+ after = smoke.wait_for_text(f"Count: {before + 2}")+ if f"Count: {before + 2}" not in tree(after):+ problems.append(f"Count went {before} -> {count_value(tree(after))}, expected {before + 2}")+ smoke.record(+ check,+ "fail" if problems else "pass",+ "; ".join(problems)+ or f"listed; 2 clicks in a script loop moved Count {before} -> {before + 2}; "+ "require/process/fetch undefined",+ )++def unknown_option_check(smoke):"""set_value with an option the drop-down does not have is refused andchanges nothing."""diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.jsonindex a92093849d..5d1a82bdd8 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json@@ -3612,6 +3612,44 @@"name": "run_steps","read_only": false},+ {+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",+ "destructive": true,+ "idempotent": false,+ "input_schema": {+ "additionalProperties": false,+ "properties": {+ "max_calls": {+ "description": "Most driver calls the script may make. Default 100.",+ "maximum": 500,+ "minimum": 1,+ "type": "integer"+ },+ "script": {+ "description": "JavaScript: the body of an async function. `return` the result.",+ "maxLength": 65536,+ "minLength": 1,+ "type": "string"+ },+ "session": {+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",+ "type": "string"+ },+ "timeout_ms": {+ "description": "Wall-time limit. Default 30000.",+ "maximum": 120000,+ "minimum": 100,+ "type": "integer"+ }+ },+ "required": [+ "script"+ ],+ "type": "object"+ },+ "name": "run_script",+ "read_only": false+ },{"description": "Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an `update_available` boolean, the install one-liner, and the release notes URL. Read-only — never installs. Pacman-owned Linux executables return package-manager guidance without checking GitHub. Mirror of `cua-driver check-update --json`.","destructive": false,diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.jsonindex c4c64913b2..82cc94d3cf 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-macos.json@@ -3248,6 +3248,44 @@"name": "run_steps","read_only": false},+ {+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",+ "destructive": true,+ "idempotent": false,+ "input_schema": {+ "additionalProperties": false,+ "properties": {+ "max_calls": {+ "description": "Most driver calls the script may make. Default 100.",+ "maximum": 500,+ "minimum": 1,+ "type": "integer"+ },+ "script": {+ "description": "JavaScript: the body of an async function. `return` the result.",+ "maxLength": 65536,+ "minLength": 1,+ "type": "string"+ },+ "session": {+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",+ "type": "string"+ },+ "timeout_ms": {+ "description": "Wall-time limit. Default 30000.",+ "maximum": 120000,+ "minimum": 100,+ "type": "integer"+ }+ },+ "required": [+ "script"+ ],+ "type": "object"+ },+ "name": "run_script",+ "read_only": false+ },{"description": "Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an `update_available` boolean, the install one-liner, and the release notes URL. Read-only — never installs. Pacman-owned Linux executables return package-manager guidance without checking GitHub. Mirror of `cua-driver check-update --json`.","destructive": false,diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.jsonindex 2e0beb5b7a..d68cd4428a 100644--- a/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json+++ b/scripts/docs-generators/cli-specs/cua-driver-mcp-windows.json@@ -3304,6 +3304,44 @@"name": "run_steps","read_only": false},+ {+ "description": "Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. Use it when the flow needs logic (a loop over rows, a branch on what the app shows, a retry); use run_steps for a fixed list of steps.\n\nThe script is the body of an async function: use `await`, and `return` a JSON value. It runs in a sandbox with no filesystem, network, process, timers or environment; the only API is `cua`:\n- `await cua.getApp(\"TextEdit\" | \"com.apple.TextEdit\" | {pid, windowId})` → app (follows the app's frontmost window unless a windowId is given)\n- `await cua.launch(nameOrBundleId)` → app; `cua.listApps()`, `cua.listWindows({pid?})`, `cua.sleep(ms)`, `cua.computer.target`\n- app.getState(opts?) → get_window_state result (`tree_markdown` or `tree_diff`, `snapshot_id`; pass get_window_state options such as {since:\"latest\"})\n- app.query({role?, name?, text?}) → matching elements across the app's windows {element_token, role, label, value, enabled, selected, frame}, then matching static-text rows {role, label, value, text, display_only} (read text such as a status line from their `value`)\n- app.waitFor({role?, name?, text?, gone?, value?, timeout_ms?}) and app.verify(predicate | predicates) (verify_state)\n- app.click(t), doubleClick(t), rightClick(t), typeText(text, t?), pressKey(\"return\" | \"cmd+s\", t?), hotkey([\"cmd\",\"s\"]), scroll(t, direction, amount?), setValue(t, value), drag([x,y], [x,y]), zoom([x1,y1,x2,y2])\nwhere a target `t` is {role, name, nth?} (found fresh, waits up to 3 s), an element_token string, a row number from this app's last getState(), or [x, y] window pixels.\n- `cua.call(tool, args)` for any other allowed tool: click, double_click, right_click, set_value, type_text, press_key, hotkey, scroll, drag, launch_app, list_apps, list_windows, get_window_state, verify_state, zoom.\nA failed driver call throws a CuaError (catch it to recover). Every call goes through the same session, permission and approval checks as a direct call.\n\nLimits: `timeout_ms` wall time (default 30000, max 120000), `max_calls` driver calls (default 100, max 500), 32 MiB heap. Returns the return value, console output, and a per-call log; an error names the script line, the call and the reason.\n\nExample:\nconst app = await cua.getApp(\"Calculator\");\nfor (const key of [\"7\", \"multiply\", \"6\", \"equals\"]) await app.click({role: \"button\", name: key});\nconst [display] = await app.query({role: \"statictext\"});\nreturn display.value;",+ "destructive": true,+ "idempotent": false,+ "input_schema": {+ "additionalProperties": false,+ "properties": {+ "max_calls": {+ "description": "Most driver calls the script may make. Default 100.",+ "maximum": 500,+ "minimum": 1,+ "type": "integer"+ },+ "script": {+ "description": "JavaScript: the body of an async function. `return` the result.",+ "maxLength": 65536,+ "minLength": 1,+ "type": "string"+ },+ "session": {+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session.",+ "type": "string"+ },+ "timeout_ms": {+ "description": "Wall-time limit. Default 30000.",+ "maximum": 120000,+ "minimum": 100,+ "type": "integer"+ }+ },+ "required": [+ "script"+ ],+ "type": "object"+ },+ "name": "run_script",+ "read_only": false+ },{"description": "Check the saved stable/nightly Cua Driver channel for a release on GitHub. Returns current and selected channels, current and latest versions, an `update_available` boolean, the install one-liner, and the release notes URL. Read-only — never installs. Pacman-owned Linux executables return package-manager guidance without checking GitHub. Mirror of `cua-driver check-update --json`.","destructive": false,diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.tsindex 445762ca68..922beb2b64 100644--- a/scripts/docs-generators/cua-driver.ts+++ b/scripts/docs-generators/cua-driver.ts@@ -298,9 +298,22 @@ export const MCP_CATEGORIES: Array<McpCategory & { tools: string[] }> = [},{slug: 'batch',- title: 'Batch tool',- summary: 'Run several action tools in one call',- tools: ['run_steps'],+ title: 'Batch and script tools',+ summary: 'Run several action tools, or a script that drives them, in one call',+ intro: [+ 'Use `run_steps` for a fixed list of actions you have already decided. Use `run_script` when the flow needs',+ 'logic between actions (a loop over rows, a branch on what the app shows, a retry): it runs a JavaScript',+ 'program over the driver\'s own tools in one call and returns only its result. Every driver call either',+ 'tool makes passes the same session, permission and approval checks as a direct call.',+ '',+ '`run_script` runs in a QuickJS sandbox with no filesystem, network, process, timers or environment.',+ 'Limits: `timeout_ms` (default 30 s, max 120 s), `max_calls` (default 100, max 500), a 32 MiB heap and',+ 'a 64 KiB script. It is on by default. Whoever runs the driver turns it off with',+ '`CUA_DRIVER_DISABLE_RUN_SCRIPT=1` or `"disable_run_script": true` in `~/.cua-driver/config.json`',+ '(`CUA_DRIVER_EXPERIMENTAL_SCRIPT=0` and `"experimental_script": false` also work); `set_config` cannot',+ 'change it.',+ ].join('\n'),+ tools: ['run_steps', 'run_script'],},{slug: 'page',