Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs(cua-driver-rs)(launch_app): surface creates_new_application_instance for concurrent multi-agent isolation (#1797)

Francesco Bonacci4c54f43ffd9a
diff --git a/docs/content/docs/cua-driver/reference/mcp-tools.mdx b/docs/content/docs/cua-driver/reference/mcp-tools.mdx
index 35940dced1..1187ec4439 100644
--- a/docs/content/docs/cua-driver/reference/mcp-tools.mdx
+++ b/docs/content/docs/cua-driver/reference/mcp-tools.mdx
@@ -131,7 +131,7 @@ Optional `electron_debugging_port`: opens a Chrome DevTools Protocol (CDP) serve
Optional `webkit_inspector_port`: opens a WebKit inspector server on the specified port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). Use this for Tauri/WebKit-based apps.
-Optional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open).
+Optional `creates_new_application_instance`: when true, forces a new app instance even if one is already running (passes -n to open). Reach for this in **concurrent multi-agent/multi-session** work — it returns a fresh pid + window so each session drives its own isolated window. Without it, single-instance apps (Calculator, many utilities) hand every caller the same window, so two sessions clobber each other.
Optional `additional_arguments`: extra argv strings appended after --args.
@@ -141,7 +141,7 @@ Returns the launched app's pid, bundle_id, name, and a `windows` array (same sha
- `additional_arguments` (array of string, optional): Extra arguments appended after --args when launching.
- `bundle_id` (string, optional): App bundle identifier, e.g. com.apple.calculator. Preferred over name.
-- `creates_new_application_instance` (boolean, optional): When true, force a new app instance even if already running (open -n).
+- `creates_new_application_instance` (boolean, optional): When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one (which makes the sessions clobber each other on single-instance apps).
- `electron_debugging_port` (integer, optional): Open a Chrome DevTools Protocol server on this port (appends --remote-debugging-port=N).
- `name` (string, optional): App display name. Used only when bundle_id is absent.
- `urls` (array of string, optional): Optional file paths or URLs to open with the app (e.g. a folder path for Finder).
diff --git a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
index cfcb7649bc..108ba652fb 100644
--- a/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
+++ b/libs/cua-driver/rust/Skills/cua-driver/SKILL.md
@@ -248,6 +248,15 @@ launch_app(target)
common case collapses to two calls (`launch_app` → `get_window_state`)
without a separate `list_windows` hop.
+**Concurrent sessions:** `launch_app` is idempotent — two sessions that
+launch the same app get the **same** instance (and on single-instance
+apps like Calculator, the same window), so they clobber each other. If
+another agent or session may drive the same app at the same time, pass
+`creates_new_application_instance: true` to get your own isolated
+instance + window. The cache and the per-session cursor are keyed on
+`(pid, window_id)`, so distinct instances keep the two sessions fully
+separated.
+
`list_apps` is for app-level discovery (answering "what's installed /
running / frontmost?") — not part of the core action loop. Skip it
in the loop. For **window-level** questions — "does this app have a
diff --git a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs
index 8506789a73..4894b28eae 100644
--- a/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs
+++ b/libs/cua-driver/rust/crates/platform-macos/src/tools/launch_app.rs
@@ -23,7 +23,11 @@ fn def() -> &'static ToolDef {
port (sets WEBKIT_INSPECTOR_SERVER=127.0.0.1:N + TAURI_WEBVIEW_AUTOMATION=1). \
Use this for Tauri/WebKit-based apps.\n\n\
Optional `creates_new_application_instance`: when true, forces a new app instance \
- even if one is already running (passes -n to open).\n\n\
+ even if one is already running (passes -n to open). Reach for this when another \
+ agent or session may drive the SAME app concurrently — it returns a fresh pid + \
+ window so each session acts on its own isolated window instead of clobbering one \
+ shared instance. Without it, single-instance apps (Calculator, many utilities) hand \
+ every caller the same window, so two sessions fight over it.\n\n\
Optional `additional_arguments`: extra argv strings appended after --args.\n\n\
Returns the launched app's pid, bundle_id, name, and a `windows` array \
(same shape as `list_windows`) so callers can skip an extra round-trip before \
@@ -58,7 +62,7 @@ fn def() -> &'static ToolDef {
},
"creates_new_application_instance": {
"type": "boolean",
- "description": "When true, force a new app instance even if already running (open -n)."
+ "description": "When true, force a new app instance even if already running (open -n). Use for concurrent multi-agent/multi-session work so each session gets an isolated instance + window instead of sharing one — on single-instance apps (e.g. Calculator) every caller otherwise gets the same window and the sessions clobber each other."
},
"additional_arguments": {
"type": "array",