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): clarify delivery_mode fallback (#2095)

injaneity422cde0809c0
diff --git a/docs/content/docs/explanation/capture-and-dispatch-modalities.mdx b/docs/content/docs/explanation/capture-and-dispatch-modalities.mdx
index 7f47ec7b4c..4798bd8fc6 100644
--- a/docs/content/docs/explanation/capture-and-dispatch-modalities.mdx
+++ b/docs/content/docs/explanation/capture-and-dispatch-modalities.mdx
@@ -41,7 +41,7 @@ Set per call on the input family (`click`, `double_click`, `right_click`, `drag`
| `background` (default) | Input is routed to the target process/window/element directly. The user's frontmost app, real cursor, and window z-order are untouched. This is the [no-foreground contract](/explanation/the-no-foreground-contract). |
| `foreground` | The target is briefly fronted (pair with `bring_to_front` to avoid a per-call flash), input lands on the now-active window, then the prior frontmost is restored. The explicit last resort when a background attempt did not land — and the only path for apps that accept events solely when foregrounded (DirectInput games, raw-input canvases). |
-Only `background` and `foreground` are valid; the historical `auto` heuristic is removed. Element ax actions (`element_index`) are inherently background — they address an element, not the focused window — so they hold the contract without any `delivery_mode` flag. The dispatch axis matters most for the pixel rung (`x, y`), where `background` routes the event to the target and `foreground` raises the window first.
+Only `background` and `foreground` are valid; the historical `auto` heuristic is removed. At runtime, omitted or unknown values fall back to `background` for safety. Element ax actions (`element_index`) are inherently background — they address an element, not the focused window — so they hold the contract without any `delivery_mode` flag. The dispatch axis matters most for the pixel rung (`x, y`), where `background` routes the event to the target and `foreground` raises the window first.
### 4. Capture scope — what coordinate space the action targets
diff --git a/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx b/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx
index 68b277b15a..6b536e5d8d 100644
--- a/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx
+++ b/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx
@@ -12,7 +12,7 @@ Several parameters are a **shared cross-platform contract**: the same JSON shape
| Parameter | Where | Notes |
| --------- | ----- | ----- |
| `session` | every action and cursor tool | Optional run identity for the agent cursor and per-session state; the same id works over MCP, the CLI, or the raw socket and follows the run across apps and windows. Accepted on all three platforms — earlier Windows and Linux builds rejected it via `additionalProperties:false`. |
-| `delivery_mode` | the input family (`click`, `double_click`, `right_click`, `drag`, `scroll`, `type_text`, `press_key`, `hotkey`) | `"background"` (default) injects without fronting or raising the target — the [no-foreground contract](/explanation/the-no-foreground-contract). `"foreground"` briefly fronts the target, acts, then restores the prior frontmost — the explicit last resort when a background attempt did not land. Legacy `"auto"` is removed. |
+| `delivery_mode` | the input family (`click`, `double_click`, `right_click`, `drag`, `scroll`, `type_text`, `press_key`, `hotkey`) | `"background"` (default) injects without fronting or raising the target — the [no-foreground contract](/explanation/the-no-foreground-contract). `"foreground"` briefly fronts the target, acts, then restores the prior frontmost — the explicit last resort when a background attempt did not land. Legacy `"auto"` is removed; omitted or unknown values fall back to `"background"` for safety. |
| `capture_mode` | `get_window_state` | **Deprecated and ignored.** Still accepted for back-compat so old callers don't error, but it has no effect — `get_window_state` always returns both the accessibility tree and a screenshot by default. There is no `ax`/`vision`/`som` capture choice; the modality (`ax` vs `px`) is chosen at action time by how you address the target. |
| `include_screenshot` | `get_window_state` | Boolean, default `true` (returns the tree **and** a screenshot). Set `false` to skip the screenshot grab and return the tree only — a **perf** opt-out for the cheap re-index-before-an-element-`ax`-action path, not a modality choice. |
| `modifier`, `button`, `element_index`, `element_token` | pointer and element tools | Held modifier keys, mouse button, and the two element-addressing handles. |