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
fix(cua-driver): align agent guidance with lifecycle sessions (#3041)
Francesco Bonaccidbde09e0bfd3
diff --git a/.github/scripts/tests/test_cua_driver_release_wiring.py b/.github/scripts/tests/test_cua_driver_release_wiring.pyindex 10216eb596..d003110e97 100644--- a/.github/scripts/tests/test_cua_driver_release_wiring.py+++ b/.github/scripts/tests/test_cua_driver_release_wiring.py@@ -411,6 +411,33 @@ class TestCuaDriverReleaseWiring(unittest.TestCase):self.assertIn('"args": ["mcp"]', shared_hints)self.assertIn("MCP servers load at startup", shared_hints)+ def test_post_install_hints_use_canonical_capability_manifest_flags(self) -> None:+ shared_hints = self.read("libs/cua-driver/scripts/post-install-hints.txt")++ self.assertIn("--capability-manifest", shared_hints)+ self.assertIn("--approve-capability-manifest", shared_hints)+ self.assertNotIn("--session-policy", shared_hints)+ self.assertNotIn("--approve-session-policy", shared_hints)++ def test_agent_sdk_examples_use_implicit_sessions_and_per_call_targets(self) -> None:+ example_dir = REPO_ROOT / "libs/cua-driver/examples/agent-sdks"+ examples = "\n".join(+ path.read_text()+ for path in example_dir.iterdir()+ if path.suffix in {".py", ".ts", ".md"}+ )++ for forbidden in [+ "CUA_CAPTURE_SCOPE",+ "StartSessionInput",+ "CaptureScope",+ "capture_scope",+ ]:+ self.assertNotIn(forbidden, examples)+ self.assertIn("implicit lifecycle session", examples)+ self.assertIn("ActionTarget.DESKTOP", examples)+ self.assertIn("new ActionTarget.Desktop", examples)+def test_local_macos_signing_uses_an_unambiguous_identity_hash(self) -> None:signing = self.read("libs/cua-driver/scripts/_local-signing.sh")diff --git a/.github/workflows/ci-cua-driver-contract-clients.yml b/.github/workflows/ci-cua-driver-contract-clients.ymlindex a07f6acfb0..e68649be98 100644--- a/.github/workflows/ci-cua-driver-contract-clients.yml+++ b/.github/workflows/ci-cua-driver-contract-clients.yml@@ -323,7 +323,11 @@ jobs:- name: Install Python agent SDK example dependenciesworking-directory: libs/cua-driver/examples/agent-sdks- run: python -m pip install -r requirements.txt+ run: |+ python -m pip install -r requirements.txt+ # Exercise the examples against this PR's candidate SDK contract,+ # not the previously published package with the same source version.+ python -m pip install --force-reinstall /tmp/cua-driver-wheels/*.whl- name: Check Python agent SDK examples and fixtureworking-directory: libs/cua-driver/examples/agent-sdks@@ -336,7 +340,11 @@ jobs:- name: Install agent SDK example dependenciesworking-directory: libs/cua-driver/examples/agent-sdks- run: npm ci+ run: |+ npm ci+ VERSION=$(node -p "require('../../typescript/package.json').version")+ npm install --no-save \+ "/tmp/cua-driver-npm/trycua-cua-driver-$VERSION.tgz"- name: Check TypeScript agent SDK exampleworking-directory: libs/cua-driver/examples/agent-sdksdiff --git a/blog/extension-free-browser-use.md b/blog/extension-free-browser-use.mdindex f4a9dbf18f..e1e345cefc 100644--- a/blog/extension-free-browser-use.md+++ b/blog/extension-free-browser-use.md@@ -86,8 +86,7 @@ Attaching an existing signed-in Chrome or Edge profile is more sensitive. A stanFor unattended work, [bounded mode](https://cua.ai/docs/how-to-guides/driver/write-a-bounded-manifest) is the recommended path. A reviewed manifest can allow an existing profile while restricting tools, apps, origins, and files. For example:```yaml-version: 2-mode: bounded+version: 3expires_after: 8hidle_timeout: 30m@@ -117,7 +116,7 @@ resources:display: false```-Start it with `cua-driver serve --permission-mode bounded --session-policy ./cua-session.yaml --approve-session-policy`. The example uses Chrome's macOS bundle id; Windows and Linux use its canonical absolute executable path. Generic desktop input is deliberately omitted because it could bypass the origin restriction.+Start it with `cua-driver serve --permission-mode bounded --capability-manifest ./cua-capability-manifest.yaml --approve-capability-manifest`. The example uses Chrome's macOS bundle id; Windows and Linux use its canonical absolute executable path. Generic desktop input is deliberately omitted because it could bypass the origin restriction.Users who explicitly accept the risk can choose [unrestricted mode](https://cua.ai/docs/reference/cua-driver/permission-modes) with `cua-driver serve --dangerously-bypass-approvals`. That bypasses Cua approval checks after launch-time acknowledgement, so it should not be the default for a personal browser.diff --git a/docs/content/docs/how-to-guides/driver/use-claude-agent-sdk.mdx b/docs/content/docs/how-to-guides/driver/use-claude-agent-sdk.mdxindex c242bf7d24..a06a44e4f6 100644--- a/docs/content/docs/how-to-guides/driver/use-claude-agent-sdk.mdx+++ b/docs/content/docs/how-to-guides/driver/use-claude-agent-sdk.mdx@@ -81,8 +81,7 @@ Install Cua Driver so `cua-driver` is on `PATH`, then run:<Tab value="Python">```bash-CUA_CAPTURE_SCOPE=auto \- .venv/bin/python claude_agent.py --route mcp \+.venv/bin/python claude_agent.py --route mcp \"Inspect the active app and summarize what is visible"```@@ -90,17 +89,18 @@ CUA_CAPTURE_SCOPE=auto \<Tab value="TypeScript">```bash-CUA_CAPTURE_SCOPE=auto \- npm run claude -- --route mcp \+npm run claude -- --route mcp \"Inspect the active app and summarize what is visible"```</Tab></Tabs>-The host creates the Cua session, supplies `cua-driver mcp` to Claude, and ends-the session in `finally`. Claude discovers the full live MCP surface; the-generated Cua language packages are not acting as MCP clients.+The host supplies one long-lived `cua-driver mcp` transport to Claude. The+first admitted stateful call creates its implicit session, later unnamed calls+reuse it, and transport shutdown runs lifecycle cleanup. Claude discovers the+full live MCP surface; the generated Cua language packages are not acting as+MCP clients.Use only trusted tasks with these examples. They remove interactive approvalprompts and deliberately exclude Claude Code's built-in shell and file tools.diff --git a/docs/content/docs/how-to-guides/driver/use-codex-sdk.mdx b/docs/content/docs/how-to-guides/driver/use-codex-sdk.mdxindex 2f910cac73..6afd088ebe 100644--- a/docs/content/docs/how-to-guides/driver/use-codex-sdk.mdx+++ b/docs/content/docs/how-to-guides/driver/use-codex-sdk.mdx@@ -44,8 +44,7 @@ Install Cua Driver so `cua-driver` is on `PATH`, or set<Tab value="Python">```bash-CUA_CAPTURE_SCOPE=window \- .venv/bin/python codex_agent.py \+.venv/bin/python codex_agent.py \"Inspect the active app and summarize what is visible without changing it"```@@ -53,8 +52,7 @@ CUA_CAPTURE_SCOPE=window \<Tab value="TypeScript">```bash-CUA_CAPTURE_SCOPE=window \- npm run codex -- \+npm run codex -- \"Inspect the active app and summarize what is visible without changing it"```@@ -67,11 +65,11 @@ The complete scripts live atBoth scripts:-1. start a uniquely named Cua session outside Codex;-2. mark the Cua MCP server required;+1. create one required, long-lived Cua MCP transport;+2. let the first admitted stateful call create its implicit session;3. run Codex in a read-only filesystem sandbox;4. instruct Codex to use only Cua tools for desktop work; and-5. end the session in `finally`.+5. rely on transport shutdown to run session cleanup.The filesystem sandbox does not sandbox the separate desktop MCP server.Restrict the task itself, choose an exact window or desktop target for each Cuadiff --git a/docs/content/docs/reference/cua-driver/contracts.mdx b/docs/content/docs/reference/cua-driver/contracts.mdxindex 653b7dc67f..e03c6c6cf7 100644--- a/docs/content/docs/reference/cua-driver/contracts.mdx+++ b/docs/content/docs/reference/cua-driver/contracts.mdx@@ -47,7 +47,12 @@ visibility only. A call in flight cannot expire, and a completed call refreshesthe lifecycle timer once. Transport close, explicit end, revocation, and idleexpiry use the same cleanup hooks.-Use `start_session` for an optional public name or initial cursor theme.+For multi-call work, prefer a short public `session` label and pass the same+value on every call that accepts it. Passing it once is not sticky: a later call+that omits the field uses the transport's implicit session instead. Use+`start_session` to name or configure a run before acting, or to revive a public+name after it has ended. For one-off or deliberately unlabeled work, omitting+`session` is valid.`get_session` reads one visible session, and `list_sessions` returns content-freesummaries scoped to the caller's transport. Trusted host code has a separateoperator listing. `get_session_state` and `escalate_session` remain deprecateddiff --git a/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx b/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdxindex 8105c8d872..853c57d285 100644--- a/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tool-notes.mdx@@ -11,7 +11,7 @@ Several parameters are a **shared cross-platform contract**: the same JSON shape| Parameter | Where | Notes || --------- | ----- | ----- |-| `session` | every action and cursor tool | Optional public run label. The runtime creates one private implicit session per authenticated transport when this field is absent, then reuses it for later calls on that transport. A public label is never caller identity or authorization evidence. Accepted on all three platforms. |+| `session` | every action and cursor tool | Optional public run label. For multi-call work, prefer a short label and repeat it on every call that accepts it; it is not sticky. When this field is absent, the call uses the authenticated transport's private implicit session. A public label is never caller identity or authorization evidence. Accepted on all three platforms. || `target` | `move_cursor`, `click`, `drag`, `scroll`, `type_text`, `press_key`, `hotkey` | Preferred tagged per-call target: `{kind:"window", pid, window_id}` or `{kind:"desktop", display_id:"primary"}`. It cannot be combined with legacy `scope`, `pid`, or `window_id` fields. || `delivery_mode` | the input family (`click`, `double_click`, `right_click`, `drag`, `scroll`, `type_text`, `press_key`, `hotkey`) | `"background"` (default) tries to inject without fronting or raising the target. See [Best-effort background](/concepts/the-no-foreground-contract). `"foreground"` briefly fronts the target, acts, then restores the prior frontmost. Use it 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 do not 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. |diff --git a/docs/content/docs/reference/cua-driver/mcp-tools.mdx b/docs/content/docs/reference/cua-driver/mcp-tools.mdxindex 5abbef0296..ef3a8f7d38 100644--- a/docs/content/docs/reference/cua-driver/mcp-tools.mdx+++ b/docs/content/docs/reference/cua-driver/mcp-tools.mdx@@ -80,7 +80,7 @@ Optional `max_elements` / `max_depth` bound the AX walk to mitigate context-wind- `pid` (integer, required): Target process ID.- `query` (string, optional): Case-insensitive filter for tree_markdown and structured elements. Returns matching actionable rows plus their actionable ancestors without renumbering element_index values.- `screenshot_out_file` (string, optional): When set, write the PNG to this file path (~ expanded) instead of embedding base64 in the response. The structured output will contain screenshot_file_path instead.-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `window_id` (integer, required): Target window ID from list_windows.```json@@ -102,7 +102,7 @@ Capture the full display in true screen pixels with no downscale. Use its native**Arguments:**- `screenshot_out_file` (string, optional): Write PNG here instead of base64.-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.### `get_screen_size`@@ -110,7 +110,7 @@ Return the logical size of the main display in points plus its backing scale fac**Arguments:**-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.### `get_cursor_position`@@ -118,7 +118,7 @@ Return the current mouse cursor position in screen points (origin top-left).**Arguments:**-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.### `get_config`@@ -208,7 +208,8 @@ Set one exact top-level window's frame in the desktop-coordinate space reported- `height` (number, required): range: 1–unbounded- `pid` (integer, required): range: 1–unbounded-- `session` (string, optional): Optional session id.+- `session` (string, optional): 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.- `width` (number, required): range: 1–unbounded- `window_id` (integer, required): range: 1–unbounded- `x` (number, required)@@ -245,7 +246,7 @@ from_zoom: set true after a zoom call to auto-translate zoom-image pixel coordin- `modifier` (array of string, optional): Modifier keys: cmd, shift, option/alt, ctrl.- `pid` (integer, optional): Target process ID.- `scope` (string, optional): Coordinate frame for a windowless screen-absolute click (default "window"). Pass "desktop" when sending x,y with NO pid/window_id — the coordinates are then true screen pixels (read from get_desktop_state with scope="desktop"). Per-call; not a setting.-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.@@ -270,7 +271,7 @@ Pixel path (x, y provided): two down/up pairs ~80 ms apart at the given coordina- `element_index` (integer, optional): Element index from get_window_state. Cua Driver 0.17 requires the matching `snapshot_id` alongside it. Prefer `element_token`, which carries both values.- `element_token` (string, optional): Opaque per-snapshot element handle from `structuredContent.elements[].element_token`. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.- `pid` (integer, required)-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `window_id` (integer, optional): CGWindowID. Required when element_index is used. Optional when element_token is supplied (the token carries it).- `x` (number, optional): Screen X coordinate (pixel path).@@ -297,7 +298,7 @@ Exactly one of `element_index` or (`x` AND `y`) must be provided. `pid` always r- `element_token` (string, optional): Opaque per-snapshot element handle from `structuredContent.elements[].element_token`. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.- `modifier` (array of string, optional): Modifier keys held during the right-click: cmd/shift/option/ctrl. Pixel path only.- `pid` (integer, required): Target process ID.-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `window_id` (integer, optional): CGWindowID. Required when element_index is used. Optional when element_token is supplied (the token carries it).- `x` (number, optional): X in window-local screenshot pixels. Must be provided together with y.@@ -330,7 +331,7 @@ When `from_zoom` is true, coordinates are in the last zoom image for this pid; t- `modifier` (array of string, optional): Modifier keys held across the entire gesture: cmd/shift/option/ctrl.- `pid` (integer, optional): Target process ID.- `scope` (string, optional): Use desktop with no pid/window_id for native get_desktop_state screenshot coordinates. default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `steps` (integer, optional): Number of intermediate mouseDragged events linearly interpolated along the path. Default: 20. range: 1–200- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.@@ -361,7 +362,7 @@ WEB CONTENT (Chromium/WebKit/Electron — browser tabs, Slack, VS Code, X's comp- `element_token` (string, optional): Opaque per-snapshot element handle from `structuredContent.elements[].element_token`. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.- `pid` (integer, optional): Target process ID.- `scope` (string, optional): Use desktop with no pid/window_id to type into the frontmost application. default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.@@ -394,7 +395,7 @@ A key press is confirmed only when a bounded native AX value/selection read-back- `modifiers` (array of string, optional): Modifier keys: cmd, shift, option/alt, ctrl, fn.- `pid` (integer, optional)- `scope` (string, optional): Use desktop with no pid/window_id to send the key to the frontmost application. default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.@@ -425,7 +426,7 @@ Recognized modifiers: cmd/command, shift, option/alt, ctrl/control, fn. Non-modi- `keys` (array of string, required): Modifier(s) and one non-modifier key, e.g. ["cmd", "c"]. items: 2–unbounded- `pid` (integer, optional): Target process ID.- `scope` (string, optional): Use desktop with no pid/window_id to send the chord to the frontmost application. default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.`display_id="primary"` is the portable desktop target in this release.@@ -454,7 +455,7 @@ For free-form text entry into web inputs, prefer `type_text_chars` which synthes- `element_index` (integer, optional): Element index from get_window_state. Cua Driver 0.17 requires the matching `snapshot_id` alongside it. Prefer `element_token`, which carries both values.- `element_token` (string, optional): Opaque per-snapshot element handle from `structuredContent.elements[].element_token`. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.- `pid` (integer, required)-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `value` (string, required): New value. AX will coerce to the element's native type.- `window_id` (integer, optional): CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used; optional when element_token is supplied (the token carries it).@@ -483,7 +484,7 @@ Mapping: by='page' → larger step; by='line' → smaller step; amount = number- `element_token` (string, optional): Opaque per-snapshot element handle from `structuredContent.elements[].element_token`. If element_index, snapshot_id, or window_id are also supplied they must agree. Returns an explicit stale error once a newer snapshot supersedes it.- `pid` (integer, optional)- `scope` (string, optional): Use desktop with x,y and no pid/window_id for native get_desktop_state screenshot coordinates. default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `snapshot_id` (string, optional): Snapshot handle from get_window_state. Required when targeting by element_index; stale snapshots fail closed.- `target` (window target or desktop target, optional): Exact capture/input target selected independently for each action.@@ -506,7 +507,7 @@ Move a cursor to (x, y). In window scope (default), moves only the agent cursor- `cursor_id` (string, optional): Cursor instance to move. Default: 'default'.- `scope` (string, optional): default: `"window"`-- `session` (string, optional): Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session.+- `session` (string, optional): 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.- `target` (window target or desktop target, optional): Preferred per-call target. New callers should set this field.- `x` (number, required)- `y` (number, required)@@ -578,7 +579,8 @@ List available system clipboard types and optionally return privacy-sensitive pl- `include_text` (boolean, optional): Return plain-text clipboard content in addition to the available types.Clipboard content is privacy-sensitive and is never retained in telemetry. default: `false`-- `session` (string, optional): Optional session id.+- `session` (string, optional): 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.### `clipboard_write`@@ -588,7 +590,8 @@ Replace the system clipboard with exactly one value: plain text, an image from a- `file_path` (string, optional): Absolute path to a local file to place on the clipboard as a file URL.- `image_path` (string, optional): Absolute path to a local image to place on the clipboard.-- `session` (string, optional): Optional session id.+- `session` (string, optional): 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.- `text` (string, optional): Plain text to place on the clipboard.## Recording tools@@ -669,7 +672,7 @@ Note: capture_mode is a per-call param (on get_window_state / click), not a stor### `start_session`-Optionally name and start a lifecycle session for this agent run. When `session` is omitted, create or return the authenticated transport lease's implicit session. Ordinary actions create that implicit session automatically, so this tool is optional. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.+Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public `session` label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.**Arguments:**@@ -813,8 +816,9 @@ Deterministically verify bounded predicates against one exact window. The driver- `include_screenshot` (boolean or null, optional): Return the final window screenshot as image content for a multimodalcaller. The driver does not interpret that image.- `pid` (integer, required): Exact process whose window may be observed. range: 1–unbounded-- `session` (string, optional): Optional public session label for lifecycle continuity. It never selects-capture modality or authorization.+- `session` (string, optional): 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. This+field never selects capture modality or authorization.- `stable_samples` (integer, optional): Consecutive satisfied samples required before returning success. default: `2`; range: 1–5- `timeout_ms` (integer, optional): Bounded wait. Zero performs one sample. default: `5000`; range: 0–10000- `window_id` (integer, required): Exact native window identifier.@@ -831,7 +835,8 @@ Resolve an exact application-menu path one live native level at a time and invok- `path` (array of string, required): items: 1–16- `pid` (integer, required): range: 1–unbounded-- `session` (string, optional): Optional session id.+- `session` (string, optional): 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.- `window_id` (integer, required): range: 1–unbounded```json@@ -863,7 +868,7 @@ Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native br- `pid` (integer, optional): Native browser process id (bind mode).- `query` (string, optional): Read-only semantic match over role, accessible name, and visible text.- `scope_ref` (string, optional): Current semantic/content ref whose subtree should be observed.-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle session.- `snapshot_format` (string, optional): Versioned snapshot contract. dom_refs_v1 remains the compatibility default.- `tab_id` (string, optional): Opaque tab id from get_browser_state (session-scoped).- `target_id` (string, optional): Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id).@@ -879,7 +884,7 @@ Explicitly prepare an owned DevTools endpoint for a browser pid. Existing endpoi- `approval_token` (string, optional): Legacy single-use setup token. Existing-profile use is disabled unless a trusted launcher explicitly enables the same-user-writable compatibility path.- `pid` (integer, required): Browser process id to prepare.- `profile` (object, optional)-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle session.- `strategy` (object, optional)- `window_id` (integer, optional): Exact native window approval anchor; required for strategy.kind=existing_profile.@@ -893,7 +898,7 @@ Navigate one tab of an exactly-bound browser target to a new URL (http/https/abo**Arguments:**-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle 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).- `url` (string, required): Destination URL (http:, https:, or about:).@@ -910,7 +915,7 @@ Click a page element (by ref) or viewport coordinates in an exactly-bound tab. D- `input_route` (string, optional): "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested. Dispatch does not prove the control activated; refresh page state and verify the expected postcondition.- `ref` (string, optional): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle 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).- `x` (number, optional): Viewport x (CSS px) — alternative to ref.@@ -929,7 +934,7 @@ Type text into an exactly-bound tab via the Input domain. mode="insert_text" (de- `mode` (string, optional): insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent.- `ref` (string, required): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.- `replace` (boolean, optional): false (default): insert at the caret, appending to whatever the field already holds. true: select the element's whole content first so the text replaces it — with an empty text this clears the field. Replacement goes through the selection, so beforeinput/input still fire and framework state stays consistent.-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle 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).- `text` (string, required): Text to type.@@ -948,7 +953,7 @@ Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunlo- `delivery_mode` (string, optional): Requested foreground posture for accept/dismiss. Linux Chromium requires foreground; inspect is read-only. default: `"background"`- `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): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle 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).@@ -964,7 +969,7 @@ Assign one or more explicit absolute local files to an exact live <input type- `files` (array of string, required): items: 1–32- `ref` (string, required): Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab.-- `session` (string, optional): Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted.+- `session` (string, optional): 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. Browser targets, tabs, and refs belong to the resolved lifecycle 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).@@ -980,7 +985,7 @@ Trigger one download through an exact live browser ref and save it inside an exp- `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.+- `session` (string, required): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs.- `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.@@ -1000,7 +1005,7 @@ Perform hover, right-click, double-click, scroll, or drag in an exactly-bound br- `destination_ref` (string, optional): Drag destination page ref in the exact same frame.- `input_route` (string, optional): default: `"trusted"`- `ref` (string, optional): Origin page ref. Alternative to x/y.-- `session` (string, required): Explicit caller session owning the browser capabilities.+- `session` (string, required): For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs.- `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.diff --git a/docs/content/docs/reference/cua-driver/sdk-reference.mdx b/docs/content/docs/reference/cua-driver/sdk-reference.mdxindex 2e7da0f8ea..b784910ece 100644--- a/docs/content/docs/reference/cua-driver/sdk-reference.mdx+++ b/docs/content/docs/reference/cua-driver/sdk-reference.mdx@@ -181,7 +181,12 @@ The default idle TTL is five minutes. Shutdown, explicit end, and transportclose run the same cleanup hooks. A call that is still in flight cannot expire,and only completed calls refresh the idle timer.-Use `start_session` when the run needs a public label or initial cursor theme.+For multi-call work, prefer a short public `session` label and pass the same+value on every call that accepts it. Passing it once is not sticky: a later call+that omits the field uses the transport's implicit session instead. Use+`start_session` to name or configure a run before acting, or to revive a public+name after it has ended. For one-off or deliberately unlabeled work, omitting+`session` is valid.`get_session` and `list_sessions` return content-free state only for sessionsvisible to that transport. The public label is a map key, never anauthorization credential. A trusted host can inspect its wider runtimediff --git a/libs/cua-driver/contract/manifest.json b/libs/cua-driver/contract/manifest.jsonindex de33a718c4..9965f5f455 100644--- a/libs/cua-driver/contract/manifest.json+++ b/libs/cua-driver/contract/manifest.json@@ -51,7 +51,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -267,7 +267,7 @@"type": "boolean"},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"}},@@ -350,7 +350,7 @@"type": "string"},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"text": {@@ -447,7 +447,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"steps": {@@ -1050,7 +1050,7 @@"additionalProperties": false,"properties": {"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"}},@@ -1106,7 +1106,7 @@"type": "string"},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"}},@@ -1187,7 +1187,7 @@"additionalProperties": false,"properties": {"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"}},@@ -1451,7 +1451,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -1670,7 +1670,7 @@"type": "integer"},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"window_id": {@@ -1966,7 +1966,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -2191,7 +2191,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -2420,7 +2420,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -2947,7 +2947,7 @@"type": "integer"},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"width": {@@ -3092,7 +3092,7 @@},{"name": "start_session",- "description": "Optionally name and start a lifecycle session for this agent run. When `session` is omitted, create or return the authenticated transport lease's implicit session. Ordinary actions create that implicit session automatically, so this tool is optional. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.",+ "description": "Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public `session` label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.","platforms": ["macos","windows",@@ -3258,7 +3258,7 @@"description": "Deprecated flat desktop target retained for wire compatibility."},"session": {- "description": "Optional session id.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session.","type": "string"},"target": {@@ -3588,7 +3588,7 @@"type": "integer"},"session": {- "description": "Optional public session label for lifecycle continuity. It never selects\ncapture modality or authorization.",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that\naccepts it. Omit it to use the authenticated transport's implicit lifecycle session. This\nfield never selects capture modality or authorization.","type": "string"},"stable_samples": {diff --git a/libs/cua-driver/examples/agent-sdks/README.md b/libs/cua-driver/examples/agent-sdks/README.mdindex 51fed908ec..fc2f14d738 100644--- a/libs/cua-driver/examples/agent-sdks/README.md+++ b/libs/cua-driver/examples/agent-sdks/README.md@@ -86,13 +86,16 @@ npm run codex -- \"Inspect the active app and summarize what is visible without changing it"```-Set `CODEX_MODEL` optionally. Both scripts create a unique Cua session outside-the agent, configure `cua-driver mcp`, and end the session in `finally`.+Set `CODEX_MODEL` optionally. Both scripts configure one long-lived+`cua-driver mcp` transport. Its first admitted stateful call creates an+implicit session, later unnamed calls reuse it, and transport shutdown runs+the same cleanup as an explicit `end_session`.## Environment and safety- Put `cua-driver` on `PATH`, or set `CUA_DRIVER_BIN` for MCP examples.-- Set `CUA_CAPTURE_SCOPE` to `auto`, `window`, or `desktop` for MCP examples.+- Select an exact window or desktop target on each action. Sessions do not+ store capture modality.- Authenticate the chosen agent SDK using its normal local login or API key.- Run only trusted tasks. These examples remove interactive approval prompts.- Keep purchases, messages, deletion, credential entry, and other irreversiblediff --git a/libs/cua-driver/examples/agent-sdks/claude_agent.py b/libs/cua-driver/examples/agent-sdks/claude_agent.pyindex 245d89aecd..d3519e6081 100644--- a/libs/cua-driver/examples/agent-sdks/claude_agent.py+++ b/libs/cua-driver/examples/agent-sdks/claude_agent.py@@ -4,12 +4,10 @@ from __future__ import annotationsimport argparseimport asyncio-import jsonimport osimport shutilfrom pathlib import Path-from typing import Literal, cast-from uuid import uuid4+from typing import Literalfrom claude_agent_sdk import (ClaudeAgentOptions,@@ -21,7 +19,6 @@ from claude_agent_sdk import (from native_tools import NativeDesktopTools-CaptureScope = Literal["auto", "window", "desktop"]Route = Literal["native", "mcp"]@@ -47,45 +44,20 @@ def driver_binary() -> str:raise RuntimeError("cua-driver is not on PATH; set CUA_DRIVER_BIN")-def capture_scope() -> CaptureScope:- value = os.environ.get("CUA_CAPTURE_SCOPE", "auto")- if value not in {"auto", "window", "desktop"}:- raise ValueError("CUA_CAPTURE_SCOPE must be auto, window, or desktop")- return cast(CaptureScope, value)---async def driver_call(binary: str, name: str, arguments: dict[str, str]) -> None:- process = await asyncio.create_subprocess_exec(- binary,- "call",- name,- json.dumps(arguments),- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- )- try:- stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=30)- except TimeoutError:- process.kill()- await process.wait()- raise RuntimeError(f"cua-driver call {name} timed out") from None- if process.returncode != 0:- detail = stderr.decode().strip() or stdout.decode().strip()- raise RuntimeError(f"cua-driver call {name} failed: {detail}")---def prompt(task: str, route: Route, session: str | None = None) -> str:+def prompt(task: str, route: Route) -> str:lifecycle = (- f"The host already started session {session!r}. Pass it to every Cua "- "tool that accepts a session; do not call start_session or end_session."- if session- else "The host owns the native driver session; the custom tools do not expose lifecycle."+ "The MCP transport owns one implicit lifecycle session. Omit the session "+ "field for ordinary calls so the runtime creates and reuses it."+ if route == "mcp"+ else "The native SDK client owns one implicit lifecycle session; custom "+ "tools do not expose lifecycle.")return f"""Complete this trusted desktop task through Cua Driver:{task}-Route: {route}. {lifecycle}+Route: {route}. {lifecycle} Select an exact window or desktop target for every+action; session identity never selects capture modality or permission authority.Use only the supplied Cua tools for desktop observation and interaction. Inspectstate before each action and verify state after it. A timeout after a mutationmeans the outcome is unknown: observe before retrying and never blindly replay.@@ -152,7 +124,6 @@ async def run_agent(options: ClaudeAgentOptions, task_prompt: str) -> None:async def run_native(task: str) -> None:runtime = NativeDesktopTools()try:- await runtime.start()options = ClaudeAgentOptions(model=os.environ.get("CLAUDE_MODEL"),cwd=Path.cwd(),@@ -175,38 +146,25 @@ async def run_native(task: str) -> None:async def run_mcp(task: str) -> None:binary = driver_binary()- scope = capture_scope()- session = f"claude-mcp-{uuid4().hex[:12]}"- started = False- try:- await driver_call(- binary,- "start_session",- {"session": session, "capture_scope": scope},- )- started = True- options = ClaudeAgentOptions(- model=os.environ.get("CLAUDE_MODEL"),- cwd=Path.cwd(),- tools=[],- mcp_servers={- "cua_driver": {- "type": "stdio",- "command": binary,- "args": ["mcp"],- }- },- strict_mcp_config=True,- # Claude's MCP allowlist accepts the server name to enable all- # tools from that server; wildcard tool-name globs are unsupported.- allowed_tools=["mcp__cua_driver"],- permission_mode="dontAsk",- max_turns=40,- )- await run_agent(options, prompt(task, "mcp", session))- finally:- if started:- await driver_call(binary, "end_session", {"session": session})+ options = ClaudeAgentOptions(+ model=os.environ.get("CLAUDE_MODEL"),+ cwd=Path.cwd(),+ tools=[],+ mcp_servers={+ "cua_driver": {+ "type": "stdio",+ "command": binary,+ "args": ["mcp"],+ }+ },+ strict_mcp_config=True,+ # Claude's MCP allowlist accepts the server name to enable all+ # tools from that server; wildcard tool-name globs are unsupported.+ allowed_tools=["mcp__cua_driver"],+ permission_mode="dontAsk",+ max_turns=40,+ )+ await run_agent(options, prompt(task, "mcp"))async def main() -> None:diff --git a/libs/cua-driver/examples/agent-sdks/claude_agent.ts b/libs/cua-driver/examples/agent-sdks/claude_agent.tsindex 0335851a6a..6512ea30ea 100644--- a/libs/cua-driver/examples/agent-sdks/claude_agent.ts+++ b/libs/cua-driver/examples/agent-sdks/claude_agent.ts@@ -1,9 +1,5 @@/** Run a Claude Agent SDK desktop task through native Cua tools or MCP. */-import { execFile } from 'node:child_process';-import { randomUUID } from 'node:crypto';-import { promisify } from 'node:util';-import {createSdkMcpServer,query,@@ -16,9 +12,6 @@ import { z } from 'zod';import { NativeDesktopTools } from './native-tools.js';type Route = 'native' | 'mcp';-type CaptureScope = 'auto' | 'window' | 'desktop';--const execFileAsync = promisify(execFile);function argumentsFromCli(): { route: Route; task: string } {const args = process.argv.slice(2);@@ -37,22 +30,6 @@ function argumentsFromCli(): { route: Route; task: string } {return { route, task };}-function captureScope(): CaptureScope {- const value = process.env.CUA_CAPTURE_SCOPE ?? 'auto';- if (value !== 'auto' && value !== 'window' && value !== 'desktop') {- throw new Error('CUA_CAPTURE_SCOPE must be auto, window, or desktop');- }- return value;-}--async function driverCall(- binary: string,- name: string,- args: Record<string, string>-): Promise<void> {- await execFileAsync(binary, ['call', name, JSON.stringify(args)], { timeout: 30_000 });-}-async function runAgent(options: Options, prompt: string): Promise<void> {let result: SDKResultMessage | undefined;for await (const message of query({ prompt, options })) {@@ -98,15 +75,17 @@ function nativeServer(runtime: NativeDesktopTools) {});}-function taskPrompt(task: string, route: Route, session?: string): string {- const lifecycle = session- ? `The host already started session ${JSON.stringify(session)}. Pass it to every Cua tool that accepts a session; do not call start_session or end_session.`- : 'The host owns the native driver session; custom tools do not expose lifecycle.';+function taskPrompt(task: string, route: Route): string {+ const lifecycle =+ route === 'mcp'+ ? 'The MCP transport owns one implicit lifecycle session. Omit the session field for ordinary calls so the runtime creates and reuses it.'+ : 'The native SDK client owns one implicit lifecycle session; custom tools do not expose lifecycle.';return `Complete this trusted desktop task through Cua Driver:${task}-Route: ${route}. ${lifecycle}+Route: ${route}. ${lifecycle} Select an exact window or desktop target for every+action; session identity never selects capture modality or permission authority.Use only supplied Cua tools for desktop observation and interaction. Inspectbefore each action and verify afterward. If a mutation times out, observe beforeany retry; never blindly replay an action with an unknown outcome. Do not@@ -117,7 +96,6 @@ action unless the task explicitly requests it. Name anything unverified.`;async function runNative(task: string): Promise<void> {const runtime = new NativeDesktopTools();try {- await runtime.start();await runAgent({model: process.env.CLAUDE_MODEL,@@ -142,31 +120,22 @@ async function runNative(task: string): Promise<void> {async function runMcp(task: string): Promise<void> {const binary = process.env.CUA_DRIVER_BIN ?? 'cua-driver';- const scope = captureScope();- const session = `claude-mcp-${randomUUID().slice(0, 12)}`;- let started = false;- try {- await driverCall(binary, 'start_session', { session, capture_scope: scope });- started = true;- await runAgent(- {- model: process.env.CLAUDE_MODEL,- tools: [],- mcpServers: {- cua_driver: { type: 'stdio', command: binary, args: ['mcp'] },- },- strictMcpConfig: true,- // A bare MCP server name enables all of its tools. Claude does not- // support wildcard tool-name globs in this allowlist.- allowedTools: ['mcp__cua_driver'],- permissionMode: 'dontAsk',- maxTurns: 40,+ await runAgent(+ {+ model: process.env.CLAUDE_MODEL,+ tools: [],+ mcpServers: {+ cua_driver: { type: 'stdio', command: binary, args: ['mcp'] },},- taskPrompt(task, 'mcp', session)- );- } finally {- if (started) await driverCall(binary, 'end_session', { session });- }+ strictMcpConfig: true,+ // A bare MCP server name enables all of its tools. Claude does not+ // support wildcard tool-name globs in this allowlist.+ allowedTools: ['mcp__cua_driver'],+ permissionMode: 'dontAsk',+ maxTurns: 40,+ },+ taskPrompt(task, 'mcp')+ );}const args = argumentsFromCli();diff --git a/libs/cua-driver/examples/agent-sdks/codex_agent.py b/libs/cua-driver/examples/agent-sdks/codex_agent.pyindex 28b373daa0..7473e1c08f 100644--- a/libs/cua-driver/examples/agent-sdks/codex_agent.py+++ b/libs/cua-driver/examples/agent-sdks/codex_agent.py@@ -7,13 +7,9 @@ import asyncioimport jsonimport osimport shutil-from typing import Literal, cast-from uuid import uuid4from openai_codex import AsyncCodex, CodexConfig, Sandbox-CaptureScope = Literal["auto", "window", "desktop"]-def parse_args() -> argparse.Namespace:parser = argparse.ArgumentParser(description=__doc__)@@ -31,76 +27,37 @@ def driver_binary() -> str:raise RuntimeError("cua-driver is not on PATH; set CUA_DRIVER_BIN")-def capture_scope() -> CaptureScope:- value = os.environ.get("CUA_CAPTURE_SCOPE", "auto")- if value not in {"auto", "window", "desktop"}:- raise ValueError("CUA_CAPTURE_SCOPE must be auto, window, or desktop")- return cast(CaptureScope, value)---async def driver_call(binary: str, name: str, arguments: dict[str, str]) -> None:- process = await asyncio.create_subprocess_exec(- binary,- "call",- name,- json.dumps(arguments),- stdout=asyncio.subprocess.PIPE,- stderr=asyncio.subprocess.PIPE,- )- try:- stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=30)- except TimeoutError:- process.kill()- await process.wait()- raise RuntimeError(f"cua-driver call {name} timed out") from None- if process.returncode != 0:- detail = stderr.decode().strip() or stdout.decode().strip()- raise RuntimeError(f"cua-driver call {name} failed: {detail}")--async def main() -> None:args = parse_args()binary = driver_binary()- scope = capture_scope()- session = f"codex-python-{uuid4().hex[:12]}"- started = False-- try:- await driver_call(- binary,- "start_session",- {"session": session, "capture_scope": scope},+ config = CodexConfig(+ config_overrides=(+ f"mcp_servers.cua_driver.command={json.dumps(binary)}",+ 'mcp_servers.cua_driver.args=["mcp"]',+ "mcp_servers.cua_driver.required=true",)- started = True- config = CodexConfig(- config_overrides=(- f'mcp_servers.cua_driver.command={json.dumps(binary)}',- 'mcp_servers.cua_driver.args=["mcp"]',- "mcp_servers.cua_driver.required=true",- )+ )+ async with AsyncCodex(config) as codex:+ thread = await codex.thread_start(+ model=os.environ.get("CODEX_MODEL"),+ sandbox=Sandbox.read_only,)- async with AsyncCodex(config) as codex:- thread = await codex.thread_start(- model=os.environ.get("CODEX_MODEL"),- sandbox=Sandbox.read_only,- )- result = await thread.run(- f"""Complete this trusted desktop task through the cua_driver MCP server:+ result = await thread.run(+ f"""Complete this trusted desktop task through the cua_driver MCP server:{args.task}-The host already started session {session!r} with capture scope {scope!r}.-Use only cua_driver MCP tools for desktop observation and interaction. Pass-session {session!r} to every tool that accepts a session. Inspect before each-action and verify afterward. Do not call start_session or end_session. If a-mutation times out, observe before any retry; never blindly replay an action-with an unknown outcome. Return a concise result and name anything unverified.+This MCP transport owns one implicit lifecycle session. Omit the session field+for ordinary calls so the runtime creates and reuses it. Select an exact window+or desktop target on every action; session identity never selects capture+modality or permission authority. Use only cua_driver MCP tools for desktop+observation and interaction. Inspect before each action and verify afterward.+If a mutation times out, observe before any retry; never blindly replay an+action with an unknown outcome. Return a concise result and name anything+unverified."""- )- print(result.final_response)- finally:- if started:- await driver_call(binary, "end_session", {"session": session})+ )+ print(result.final_response)if __name__ == "__main__":diff --git a/libs/cua-driver/examples/agent-sdks/codex_agent.ts b/libs/cua-driver/examples/agent-sdks/codex_agent.tsindex 1d0230d5c2..6870a99a3b 100644--- a/libs/cua-driver/examples/agent-sdks/codex_agent.ts+++ b/libs/cua-driver/examples/agent-sdks/codex_agent.ts@@ -1,16 +1,9 @@/** Run a Codex SDK desktop task through Cua Driver's MCP server. */-import { execFile } from 'node:child_process';import process from 'node:process';-import { promisify } from 'node:util';-import { randomUUID } from 'node:crypto';import { Codex } from '@openai/codex-sdk';-type CaptureScope = 'auto' | 'window' | 'desktop';--const execFileAsync = promisify(execFile);-function taskFromArgs(): string {const task = process.argv.slice(2).join(' ').trim();if (!task) {@@ -19,37 +12,19 @@ function taskFromArgs(): string {return task;}-function captureScope(): CaptureScope {- const value = process.env.CUA_CAPTURE_SCOPE ?? 'auto';- if (value !== 'auto' && value !== 'window' && value !== 'desktop') {- throw new Error('CUA_CAPTURE_SCOPE must be auto, window, or desktop');- }- return value;-}--async function driverCall(- binary: string,- tool: string,- args: Record<string, string>-): Promise<void> {- await execFileAsync(binary, ['call', tool, JSON.stringify(args)], {- timeout: 30_000,- });-}--function agentPrompt(task: string, session: string, scope: CaptureScope): string {+function agentPrompt(task: string): string {return `Complete this desktop task through the cua_driver MCP server:${task}-The host has already started session ${JSON.stringify(session)} with capture-scope ${JSON.stringify(scope)}. Use only cua_driver MCP tools for desktop+This MCP transport owns one implicit lifecycle session. Omit the session field+for ordinary calls so the runtime creates and reuses it. Select an exact window+or desktop target on every action; session identity never selects capture+modality or permission authority. Use only cua_driver MCP tools for desktopobservation and interaction. Do not substitute shell, filesystem, web, or code-execution. Pass session ${JSON.stringify(session)} to every Cua tool that-accepts a session. Inspect state before each action and verify state after it.-Do not call start_session or end_session; the host owns lifecycle cleanup. Do-not blindly retry a mutation after a timeout or disconnect; observe first. Do-not perform purchases, send messages, delete data, expose credentials, or take+execution. Inspect state before each action and verify state after it. Do not+blindly retry a mutation after a timeout or disconnect; observe first. Do not+perform purchases, send messages, delete data, expose credentials, or takeanother irreversible action unless the task explicitly requests that exactaction. Return a concise result and mention any step you could not verify.`;}@@ -57,44 +32,28 @@ action. Return a concise result and mention any step you could not verify.`;async function main(): Promise<void> {const task = taskFromArgs();const binary = process.env.CUA_DRIVER_BIN ?? 'cua-driver';- const scope = captureScope();- const session = `codex-agent-${randomUUID().slice(0, 12)}`;- let started = false;-- try {- await driverCall(binary, 'start_session', {- session,- capture_scope: scope,- });- started = true;-- const codex = new Codex({- config: {- mcp_servers: {- cua_driver: {- command: binary,- args: ['mcp'],- startup_timeout_sec: 30,- required: true,- },+ const codex = new Codex({+ config: {+ mcp_servers: {+ cua_driver: {+ command: binary,+ args: ['mcp'],+ startup_timeout_sec: 30,+ required: true,},},- });- const model = process.env.CODEX_MODEL;- const thread = codex.startThread({- ...(model ? { model } : {}),- sandboxMode: 'read-only',- approvalPolicy: 'never',- skipGitRepoCheck: true,- });+ },+ });+ const model = process.env.CODEX_MODEL;+ const thread = codex.startThread({+ ...(model ? { model } : {}),+ sandboxMode: 'read-only',+ approvalPolicy: 'never',+ skipGitRepoCheck: true,+ });- const result = await thread.run(agentPrompt(task, session, scope));- console.log(result.finalResponse);- } finally {- if (started) {- await driverCall(binary, 'end_session', { session });- }- }+ const result = await thread.run(agentPrompt(task));+ console.log(result.finalResponse);}await main();diff --git a/libs/cua-driver/examples/agent-sdks/native-tools.ts b/libs/cua-driver/examples/agent-sdks/native-tools.tsindex 2b2470a80e..3534beed63 100644--- a/libs/cua-driver/examples/agent-sdks/native-tools.ts+++ b/libs/cua-driver/examples/agent-sdks/native-tools.ts@@ -1,17 +1,12 @@/** Narrow agent-tool adapter over the same-process Cua Driver TypeScript SDK. */-import { randomUUID } from 'node:crypto';-import {- CaptureScope,+ ActionTarget,ClickButton,ClickInput,CuaDriver,- DesktopScope,- EndSessionInput,GetDesktopStateInput,PressKeyInput,- StartSessionInput,ToolResult,TypeTextInput,} from '@trycua/cua-driver';@@ -27,47 +22,23 @@ export type NativeToolResult = {export class NativeDesktopTools {readonly driver = CuaDriver.create(undefined);- readonly session = `claude-native-${randomUUID().slice(0, 12)}`;- private started = false;+ readonly desktopTarget = new ActionTarget.Desktop({ displayId: 'primary' });constructor(private readonly timeoutMs = 30_000) {}- async start(): Promise<void> {- await this.bounded(- this.driver.startSession(- StartSessionInput.new({- session: this.session,- captureScope: CaptureScope.Desktop,- })- ),- 'start_session'- );- this.started = true;- }-async close(): Promise<void> {try {- if (this.started) {- await this.bounded(- this.driver.endSession(EndSessionInput.new({ session: this.session })),- 'end_session'- );- this.started = false;- }+ await this.driver.shutdown();} finally {- try {- await this.driver.shutdown();- } finally {- // Generated UniFFI bindings expose deterministic handle release- // separately from asynchronous runtime shutdown.- (this.driver as unknown as { uniffiDestroy(): void }).uniffiDestroy();- }+ // Generated UniFFI bindings expose deterministic handle release+ // separately from asynchronous runtime shutdown.+ (this.driver as unknown as { uniffiDestroy(): void }).uniffiDestroy();}}async observe(): Promise<NativeToolResult> {const result = await this.bounded(- this.driver.getDesktopState(GetDesktopStateInput.new({ session: this.session })),+ this.driver.getDesktopState(GetDesktopStateInput.new({})),'get_desktop_state');return this.content(result);@@ -79,8 +50,7 @@ export class NativeDesktopTools {ClickInput.new({x,y,- scope: DesktopScope.Desktop,- session: this.session,+ target: this.desktopTarget,button: ClickButton.Left,count: 1,})@@ -93,8 +63,7 @@ export class NativeDesktopTools {this.driver.typeText(TypeTextInput.new({text,- scope: DesktopScope.Desktop,- session: this.session,+ target: this.desktopTarget,})));@@ -105,8 +74,7 @@ export class NativeDesktopTools {this.driver.pressKey(PressKeyInput.new({key,- scope: DesktopScope.Desktop,- session: this.session,+ target: this.desktopTarget,})));diff --git a/libs/cua-driver/examples/agent-sdks/native_driver.py b/libs/cua-driver/examples/agent-sdks/native_driver.pyindex a2a7bf8b7b..205e4df2de 100644--- a/libs/cua-driver/examples/agent-sdks/native_driver.py+++ b/libs/cua-driver/examples/agent-sdks/native_driver.py@@ -9,13 +9,10 @@ from urllib.request import Request, urlopenfrom uuid import uuid4from cua_driver import (- CaptureScope,+ ActionTarget,CuaDriver,- DesktopScope,- EndSessionInput,GetDesktopStateInput,PressKeyInput,- StartSessionInput,TypeTextInput,)@@ -47,25 +44,13 @@ def parse_args() -> argparse.Namespace:async def main() -> None:args = parse_args()token = f"cua-{uuid4().hex[:10]}"- session = f"native-python-{uuid4().hex[:10]}"await asyncio.to_thread(fixture_request, args.fixture, "/reset", method="POST")driver = CuaDriver.create()- started = Falsemutation_outcome_unknown = Falsetry:- await asyncio.wait_for(- driver.start_session(- StartSessionInput(session=session, capture_scope=CaptureScope.DESKTOP)- ),- args.timeout,- )- started = True-before = await asyncio.wait_for(- driver.get_desktop_state(- GetDesktopStateInput(session=session, screenshot_out_file=None)- ),+ driver.get_desktop_state(GetDesktopStateInput(session=None, screenshot_out_file=None)),args.timeout,)if before.is_error or not before.images:@@ -77,8 +62,9 @@ async def main() -> None:driver.type_text(TypeTextInput(text=token,- scope=DesktopScope.DESKTOP,- session=session,+ target=ActionTarget.DESKTOP(display_id="primary"),+ scope=None,+ session=None,)),args.timeout,@@ -90,8 +76,9 @@ async def main() -> None:PressKeyInput(key="ENTER",modifiers=None,- scope=DesktopScope.DESKTOP,- session=session,+ target=ActionTarget.DESKTOP(display_id="primary"),+ scope=None,+ session=None,)),args.timeout,@@ -105,9 +92,7 @@ async def main() -> None:# the independent fixture first; it may have consumed the action.await wait_for_submission(args.fixture, token, args.timeout)after = await asyncio.wait_for(- driver.get_desktop_state(- GetDesktopStateInput(session=session, screenshot_out_file=None)- ),+ driver.get_desktop_state(GetDesktopStateInput(session=None, screenshot_out_file=None)),args.timeout,)if after.is_error or not after.images:@@ -116,11 +101,7 @@ async def main() -> None:if mutation_outcome_unknown:print("the driver response was uncertain; the external postcondition resolved it")finally:- try:- if started:- await driver.end_session(EndSessionInput(session=session))- finally:- await driver.shutdown()+ await driver.shutdown()if __name__ == "__main__":diff --git a/libs/cua-driver/examples/agent-sdks/native_driver.ts b/libs/cua-driver/examples/agent-sdks/native_driver.tsindex 67e41b294b..81528f09a2 100644--- a/libs/cua-driver/examples/agent-sdks/native_driver.ts+++ b/libs/cua-driver/examples/agent-sdks/native_driver.ts@@ -3,18 +3,16 @@import { randomUUID } from 'node:crypto';import {- CaptureScope,+ ActionTarget,CuaDriver,- DesktopScope,- EndSessionInput,GetDesktopStateInput,PressKeyInput,- StartSessionInput,TypeTextInput,} from '@trycua/cua-driver';const fixture = process.env.CUA_FIXTURE_URL ?? 'http://127.0.0.1:8765';const timeoutMs = 10_000;+const desktopTarget = new ActionTarget.Desktop({ displayId: 'primary' });async function bounded<T>(promise: Promise<T>, label: string): Promise<T> {let timer: ReturnType<typeof setTimeout> | undefined;@@ -47,27 +45,14 @@ async function waitForSubmission(token: string): Promise<void> {}const token = `cua-${randomUUID().slice(0, 10)}`;-const session = `native-typescript-${randomUUID().slice(0, 10)}`;await resetFixture();const driver = CuaDriver.create(undefined);-let started = false;let mutationOutcomeUnknown = false;try {- await bounded(- driver.startSession(- StartSessionInput.new({- session,- captureScope: CaptureScope.Desktop,- })- ),- 'start_session'- );- started = true;-const before = await bounded(- driver.getDesktopState(GetDesktopStateInput.new({ session })),+ driver.getDesktopState(GetDesktopStateInput.new({})),'get_desktop_state');if (before.isError || before.images.length === 0) {@@ -80,8 +65,7 @@ try {driver.typeText(TypeTextInput.new({text: token,- scope: DesktopScope.Desktop,- session,+ target: desktopTarget,})),'type_text'@@ -92,8 +76,7 @@ try {driver.pressKey(PressKeyInput.new({key: 'ENTER',- scope: DesktopScope.Desktop,- session,+ target: desktopTarget,})),'press_key'@@ -107,7 +90,7 @@ try {// fixture before considering any retry.await waitForSubmission(token);const after = await bounded(- driver.getDesktopState(GetDesktopStateInput.new({ session })),+ driver.getDesktopState(GetDesktopStateInput.new({})),'post-action get_desktop_state');if (after.isError || after.images.length === 0) {@@ -119,16 +102,10 @@ try {}} finally {try {- if (started) {- await driver.endSession(EndSessionInput.new({ session }));- }+ await driver.shutdown();} finally {- try {- await driver.shutdown();- } finally {- // shutdown() drains the runtime; this generated destructor releases the- // native UniFFI handle immediately instead of waiting for JavaScript GC.- (driver as unknown as { uniffiDestroy(): void }).uniffiDestroy();- }+ // shutdown() drains the runtime; this generated destructor releases the+ // native UniFFI handle immediately instead of waiting for JavaScript GC.+ (driver as unknown as { uniffiDestroy(): void }).uniffiDestroy();}}diff --git a/libs/cua-driver/examples/agent-sdks/native_tools.py b/libs/cua-driver/examples/agent-sdks/native_tools.pyindex bb5c7f4774..78a071c82b 100644--- a/libs/cua-driver/examples/agent-sdks/native_tools.py+++ b/libs/cua-driver/examples/agent-sdks/native_tools.py@@ -5,18 +5,14 @@ from __future__ import annotationsimport asynciofrom collections.abc import Awaitable, Callablefrom typing import TypeVar-from uuid import uuid4from cua_driver import (- CaptureScope,+ ActionTarget,ClickButton,ClickInput,CuaDriver,- DesktopScope,- EndSessionInput,GetDesktopStateInput,PressKeyInput,- StartSessionInput,ToolResult,TypeTextInput,)@@ -26,40 +22,20 @@ T = TypeVar("T")class NativeDesktopTools:- """Own one in-process driver runtime and one desktop-scoped session."""+ """Own one in-process runtime with one implicit lifecycle session."""def __init__(self, timeout: float = 30.0) -> None:self.driver = CuaDriver.create()- self.session = f"claude-native-{uuid4().hex[:12]}"self.timeout = timeout- self.started = False-- async def start(self) -> None:- await self._bounded(- self.driver.start_session(- StartSessionInput(- session=self.session,- capture_scope=CaptureScope.DESKTOP,- )- )- )- self.started = Trueasync def close(self) -> None:- try:- if self.started:- await self._bounded(- self.driver.end_session(EndSessionInput(session=self.session))- )- self.started = False- finally:- await self.driver.shutdown()+ await self.driver.shutdown()async def observe(self) -> dict[str, object]:result = await self._bounded(self.driver.get_desktop_state(GetDesktopStateInput(- session=self.session,+ session=None,screenshot_out_file=None,))@@ -72,8 +48,9 @@ class NativeDesktopTools:ClickInput(x=x,y=y,- scope=DesktopScope.DESKTOP,- session=self.session,+ target=ActionTarget.DESKTOP(display_id="primary"),+ scope=None,+ session=None,button=ClickButton.LEFT,count=1,)@@ -85,8 +62,9 @@ class NativeDesktopTools:lambda: self.driver.type_text(TypeTextInput(text=text,- scope=DesktopScope.DESKTOP,- session=self.session,+ target=ActionTarget.DESKTOP(display_id="primary"),+ scope=None,+ session=None,)))@@ -97,8 +75,9 @@ class NativeDesktopTools:PressKeyInput(key=key,modifiers=None,- scope=DesktopScope.DESKTOP,- session=self.session,+ target=ActionTarget.DESKTOP(display_id="primary"),+ scope=None,+ session=None,)))diff --git a/libs/cua-driver/examples/agent-sdks/package-lock.json b/libs/cua-driver/examples/agent-sdks/package-lock.jsonindex ca497c2fb3..85adb06240 100644--- a/libs/cua-driver/examples/agent-sdks/package-lock.json+++ b/libs/cua-driver/examples/agent-sdks/package-lock.json@@ -8,7 +8,7 @@"dependencies": {"@anthropic-ai/claude-agent-sdk": "0.3.218","@openai/codex-sdk": "0.145.0",- "@trycua/cua-driver": "0.12.2",+ "@trycua/cua-driver": "0.19.2","zod": "4.1.12"},"devDependencies": {@@ -827,27 +827,27 @@"peer": true},"node_modules/@trycua/cua-driver": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver/-/cua-driver-0.12.2.tgz",- "integrity": "sha512-Jbhb6KwyRWng6BFyoudxkUPGkJrdvw1TfSIpMNvQbQpcCPgQgc54r2aIoR+Kcl4P54JScY85dZFc5285qcHcKw==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver/-/cua-driver-0.19.2.tgz",+ "integrity": "sha512-fL7WQrfXTSb6q/I9R3ryHaYdSsDqZehMtUAsLt7aN4Xn5IpAU7ulFFRiwro9oBIipShxNfrf1Aw+sTx9PgduXQ==","license": "MIT","dependencies": {"@ubjs/core": "0.31.0-3","@ubjs/node": "0.31.0-3"},"optionalDependencies": {- "@trycua/cua-driver-darwin-arm64": "0.12.2",- "@trycua/cua-driver-darwin-x64": "0.12.2",- "@trycua/cua-driver-linux-arm64-gnu": "0.12.2",- "@trycua/cua-driver-linux-x64-gnu": "0.12.2",- "@trycua/cua-driver-win32-arm64-msvc": "0.12.2",- "@trycua/cua-driver-win32-x64-msvc": "0.12.2"+ "@trycua/cua-driver-darwin-arm64": "0.19.2",+ "@trycua/cua-driver-darwin-x64": "0.19.2",+ "@trycua/cua-driver-linux-arm64-gnu": "0.19.2",+ "@trycua/cua-driver-linux-x64-gnu": "0.19.2",+ "@trycua/cua-driver-win32-arm64-msvc": "0.19.2",+ "@trycua/cua-driver-win32-x64-msvc": "0.19.2"}},"node_modules/@trycua/cua-driver-darwin-arm64": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-arm64/-/cua-driver-darwin-arm64-0.12.2.tgz",- "integrity": "sha512-rR4KpxaE/R/RAQ718YAIJ+YXuHewdAxq1kmtcPh0thhZCxcckTfVHk6sa6XSfwmqeNF1kTR82zKaeOhr55uBlw==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-arm64/-/cua-driver-darwin-arm64-0.19.2.tgz",+ "integrity": "sha512-ZTYjJfe6PnA5hTblbJ8aUwwfymsWOPjXLiE1Hn/DsoAK0Gx8eUAEXQCv2fm7UqqMF8bN7BgEmunIQRKzeP6mug==","cpu": ["arm64"],@@ -858,9 +858,9 @@]},"node_modules/@trycua/cua-driver-darwin-x64": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-x64/-/cua-driver-darwin-x64-0.12.2.tgz",- "integrity": "sha512-BBFhMjmKZTvb24Z7NiYmWR2+yvTQgYat1biStxd6T+yPv6aTNFho/QE6YrVYxEzQTNHv3Rr6aa9Fu72mcmzBag==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-darwin-x64/-/cua-driver-darwin-x64-0.19.2.tgz",+ "integrity": "sha512-q7jeEAN0HrgE7P7z+ou8duIJgLkg53KH+sx/yVbVyCdqEjiMiKcsU9aSS78ZTg14TdXwem7kItAyCRDWnBSeTg==","cpu": ["x64"],@@ -871,9 +871,9 @@]},"node_modules/@trycua/cua-driver-linux-arm64-gnu": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-arm64-gnu/-/cua-driver-linux-arm64-gnu-0.12.2.tgz",- "integrity": "sha512-XJPPLwnUroKsD0vh2dkE+NUaSElKwWNmjfy48cc/j/iLve8m2xZAFcmHgEug6Ps94AdRQ/Ko3w9z9jeCzJr72w==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-arm64-gnu/-/cua-driver-linux-arm64-gnu-0.19.2.tgz",+ "integrity": "sha512-E5VkoWpMzpGErz7oetFudRszNpMxGMfJjWdQ9xoIhP4x9t6EIZ89NdbLJerhO4mZN2mQP1PJybACODggJMxUZw==","cpu": ["arm64"],@@ -887,9 +887,9 @@]},"node_modules/@trycua/cua-driver-linux-x64-gnu": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-x64-gnu/-/cua-driver-linux-x64-gnu-0.12.2.tgz",- "integrity": "sha512-JekaFKUol9DYJqw90Td8OISemRSDKyzOUoWfVRIQfLqm8YveySP3+sHGOovJDytTDXVuSKEJOIdV7q678gr4rA==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-linux-x64-gnu/-/cua-driver-linux-x64-gnu-0.19.2.tgz",+ "integrity": "sha512-UrNp9IFixsTI3yPnxxE1gCXfrfF4Ii4tzSawTRIOMiTEwwe8pvUYxP3Ngv1uAhDwmYbZp+sqxeARH9eg+ShvQg==","cpu": ["x64"],@@ -903,9 +903,9 @@]},"node_modules/@trycua/cua-driver-win32-arm64-msvc": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-arm64-msvc/-/cua-driver-win32-arm64-msvc-0.12.2.tgz",- "integrity": "sha512-0sU/GSGyfrIjBpOsc9UObi2bdD1oUcuaYqB/HIzWXIDdUmoMfXIsHPnPb0QvUnsm0EI6cFXjBzURlBKHhITKQQ==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-arm64-msvc/-/cua-driver-win32-arm64-msvc-0.19.2.tgz",+ "integrity": "sha512-N1/pMIPRJ1ROyKgNnx5e3ANfGjgr4MKqSxMIejUn9f7q+YGzN8jvkYhUpndjJA2j+iivtekK6c4QORY425qk5g==","cpu": ["arm64"],@@ -916,9 +916,9 @@]},"node_modules/@trycua/cua-driver-win32-x64-msvc": {- "version": "0.12.2",- "resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-x64-msvc/-/cua-driver-win32-x64-msvc-0.12.2.tgz",- "integrity": "sha512-ZZC8EPvuDPxg+/aOy8LX53AirEdqlO6xd4Vqsm3uWmNjfis+D8Fg9Fko2mOO5LWbuGzBYePyQlHji4n4Kqe2Lw==",+ "version": "0.19.2",+ "resolved": "https://registry.npmjs.org/@trycua/cua-driver-win32-x64-msvc/-/cua-driver-win32-x64-msvc-0.19.2.tgz",+ "integrity": "sha512-S8b9+Yg+Ks4lpBq5TS6Dp2Z/DJfLJ67GfICTkx8djW6UZDtyCNmCuX5EMwWbY1SfnZw+iaEZRuX948DguCue0g==","cpu": ["x64"],diff --git a/libs/cua-driver/examples/agent-sdks/package.json b/libs/cua-driver/examples/agent-sdks/package.jsonindex 9090e10fef..517295a9e3 100644--- a/libs/cua-driver/examples/agent-sdks/package.json+++ b/libs/cua-driver/examples/agent-sdks/package.json@@ -11,7 +11,7 @@"dependencies": {"@anthropic-ai/claude-agent-sdk": "0.3.218","@openai/codex-sdk": "0.145.0",- "@trycua/cua-driver": "0.12.2",+ "@trycua/cua-driver": "0.19.2","zod": "4.1.12"},"devDependencies": {diff --git a/libs/cua-driver/examples/agent-sdks/requirements.txt b/libs/cua-driver/examples/agent-sdks/requirements.txtindex 40fa8f33ef..3f090246d8 100644--- a/libs/cua-driver/examples/agent-sdks/requirements.txt+++ b/libs/cua-driver/examples/agent-sdks/requirements.txt@@ -1,3 +1,3 @@claude-agent-sdk==0.2.124openai-codex==0.144.4-cua-driver==0.12.2+cua-driver==0.19.2diff --git a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.mdindex 465ad52b1a..3adafa6e02 100644--- a/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md+++ b/libs/cua-driver/rust/Skills/cua-driver/BROWSER.md@@ -15,21 +15,26 @@ mints session-scoped tab and element capabilities.The canonical loop is:```text-start_session+start_session(session?) # optional; can name before actinglist_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+get_browser_state(pid, window_id, session?) # bind+get_browser_state(target_id, tab_id, session?,+ snapshot_format=semantic_v2) # snapshotbrowser_navigate / browser_click / browser_type / browser_pointerbrowser_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+get_browser_state(target_id, tab_id, session?,+ snapshot_format=semantic_v2) # verify and refresh refs+end_session(session?) # optional cleanup```-Use one explicit `session` value throughout. Never substitute a raw CDP-target id, tab ordinal, URL match, or remembered ref for a capability returned-by `get_browser_state`.+For a multi-call browser workflow, prefer a short `session` label and pass the+same value on every call that accepts it. Passing it once is not sticky; a later+omitted value uses the transport's implicit session. One long-lived MCP or SDK+transport may omit `session` for one-off or deliberately unlabeled work; its+first admitted call creates one implicit session and later unnamed calls reuse+it. Direct one-shot CLI calls use disposable transports. Never substitute a raw+CDP target id, tab ordinal, URL match, or remembered ref for a capability+returned by `get_browser_state`.### Copy page content to the system clipboard@@ -425,8 +430,9 @@ result from the current host, process, window, session, and tab.- `browser_requires_setup`: obtain explicit approval and call`browser_prepare`; never make setup a hidden read side effect.- `browser_consent_required`: restart standard mode with the trusted launch- grant, use a matching bounded manifest, or let the embedding host decide the- attested request. Do not automate a generic approval dialog.+ grant, use a capability manifest that admits the exact resource while the+ selected profile remains independently binding, or let the embedding host+ decide the attested request. Do not automate a generic approval dialog.- `browser_binding_ambiguous` or heuristic binding: resolve the native-windowambiguity and bind again; do not mutate.- `browser_ref_stale`: snapshot again and use a new ref.diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.mdindex cb8960b8fd..2e1e53dd87 100644--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md@@ -86,7 +86,8 @@ before stopping or advancing:3. **Background pixel action.** Use the pixels from the same state snapshot.4. **Foreground delivery.** Retry only the action that evidence says could notland in the background.-5. **Desktop fallback.** Enter this explicit, one-way session phase last.+5. **Desktop fallback.** Select an exact desktop target for that call only.+ Later calls may return to an exact window target in the same session.Use Cua Driver when the outcome lives in an application's UI or window state,or when the user explicitly asks to operate that GUI. Once the task crosses@@ -346,7 +347,8 @@ The route vocabulary is intentionally cross-platform:An optional escalation is a harness instruction, never an automatic retry:- `pixel`: refresh visual state and choose an exact pixel target;-- `foreground`: explicitly select foreground delivery if session policy allows;+- `foreground`: explicitly select foreground delivery if the authorization+ stack admits the tool and exact target;- `page`: bind the native window to a supported browser page route;- `session`: a legacy compatibility signal from an older capture-scope daemon;current callers choose a desktop target on the specific action instead.@@ -374,10 +376,13 @@ The window target uses window-local coordinates and the background/foregrounddelivery ladder. The desktop target uses screen coordinates and foregrounddelivery. A desktop action does not disable window tools for later calls.-`start_session` is optional. The first admitted stateful call creates one-implicit session for the authenticated transport, and later unnamed calls on-that transport reuse it. The default idle TTL is five minutes. Use a public-session label only when you need explicit naming or lifecycle control.+`start_session` is optional. For a multi-call run, prefer a short public+`session` label and pass the same label on every call that accepts it. The label+is call-scoped: if a later call omits it, that call uses the authenticated+transport's implicit session instead. Unnamed calls on one transport reuse that+implicit identity. The default idle TTL is five minutes. Call+`start_session(session)` to name or configure a run before acting, or to revive+an ended name.Do not use `config set capture_scope` or `set_config`; that key is retired andstale values on disk are ignored. `start_session.capture_scope`,@@ -385,6 +390,39 @@ stale values on disk are ignored. `start_session.capture_scope`,surfaces. There is no `deescalate_session`. Reserved fields such as`_session_id` are transport metadata and cannot create authority.+## Keep authorization separate from sessions++The trusted host selects one permission profile at startup. `standard` keeps+the normal profile behavior and residual approval requirements, `bounded`+requires a reviewed capability manifest and has no runtime approval path, and+`unrestricted` bypasses Cua approval prompts after explicit risk acceptance.+Hard invariants plus managed and user policy remain binding in every profile.++An optional capability manifest is a deny-by-default ceiling in `standard` and+`unrestricted`; `bounded` requires one. It can remove tools or typed resources+from the selected profile, but it cannot grant a tool, resource, or approval+bypass that another authorization layer denies. Approval is considered only+after the tool and every adapter-attested resource are inside manifest scope.++Use the canonical startup pair together:++```bash+cua-driver mcp \+ --permission-mode standard \+ --capability-manifest ./capabilities.yaml \+ --approve-capability-manifest+```++Capability manifest v3 omits file-level `mode` and `ask.tools`. Its+`allow.tools` list is nonempty. Lifetime fields are optional in `standard` and+`unrestricted`; `bounded` requires both `expires_after` and `idle_timeout`.+The older `--session-policy` names remain compatibility aliases and must not be+used in new configurations.++Starting, ending, naming, reconnecting, or omitting a session never changes+permission authority. A public session label is lifecycle metadata, never a+grant, caller identity, or bearer credential.+### Why window selection is the caller's job now`get_app_state` used to pick a window for you via a max-area heuristic@@ -604,8 +642,8 @@ last resort.## The canonical loop```-# start_session(session) is optional; ordinary calls create an implicit session-launch_app(target)+# for multi-call work, repeat the same session label on every call that accepts it+launch_app(target, session)→ pick window_id from the returned `windows` array(or call list_windows(pid) separately)→ get_window_state(pid, window_id)@@ -623,9 +661,14 @@ full-display image.common case collapses to two calls (`launch_app` → `get_window_state`)without a separate `list_windows` hop.-**Name a session only when useful.** An unnamed transport still gets one private-lifecycle identity and visible agent cursor. A public label such as-`"research-1"` makes explicit inspection and cleanup easier, but it is not a+**Prefer a named session for multi-call work.** Choose a short label (for+example, `session: "research-1"`) and pass the same value on every call that+accepts it. Passing it once is not sticky: a later call that omits `session`+uses the transport's implicit session. Call `start_session(session)` when you+need to name or configure the run before acting, or to revive a name after+`end_session`. For one-off or deliberately unlabeled work, omission is valid+and the transport still gets one private lifecycle identity and visible agent+cursor. A public label makes inspection and cleanup easier, but it is not acredential. End with `end_session` when useful; transport close or thefive-minute idle TTL also reclaims it.diff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/inputs.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/inputs.rsindex cbf03afa61..b095bcfaee 100644--- a/libs/cua-driver/rust/crates/cua-driver-contract/src/inputs.rs+++ b/libs/cua-driver/rust/crates/cua-driver-contract/src/inputs.rs@@ -58,6 +58,10 @@ fn string_schema(generator: &mut SchemaGenerator) -> Schema {String::json_schema(generator)}+pub const MULTI_CALL_SESSION_DESCRIPTION: &str =+ "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.";+fn string_list_schema(generator: &mut SchemaGenerator) -> Schema {Vec::<String>::json_schema(generator)}@@ -439,7 +443,8 @@ impl ToolInput for EndSessionInput {#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, uniffi::Record)]#[serde(deny_unknown_fields)]pub struct GetDesktopStateInput {- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -456,7 +461,8 @@ impl ToolInput for GetDesktopStateInput {#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, uniffi::Record)]#[serde(deny_unknown_fields)]pub struct GetScreenSizeInput {- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -469,7 +475,8 @@ impl ToolInput for GetScreenSizeInput {#[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema, PartialEq, uniffi::Record)]#[serde(deny_unknown_fields)]pub struct GetCursorPositionInput {- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -493,7 +500,8 @@ pub struct MoveCursorInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -514,7 +522,8 @@ pub struct SetWindowFrameInput {pub width: f64,#[schemars(schema_with = "positive_number_schema")]pub height: f64,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -536,7 +545,8 @@ pub struct InvokeMenuInput {pub window_id: u64,#[schemars(schema_with = "menu_path_schema")]pub path: Vec<String>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -563,7 +573,8 @@ pub struct ClickInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -596,7 +607,8 @@ pub struct DragInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -632,7 +644,8 @@ pub struct ScrollInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -658,7 +671,8 @@ pub struct TypeTextInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -675,7 +689,8 @@ pub struct ClipboardReadInput {/// Clipboard content is privacy-sensitive and is never retained in telemetry.#[serde(default)]pub include_text: bool,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -700,7 +715,8 @@ pub struct ClipboardWriteInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub file_path: Option<String>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -720,7 +736,8 @@ pub struct PressKeyInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,@@ -744,7 +761,8 @@ pub struct HotkeyInput {#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "desktop_scope_schema")]pub scope: Option<DesktopScope>,- /// Optional session id.+ /// 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.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,diff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/lib.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/lib.rsindex 45cd526f73..a5a72e84dc 100644--- a/libs/cua-driver/rust/crates/cua-driver-contract/src/lib.rs+++ b/libs/cua-driver/rust/crates/cua-driver-contract/src/lib.rs@@ -34,6 +34,7 @@ pub use inputs::{ListSessionsInput, MoveCursorInput, PressKeyInput, ScrollBy, ScrollDirection, ScrollInput,SetAgentCursorEnabledInput, SetAgentCursorMotionInput, SetAgentCursorThemeInput,SetWindowFrameInput, StartSessionInput, ToolInput, TypeTextInput,+ MULTI_CALL_SESSION_DESCRIPTION,};pub use outputs::{advertised_output_schema, refusal_envelope_schema, ActionDelivery, ActionDeliveryMode,@@ -345,6 +346,45 @@ mod tests {);}+ #[test]+ fn portable_action_sessions_explain_named_multi_call_runs() {+ for name in [+ "click",+ "clipboard_read",+ "clipboard_write",+ "drag",+ "get_cursor_position",+ "get_desktop_state",+ "get_screen_size",+ "hotkey",+ "invoke_menu",+ "move_cursor",+ "press_key",+ "scroll",+ "set_window_frame",+ "type_text",+ ] {+ let contract = tool_contract(name).expect("portable action contract");+ let description = contract.input_schema["properties"]["session"]["description"]+ .as_str()+ .expect("portable session description")+ .split_whitespace()+ .collect::<Vec<_>>()+ .join(" ");+ assert_eq!(description, MULTI_CALL_SESSION_DESCRIPTION, "{name}");+ }++ let verify = tool_contract("verify_state").expect("verify_state contract");+ let description = verify.input_schema["properties"]["session"]["description"]+ .as_str()+ .expect("verify_state session description")+ .split_whitespace()+ .collect::<Vec<_>>()+ .join(" ");+ assert!(description.starts_with(MULTI_CALL_SESSION_DESCRIPTION));+ assert!(description.contains("never selects capture modality or authorization"));+ }+#[test]fn every_contract_has_success_schema_and_platforms() {for tool in manifest().tools {diff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/session.rsindex 0790ec1822..d887050f06 100644--- a/libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs+++ b/libs/cua-driver/rust/crates/cua-driver-contract/src/session.rs@@ -39,7 +39,7 @@ fn contract<I: ToolInput, O: ToolOutput>(fn start() -> ToolContract {contract::<StartSessionInput, StartSessionOutput>("start_session",- "Optionally name and start a lifecycle session for this agent run. When `session` is omitted, create or return the authenticated transport lease's implicit session. Ordinary actions create that implicit session automatically, so this tool is optional. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.",+ "Optionally create or return a lifecycle session before acting. For multi-call work, prefer a short public `session` label and repeat it on every call that accepts it; an omitted value uses the authenticated transport lease's implicit session instead. This tool is optional because an ordinary action can create or reuse a named run directly. Use it to set the initial cursor theme before acting or to revive a public name after it has ended; ordinary actions never revive ended names. `capture_scope` is deprecated compatibility input; new callers select window or desktop modality per action. Idempotent.",&["session.lifecycle.start", "session.capture_scope"],ToolAnnotations {read_only: false,@@ -119,3 +119,18 @@ fn end() -> ToolContract {},)}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn start_description_explains_direct_naming_and_explicit_revival() {+ let description = start().description;+ assert!(description.contains("prefer a short public `session` label"));+ assert!(description.contains("repeat it on every call that accepts it"));+ assert!(description.contains("omitted value uses the authenticated transport"));+ assert!(description.contains("revive a public name after it has ended"));+ assert!(description.contains("ordinary actions never revive ended names"));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-contract/src/verification.rs b/libs/cua-driver/rust/crates/cua-driver-contract/src/verification.rsindex aa13ab34f0..fb4c068baf 100644--- a/libs/cua-driver/rust/crates/cua-driver-contract/src/verification.rs+++ b/libs/cua-driver/rust/crates/cua-driver-contract/src/verification.rs@@ -156,8 +156,9 @@ pub struct VerifyStateInput {/// One to eight predicates, combined with logical AND.#[schemars(length(min = 1, max = 8))]pub expect: Vec<StatePredicate>,- /// Optional public session label for lifecycle continuity. It never selects- /// capture modality or authorization.+ /// 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. This+ /// field never selects capture modality or authorization.#[serde(default, skip_serializing_if = "Option::is_none")]#[schemars(schema_with = "string_schema")]pub session: Option<String>,diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/download.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/download.rsindex 46871f5218..3a2a467705 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/download.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/download.rs@@ -19,6 +19,7 @@ use crate::tool_args::ArgsExt;use super::cdp_ws::CdpConnection;use super::engine::BrowserEngine;use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::required_session_schema;use super::store::BrowserActionKind;/// Injected by an MCP host only after its destructive-tool approval flow.@@ -46,10 +47,7 @@ impl BrowserDownloadTool {input_schema: json!({"type": "object","properties": {- "session": {- "type": "string",- "description": "Explicit caller session owning the browser capabilities."- },+ "session": required_session_schema(),"target_id": {"type": "string","description": "Opaque exact browser target id from get_browser_state."diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rsindex 7bcbe2ef1b..022eb0ad3d 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/mod.rs@@ -74,3 +74,48 @@ pub use types::{EndpointOwnershipMethod, EndpointOwnershipProof, NativeOwnershipMethod, NativeOwnershipProof,NativeWindowInfo, OwnedEndpoint, ProcessFingerprint, Rect,};++pub(crate) fn session_schema() -> serde_json::Value {+ serde_json::json!({+ "type": "string",+ "description": format!(+ "{} Browser targets, tabs, and refs belong to the resolved lifecycle session.",+ cua_driver_contract::MULTI_CALL_SESSION_DESCRIPTION+ )+ })+}++pub(crate) fn required_session_schema() -> serde_json::Value {+ serde_json::json!({+ "type": "string",+ "description": "For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs."+ })+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn browser_session_schema_keeps_naming_and_capability_guidance_together() {+ let schema = session_schema();+ let description = schema["description"]+ .as_str()+ .expect("browser session description");+ assert!(description.contains("prefer a short public session label"));+ assert!(description.contains("repeat it on every call that accepts it"));+ assert!(description.contains("Browser targets, tabs, and refs"));+ }++ #[test]+ fn required_browser_session_schema_does_not_suggest_omission() {+ let schema = required_session_schema();+ let description = schema["description"]+ .as_str()+ .expect("required browser session description");+ assert!(description.contains("prefer a short public session label"));+ assert!(description.contains("repeat it on every call that accepts it"));+ assert!(description.contains("requires the label"));+ assert!(!description.contains("Omit it"));+ }+}diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rsindex 1ae2bf5de1..ad80763bb4 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/pointer.rs@@ -20,6 +20,7 @@ use super::cdp_ws::CdpConnection;use super::engine::{BrowserEngine, ValidatedTab};use super::platform::BrowserVisualActionKind;use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::required_session_schema;use super::store::{BrowserActionKind, FrameKind, FrameRef};use super::tools::{browser_protected_resource_scope, browser_resource_ownership};@@ -299,7 +300,7 @@ impl BrowserPointerTool {"properties": {"target_id": { "type": "string", "description": "Opaque target id minted by get_browser_state." },"tab_id": { "type": "string", "description": "Opaque tab id minted by get_browser_state." },- "session": { "type": "string", "description": "Explicit caller session owning the browser capabilities." },+ "session": required_session_schema(),"action": { "type": "string", "enum": ["hover", "right_click", "double_click", "scroll", "drag"] },"input_route": { "type": "string", "enum": ["trusted", "dom_event"], "default": "trusted" },"ref": { "type": "string", "description": "Origin page ref. Alternative to x/y." },diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rsindex 44f5b1ab8b..60ea062159 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/browser/tools.rs@@ -23,6 +23,7 @@ use super::platform::{};use super::pointer::BrowserPointerTool;use super::refusal::{BrowserRefusal, BrowserRefusalCode};+use super::session_schema as schema_session;use super::store::BrowserActionKind;use super::types::BindingQuality;@@ -87,13 +88,6 @@ fn schema_ref() -> Value {})}-fn schema_session() -> Value {- json!({- "type": "string",- "description": "Optional public session label. Browser targets, tabs, and refs use the authenticated transport's implicit lifecycle session when omitted."- })-}-pub(crate) fn browser_resource_ownership(engine: &BrowserEngine,args: &Value,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 8f5f1c72ae..9785974f9d 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@@ -374,7 +374,7 @@ Before starting UI work, classify the desired postcondition. For a non-GUI outcoFor an app or window outcome, use the narrowest semantic Cua route first: `set_window_frame` plus `list_windows` readback for geometry, typed browser tools for supported page content, and clipboard tools for clipboard state. Then climb through background `element_index` ({tree_kind}), background pixels, foreground delivery, and desktop fallback. Never advance on transport success alone.Workflow per turn:-0. `start_session(session)` once; reuse that id and end it when done.+0. `start_session` is optional. For multi-call work, prefer a short `session` label and repeat it on every call that accepts it. Unnamed calls use the transport's implicit session. Only `start_session` revives an ended name; `end_session` explicitly cleans up.1. `launch_app`, then `get_window_state(pid, window_id)` to refresh element indices.2. Act with the fresh index.3. `verify_state(pid, window_id, expect)` checks bounded postconditions. `unknown` is not success; `include_screenshot:true` lets the multimodal agent judge visual evidence.@@ -465,7 +465,7 @@ mod action_record_wire_tests {#[cfg(test)]mod agent_instruction_tests {- use super::agent_instructions;+ use super::{agent_instructions, initialize_result};#[test]fn instructions_route_structured_and_visual_verification_to_the_right_owner() {@@ -490,6 +490,25 @@ mod agent_instruction_tests {"initialize instructions should stay within the documented context budget");}++ #[test]+ fn initialize_instructions_describe_implicit_session_lifecycle() {+ let result = initialize_result();+ let instructions = result["instructions"]+ .as_str()+ .expect("initialize result should carry agent instructions");++ assert!(instructions.contains("`start_session` is optional"));+ assert!(instructions.contains("prefer a short `session` label"));+ assert!(instructions.contains("repeat it on every call that accepts it"));+ assert!(instructions.contains("transport's implicit session"));+ assert!(instructions.contains("Only `start_session` revives an ended name"));+ assert!(instructions.contains("`end_session` explicitly cleans up"));+ assert!(+ !instructions.contains("`start_session(session)` once"),+ "initialize instructions must not require explicit session setup"+ );+ }}#[cfg(test)]diff --git a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_schema.rs b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_schema.rsindex 7a73c2252a..b42c0f6040 100644--- a/libs/cua-driver/rust/crates/cua-driver-core/src/tool_schema.rs+++ b/libs/cua-driver/rust/crates/cua-driver-core/src/tool_schema.rs@@ -15,10 +15,11 @@//! required-set spec. Each platform calls it from a test against its own//! registry, so CI fails the moment a platform drifts.//!-//! Descriptions are intentionally NOT compared — prose can legitimately vary+//! Descriptions are generally not compared because prose can legitimately vary//! per tool (a `delivery_mode` blurb mentioning "PIXEL click" vs "AX insert").-//! The gate enforces *shape* (`type` / `enum` / `items`), which is what governs-//! client compatibility.+//! The `session` guidance is the exception: action tools must tell callers that+//! public labels are preferred for multi-call work and must be repeated on each+//! call. Lifecycle-management tools keep their resource-specific wording.use serde_json::{json, Value};@@ -28,11 +29,20 @@ use serde_json::{json, Value};pub fn session_schema() -> Value {json!({"type": "string",- "description": "Optional public session label. Omit it to use the \- authenticated transport's implicit lifecycle session."+ "description": cua_driver_contract::MULTI_CALL_SESSION_DESCRIPTION})}+/// Canonical lifecycle guidance plus a tool-specific ownership or precedence note.+pub fn session_schema_with(note: &str) -> Value {+ let mut schema = session_schema();+ schema["description"] = Value::String(format!(+ "{} {note}",+ cua_driver_contract::MULTI_CALL_SESSION_DESCRIPTION+ ));+ schema+}+/// `delivery_mode` — the best-effort-background ladder rung. The prose varies by/// tool (the surface it injects through differs), so callers may pass their own/// `description`; the shape is fixed here.@@ -169,6 +179,33 @@ fn structural(schema: &Value) -> Value {Value::Object(out)}+fn session_guidance_is_exempt(tool_name: &str) -> bool {+ matches!(+ tool_name,+ "start_session"+ | "end_session"+ | "get_session"+ | "get_session_state"+ | "list_sessions"+ | "escalate_session"+ | "set_agent_cursor_enabled"+ | "set_agent_cursor_motion"+ | "set_agent_cursor_theme"+ | "get_agent_cursor_state"+ )+}++fn session_description_has_multi_call_guidance(schema: &Value) -> bool {+ schema+ .get("description")+ .and_then(Value::as_str)+ .map(|description| description.split_whitespace().collect::<Vec<_>>().join(" "))+ .is_some_and(|description| {+ description.contains("prefer a short public session label")+ && description.contains("repeat it on every call that accepts it")+ })+}+/// Check one tool's `input_schema` against the shared canon. Returns a list of/// human-readable violation strings (empty == consistent). Each platform calls/// this for every tool in its registry from a test.@@ -186,6 +223,15 @@ pub fn shared_schema_violations(tool_name: &str, input_schema: &Value) -> Vec<St));}}+ if pname == "session"+ && !session_guidance_is_exempt(tool_name)+ && !session_description_has_multi_call_guidance(pschema)+ {+ violations.push(format!(+ "{tool_name}.session: description must prefer a short public session label \+ for multi-call work and tell callers to repeat it on every accepting call"+ ));+ }}}@@ -225,6 +271,41 @@ mod tests {assert_eq!(s, json!({ "type": "string", "enum": ["a", "b"] }));}+ #[test]+ fn session_description_prefers_named_multi_call_runs() {+ let schema = session_schema();+ let description = schema["description"]+ .as_str()+ .expect("session schema should carry agent guidance");+ assert!(description.contains("prefer a short public session label"));+ assert!(description.contains("repeat it on every call that accepts it"));+ assert!(description.contains("implicit lifecycle session"));+ }++ #[test]+ fn action_session_description_without_repeat_guidance_is_flagged() {+ let tool = json!({+ "type": "object",+ "properties": {+ "session": { "type": "string", "description": "Optional session id." }+ }+ });+ let violations = shared_schema_violations("clipboard_write", &tool);+ assert_eq!(violations.len(), 1);+ assert!(violations[0].contains("repeat it on every accepting call"));+ }++ #[test]+ fn lifecycle_session_tools_keep_resource_specific_descriptions() {+ let tool = json!({+ "type": "object",+ "properties": {+ "session": { "type": "string", "description": "Public label to end." }+ }+ });+ assert!(shared_schema_violations("end_session", &tool).is_empty());+ }+#[test]fn matching_param_with_different_prose_passes() {// Same shape, different description → no violation.diff --git a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs b/libs/cua-driver/rust/crates/cua-driver/src/serve.rsindex e37ea88180..5fdd982701 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/serve.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/serve.rs@@ -2256,8 +2256,8 @@ mod gate_tests {let start = DaemonRequest {method: "call".into(),name: Some("start_session".into()),- // Session policy is caller-declared. The transport session id is- // cleanup/ownership metadata and must not grant policy authority.+ // The public lifecycle label is caller-declared. The transport+ // session id is cleanup metadata and cannot grant authority.args: Some(serde_json::json!({ "session": s3b.clone() })),session_id: Some(s3b),observation_origin: None,diff --git a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs b/libs/cua-driver/rust/crates/cua-driver/src/skills.rsindex 5e9e0bbf3a..27858cf2e8 100644--- a/libs/cua-driver/rust/crates/cua-driver/src/skills.rs+++ b/libs/cua-driver/rust/crates/cua-driver/src/skills.rs@@ -911,6 +911,56 @@ mod tests {}}+ #[test]+ fn bundled_skill_keeps_sessions_and_authorization_as_separate_concepts() {+ let crate_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));+ let skill = std::fs::read_to_string(crate_dir.join("../../Skills/cua-driver/SKILL.md"))+ .expect("canonical skill must be readable");+ let browser = std::fs::read_to_string(crate_dir.join("../../Skills/cua-driver/BROWSER.md"))+ .expect("canonical browser skill must be readable");++ for required in [+ "Choose the target on each action",+ "transport's implicit session",+ "prefer a short public",+ "pass the same label on every call that accepts it",+ "Passing it once is not sticky",+ "revive a name after",+ "There is no `deescalate_session`",+ "--capability-manifest",+ "--approve-capability-manifest",+ "It can remove tools or typed resources",+ "permission authority. A public session",+ ] {+ assert!(+ skill.contains(required),+ "skill lost required lifecycle/authorization guidance: {required}"+ );+ }+ for forbidden in [+ "one-way session phase",+ "if session policy allows",+ "Pass `session` on the first action",+ ] {+ assert!(+ !skill.contains(forbidden),+ "skill restored stale session-state guidance: {forbidden}"+ );+ }+ for required in [+ "start_session(session?)",+ "optional; can name before acting",+ "prefer a short `session` label",+ "Passing it once is not sticky",+ "one-shot CLI calls use disposable transports",+ ] {+ assert!(+ browser.contains(required),+ "browser skill lost required session guidance: {required}"+ );+ }+ }+#[test]fn extract_flat_tarball_v_0_2_20_plus() {// Post-fix shape: one wrapper dir, files directly under it.diff --git a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rsindex 4e2f091e14..046592ba68 100644--- a/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-linux/src/tools/impl_.rs@@ -5383,7 +5383,9 @@ impl Tool for MouseButtonDownTool {Does not release the button; pair with mouse_drag / mouse_button_up. \Returns the current held-button state.".into(),input_schema: json!({"type":"object","required":["pid","window_id","x","y"],"properties":{- "session":{"type":"string","description":"Optional multi-cursor session id; takes precedence over cursor_id."},+ "session": cua_driver_core::tool_schema::session_schema_with(+ "When both are present, session takes precedence over cursor_id."+ ),"cursor_id":{"type":"string","description":"Optional multi-cursor instance id. Default: 'default'."},"pid":{"type":"integer"},"window_id":{"type":"integer"},@@ -5531,7 +5533,9 @@ impl Tool for MouseDragTool {Requires an active mouse_button_down state; does not release the button. \Returns the updated held-button state.".into(),input_schema: json!({"type":"object","required":["x","y"],"properties":{- "session":{"type":"string","description":"Optional multi-cursor session id; takes precedence over cursor_id."},+ "session": cua_driver_core::tool_schema::session_schema_with(+ "When both are present, session takes precedence over cursor_id."+ ),"cursor_id":{"type":"string","description":"Optional multi-cursor instance id. Default: 'default'."},"pid":{"type":"integer"},"window_id":{"type":"integer"},@@ -5735,7 +5739,9 @@ impl Tool for MouseButtonUpTool {description: "Release a previously-held mouse button via background X11 delivery. \If x/y are omitted, releases at the last held position. Returns the current held-button state.".into(),input_schema: json!({"type":"object","properties":{- "session":{"type":"string","description":"Optional multi-cursor session id; takes precedence over cursor_id."},+ "session": cua_driver_core::tool_schema::session_schema_with(+ "When both are present, session takes precedence over cursor_id."+ ),"cursor_id":{"type":"string","description":"Optional multi-cursor instance id. Default: 'default'."},"pid":{"type":"integer"},"window_id":{"type":"integer"},@@ -6274,7 +6280,7 @@ impl Tool for GetDesktopStateTool {Use its native-size PNG as the coordinate source for actions whose target is \{kind:\"desktop\",display_id:\"primary\"}. No AT-SPI walk.".into(),input_schema: json!({"type":"object","properties":{- "session":{"type":"string","description":"Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session."},+ "session":{"type":"string","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."},"screenshot_out_file":{"type":"string","description":"Write PNG here instead of base64."}},"additionalProperties":false}),read_only: true, destructive: false, idempotent: false, open_world: false,diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rsindex 8faa6c24df..26b45ef591 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/click.rs@@ -159,7 +159,7 @@ fn def() -> &'static ToolDef {// cua_driver_core::tool_schema.)"required": [],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"window_id": { "type": "integer", "description": "Target window ID. Required for element_index. Optional when element_token is supplied (the token carries it)." },"element_index": cua_driver_core::tool_schema::element_index_schema(),diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/double_click.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/double_click.rsindex c3ae1439ce..02aa54a9e9 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/double_click.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/double_click.rs@@ -48,7 +48,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["pid"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer" },"x": { "type": "number", "description": "Screen X coordinate (pixel path)." },"y": { "type": "number", "description": "Screen Y coordinate (pixel path)." },diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rsindex 62c9d1aadc..f5eb9d0395 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/drag.rs@@ -56,7 +56,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["from_x", "from_y", "to_x", "to_y"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"window_id": {"type": "integer",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_desktop_state.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_desktop_state.rsindex 5bb1a51cef..652a372ade 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_desktop_state.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_desktop_state.rs@@ -36,7 +36,7 @@ fn def() -> &'static ToolDef {input_schema: serde_json::json!({"type": "object","properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"screenshot_out_file": { "type": "string", "description": "Write PNG here instead of base64." }},"additionalProperties": falsediff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rsindex e32a8dbbe0..378023c169 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/get_window_state.rs@@ -74,7 +74,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["pid", "window_id"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"window_id": { "type": "integer", "description": "Target window ID from list_windows." },"query": { "type": "string", "description": "Case-insensitive filter for tree_markdown and structured elements. Returns matching actionable rows plus their actionable ancestors without renumbering element_index values." },diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rsindex b907d7b2d0..685bf9e31c 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/hotkey.rs@@ -61,7 +61,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["keys"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"keys": {"type": "array",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rsindex 59bc55f4b8..64917854a9 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/move_cursor.rs@@ -32,7 +32,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["x", "y"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"x": { "type": "number" },"y": { "type": "number" },"scope": { "type": "string", "enum": ["window", "desktop"], "default": "window" },diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/press_key.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/press_key.rsindex 6854393ec0..8378796e41 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/press_key.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/press_key.rs@@ -200,7 +200,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["key"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer" },"key": { "type": "string", "description": "Key name: return, tab, escape, up, down, etc." },"modifiers": {diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/right_click.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/right_click.rsindex 112b0b2339..723155f5b7 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/right_click.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/right_click.rs@@ -43,7 +43,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["pid"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"element_index": cua_driver_core::tool_schema::element_index_schema(),"element_token": cua_driver_core::tool_schema::element_token_schema(),diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rsindex 33f1b67d91..3ac5b1477c 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/scroll.rs@@ -79,7 +79,7 @@ fn def() -> &'static ToolDef {// schema — keeps the contract consistent across platforms."required": ["direction"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer" },"direction": {"type": "string",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rsindex d91f3c6ece..449f6306fe 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/set_value.rs@@ -64,7 +64,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["pid", "value"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer" },"window_id": {"type": "integer",diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rsindex b92a02a9cd..90c8ac4a53 100644--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/type_text.rs@@ -90,7 +90,7 @@ fn def() -> &'static ToolDef {"type": "object","required": ["text"],"properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"pid": { "type": "integer", "description": "Target process ID." },"text": { "type": "string", "description": "Text to insert at the target's cursor." },"window_id": {diff --git a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rsindex a1ca333b17..e2b91730d1 100644--- a/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs+++ b/libs/cua-driver/rust/crates/platform-windows/src/tools/impl_.rs@@ -7268,7 +7268,7 @@ impl Tool for GetDesktopStateTool {input_schema: json!({"type": "object","properties": {- "session": { "type": "string", "description": "Optional public session label. Omit it to use the authenticated transport's implicit lifecycle session." },+ "session": { "type": "string", "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." },"screenshot_out_file": { "type": "string", "description": "Write PNG here instead of base64." }},"additionalProperties": falsediff --git a/libs/cua-driver/scripts/post-install-hints.txt b/libs/cua-driver/scripts/post-install-hints.txtindex 6f60dba184..a113cedcf2 100644--- a/libs/cua-driver/scripts/post-install-hints.txt+++ b/libs/cua-driver/scripts/post-install-hints.txt@@ -91,10 +91,11 @@ Next steps:• To use an existing logged-in Chrome or Edge profile in standard:{{BINARY}} mcp --grant existing-profileAdd the same flag to `serve` when using a long-running daemon.- • Use bounded with a reviewed manifest to limit tools, apps, browser- profiles, origins, and file roots:+ • Use a reviewed capability manifest to limit tools, apps, browser+ profiles, origins, and file roots. Bounded requires one:{{BINARY}} serve --permission-mode bounded \- --session-policy ./cua-session.yaml --approve-session-policy+ --capability-manifest ./cua-capabilities.yaml \+ --approve-capability-manifest• unrestricted requires explicit risk acceptance:{{BINARY}} serve --permission-mode unrestricted \--dangerously-bypass-approvalsdiff --git a/libs/cua-driver/typescript/src/native/cua_driver_contract.ts b/libs/cua-driver/typescript/src/native/cua_driver_contract.tsindex c95b948ea4..48aaa34a5b 100644--- a/libs/cua-driver/typescript/src/native/cua_driver_contract.ts+++ b/libs/cua-driver/typescript/src/native/cua_driver_contract.ts@@ -711,7 +711,8 @@ export type ClickInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string,button?: ClickButton,@@ -778,7 +779,8 @@ export type ClipboardReadInput = {*/includeText: boolean,/**- * Optional session id.+ * 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.*/session?: string}@@ -890,7 +892,8 @@ export type ClipboardWriteInput = {*/filePath?: string,/**- * Optional session id.+ * 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.*/session?: string}@@ -1367,7 +1370,8 @@ export type DragInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string,durationMs?: bigint,@@ -1823,7 +1827,8 @@ const FfiConverterTypeGetAgentCursorStateOutput = (() => {export type GetCursorPositionInput = {/**- * Optional session id.+ * 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.*/session?: string}@@ -1865,7 +1870,8 @@ const FfiConverterTypeGetCursorPositionInput = (() => {export type GetDesktopStateInput = {/**- * Optional session id.+ * 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.*/session?: string,/**@@ -1914,7 +1920,8 @@ const FfiConverterTypeGetDesktopStateInput = (() => {export type GetScreenSizeInput = {/**- * Optional session id.+ * 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.*/session?: string}@@ -2048,7 +2055,8 @@ export type HotkeyInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string}@@ -2107,7 +2115,8 @@ export type InvokeMenuInput = {windowId: bigint,path: Array<string>,/**- * Optional session id.+ * 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.*/session?: string}@@ -2440,7 +2449,8 @@ export type MoveCursorInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string}@@ -2630,7 +2640,8 @@ export type PressKeyInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string,modifiers?: Array<string>@@ -2757,7 +2768,8 @@ export type ScrollInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string,by?: ScrollBy,@@ -3245,7 +3257,8 @@ export type SetWindowFrameInput = {width: number,height: number,/**- * Optional session id.+ * 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.*/session?: string}@@ -3507,7 +3520,8 @@ export type TypeTextInput = {*/scope?: DesktopScope,/**- * Optional session id.+ * 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.*/session?: string}@@ -3570,8 +3584,9 @@ export type VerifyStateInput = {*/expect: Array<StatePredicate>,/**- * Optional public session label for lifecycle continuity. It never selects- * capture modality or authorization.+ * 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. This+ * field never selects capture modality or authorization.*/session?: string,/**