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): 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.json
index 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.py
index 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 @@ fi
self.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.yml
index 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.mdx
index 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 SDKs
already 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 targeting
Releases that include [#3873](https://github.com/trycua/cua/pull/3873) address
diff --git a/docs/content/docs/cua-driver/reference/index.mdx b/docs/content/docs/cua-driver/reference/index.mdx
index 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.mdx
index 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.mdx
index 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 tools
diff --git a/libs/cua-driver/rust/Skills/cua-driver/MACOS.md b/libs/cua-driver/rust/Skills/cua-driver/MACOS.md
index 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.md
index 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 f
1. 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.md
index 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 coordinates
Ground 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.toml
index 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 = false
default = ["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.rs
index 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.rs
index 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.rs
index 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!(registry
diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool.rs
index 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.rs
index 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 to
diff --git a/scripts/ci/cua-driver-live-smoke/smoke.py b/scripts/ci/cua-driver-live-smoke/smoke.py
index 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's
element 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 and
changes nothing."""
diff --git a/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json b/scripts/docs-generators/cli-specs/cua-driver-mcp-linux.json
index 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.json
index 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.json
index 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.ts
index 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',