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.

docs(cua-driver): document browser mutation coverage

trycua-release[bot]b1ef600d3d5b
diff --git a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
index 85cc2e02e0..8969a0a2d9 100644
--- a/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
+++ b/docs/content/docs/concepts/browser-targeting-and-background-delivery.mdx
@@ -18,6 +18,12 @@ Agents still begin with `list_apps` and `list_windows`. They select a concrete
mints opaque target and tab capabilities. Raw DevTools target identifiers are
not part of the public contract.
+Selected-tab state is deliberately tri-state. `active: true` or `false` is
+reported only when the native window title uniquely identifies one DevTools
+tab. Duplicate titles, empty titles, and other ambiguity produce `active:
+null` for every candidate instead of treating DevTools list order as native
+selection evidence. A caller can still target an explicit returned tab id.
+
This preserves one targeting model across native and web content. It also
prevents a browser helper from choosing the first tab, first window, or first
process match when several candidates exist.
@@ -54,13 +60,24 @@ default click uses `Input.dispatchMouseEvent`, but Chromium's standalone window
is known to activate on that route on macOS and Linux. Cua Driver returns
`browser_input_trust_unavailable` there before dispatch. Standalone Chrome and
Edge on Windows, and the bounded embedded Electron route, have passing trusted
-background evidence.
+background evidence. The same trust distinction applies to hover,
+right-click, double-click, scroll, and drag through `browser_pointer`.
A caller must explicitly request `input_route: "dom_event"` to invoke an
element's DOM click behavior. That route is synthetic even when it preserves
full-background posture. The driver does not silently change trust models to
make a call appear successful.
+Page-owned JavaScript dialogs are modeled as short-lived capabilities rather
+than native-window guesses. Inspection returns the kind and an opaque dialog
+generation; accept or dismiss succeeds only while that exact dialog remains
+current. The page's initial creation of a Chromium native modal may activate
+the browser; after occlusion is re-established, inspection and resolution do
+not require another activation. File assignment bypasses native pickers through an exact live file
+input ref. Downloads additionally cross an open-world filesystem boundary, so
+they require host approval, a canonical destination directory, exact event
+correlation, and path-free output.
+
## Capabilities have a lifetime
Target ids, tab ids, and page refs belong to a named driver session. Page refs
diff --git a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx b/docs/content/docs/concepts/how-cua-driver-is-validated.mdx
index 6dedc418a1..e9e0e78d10 100644
--- a/docs/content/docs/concepts/how-cua-driver-is-validated.mdx
+++ b/docs/content/docs/concepts/how-cua-driver-is-validated.mdx
@@ -41,6 +41,15 @@ keys, scrolling, dragging, child windows, controls, and editor behavior. This
makes a failure reproducible without depending on the changing state of an
installed third-party application.
+The optional standalone-browser lane launches installed Chrome, Edge, or
+Chromium with a fresh repo-owned profile and one exact source-built driver. Its
+rows cover binding and ambiguous active-tab evidence, semantic snapshots,
+frames, inactive tabs, JavaScript dialogs, file assignment, extended pointer
+actions, and approval-scoped downloads. The target stays fully occluded behind
+the foreground sentinel while the fixture journal proves page state. This lane
+is the release evidence for typed browser behavior; CDP acknowledgements alone
+do not count as delivery.
+
## One catalog describes each behavior cell
The Rust catalog records the dimensions that affect delivery:
diff --git a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
index 6ab05cec10..039c7622db 100644
--- a/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
+++ b/docs/content/docs/how-to-guides/driver/drive-a-web-page.mdx
@@ -154,9 +154,13 @@ get_browser_state({
})
```
-Keep the returned opaque `target_id` and the `tab_id` whose `active` field is
-`true`. Mutation is available only when `binding_quality` is `exact`. A
-heuristic or ambiguous match is refused.
+Keep the returned opaque `target_id`. Use the `tab_id` whose `active` field is
+`true` only when selection is uniquely proven. `active: false` is proven
+unselected; `active: null` means the native window cannot distinguish tabs,
+such as two tabs with the same title. In that case, select an explicit tab by
+its returned metadata and never infer selection from list order. Mutation is
+available only when `binding_quality` is `exact`. A heuristic or ambiguous
+window match is refused.
## Snapshot the tab
@@ -249,6 +253,57 @@ browser_type({
The default `insert_text` mode is efficient for ordinary text. Use
`mode: "keystrokes"` when the page depends on per-character keyboard events.
+## Use extended pointer actions
+
+`browser_pointer` supports `hover`, `right_click`, `double_click`, `scroll`,
+and `drag`. Use the trusted route when genuine browser input semantics are
+required and the platform reports that it can preserve posture. Use the
+explicit synthetic route with current refs when DOM event semantics are
+acceptable:
+
+```jsonc
+browser_pointer({
+ "target_id": "<target_id>",
+ "tab_id": "<tab_id>",
+ "ref": "p3:4",
+ "action": "scroll",
+ "input_route": "dom_event",
+ "delta_y": 240,
+ "session": "research-1"
+})
+```
+
+For drag, pass `destination_ref` from the same exact frame. The driver refuses
+mixed-frame or stale destinations instead of translating them approximately.
+
+## Handle a page-owned dialog
+
+Prime and inspect the exact tab with `browser_dialog({action:"inspect"})`.
+When `present` is true, pass the returned `dialog_id` to `accept` or `dismiss`.
+Only an accepted prompt may include `prompt_text`. This tool does not handle
+browser permission prompts, extension UI, native sheets, or file pickers.
+Creating a Chromium native modal can activate its browser window; once you
+restore the intended occlusion, inspecting and resolving that exact dialog do
+not activate it again.
+
+## Assign files without a picker
+
+Take a semantic snapshot and choose a file-input ref whose `actions` contains
+`upload`. Call `browser_set_input_files` with absolute paths to direct regular
+files. Symlinks, directories, missing paths, and more than 32 files are
+refused. Verify the page's uploaded-file state afterward; the tool response
+contains only a count and never echoes the local paths.
+
+## Download into an approved directory
+
+Choose a current ref that activates the download and call `browser_download`
+through an MCP host that presents its destructive-tool approval. Pass an
+existing canonical absolute `destination_root`. The tool temporarily scopes
+Chromium's browser-wide download behavior, correlates the exact frame and
+opaque download id, restores the default on every outcome, and returns only
+the final byte count and opaque id. It does not return a filename, URL, or
+local path. A direct raw call without host approval is refused.
+
## Navigate
```jsonc
diff --git a/docs/content/docs/reference/cua-driver/browser-semantic-snapshots.mdx b/docs/content/docs/reference/cua-driver/browser-semantic-snapshots.mdx
index 131525af32..74fa8ced16 100644
--- a/docs/content/docs/reference/cua-driver/browser-semantic-snapshots.mdx
+++ b/docs/content/docs/reference/cua-driver/browser-semantic-snapshots.mdx
@@ -97,9 +97,11 @@ Entries in `refs` declare their supported action kinds:
}
```
-`browser_click` and `browser_type` reject a semantic ref when the requested
-action is absent from `actions`, returning `browser_action_unavailable` before
-delivery. Legacy `dom_refs_v1` refs retain their existing behavior.
+The closed action vocabulary is `click`, `type`, and `upload`.
+`browser_click`, `browser_type`, `browser_set_input_files`, and
+`browser_download` reject a semantic ref when the required action is absent,
+returning `browser_action_unavailable` before delivery. A file input declares
+`upload`, not `type`. Legacy `dom_refs_v1` refs retain their existing behavior.
## Content refs
diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
index cc7ce61231..2e3d9be383 100644
--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx
+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx
@@ -12,7 +12,7 @@ description: Reference for every MCP tool Cua Driver exposes
import { Callout } from 'fumadocs-ui/components/callout';
-`cua-driver` exposes 43 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
+`cua-driver` exposes 47 MCP tools through a single stdio server (`cua-driver mcp`). Every tool is also callable from the shell as `cua-driver <name> '<JSON-args>'`.
Tool names are `snake_case`. Responses are MCP `CallTool.Result` envelopes: a text content block prefixed with a `✅` summary (or the error reason on failure), plus optional image or structured-content blocks on tools that produce them. See the [CLI reference](/reference/cua-driver/cli-reference) for CLI-specific options like `--socket` and `--screenshot-out-file`.
@@ -425,7 +425,7 @@ Mapping: by='page' → larger step; by='line' → smaller step; amount = number
- `y` (number, optional): Window-local screenshot Y. See `x`.
```json
-{"direction":"down"}
+{"direction":"up"}
```
### `move_cursor`
@@ -493,7 +493,7 @@ Actions:
- `window_id` (integer, optional): Target window ID from list_windows.
```json
-{"action":"get_text"}
+{"action":"execute_javascript"}
```
## Recording tools
@@ -827,3 +827,76 @@ Type text into an exactly-bound tab via the Input domain. mode="insert_text" (de
```json
{"ref":"example","tab_id":"example","target_id":"example","text":"hello"}
```
+
+### `browser_dialog`
+
+Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. This never handles browser permission UI, extension UI, native dialogs, or file pickers. Inspect returns an opaque dialog_id; accept/dismiss require that exact current id.
+
+**Arguments:**
+
+- `action` (string, required)
+- `dialog_id` (string, optional): Opaque current dialog generation returned by action=inspect.
+- `prompt_text` (string, optional): Sensitive response text, valid only when accepting a prompt dialog.
+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.
+- `tab_id` (string, required): Opaque tab id from get_browser_state (session-scoped).
+- `target_id` (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
+
+```json
+{"action":"inspect","tab_id":"example","target_id":"example"}
+```
+
+### `browser_set_input_files`
+
+Assign one or more explicit absolute local files to an exact live &lt;input type=file&gt; ref through CDP. This bypasses native file pickers, rejects symlinks and non-regular files, and never returns local paths.
+
+**Arguments:**
+
+- `files` (array of string, required)
+- `ref` (string, required): Page element ref in the p&lt;snapshot&gt;:&lt;index&gt; namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.
+- `session` (string, optional): Stable caller-declared session id. Browser targets, tabs, and refs are scoped to this session.
+- `tab_id` (string, required): Opaque tab id from get_browser_state (session-scoped).
+- `target_id` (string, required): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).
+
+```json
+{"files":["example"],"ref":"example","tab_id":"example","target_id":"example"}
+```
+
+### `browser_download`
+
+Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. Requires MCP-host destructive-tool approval, refuses ambiguous or stale capabilities, and never returns the source URL, filename, or destination path.
+
+**Arguments:**
+
+- `destination_root` (string, required): Absolute, existing, canonical directory approved to receive the download.
+- `ref` (string, required): Live page ref whose activation initiates the download.
+- `session` (string, required): Explicit caller session owning the browser capabilities.
+- `tab_id` (string, required): Opaque exact tab id from get_browser_state.
+- `target_id` (string, required): Opaque exact browser target id from get_browser_state.
+
+```json
+{"destination_root":"example","ref":"example","session":"example","tab_id":"example","target_id":"example"}
+```
+
+### `browser_pointer`
+
+Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. The trusted route uses CDP Input events and refuses if standalone background posture cannot be preserved. The explicit dom_event route requires a page ref and synthesizes full-background DOM events. Never activates or brings a tab to the foreground.
+
+**Arguments:**
+
+- `action` (string, required)
+- `delta_x` (number, optional): Horizontal scroll delta in CSS pixels.
+- `delta_y` (number, optional): Vertical scroll delta in CSS pixels.
+- `destination_ref` (string, optional): Drag destination page ref in the exact same frame.
+- `input_route` (string, optional)
+- `ref` (string, optional): Origin page ref. Alternative to x/y.
+- `session` (string, required): Explicit caller session owning the browser capabilities.
+- `tab_id` (string, required): Opaque tab id minted by get_browser_state.
+- `target_id` (string, required): Opaque target id minted by get_browser_state.
+- `to_x` (number, optional): Drag destination viewport x in CSS pixels.
+- `to_y` (number, optional): Drag destination viewport y in CSS pixels.
+- `x` (number, optional): Origin viewport x in CSS pixels.
+- `y` (number, optional): Origin viewport y in CSS pixels.
+
+```json
+{"action":"hover","session":"example","tab_id":"example","target_id":"example"}
+```
diff --git a/docs/content/docs/reference/cua-driver/platform-support.mdx b/docs/content/docs/reference/cua-driver/platform-support.mdx
index c1e347f22d..a57aefd7a3 100644
--- a/docs/content/docs/reference/cua-driver/platform-support.mdx
+++ b/docs/content/docs/reference/cua-driver/platform-support.mdx
@@ -38,9 +38,9 @@ harnesses; an unlisted trust class or host shape is not implied.
| Surface | Proven page routes | Explicit limit |
| --- | --- | --- |
-| Standalone Chrome and Edge on Windows | Snapshot, navigation, ref-bound typing, trusted background click, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Elevated-integrity and unsupported native-host relationships still refuse |
-| Standalone Chrome on macOS | Snapshot, navigation, ref-bound typing, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |
-| Standalone Chrome on Linux X11 | Snapshot, navigation, ref-bound typing, explicit DOM click, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |
+| Standalone Chrome and Edge on Windows | Snapshot, navigation, ref-bound typing, trusted background click, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Elevated-integrity and unsupported native-host relationships still refuse |
+| Standalone Chrome on macOS | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |
+| Standalone Chrome on Linux X11 | Snapshot, navigation, ref-bound typing, explicit DOM click and pointer actions, JavaScript dialogs, file assignment, approved downloads, frames, multi-tab, and exact ambiguity refusal | Trusted CDP pointer input returns `browser_input_trust_unavailable` before dispatch |
| Electron on Windows, macOS, X11, and validated Sway | Typed mutation while one proven native window maps to one CDP page | A second page or native window invalidates the bounded exact route |
| Tauri, WKWebView, WebKitGTK, and common split-process WebView2 | Browser identity plus a side-effect-free structured refusal | No exact native-host-to-engine relationship is currently proven |
| Safari and Firefox | Native discovery and native AX/PX fallbacks | No typed browser mutation engine is currently advertised |
diff --git a/docs/content/docs/reference/cua-driver/telemetry.mdx b/docs/content/docs/reference/cua-driver/telemetry.mdx
index 4344e54bf6..506a0eee80 100644
--- a/docs/content/docs/reference/cua-driver/telemetry.mdx
+++ b/docs/content/docs/reference/cua-driver/telemetry.mdx
@@ -123,7 +123,7 @@ The start event is emitted for a successful `start_session` declaration or the f
The end event is emitted for `end_session` and idle eviction. It contains aggregate counters and booleans. When the platform has a cursor entry for that session, it also includes bounded cursor categories: enabled state, built-in/default/custom icon class, automatic/custom color source, label presence, motion customization, and an active-cursor count bucket. `cursor_outcome_observed=false` distinguishes sessions with no readable cursor entry from a disabled or default cursor. Cua Driver uses the caller session string only as a process-local map key. The string, a hash of it, and a replacement join token are absent from telemetry payloads.
-Computer-action success covers fixed pointer and keyboard capabilities, app launch and kill, window activation, state-changing `page` operations, and successful `browser_navigate`, `browser_click`, and `browser_type` calls. A structured browser refusal does not count as a completed computer action. `get_browser_state` is a read, and `browser_prepare` is tracked as browser use rather than a computer action because preparation may either reuse an endpoint or produce an approved visible side effect.
+Computer-action success covers fixed pointer and keyboard capabilities, app launch and kill, window activation, state-changing `page` operations, and successful browser navigation, click, type, pointer, file-assignment, download, or dialog-resolution calls. A structured browser refusal does not count as a completed computer action. `get_browser_state` and `browser_dialog` inspection are reads for this classifier, and `browser_prepare` is tracked as browser use rather than a computer action because preparation may either reuse an endpoint or produce an approved visible side effect.
The end event includes `used_browser` and a bounded `browser_refusal_count_bucket`. It does not include browser targets, pages, profiles, or per-site information.
@@ -141,6 +141,10 @@ Typed browser tools use these reviewed operation values:
| `browser_prepare` | `browser_prepare_isolated`, `browser_prepare_existing_profile`, or `other` |
| `browser_click` | `browser_click_trusted`, `browser_click_dom_event`, or `other` |
| `browser_type` | `browser_type_insert_text`, `browser_type_keystrokes`, or `other` |
+| `browser_dialog` | `browser_dialog_inspect`, `browser_dialog_accept`, `browser_dialog_dismiss`, or `other` |
+| `browser_set_input_files` | `browser_set_input_files` |
+| `browser_download` | `browser_download` |
+| `browser_pointer` | Action-and-route values such as `browser_pointer_scroll_trusted` or `browser_pointer_drag_dom_event`; invalid combinations become `other` |
| `browser_navigate` | `not_applicable`; the tool name already identifies the operation |
### Structured browser refusals
diff --git a/libs/cua-driver/docs/browser-tool-implementation-journal.md b/libs/cua-driver/docs/browser-tool-implementation-journal.md
index c3f68cd7a3..44325c964a 100644
--- a/libs/cua-driver/docs/browser-tool-implementation-journal.md
+++ b/libs/cua-driver/docs/browser-tool-implementation-journal.md
@@ -6,9 +6,8 @@ URLs, profile paths, and raw DevTools endpoint identifiers.
## Definition of done
-- Add a capability-aware browser API with five typed tools:
- `get_browser_state`, `browser_prepare`, `browser_navigate`, `browser_click`,
- and `browser_type`.
+- Add a capability-aware browser API whose typed tools share one exact target,
+ tab, frame, and ref model.
- Keep `get_browser_state` read-only and make setup explicit.
- Bind native `(pid, window_id)` targets to browser tabs exactly or refuse all
mutation. Never promote a heuristic match into an action route.
@@ -719,3 +718,36 @@ link checks. A source-installed macOS product-path replay passed the real Chrome
semantic row with the TCC-authorized daemon, foreground sentinel, fixture
journal, exact DOM click, re-snapshot, and typed-value oracle. Windows and Linux
X11 exact-SHA workflow evidence is the remaining release-acceptance gate.
+
+## 2026-07-18: browser completeness and adversarial tab state
+
+The bind response no longer labels a representative DevTools target as the
+active native tab. A unique exact native-title match produces one `true` and
+the remaining tabs `false`; duplicate, empty, substring-only, or otherwise
+ambiguous titles produce `null` for every tab. The standalone harness adds a
+same-title adversarial row so future list-order regressions are externally
+visible.
+
+The typed surface now includes page-owned JavaScript dialog inspection and
+resolution, exact file-input assignment, extended pointer actions, and
+approval-scoped downloads. All mutations retain the existing exact binding,
+tab lock, reconnect generation, ref/frame identity, and fail-closed posture.
+Synthetic pointer actions are explicit `dom_event` requests; trusted pointer
+actions never fall back after a refusal. Downloads serialize Chromium's
+browser-wide setting, subscribe before triggering, correlate exact frame and
+opaque id events, restore defaults on every outcome, and remove only a proven
+direct partial file after failure.
+
+The real-browser harness adds separate background rows for dialogs, upload,
+hover/right-click/double-click/scroll/drag, and downloads. A fixed loopback
+attachment keeps download evidence deterministic. Every row uses the
+foreground sentinel and fixture-owned state rather than treating a CDP reply
+as delivery. Trajectory recording redacts prompt text, upload paths, download
+directories, and internal approval markers; product telemetry retains only
+fixed operation and refusal categories.
+
+The dialog design adapts the exact-target, no-replay security model introduced
+in PR #2166. Its contributor remains credited through `Co-authored-by` and
+`Salvaged from #2166` in the adapting commit even though this implementation
+supersedes that earlier code shape. Issue authors remain reporter-attributed
+when the landing PR closes their linked issues.
diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
index 73646a4848..20a6197d78 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md
@@ -20,7 +20,8 @@ list_windows or launch_app
get_browser_state(pid, window_id, session) # bind
get_browser_state(target_id, tab_id, session,
snapshot_format=semantic_v2) # snapshot
-browser_navigate / browser_click / browser_type
+browser_navigate / browser_click / browser_type / browser_pointer
+browser_dialog / browser_set_input_files / browser_download
get_browser_state(target_id, tab_id, session,
snapshot_format=semantic_v2) # verify and refresh refs
end_session
@@ -119,7 +120,10 @@ Never:
## 3. Snapshot the selected tab
-Choose a returned `tab_id`, then request the page snapshot:
+Choose a returned `tab_id`, then request the page snapshot. `active` is
+tri-state: `true` is a uniquely proven selected tab, `false` is a proven
+unselected tab, and `null` means native evidence cannot distinguish the
+selection. Never guess from list order when all tabs are `null`.
```bash
cua-driver get_browser_state \
@@ -240,14 +244,57 @@ ownership, and reports requested versus delivered characters. Snapshot again
to verify application state rather than treating transport completion as the
task result.
+### Extended pointer actions
+
+Use `browser_pointer` for `hover`, `right_click`, `double_click`, `scroll`, and
+`drag`. It uses the same `trusted` versus explicit `dom_event` distinction as
+`browser_click`. The synthetic route requires a current ref; drag also requires
+`destination_ref` in the same proven frame. Coordinate origins and destinations
+are available only where the trusted route can preserve the requested posture.
+
+```bash
+cua-driver browser_pointer \
+ '{"target_id":"<target>","tab_id":"<tab>","ref":"p5:2",
+ "action":"scroll","input_route":"dom_event","delta_y":240,
+ "session":"browser-run-1"}'
+```
+
+### JavaScript dialogs
+
+`browser_dialog` handles only page-owned `alert`, `confirm`, `prompt`, and
+`beforeunload` dialogs. First inspect the exact tab, then accept or dismiss the
+returned opaque `dialog_id`. A prompt response is allowed only with
+`action:"accept"` on a current prompt. Browser permission UI and native dialogs
+remain outside this tool. Creating Chromium's native modal can activate the
+browser; after the caller restores occlusion, inspecting and resolving the
+exact page-owned dialog do not require another activation.
+
+### File inputs
+
+Use a current semantic ref whose `actions` contains `upload`, then call
+`browser_set_input_files` with one to 32 absolute regular-file paths. The tool
+rejects symlinks and directories, bypasses the native file picker, and returns
+only the assigned file count. Paths are redacted from trajectory arguments.
+
+### Downloads
+
+`browser_download` activates one exact ref under a destructive MCP-host
+approval and saves the result under an existing canonical absolute
+`destination_root`. It correlates browser download events to the exact frame,
+serializes Chromium's browser-wide download setting, restores that setting on
+every outcome, and returns only an opaque download id and byte count. It never
+returns the source URL, filename, or destination path. Direct raw calls without
+the host approval proof are refused.
+
## Browser chrome and native fallbacks
The browser tools operate on page content, not the surrounding native UI. Use
the normal native loop for:
- tabs, address bar, menus, bookmarks, and extension UI;
-- permission prompts and remote-debugging consent UI;
-- downloads, save dialogs, authentication sheets, and file pickers;
+- permission prompts, remote-debugging consent UI, and authentication sheets;
+- native save dialogs and file pickers that are not represented by an exact
+ page ref;
- WebView2, WKWebView, WebKitGTK, Tauri, or Electron surfaces that cannot be
exactly correlated to a page target;
- Safari and Firefox, whose typed mutation engines are not yet supported.
diff --git a/scripts/docs-generators/cua-driver.ts b/scripts/docs-generators/cua-driver.ts
index 098486d0ce..59ae169cc3 100644
--- a/scripts/docs-generators/cua-driver.ts
+++ b/scripts/docs-generators/cua-driver.ts
@@ -76,6 +76,8 @@ export interface MCPPropertyDoc {
type: string;
description: string;
items?: { type: string };
+ enum?: string[];
+ minItems?: number;
}
export interface MCPDocumentation {
@@ -773,6 +775,9 @@ function formatPropertyType(prop: MCPPropertyDoc): string {
}
function syntheticExampleValue(name: string, prop: MCPPropertyDoc): unknown {
+ if (prop.enum?.length) {
+ return prop.enum[0];
+ }
switch (prop.type) {
case 'integer':
if (name === 'pid') return 844;
@@ -794,6 +799,7 @@ function syntheticExampleValue(name: string, prop: MCPPropertyDoc): unknown {
case 'array':
if (name === 'keys') return ['cmd', 'c'];
if (name === 'modifiers') return ['cmd'];
+ if (name === 'files' || (prop.minItems ?? 0) > 0) return ['example'];
return [];
case 'string':
if (name === 'text') return 'hello';