Skip to content

armgit / cua

Public Imported from GitHub
0

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

feat(platform-macos): port focus-steal prevention from Swift (macOS-Rust GA blocker) (#1524)

Francesco Bonacci63be0affdeb2
diff --git a/libs/cua-driver-rs/Cargo.lock b/libs/cua-driver-rs/Cargo.lock
index 1779741749..cd1f8638d5 100644
--- a/libs/cua-driver-rs/Cargo.lock
+++ b/libs/cua-driver-rs/Cargo.lock
@@ -88,6 +88,12 @@ dependencies = [
"objc2",
]
+[[package]]
+name = "bumpalo"
+version = "3.20.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
+
[[package]]
name = "bytemuck"
version = "1.25.0"
@@ -207,7 +213,7 @@ dependencies = [
[[package]]
name = "cua-driver"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"async-trait",
@@ -227,7 +233,7 @@ dependencies = [
[[package]]
name = "cursor-overlay"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"image",
@@ -325,7 +331,7 @@ checksum = "98de4bbd547a563b716d8dfa9aad1cb19bfab00f4fa09a6a4ed21dbcf44ce9c4"
[[package]]
name = "focus-monitor-win"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"windows",
]
@@ -559,6 +565,18 @@ version = "1.0.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+[[package]]
+name = "js-sys"
+version = "0.3.98"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67df7112613f8bfd9150013a0314e196f4800d3201ae742489d999db2f979f08"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "once_cell",
+ "wasm-bindgen",
+]
+
[[package]]
name = "kurbo"
version = "0.11.3"
@@ -626,7 +644,7 @@ dependencies = [
[[package]]
name = "mcp-server"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"async-trait",
@@ -900,7 +918,7 @@ checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e"
[[package]]
name = "platform-linux"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"async-trait",
@@ -919,11 +937,12 @@ dependencies = [
[[package]]
name = "platform-macos"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"async-trait",
"base64",
+ "block2",
"core-foundation",
"core-graphics",
"cursor-overlay",
@@ -943,11 +962,12 @@ dependencies = [
"tokio",
"tokio-tungstenite",
"tracing",
+ "uuid",
]
[[package]]
name = "platform-windows"
-version = "0.1.2"
+version = "0.1.3"
dependencies = [
"anyhow",
"async-trait",
@@ -1137,6 +1157,12 @@ dependencies = [
"windows-sys",
]
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
[[package]]
name = "rustybuzz"
version = "0.18.0"
@@ -1671,6 +1697,17 @@ version = "0.7.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09cc8ee72d2a9becf2f2febe0205bbed8fc6615b7cb429ad062dc7b7ddd036a9"
+[[package]]
+name = "uuid"
+version = "1.23.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"
+dependencies = [
+ "getrandom 0.4.2",
+ "js-sys",
+ "wasm-bindgen",
+]
+
[[package]]
name = "valuable"
version = "0.1.1"
@@ -1713,6 +1750,51 @@ dependencies = [
"wit-bindgen 0.51.0",
]
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.121"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "49ace1d07c165b0864824eee619580c4689389afa9dc9ed3a4c75040d82e6790"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.121"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e68e6f4afd367a562002c05637acb8578ff2dea1943df76afb9e83d177c8578"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.121"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d95a9ec35c64b2a7cb35d3fead40c4238d0940c86d107136999567a4703259f2"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.121"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4e0100b01e9f0d03189a92b96772a1fb998639d981193d7dbab487302513441"
+dependencies = [
+ "unicode-ident",
+]
+
[[package]]
name = "wasm-encoder"
version = "0.244.0"
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.md
index 9ff1dc1f6a..0bf07cf3e1 100644
--- a/libs/cua-driver-rs/PARITY.md
+++ b/libs/cua-driver-rs/PARITY.md
@@ -38,7 +38,7 @@ Format per entry:
```
## <surface>
- Swift: <path:line>
-- Rust: macos=<path:line>, windows=<path:line>, linux=<path:line>
+- Rust: macOS=<path:line>, windows=<path:line>, linux=<path:line>
- Status: VERIFIED | INTENTIONAL_DIVERGENCE | OPEN
- Test: <path>
- Notes: ...
@@ -49,7 +49,7 @@ Format per entry:
## MCP tool: `move_cursor`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/MoveCursorTool.swift:6-60`
- Rust:
- - macos=`crates/platform-macos/src/tools/move_cursor.rs`
+ - macOS=`crates/platform-macos/src/tools/move_cursor.rs`
- windows=`crates/platform-windows/src/tools/impl_.rs` (MoveCursorTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (MoveCursorTool)
- Status: INTENTIONAL_DIVERGENCE (semantic) + VERIFIED (overlay behavior)
@@ -102,7 +102,7 @@ Unix socket).
## MCP tool: `get_cursor_position`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/GetCursorPositionTool.swift:6-37`
- Rust:
- - macos=`crates/platform-macos/src/tools/get_cursor_position.rs`
+ - macOS=`crates/platform-macos/src/tools/get_cursor_position.rs`
- windows=`crates/platform-windows/src/tools/impl_.rs` (GetCursorPositionTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (GetCursorPositionTool)
- Status: VERIFIED
@@ -146,7 +146,7 @@ documented Swift behavior.
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/GetScreenSizeTool.swift:6-46`
+ `libs/cua-driver/Sources/CuaDriverCore/Capture/ScreenInfo.swift`
- Rust:
- - macos=`crates/platform-macos/src/tools/get_screen_size.rs`
+ - macOS=`crates/platform-macos/src/tools/get_screen_size.rs`
- windows=`crates/platform-windows/src/tools/impl_.rs` (GetScreenSizeTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (GetScreenSizeTool)
- Status: VERIFIED
@@ -190,11 +190,11 @@ still matches Swift exactly.
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/CheckPermissionsTool.swift:6-59`
+ `libs/cua-driver/Sources/CuaDriverCore/Permissions/Permissions.swift`
- Rust:
- - macos=`crates/platform-macos/src/tools/check_permissions.rs` (FIXED, pending macOS run)
+ - macOS=`crates/platform-macos/src/tools/check_permissions.rs` (FIXED, pending macOS run)
- windows=`crates/platform-windows/src/tools/impl_.rs` (CheckPermissionsTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (CheckPermissionsTool)
- Status:
- - macos: OPEN (fixed in source; macOS runner needed to verify)
+ - macOS: OPEN (fixed in source; macOS runner needed to verify)
- windows / linux: INTENTIONAL_DIVERGENCE
- Test: TODO macOS — needs a macOS machine or CI runner to drive the daemon
and assert the text format + structured response.
@@ -246,11 +246,11 @@ status).
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ListAppsTool.swift:6-71`
+ `libs/cua-driver/Sources/CuaDriverCore/Apps/AppInfo.swift`
- Rust:
- - macos=`crates/platform-macos/src/tools/list_apps.rs` + `apps.rs:format_app_list`
+ - macOS=`crates/platform-macos/src/tools/list_apps.rs` + `apps.rs:format_app_list`
- windows=`crates/platform-windows/src/tools/impl_.rs` (ListAppsTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (ListAppsTool)
- Status:
- - macos: code fixed (✅ checkmark added, description copied from Swift); pending macOS run
+ - macOS: code fixed (✅ checkmark added, description copied from Swift); pending macOS run
- windows: VERIFIED (text format + structured shape + `active` flag)
- linux: OPEN (subagent currently fixing pre-existing compile errors)
- Test: `crates/platform-windows/examples/list_apps_parity.rs`
@@ -298,12 +298,12 @@ at least one entry has `active: true` (the foreground app).
## MCP tool: `list_windows`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ListWindowsTool.swift:6-245`
- Rust:
- - macos=`crates/platform-macos/src/tools/list_windows.rs` (TBD audit)
+ - macOS=`crates/platform-macos/src/tools/list_windows.rs` (TBD audit)
- windows=`crates/platform-windows/src/tools/impl_.rs` (ListWindowsTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (ListWindowsTool, blocked behind Linux compile fix)
- Status:
- windows: VERIFIED
- - macos: OPEN (audit pending — macOS port already exists)
+ - macOS: OPEN (audit pending — macOS port already exists)
- linux: OPEN
- Test: `crates/platform-windows/examples/list_windows_parity.rs`
@@ -356,12 +356,12 @@ filter at the tool layer.
## MCP tool: `click`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ClickTool.swift:29-595`
- Rust:
- - macos=`crates/platform-macos/src/tools/click.rs` (TBD audit)
+ - macOS=`crates/platform-macos/src/tools/click.rs` (TBD audit)
- windows=`crates/platform-windows/src/tools/impl_.rs` (ClickTool)
- linux=`crates/platform-linux/src/tools/impl_.rs` (ClickTool)
- Status:
- windows: VERIFIED (text format + error wording); schema divergences documented below
- - macos: OPEN (already exists; line-by-line audit pending)
+ - macOS: OPEN (already exists; line-by-line audit pending)
- linux: OPEN
- Test: `crates/platform-windows/examples/click_parity.rs`
@@ -417,13 +417,15 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/LaunchAppTool.swift:6-490`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (LaunchAppTool)
- - macos=`crates/platform-macos/src/tools/launch_app.rs` (TBD audit)
+ - macOS=`crates/platform-macos/src/tools/launch_app.rs` (full focus-steal contract)
- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD audit)
- Status:
- windows: VERIFIED
- - macos: OPEN
+ - macOS: VERIFIED (full focus-steal contract — see [Focus-steal prevention](#focus-steal-prevention))
- linux: OPEN
-- Test: `crates/platform-windows/examples/launch_app_parity.rs`
+- Tests:
+ - windows=`crates/platform-windows/examples/launch_app_parity.rs`
+ - macOS=`tests/integration/test_focus_steal_parity.py` + `crates/platform-macos/src/focus_steal.rs` (Rust unit tests)
### Fixed (Windows)
@@ -469,15 +471,57 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- `bundle_id: null`, `running: true`, `active: false` ✓
- Notepad killed on test exit. ✓
+### Fixed (macOS)
+
+1. **No more shell-out** — `apps::launch_app`, `launch_app_by_name`, and
+ `launch_with_urls_*` no longer `Command::new("open")`. All paths now
+ call `apps::nsworkspace::open_application` /
+ `open_urls_with_application` directly via objc2-app-kit's
+ `NSWorkspace.openApplication(at:configuration:completionHandler:)`
+ (no-URL) and `open(_:withApplicationAt:configuration:)` (URL-handoff)
+ variants. Matches Swift `AppLauncher.swift:106-131` byte-for-byte in
+ the launch semantics.
+2. **`activates = false` + `addsToRecentItems = false`** — set on every
+ launch via `NSWorkspaceOpenConfiguration`. Mirrors Swift
+ `AppLauncher.swift:65-66`.
+3. **`oapp` AppleEvent descriptor on the no-URL path** — hand-rolled
+ `extern_methods!` block in `apps/nsworkspace.rs` binds
+ `NSAppleEventDescriptor.init(eventClass:eventID:targetDescriptor:returnID:transactionID:)`
+ (not exposed by objc2-foundation 0.2.2). Without this, cold-launches
+ of state-restored apps (Calculator-class) are windowless. Matches
+ Swift `AppLauncher.swift:85-103`.
+4. **3-phase focus-steal wrap** — `LaunchAppTool::invoke` captures the
+ prior frontmost pid, arms a wildcard suppression entry, launches,
+ swaps to a targeted entry (with overlap, not drop-then-begin, to
+ avoid the hoang17 PR #1521 race), sleeps 500ms, drops the lease,
+ and belt-and-braces re-activates the prior frontmost if the target
+ is still on top. Matches Swift `LaunchAppTool.swift:181-281`.
+5. **Direct pid from completion handler** — the `NSRunningApplication`
+ returned by `openApplication` is used directly; no `list_running_apps`
+ scan-and-match race. Matches Swift.
+6. **Window-resolution retry** — same 5-attempt 100ms retry as before;
+ unchanged.
+
+### Verified on macOS
+
+`tests/integration/test_focus_steal_parity.py` covers:
+- Passive app launch (Calculator) — frontmost unchanged ✓
+- Self-activating app launch (Safari) — frontmost restored within 1.5s ✓
+- Launch with `urls=["about:blank"]` — frontmost preserved ✓
+- Cold launch creates a window (verifies the `oapp` AppleEvent) ✓
+- Back-to-back launches don't leak suppression state across calls ✓
+- 5s deadline reaper evicts leaked entries ✓ (Rust unit test
+ `focus_steal::tests::deadline_reaps_leaked_entry`)
+
---
## MCP tool: `press_key`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift:20-202`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (PressKeyTool)
- - macos=`crates/platform-macos/src/tools/press_key.rs` (TBD)
+ - macOS=`crates/platform-macos/src/tools/press_key.rs` (TBD)
- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)
-- Status: windows VERIFIED; macos / linux OPEN
+- Status: windows VERIFIED; macOS / linux OPEN
- Test: `crates/platform-windows/examples/press_key_parity.rs`
### Fixed (Windows)
@@ -519,9 +563,9 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift:6-142`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (HotkeyTool)
- - macos=`crates/platform-macos/src/tools/hotkey.rs` (TBD)
+ - macOS=`crates/platform-macos/src/tools/hotkey.rs` (TBD)
- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)
-- Status: windows VERIFIED; macos / linux OPEN
+- Status: windows VERIFIED; macOS / linux OPEN
- Test: `crates/platform-windows/examples/hotkey_parity.rs`
### Fixed (Windows)
@@ -552,7 +596,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/DoubleClickTool.swift:28-327`
- Rust:
- windows=`crates/platform-windows/src/tools/impl_.rs` (DoubleClickTool)
- - macos / linux: OPEN
+ - macOS / linux: OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/double_click_parity.rs`
@@ -595,7 +639,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `right_click`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/RightClickTool.swift:27-324`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (RightClickTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (RightClickTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/right_click_parity.rs`
@@ -623,7 +667,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `screenshot`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ScreenshotTool.swift:5-170`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ScreenshotTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ScreenshotTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/screenshot_parity.rs`
@@ -659,7 +703,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `scroll`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ScrollTool.swift:23-211`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ScrollTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ScrollTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/scroll_parity.rs`
@@ -697,7 +741,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `type_text`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/TypeTextTool.swift:13-225`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (TypeTextTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (TypeTextTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/type_text_parity.rs`
@@ -732,7 +776,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `set_value`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/SetValueTool.swift:8-336`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (SetValueTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (SetValueTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/set_value_parity.rs`
@@ -769,7 +813,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tools: `get_config` + `set_config`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/GetConfigTool.swift:13-79`
+ `libs/cua-driver/Sources/CuaDriverServer/Tools/SetConfigTool.swift:25-167`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetConfigTool, SetConfigTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetConfigTool, SetConfigTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/config_parity.rs`
@@ -807,7 +851,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tool: `get_agent_cursor_state`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/GetAgentCursorStateTool.swift:9-68`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetAgentCursorStateTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetAgentCursorStateTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/get_agent_cursor_state_parity.rs`
@@ -838,7 +882,7 @@ Windows's `click` takes `{button: enum}` instead. Rationale:
## MCP tools: `set_agent_cursor_enabled` + `set_agent_cursor_motion`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorEnabledTool.swift:8-85`
+ `libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorMotionTool.swift:11-187`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs`; macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs`; macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/agent_cursor_setters_parity.rs`
@@ -961,7 +1005,7 @@ Swift.
## MCP tool: `get_window_state`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/GetWindowStateTool.swift:5-end`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetWindowStateTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (GetWindowStateTool); macOS/linux OPEN
- Status: windows VERIFIED (error wording + validation); response shape already verified
- Test: `crates/platform-windows/examples/get_window_state_parity.rs`
@@ -998,7 +1042,7 @@ Swift.
## MCP tool: `drag`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/DragTool.swift:21-327`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (DragTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (DragTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/drag_parity.rs`
@@ -1106,7 +1150,7 @@ Changes:
## MCP tool: `set_agent_cursor_style`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/SetAgentCursorStyleTool.swift:10-111`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (SetAgentCursorStyleTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (SetAgentCursorStyleTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/set_agent_cursor_style_parity.rs`
@@ -1127,7 +1171,7 @@ Changes:
## MCP tool: `zoom`
- Swift: `libs/cua-driver/Sources/CuaDriverServer/Tools/ZoomTool.swift:12-end`
-- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ZoomTool); macos/linux OPEN
+- Rust: windows=`crates/platform-windows/src/tools/impl_.rs` (ZoomTool); macOS/linux OPEN
- Status: windows VERIFIED
- Test: `crates/platform-windows/examples/zoom_parity.rs`
@@ -1233,3 +1277,70 @@ Now uses prefix `cua-driver-rs-v` (Rust port's actual tag prefix).
- `--type=mcp`: top-level `{version, tools}` ✓
- `--type=cli`: stub section ✓
- `--pretty`: multi-line JSON (991 lines) ✓
+
+---
+
+## Focus-steal prevention
+
+Cross-cutting infrastructure (not an MCP tool) used by `launch_app` today
+and slated for use by `click`/`hotkey`/AX-action tools when those are
+ported to Rust macOS. Catches apps that self-activate during launch
+(Chrome, Electron, Safari) and re-activates the prior frontmost app
+before the user perceives the steal.
+
+- Swift: `libs/cua-driver/Sources/CuaDriverCore/Focus/SystemFocusStealPreventer.swift`
+- Swift hardening: open PR [#1521](https://github.com/trycua/cua/pull/1521)
+ (4-layer leak prevention: closure scope, RAII lease, 5s monotonic
+ deadline, 1s janitor)
+- Rust: `crates/platform-macos/src/focus_steal.rs`
+- Status: macOS VERIFIED. windows/linux N/A (no equivalent OS focus-steal
+ surface area).
+- Tests:
+ - Rust unit: `crates/platform-macos/src/focus_steal.rs` `#[cfg(test)] mod tests`
+ — dispatcher add/remove/match, deadline reap, janitor start/stop
+ lifecycle.
+ - Integration: `tests/integration/test_focus_steal_parity.py` — runs
+ against both Swift and Rust binaries with `expectedFailure` on the
+ Swift Safari-URL case for the known Cryptex+`oapp` LaunchServices bug.
+
+### Design
+
+- Process-wide singleton (`OnceLock<Arc<FocusStealPreventer>>`) — mirrors
+ Swift's `AppStateRegistry.systemFocusStealPreventer`.
+- One `NSWorkspaceDidActivateApplicationNotification` observer, registered
+ on a **fresh background `NSOperationQueue`** (not `mainQueue`). This is
+ load-bearing: the binary's `Call` and `--no-overlay` Serve modes don't
+ run an NSApplication main-thread run loop, so an observer on `mainQueue`
+ would silently no-op. Background queue means the block fires regardless
+ of run-loop state.
+- Dispatcher: `Mutex<HashMap<Uuid, SuppressionEntry>>` where each entry is
+ `(target_pid: Option<i32>, restore_to: i32, deadline: Instant, origin)`.
+ `target_pid = None` is the wildcard (catches any activation other than
+ `restore_to`).
+- API:
+ - Closure: `with_suppression(target_pid, restore_to, origin, async fn)`.
+ - RAII: `begin_suppression(...) -> SuppressionLease`, `Drop` calls
+ `end_suppression` synchronously.
+- Deadline reaper: each entry stamped `Instant::now() + 5s`. Pruned on
+ every observer fire and by a 1s tokio interval task gated by a
+ `watch::Sender` (start on first-add, stop on last-remove). Mirrors
+ PR #1521's deadline + janitor layers; RAII (`SuppressionLease`)
+ subsumes Swift's `withSuppression` (layer 1) + `SuppressionLease`
+ (layer 2) into one Rust idiom.
+- Restore: when a notification matches an entry, the observer block
+ resolves `NSRunningApplication::runningApplicationWithProcessIdentifier(restore_to)`
+ and calls `activate(options:[])`. `-[NSRunningApplication activate:]`
+ is documented thread-safe — no main-thread hop needed.
+
+### Intentional simplifications vs Swift
+
+- **No `FocusGuard.withFocusSuppressed` analogue yet** — Swift's
+ per-AX-action wrapper. The Rust `click` AX path doesn't exist yet, so
+ there's nothing to wrap. Port when the AX action path lands.
+- **No `WindowChangeDetector` analogue yet** — same reason; the Rust port
+ has no snapshot/detect cycle to wrap. Port when WindowChangeDetector
+ lands.
+- **Janitor uses `tokio::sync::watch`** — Swift uses Task cancellation;
+ Rust's tokio idiom is the watch-channel select pattern. Behavior is
+ identical: idle dispatcher → janitor sleeps; new entry → janitor
+ wakes; map drains → janitor exits and waits for the next add.
diff --git a/libs/cua-driver-rs/crates/platform-macos/Cargo.toml b/libs/cua-driver-rs/crates/platform-macos/Cargo.toml
index da75e504f8..5559635474 100644
--- a/libs/cua-driver-rs/crates/platform-macos/Cargo.toml
+++ b/libs/cua-driver-rs/crates/platform-macos/Cargo.toml
@@ -13,6 +13,7 @@ tracing = { workspace = true }
base64 = { workspace = true }
image = { workspace = true }
async-trait = "0.1"
+uuid = { workspace = true }
mcp-server = { path = "../mcp-server" }
cursor-overlay = { path = "../cursor-overlay" }
@@ -22,16 +23,21 @@ core-foundation = "0.10"
core-graphics = { version = "0.24", features = ["highsierra", "elcapitan"] }
foreign-types = "0.5"
libc = "0.2"
+block2 = "0.5"
# objc2 and its AppKit/CoreFoundation bindings
objc2 = "0.5"
objc2-foundation = { version = "0.2", features = [
"NSArray", "NSString", "NSDictionary", "NSRunLoop",
"NSThread", "NSObject", "NSValue",
+ "NSAppleEventDescriptor", "NSNotification", "NSOperation",
+ "NSURL", "NSDate", "NSError",
+ "block2", "libc",
] }
objc2-app-kit = { version = "0.2", features = [
"NSApplication", "NSWindow", "NSScreen", "NSColor",
"NSEvent", "NSRunningApplication", "NSWorkspace",
"NSView", "NSGraphicsContext", "NSResponder",
+ "block2", "libc",
] }
# QuartzCore for CALayer
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/apps.rs b/libs/cua-driver-rs/crates/platform-macos/src/apps.rs
deleted file mode 100644
index 3c1b4cfc59..0000000000
--- a/libs/cua-driver-rs/crates/platform-macos/src/apps.rs
+++ /dev/null
@@ -1,249 +0,0 @@
-//! macOS app enumeration via NSWorkspace and NSRunningApplication.
-
-use std::process::Command;
-use serde::{Deserialize, Serialize};
-
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct AppInfo {
- pub name: String,
- pub pid: i32,
- pub bundle_id: Option<String>,
- pub running: bool,
- pub active: bool,
-}
-
-/// Enumerate running apps with NSApplicationActivationPolicyRegular.
-/// Uses `osascript` to query System Events — no Accessibility permission needed.
-pub fn list_running_apps() -> Vec<AppInfo> {
- // Use `ps` + NSWorkspace via a brief Swift one-liner via swift-sh is heavy;
- // instead use the Obj-C bridge via `osascript`.
- // Fallback: parse `ps -axo pid,command` and cross-reference with bundle IDs.
- // Better: use a native call via core-foundation bindings.
- list_running_apps_native()
-}
-
-fn list_running_apps_native() -> Vec<AppInfo> {
- // Use `lsappinfo list` which is a macOS system tool available on all versions.
- // Alternatively we can use NSWorkspace via objc2 — but for simplicity and
- // to match the Swift reference, we use a subprocess call to `osascript`.
- let script = r#"
-set output to ""
-tell application "System Events"
- set appList to every application process whose background only is false
- repeat with proc in appList
- set procName to name of proc
- set procPid to unix id of proc
- set bundleId to bundle identifier of proc
- if bundleId is missing value then set bundleId to ""
- set isFront to "0"
- if frontmost of proc then set isFront to "1"
- set output to output & procName & "|" & procPid & "|" & bundleId & "|" & isFront & linefeed
- end repeat
-end tell
-return output
-"#;
-
- let out = Command::new("osascript")
- .arg("-e")
- .arg(script)
- .output();
-
- match out {
- Err(_) => vec![],
- Ok(o) => {
- let text = String::from_utf8_lossy(&o.stdout);
- parse_osascript_app_list(&text)
- }
- }
-}
-
-fn parse_osascript_app_list(text: &str) -> Vec<AppInfo> {
- let mut apps = Vec::new();
- for line in text.lines() {
- let parts: Vec<&str> = line.splitn(4, '|').collect();
- if parts.len() < 2 { continue; }
- let name = parts[0].trim().to_owned();
- let pid: i32 = parts[1].trim().parse().unwrap_or(0);
- let bundle_id = if parts.len() > 2 && !parts[2].trim().is_empty() {
- Some(parts[2].trim().to_owned())
- } else {
- None
- };
- let active = parts.get(3).map(|s| s.trim() == "1").unwrap_or(false);
- if name.is_empty() || pid == 0 { continue; }
- apps.push(AppInfo { name, pid, bundle_id, running: true, active });
- }
- apps
-}
-
-/// Launch an app by bundle ID using `open -g -b` (background, no activation).
-/// Returns the pid on success.
-pub fn launch_app(bundle_id: &str) -> anyhow::Result<i32> {
- let status = Command::new("open")
- .args(["-g", "-b", bundle_id])
- .status()?;
- if !status.success() {
- anyhow::bail!("Failed to launch {bundle_id}");
- }
- // Give the app a moment to start.
- std::thread::sleep(std::time::Duration::from_millis(500));
- // Find its pid.
- let apps = list_running_apps();
- for app in &apps {
- if app.bundle_id.as_deref() == Some(bundle_id) {
- return Ok(app.pid);
- }
- }
- anyhow::bail!("Launched {bundle_id} but could not find its pid")
-}
-
-/// Launch an app by display name using `open -g -a AppName` (background, no activation).
-/// Returns the pid on success.
-pub fn launch_app_by_name(name: &str) -> anyhow::Result<i32> {
- let status = Command::new("open")
- .args(["-g", "-a", name])
- .status()?;
- if !status.success() {
- anyhow::bail!("Failed to launch app '{name}'");
- }
- std::thread::sleep(std::time::Duration::from_millis(500));
- let apps = list_running_apps();
- for app in &apps {
- if app.name.eq_ignore_ascii_case(name) {
- return Ok(app.pid);
- }
- }
- anyhow::bail!("Launched '{name}' but could not find its pid")
-}
-
-/// Return all apps: running apps merged with installed-but-not-running apps.
-pub fn list_all_apps() -> Vec<AppInfo> {
- let running = list_running_apps();
- let running_bundles: std::collections::HashSet<String> = running.iter()
- .filter_map(|a| a.bundle_id.clone())
- .collect();
-
- let mut installed = scan_installed_apps();
- // Remove apps already in running list.
- installed.retain(|a| !a.bundle_id.as_ref().map_or(false, |b| running_bundles.contains(b)));
-
- let mut all = running;
- all.extend(installed);
- all
-}
-
-fn scan_installed_apps() -> Vec<AppInfo> {
- let dirs = [
- "/Applications",
- "/Applications/Utilities",
- "/System/Applications",
- "/System/Applications/Utilities",
- ];
- let home = std::env::var("HOME").unwrap_or_default();
- let user_apps = format!("{home}/Applications");
-
- let mut result = Vec::new();
- let mut all_dirs: Vec<&str> = dirs.to_vec();
- let user_apps_str: &str = user_apps.as_str();
- all_dirs.push(user_apps_str);
-
- for dir in all_dirs {
- let Ok(entries) = std::fs::read_dir(dir) else { continue };
- for entry in entries.flatten() {
- let path = entry.path();
- if path.extension().and_then(|e| e.to_str()) != Some("app") { continue }
- let plist_path = path.join("Contents/Info.plist");
- if let Some(info) = read_app_plist(&plist_path) {
- result.push(info);
- }
- }
- }
- result
-}
-
-fn read_app_plist(plist_path: &std::path::Path) -> Option<AppInfo> {
- let bundle_id_out = Command::new("plutil")
- .args(["-extract", "CFBundleIdentifier", "raw", "-o", "-",
- plist_path.to_str()?])
- .output().ok()?;
- if !bundle_id_out.status.success() { return None; }
- let bundle_id = String::from_utf8_lossy(&bundle_id_out.stdout).trim().to_string();
- if bundle_id.is_empty() { return None; }
-
- let name_out = Command::new("plutil")
- .args(["-extract", "CFBundleDisplayName", "raw", "-o", "-",
- plist_path.to_str()?])
- .output().ok();
- let name = name_out
- .filter(|o| o.status.success())
- .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
- .filter(|s| !s.is_empty())
- .unwrap_or_else(|| {
- // Fallback: CFBundleName.
- Command::new("plutil")
- .args(["-extract", "CFBundleName", "raw", "-o", "-",
- plist_path.to_str().unwrap_or("")])
- .output().ok()
- .filter(|o| o.status.success())
- .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
- .filter(|s| !s.is_empty())
- .unwrap_or_else(|| {
- plist_path.parent()
- .and_then(|p| p.parent())
- .and_then(|p| p.file_stem())
- .and_then(|s| s.to_str())
- .unwrap_or("")
- .to_string()
- })
- });
-
- if name.is_empty() { return None; }
-
- Some(AppInfo {
- name,
- pid: 0,
- bundle_id: Some(bundle_id),
- running: false,
- active: false,
- })
-}
-
-/// Return the localized application name for a running process by PID.
-/// Uses `ps -p {pid} -o comm=` which gives the command name without path.
-/// Returns `None` if the PID is unknown or the command fails.
-pub fn get_app_name_for_pid(pid: i32) -> Option<String> {
- let out = Command::new("ps")
- .args(["-p", &pid.to_string(), "-o", "comm="])
- .output()
- .ok()?;
- let raw = String::from_utf8_lossy(&out.stdout).trim().to_string();
- if raw.is_empty() {
- return None;
- }
- // Strip path prefix: "/Applications/Safari.app/Contents/MacOS/Safari" → "Safari"
- Some(
- std::path::Path::new(&raw)
- .file_name()
- .and_then(|n| n.to_str())
- .unwrap_or(&raw)
- .to_string(),
- )
-}
-
-/// Format the app list in the same text style as libs/cua-driver.
-pub fn format_app_list(apps: &[AppInfo]) -> String {
- let running: Vec<&AppInfo> = apps.iter().filter(|a| a.running).collect();
- let total = apps.len();
- // Match Swift `ListAppsTool.swift` `summary(_:)` text format 1:1.
- let mut lines = vec![format!(
- "✅ Found {} app(s): {} running, {} installed-not-running.",
- total,
- running.len(),
- total - running.len()
- )];
- for app in &running {
- let bundle = app.bundle_id.as_deref().map(|b| format!(" [{b}]")).unwrap_or_default();
- lines.push(format!("- {} (pid {}){}", app.name, app.pid, bundle));
- }
- lines.join("\n")
-}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/apps/mod.rs b/libs/cua-driver-rs/crates/platform-macos/src/apps/mod.rs
new file mode 100644
index 0000000000..19c197adc2
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/apps/mod.rs
@@ -0,0 +1,485 @@
+//! macOS app enumeration via NSWorkspace and NSRunningApplication.
+
+pub mod nsworkspace;
+
+use std::process::Command;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct AppInfo {
+ pub name: String,
+ pub pid: i32,
+ pub bundle_id: Option<String>,
+ pub running: bool,
+ pub active: bool,
+}
+
+/// Enumerate running apps with NSApplicationActivationPolicyRegular.
+/// Uses `osascript` to query System Events — no Accessibility permission needed.
+pub fn list_running_apps() -> Vec<AppInfo> {
+ // Use `ps` + NSWorkspace via a brief Swift one-liner via swift-sh is heavy;
+ // instead use the Obj-C bridge via `osascript`.
+ // Fallback: parse `ps -axo pid,command` and cross-reference with bundle IDs.
+ // Better: use a native call via core-foundation bindings.
+ list_running_apps_native()
+}
+
+fn list_running_apps_native() -> Vec<AppInfo> {
+ // Use `lsappinfo list` which is a macOS system tool available on all versions.
+ // Alternatively we can use NSWorkspace via objc2 — but for simplicity and
+ // to match the Swift reference, we use a subprocess call to `osascript`.
+ let script = r#"
+set output to ""
+tell application "System Events"
+ set appList to every application process whose background only is false
+ repeat with proc in appList
+ set procName to name of proc
+ set procPid to unix id of proc
+ set bundleId to bundle identifier of proc
+ if bundleId is missing value then set bundleId to ""
+ set isFront to "0"
+ if frontmost of proc then set isFront to "1"
+ set output to output & procName & "|" & procPid & "|" & bundleId & "|" & isFront & linefeed
+ end repeat
+end tell
+return output
+"#;
+
+ let out = Command::new("osascript")
+ .arg("-e")
+ .arg(script)
+ .output();
+
+ match out {
+ Err(_) => vec![],
+ Ok(o) => {
+ let text = String::from_utf8_lossy(&o.stdout);
+ parse_osascript_app_list(&text)
+ }
+ }
+}
+
+fn parse_osascript_app_list(text: &str) -> Vec<AppInfo> {
+ let mut apps = Vec::new();
+ for line in text.lines() {
+ let parts: Vec<&str> = line.splitn(4, '|').collect();
+ if parts.len() < 2 { continue; }
+ let name = parts[0].trim().to_owned();
+ let pid: i32 = parts[1].trim().parse().unwrap_or(0);
+ let bundle_id = if parts.len() > 2 && !parts[2].trim().is_empty() {
+ Some(parts[2].trim().to_owned())
+ } else {
+ None
+ };
+ let active = parts.get(3).map(|s| s.trim() == "1").unwrap_or(false);
+ if name.is_empty() || pid == 0 { continue; }
+ apps.push(AppInfo { name, pid, bundle_id, running: true, active });
+ }
+ apps
+}
+
+/// Launch an app by bundle ID via NSWorkspace, background only (no focus
+/// steal). Returns the pid on success.
+///
+/// Replaces a prior `open -g -b` shell-out. The NSWorkspace path:
+/// * honors `activates = false` so LaunchServices doesn't bring the
+/// target frontmost,
+/// * attaches an `aevt/oapp` AppleEvent descriptor so cold-launched
+/// apps (Calculator, etc) get their window-creation handler invoked
+/// reliably (the shell-out path silently skipped this for state-
+/// restored apps),
+/// * returns the actual `NSRunningApplication.processIdentifier`
+/// without needing a separate `list_running_apps` lookup, so we
+/// can't race a same-bundle-id helper that happens to be running.
+pub fn launch_app(bundle_id: &str) -> anyhow::Result<i32> {
+ // Pass the bundle id straight through — `nsworkspace::resolve_application_url`
+ // calls `URLForApplicationWithBundleIdentifier` and uses the resulting
+ // NSURL verbatim. Going via a `path` string and back loses the
+ // alias/cryptex metadata Safari (and other Cryptex-installed apps)
+ // need to relaunch from `/System/Cryptexes/App/...`.
+ let cfg = nsworkspace::OpenConfig {
+ apple_event_bundle_id: Some(bundle_id.to_owned()),
+ ..Default::default()
+ };
+ let running = nsworkspace::open_application(bundle_id, &cfg)
+ .map_err(|e| anyhow::anyhow!("Failed to launch {bundle_id}: {e}"))?;
+ let pid: i32 = unsafe { running.processIdentifier() };
+ Ok(pid)
+}
+
+/// Launch an app by display name via NSWorkspace. Background-only.
+/// Returns the pid on success.
+///
+/// Mirror of Swift `AppLauncher.locate(name:)`: scan the standard
+/// roots for `<Name>.app`, then fall back to a LaunchServices lookup
+/// in case the caller passed a bundle identifier in the `name` slot.
+pub fn launch_app_by_name(name: &str) -> anyhow::Result<i32> {
+ let located = locate_by_name(name)
+ .ok_or_else(|| anyhow::anyhow!("Could not locate app with name '{name}'"))?;
+ let (app_ref, bid) = located.app_ref_and_bundle_id();
+ let cfg = nsworkspace::OpenConfig {
+ apple_event_bundle_id: bid,
+ ..Default::default()
+ };
+ let running = nsworkspace::open_application(&app_ref, &cfg)
+ .map_err(|e| anyhow::anyhow!("Failed to launch '{name}': {e}"))?;
+ let pid: i32 = unsafe { running.processIdentifier() };
+ Ok(pid)
+}
+
+/// Launch a bundle with URL handoff. Mirrors Swift's
+/// `NSWorkspace.open(urls:withApplicationAt:configuration:)` flow.
+///
+/// `additional_args` and `env` are merged into the `OpenConfig`.
+/// `creates_new_instance` corresponds to AppKit's
+/// `createsNewApplicationInstance = true`.
+pub fn launch_with_urls_by_bundle(
+ bundle_id: &str,
+ urls: &[String],
+ additional_args: &[String],
+ env: &std::collections::HashMap<String, String>,
+ creates_new_instance: bool,
+) -> anyhow::Result<i32> {
+ // Pass the bundle id directly — see `launch_app` rationale above
+ // (Cryptex-installed apps).
+ //
+ // Only attach the `oapp` AppleEvent on the no-URL path. With URLs
+ // present, the URL-handoff path delivers its own `aevt/odoc` to
+ // the target and attaching `oapp` on top causes
+ // openURLs:withApplicationAtURL: to bail with "application not
+ // found" for Cryptex-installed apps (Safari). Verified empirically.
+ let cfg = nsworkspace::OpenConfig {
+ arguments: additional_args.to_vec(),
+ environment: env.clone(),
+ creates_new_instance,
+ apple_event_bundle_id: if urls.is_empty() {
+ Some(bundle_id.to_owned())
+ } else {
+ None
+ },
+ };
+ let running = if urls.is_empty() {
+ nsworkspace::open_application(bundle_id, &cfg)
+ } else {
+ nsworkspace::open_urls_with_application(urls, bundle_id, &cfg)
+ }
+ .map_err(|e| anyhow::anyhow!("Failed to launch {bundle_id}: {e}"))?;
+ let pid: i32 = unsafe { running.processIdentifier() };
+ Ok(pid)
+}
+
+/// Launch by name with URL handoff. Same contract as
+/// `launch_with_urls_by_bundle` but resolves the bundle URL by display
+/// name first.
+pub fn launch_with_urls_by_name(
+ name: &str,
+ urls: &[String],
+ additional_args: &[String],
+ env: &std::collections::HashMap<String, String>,
+ creates_new_instance: bool,
+) -> anyhow::Result<i32> {
+ let located = locate_by_name(name)
+ .ok_or_else(|| anyhow::anyhow!("Could not locate app with name '{name}'"))?;
+ let (app_ref, bid) = located.app_ref_and_bundle_id();
+ // See `launch_with_urls_by_bundle` — skip `oapp` AppleEvent on
+ // the URL-handoff path.
+ let cfg = nsworkspace::OpenConfig {
+ arguments: additional_args.to_vec(),
+ environment: env.clone(),
+ creates_new_instance,
+ apple_event_bundle_id: if urls.is_empty() { bid } else { None },
+ };
+ let running = if urls.is_empty() {
+ nsworkspace::open_application(&app_ref, &cfg)
+ } else {
+ nsworkspace::open_urls_with_application(urls, &app_ref, &cfg)
+ }
+ .map_err(|e| anyhow::anyhow!("Failed to launch '{name}': {e}"))?;
+ let pid: i32 = unsafe { running.processIdentifier() };
+ Ok(pid)
+}
+
+// ── Bundle resolution ────────────────────────────────────────────────────────
+
+/// What `locate_by_name` resolved a display name into.
+///
+/// Two shapes because Cryptex-installed apps (Safari on macOS Sonoma+,
+/// and a growing set of other system apps) live under
+/// `/System/Cryptexes/App/...` — flattening their LaunchServices NSURL
+/// to a filesystem path via `-[NSURL path]` loses the
+/// alias/cryptex metadata LaunchServices needs to relaunch the bundle.
+/// The fix: when the resolver went through LaunchServices, hand the
+/// bundle id back to the launch helpers verbatim — they pass it
+/// straight through to `URLForApplicationWithBundleIdentifier` and
+/// use the resulting NSURL unmodified.
+pub(crate) enum AppLocator {
+ /// Found by filesystem scan (`/Applications/...`, `~/Applications/...`).
+ /// Path-based launch is safe here — these apps aren't Cryptex-installed.
+ Path(String),
+ /// Found via LaunchServices bundle-id lookup. Carry the bundle id
+ /// (NOT the lossy `url.path()`) so the launch helpers re-resolve
+ /// the live NSURL on demand and preserve cryptex metadata.
+ BundleId(String),
+}
+
+impl AppLocator {
+ /// `(app_ref_for_nsworkspace, optional_bundle_id_for_oapp_event)`.
+ ///
+ /// `app_ref` is the string the `nsworkspace::*` helpers consume —
+ /// a filesystem path or a bundle id; either flows through
+ /// `resolve_application_url` correctly. `bundle_id` is `Some(...)`
+ /// when known (either because LaunchServices gave it to us or
+ /// because we read it from the bundle's Info.plist) and `None`
+ /// when it couldn't be determined — callers use it for the `oapp`
+ /// AppleEvent attachment on the no-URL launch path.
+ pub(crate) fn app_ref_and_bundle_id(self) -> (String, Option<String>) {
+ match self {
+ AppLocator::Path(p) => {
+ let bid = bundle_id_for_app_path(&p);
+ (p, bid)
+ }
+ AppLocator::BundleId(bid) => (bid.clone(), Some(bid)),
+ }
+ }
+}
+
+/// Resolve a bundle id to its `AppLocator::BundleId` form.
+///
+/// Returns `None` if LaunchServices can't find an app for the given
+/// bundle id. Note: we deliberately do NOT call `-[NSURL path]` on
+/// the resolved URL — that's the fix for CodeRabbit #3 (Cryptex
+/// relaunch). Callers should pass the bundle id back to the
+/// `nsworkspace::*` helpers, which re-resolve the live NSURL.
+pub(crate) fn resolve_bundle_id_to_locator(bundle_id: &str) -> Option<AppLocator> {
+ use objc2_app_kit::NSWorkspace;
+ use objc2_foundation::NSString;
+ unsafe {
+ let ws = NSWorkspace::sharedWorkspace();
+ let ns = NSString::from_str(bundle_id);
+ // We only care about presence here — the live NSURL is
+ // re-fetched inside `nsworkspace::resolve_application_url`
+ // when the launch actually fires. Returning the bundle id
+ // (not a flattened `url.path()`) preserves the alias/cryptex
+ // metadata Safari needs to relaunch from `/System/Cryptexes/App/...`.
+ let _url = ws.URLForApplicationWithBundleIdentifier(&ns)?;
+ Some(AppLocator::BundleId(bundle_id.to_owned()))
+ }
+}
+
+/// Mirror of Swift's `AppLauncher.locate(name:)`.
+///
+/// 1. filesystem lookup by bundle filename in the canonical roots
+/// (system first so /Applications wins over ~/Applications);
+/// 2. LaunchServices bundle-id lookup, in case the caller passed a
+/// bundle identifier in the `name` slot — preserved as
+/// `AppLocator::BundleId` so the launch path uses the live NSURL
+/// (Cryptex-safe — see CodeRabbit #3);
+/// 3. (skipped) full localized-name scan — not yet needed by current
+/// integration tests; can be added if we hit a non-English-name app
+/// in the wild.
+fn locate_by_name(name: &str) -> Option<AppLocator> {
+ let app_name = if name.ends_with(".app") {
+ name.to_owned()
+ } else {
+ format!("{name}.app")
+ };
+ let home = std::env::var("HOME").unwrap_or_default();
+ let roots = [
+ "/Applications".to_owned(),
+ "/System/Applications".to_owned(),
+ "/System/Applications/Utilities".to_owned(),
+ "/Applications/Utilities".to_owned(),
+ format!("{home}/Applications"),
+ format!("{home}/Applications/Chrome Apps.localized"),
+ ];
+ for root in &roots {
+ let path = format!("{root}/{app_name}");
+ if std::path::Path::new(&path).is_dir() {
+ return Some(AppLocator::Path(path));
+ }
+ }
+ // Fallback: maybe caller passed a bundle id as `name`. Use the
+ // Cryptex-safe locator (carries the bundle id, never the lossy
+ // url.path()).
+ resolve_bundle_id_to_locator(name)
+}
+
+/// Read `CFBundleIdentifier` from an `.app` bundle's `Info.plist`.
+/// Falls back to shelling out to `plutil` (already used elsewhere in
+/// this file) to avoid pulling in a plist crate just for this.
+fn bundle_id_for_app_path(app_path: &str) -> Option<String> {
+ let plist = format!("{app_path}/Contents/Info.plist");
+ let out = Command::new("plutil")
+ .args(["-extract", "CFBundleIdentifier", "raw", "-o", "-", &plist])
+ .output()
+ .ok()?;
+ if !out.status.success() {
+ return None;
+ }
+ let bid = String::from_utf8_lossy(&out.stdout).trim().to_string();
+ if bid.is_empty() {
+ None
+ } else {
+ Some(bid)
+ }
+}
+
+/// Return all apps: running apps merged with installed-but-not-running apps.
+pub fn list_all_apps() -> Vec<AppInfo> {
+ let running = list_running_apps();
+ let running_bundles: std::collections::HashSet<String> = running.iter()
+ .filter_map(|a| a.bundle_id.clone())
+ .collect();
+
+ let mut installed = scan_installed_apps();
+ // Remove apps already in running list.
+ installed.retain(|a| !a.bundle_id.as_ref().map_or(false, |b| running_bundles.contains(b)));
+
+ let mut all = running;
+ all.extend(installed);
+ all
+}
+
+fn scan_installed_apps() -> Vec<AppInfo> {
+ let dirs = [
+ "/Applications",
+ "/Applications/Utilities",
+ "/System/Applications",
+ "/System/Applications/Utilities",
+ ];
+ let home = std::env::var("HOME").unwrap_or_default();
+ let user_apps = format!("{home}/Applications");
+
+ let mut result = Vec::new();
+ let mut all_dirs: Vec<&str> = dirs.to_vec();
+ let user_apps_str: &str = user_apps.as_str();
+ all_dirs.push(user_apps_str);
+
+ for dir in all_dirs {
+ let Ok(entries) = std::fs::read_dir(dir) else { continue };
+ for entry in entries.flatten() {
+ let path = entry.path();
+ if path.extension().and_then(|e| e.to_str()) != Some("app") { continue }
+ let plist_path = path.join("Contents/Info.plist");
+ if let Some(info) = read_app_plist(&plist_path) {
+ result.push(info);
+ }
+ }
+ }
+ result
+}
+
+fn read_app_plist(plist_path: &std::path::Path) -> Option<AppInfo> {
+ let bundle_id_out = Command::new("plutil")
+ .args(["-extract", "CFBundleIdentifier", "raw", "-o", "-",
+ plist_path.to_str()?])
+ .output().ok()?;
+ if !bundle_id_out.status.success() { return None; }
+ let bundle_id = String::from_utf8_lossy(&bundle_id_out.stdout).trim().to_string();
+ if bundle_id.is_empty() { return None; }
+
+ let name_out = Command::new("plutil")
+ .args(["-extract", "CFBundleDisplayName", "raw", "-o", "-",
+ plist_path.to_str()?])
+ .output().ok();
+ let name = name_out
+ .filter(|o| o.status.success())
+ .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+ .filter(|s| !s.is_empty())
+ .unwrap_or_else(|| {
+ // Fallback: CFBundleName.
+ Command::new("plutil")
+ .args(["-extract", "CFBundleName", "raw", "-o", "-",
+ plist_path.to_str().unwrap_or("")])
+ .output().ok()
+ .filter(|o| o.status.success())
+ .map(|o| String::from_utf8_lossy(&o.stdout).trim().to_string())
+ .filter(|s| !s.is_empty())
+ .unwrap_or_else(|| {
+ plist_path.parent()
+ .and_then(|p| p.parent())
+ .and_then(|p| p.file_stem())
+ .and_then(|s| s.to_str())
+ .unwrap_or("")
+ .to_string()
+ })
+ });
+
+ if name.is_empty() { return None; }
+
+ Some(AppInfo {
+ name,
+ pid: 0,
+ bundle_id: Some(bundle_id),
+ running: false,
+ active: false,
+ })
+}
+
+/// Return the pid of the current frontmost application via
+/// `NSWorkspace.shared.frontmostApplication`. `None` if there isn't one
+/// (rare — e.g. screensaver).
+pub fn frontmost_pid() -> Option<i32> {
+ use objc2_app_kit::NSWorkspace;
+ unsafe {
+ let ws = NSWorkspace::sharedWorkspace();
+ let app = ws.frontmostApplication()?;
+ let pid: i32 = app.processIdentifier();
+ Some(pid)
+ }
+}
+
+/// Re-activate the app with `pid` via
+/// `NSRunningApplication.runningApplicationWithProcessIdentifier(pid)?.activateWithOptions([])`.
+/// Returns `true` if the app was found and activate was attempted.
+/// Used as the belt-and-braces step in `LaunchAppTool` when the target
+/// has self-activated despite the focus-steal observer.
+pub fn activate_pid(pid: i32) -> bool {
+ use objc2_app_kit::{NSApplicationActivationOptions, NSRunningApplication};
+ unsafe {
+ match NSRunningApplication::runningApplicationWithProcessIdentifier(pid) {
+ Some(app) => app.activateWithOptions(NSApplicationActivationOptions(0)),
+ None => false,
+ }
+ }
+}
+
+/// Return the localized application name for a running process by PID.
+/// Uses `ps -p {pid} -o comm=` which gives the command name without path.
+/// Returns `None` if the PID is unknown or the command fails.
+pub fn get_app_name_for_pid(pid: i32) -> Option<String> {
+ let out = Command::new("ps")
+ .args(["-p", &pid.to_string(), "-o", "comm="])
+ .output()
+ .ok()?;
+ let raw = String::from_utf8_lossy(&out.stdout).trim().to_string();
+ if raw.is_empty() {
+ return None;
+ }
+ // Strip path prefix: "/Applications/Safari.app/Contents/MacOS/Safari" → "Safari"
+ Some(
+ std::path::Path::new(&raw)
+ .file_name()
+ .and_then(|n| n.to_str())
+ .unwrap_or(&raw)
+ .to_string(),
+ )
+}
+
+/// Format the app list in the same text style as libs/cua-driver.
+pub fn format_app_list(apps: &[AppInfo]) -> String {
+ let running: Vec<&AppInfo> = apps.iter().filter(|a| a.running).collect();
+ let total = apps.len();
+ // Match Swift `ListAppsTool.swift` `summary(_:)` text format 1:1.
+ let mut lines = vec![format!(
+ "✅ Found {} app(s): {} running, {} installed-not-running.",
+ total,
+ running.len(),
+ total - running.len()
+ )];
+ for app in &running {
+ let bundle = app.bundle_id.as_deref().map(|b| format!(" [{b}]")).unwrap_or_default();
+ lines.push(format!("- {} (pid {}){}", app.name, app.pid, bundle));
+ }
+ lines.join("\n")
+}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/apps/nsworkspace.rs b/libs/cua-driver-rs/crates/platform-macos/src/apps/nsworkspace.rs
new file mode 100644
index 0000000000..ec6bdf8e00
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/apps/nsworkspace.rs
@@ -0,0 +1,377 @@
+//! Thin NSWorkspace launch helpers.
+//!
+//! Wraps the two AppKit launch entry points used by Swift's `AppLauncher.swift`:
+//!
+//! * `-[NSWorkspace openApplicationAtURL:configuration:completionHandler:]` —
+//! pure launch (no URL handoff).
+//! * `-[NSWorkspace openURLs:withApplicationAtURL:configuration:completionHandler:]` —
+//! launch with one or more `application(_:open:)` payloads (used to open
+//! Safari to `about:blank`, Finder to a folder, etc).
+//!
+//! Both share an `OpenConfig` builder that mirrors the subset of
+//! `NSWorkspaceOpenConfiguration` properties Swift sets:
+//! * `activates = false` (background launch — no focus steal)
+//! * `addsToRecentItems = false` (don't pollute the Apple menu)
+//! * `createsNewApplicationInstance = …`
+//! * `arguments = …` / `environment = …`
+//! * `appleEvent = oapp(<bundleId>)` — synthetic `aevt/oapp` AppleEvent so
+//! LaunchServices reliably triggers window creation on cold launch /
+//! state-restored apps (see comments in Swift `AppLauncher.swift`).
+//!
+//! The Cocoa completion handler is bridged to a synchronous return value via
+//! `tokio::sync::oneshot` + a 30s timeout. A wedged launch surfaces as an
+//! error instead of hanging the caller's worker thread.
+//!
+//! The `oapp` AppleEvent descriptor uses the
+//! `init(eventClass:eventID:targetDescriptor:returnID:transactionID:)`
+//! selector which `objc2-foundation 0.2.2` does not bind natively — we
+//! hand-roll the binding in [`apple_event`] via `extern_methods!`.
+
+use std::ptr::NonNull;
+use std::sync::Arc;
+use std::time::Duration;
+
+use block2::RcBlock;
+use objc2::rc::Retained;
+use objc2_app_kit::{
+ NSRunningApplication, NSWorkspace, NSWorkspaceOpenConfiguration,
+};
+use objc2_foundation::{
+ NSAppleEventDescriptor, NSArray, NSDictionary, NSError, NSString, NSURL,
+};
+
+/// FourCharCode helper — packs a 4-byte ASCII tag into a `u32` the same way
+/// Apple's CoreServices headers do (`kCoreEventClass = 'aevt'` etc).
+const fn fourcc(s: &[u8; 4]) -> u32 {
+ ((s[0] as u32) << 24)
+ | ((s[1] as u32) << 16)
+ | ((s[2] as u32) << 8)
+ | (s[3] as u32)
+}
+
+const K_CORE_EVENT_CLASS: u32 = fourcc(b"aevt"); // kCoreEventClass
+const K_AE_OPEN_APPLICATION: u32 = fourcc(b"oapp"); // kAEOpenApplication
+const K_AUTO_GENERATE_RETURN_ID: i16 = -1; // kAutoGenerateReturnID
+const K_ANY_TRANSACTION_ID: i32 = 0; // kAnyTransactionID
+
+/// Caller-friendly launch options. Mirrors the subset of
+/// `NSWorkspaceOpenConfiguration` properties Swift `AppLauncher` sets.
+///
+/// Always sends `activates = false` + `addsToRecentItems = false`. The
+/// optional fields are applied only when present so the builder doesn't
+/// override an inherited default.
+#[derive(Default, Debug, Clone)]
+pub struct OpenConfig {
+ /// `--args` for the launched process. Passed as argv entries (no shell
+ /// expansion).
+ pub arguments: Vec<String>,
+ /// Additional env vars merged into the current process environment.
+ pub environment: std::collections::HashMap<String, String>,
+ /// Force a fresh application instance even if one is already running.
+ pub creates_new_instance: bool,
+ /// Attach a synthetic `aevt/oapp` AppleEvent addressed to this bundle id.
+ /// Set this whenever the bundle id is known — see Swift `AppLauncher`
+ /// comment for the reasoning (cold-launch window-creation reliability).
+ pub apple_event_bundle_id: Option<String>,
+}
+
+/// One-shot timeout for the LaunchServices completion handler. A wedged
+/// `open(...)` call returns `Err(LaunchError::Timeout)` instead of hanging
+/// the calling thread forever.
+const COMPLETION_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Errors returned by the NSWorkspace launch helpers.
+#[derive(Debug, thiserror::Error)]
+pub enum LaunchError {
+ #[error("NSWorkspace launch failed: {0}")]
+ Cocoa(String),
+ #[error("NSWorkspace launch returned no NSRunningApplication and no NSError")]
+ NoApp,
+ #[error("NSWorkspace launch did not complete within {:?}", COMPLETION_TIMEOUT)]
+ Timeout,
+ #[error("invalid url: {0}")]
+ BadUrl(String),
+}
+
+/// Launch the application bundle at `app_url`, no URL handoff.
+///
+/// Equivalent to Swift's
+/// ```swift
+/// NSWorkspace.shared.open(appURL, configuration: cfg) { app, err in … }
+/// ```
+/// — the URL points to a `.app` bundle, NSWorkspace launches it,
+/// `activates = false` keeps the prior frontmost app on top, and the
+/// `oapp` AppleEvent attached to `cfg.appleEvent` triggers window creation
+/// on cold launch.
+/// `app_url` may be either:
+/// * a bundle id (`com.apple.Safari`) — resolved via
+/// `NSWorkspace.URLForApplicationWithBundleIdentifier`, preserving
+/// the NSURL exactly as LaunchServices returns it (avoids
+/// round-tripping through `path()` which can lose alias/cryptex
+/// metadata — Safari lives under `/System/Cryptexes/App/...` and
+/// can't be re-opened from its `path()` string),
+/// * a filesystem path to an `.app` bundle (`/Applications/Foo.app`),
+/// * a URL string with a scheme (`file:///...`, `http://...`).
+pub fn open_application(
+ app_url: &str,
+ cfg: &OpenConfig,
+) -> Result<Retained<NSRunningApplication>, LaunchError> {
+ let ws = unsafe { NSWorkspace::sharedWorkspace() };
+ let url = resolve_application_url(&ws, app_url)?;
+ let config = build_configuration(cfg);
+
+ let (tx, rx) = std::sync::mpsc::sync_channel::<CompletionResult>(1);
+ let tx = Arc::new(std::sync::Mutex::new(Some(tx)));
+
+ let block = make_completion_block(tx);
+
+ tracing::debug!(target: "platform_macos::apps::nsworkspace",
+ ?app_url, "calling openApplicationAtURL");
+
+ unsafe {
+ ws.openApplicationAtURL_configuration_completionHandler(
+ &url,
+ &config,
+ Some(&block),
+ );
+ }
+
+ wait_for_completion(rx)
+}
+
+/// Launch the application bundle at `app_url` and hand it `urls` via
+/// `application(_:open:)`.
+///
+/// Equivalent to Swift's
+/// ```swift
+/// NSWorkspace.shared.open(urls, withApplicationAt: appURL,
+/// configuration: cfg) { app, err in … }
+/// ```
+pub fn open_urls_with_application(
+ urls: &[String],
+ app_url: &str,
+ cfg: &OpenConfig,
+) -> Result<Retained<NSRunningApplication>, LaunchError> {
+ let ws = unsafe { NSWorkspace::sharedWorkspace() };
+ let url = resolve_application_url(&ws, app_url)?;
+ let config = build_configuration(cfg);
+
+ let ns_urls: Vec<Retained<NSURL>> = urls
+ .iter()
+ .map(|u| file_or_app_url(u))
+ .collect::<Result<_, _>>()?;
+ let ns_array = NSArray::from_vec(ns_urls);
+
+ let (tx, rx) = std::sync::mpsc::sync_channel::<CompletionResult>(1);
+ let tx = Arc::new(std::sync::Mutex::new(Some(tx)));
+
+ let block = make_completion_block(tx);
+
+ tracing::debug!(target: "platform_macos::apps::nsworkspace",
+ ?app_url, urls_len = urls.len(), "calling openURLs:withApplicationAtURL");
+
+ unsafe {
+ ws.openURLs_withApplicationAtURL_configuration_completionHandler(
+ &ns_array,
+ &url,
+ &config,
+ Some(&block),
+ );
+ }
+
+ wait_for_completion(rx)
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/// Build an `NSWorkspaceOpenConfiguration` from `cfg`.
+///
+/// Always sets `activates = false` and `addsToRecentItems = false` to match
+/// Swift's background-launch invariant.
+fn build_configuration(cfg: &OpenConfig) -> Retained<NSWorkspaceOpenConfiguration> {
+ let config = unsafe { NSWorkspaceOpenConfiguration::configuration() };
+ unsafe {
+ config.setActivates(false);
+ config.setAddsToRecentItems(false);
+ config.setCreatesNewApplicationInstance(cfg.creates_new_instance);
+
+ if !cfg.arguments.is_empty() {
+ let strs: Vec<Retained<NSString>> = cfg
+ .arguments
+ .iter()
+ .map(|a| NSString::from_str(a))
+ .collect();
+ let arr = NSArray::from_vec(strs);
+ config.setArguments(&arr);
+ }
+
+ if !cfg.environment.is_empty() {
+ // Pass ONLY the caller's explicit overrides — never merge in
+ // `std::env::vars()`. The launching process inherits its
+ // environment from the user's shell (or systemd/launchd
+ // service), which carries secrets, tokens, API keys, SSH
+ // agent sockets, etc. Forwarding any of that to every
+ // launched app is a real security leak.
+ //
+ // If `cfg.environment` is empty we don't set the field at
+ // all (above guard) — LaunchServices then applies the
+ // default app environment, same as a Finder double-click.
+ let entries: Vec<(&String, &String)> = cfg.environment.iter().collect();
+ let keys: Vec<Retained<NSString>> =
+ entries.iter().map(|(k, _)| NSString::from_str(k)).collect();
+ let vals: Vec<Retained<NSString>> =
+ entries.iter().map(|(_, v)| NSString::from_str(v)).collect();
+ let key_refs: Vec<&NSString> = keys.iter().map(|s| s.as_ref()).collect();
+ let dict = NSDictionary::from_vec(&key_refs, vals);
+ config.setEnvironment(&dict);
+ }
+
+ if let Some(bid) = &cfg.apple_event_bundle_id {
+ if !bid.is_empty() {
+ let event = apple_event::open_application_event(bid);
+ config.setAppleEvent(Some(&event));
+ }
+ }
+ }
+ config
+}
+
+/// Resolve a caller-supplied app reference (bundle id, path, or URL
+/// string) into the `NSURL` LaunchServices wants. Bundle ids preferred
+/// when available — they preserve the NSURL exactly as LaunchServices
+/// hands it back, which is the only thing that reliably launches
+/// Cryptex-installed apps (Safari, etc).
+fn resolve_application_url(
+ ws: &NSWorkspace,
+ app_ref: &str,
+) -> Result<Retained<NSURL>, LaunchError> {
+ // Heuristic: bundle ids contain at least one '.' and no '/' and no
+ // '://'. Otherwise treat as a path / URL string.
+ let looks_like_bundle_id =
+ !app_ref.contains('/') && !app_ref.contains("://") && app_ref.contains('.');
+ if looks_like_bundle_id {
+ let ns = NSString::from_str(app_ref);
+ if let Some(url) = unsafe { ws.URLForApplicationWithBundleIdentifier(&ns) } {
+ return Ok(url);
+ }
+ // Fall through to the path/URL parse — caller might have passed
+ // something odd that happens to look like a bundle id (e.g. an
+ // app folder name).
+ }
+ file_or_app_url(app_ref)
+}
+
+/// Build an `NSURL` from a caller-supplied string.
+///
+/// * Strings containing `:` (any URL scheme — `http://`, `https://`,
+/// `file://`, `about:blank`, custom schemes) go through `URLWithString:`.
+/// The colon test catches `about:blank` (no `://`) which Swift's
+/// `URL(string:)` also handles.
+/// * Anything else is a bare filesystem path → `fileURLWithPath:`.
+fn file_or_app_url(s: &str) -> Result<Retained<NSURL>, LaunchError> {
+ if s.is_empty() {
+ return Err(LaunchError::BadUrl("empty".into()));
+ }
+ unsafe {
+ // A path can contain a colon (rare) but is far less likely to
+ // start with `scheme:`. Use a slightly stricter test: must
+ // contain a colon AND not start with `/` AND not start with `~`.
+ let looks_like_url = s.contains(':') && !s.starts_with('/') && !s.starts_with('~');
+ if looks_like_url {
+ let ns = NSString::from_str(s);
+ match NSURL::URLWithString(&ns) {
+ Some(u) => Ok(u),
+ None => Err(LaunchError::BadUrl(s.into())),
+ }
+ } else {
+ let ns = NSString::from_str(s);
+ Ok(NSURL::fileURLWithPath(&ns))
+ }
+ }
+}
+
+type CompletionResult = Result<Retained<NSRunningApplication>, LaunchError>;
+
+/// Build the `(NSRunningApplication?, NSError?) -> Void` completion block.
+///
+/// Sends exactly one result through `tx`. Late completions (after timeout)
+/// land in `try_send` and are silently dropped — the channel is closed.
+fn make_completion_block(
+ tx: Arc<std::sync::Mutex<Option<std::sync::mpsc::SyncSender<CompletionResult>>>>,
+) -> RcBlock<dyn Fn(*mut NSRunningApplication, *mut NSError)> {
+ RcBlock::new(
+ move |app_ptr: *mut NSRunningApplication, err_ptr: *mut NSError| {
+ let result: CompletionResult = unsafe {
+ if !err_ptr.is_null() {
+ let err = &*err_ptr;
+ let desc = err.localizedDescription();
+ Err(LaunchError::Cocoa(desc.to_string()))
+ } else if let Some(app_ref) = NonNull::new(app_ptr) {
+ // `Retained::retain` bumps the refcount so we own it
+ // beyond the block scope.
+ match Retained::retain(app_ref.as_ptr()) {
+ Some(r) => Ok(r),
+ None => Err(LaunchError::NoApp),
+ }
+ } else {
+ Err(LaunchError::NoApp)
+ }
+ };
+ // Take the sender out so the channel closes after one send.
+ let sender = tx.lock().ok().and_then(|mut g| g.take());
+ if let Some(s) = sender {
+ let _ = s.send(result);
+ }
+ },
+ )
+}
+
+/// Block on `rx` for up to `COMPLETION_TIMEOUT`. Returns `Err(Timeout)` if
+/// the completion handler never fires (wedged LaunchServices).
+fn wait_for_completion(
+ rx: std::sync::mpsc::Receiver<CompletionResult>,
+) -> Result<Retained<NSRunningApplication>, LaunchError> {
+ match rx.recv_timeout(COMPLETION_TIMEOUT) {
+ Ok(r) => r,
+ Err(std::sync::mpsc::RecvTimeoutError::Timeout) => Err(LaunchError::Timeout),
+ Err(std::sync::mpsc::RecvTimeoutError::Disconnected) => Err(LaunchError::NoApp),
+ }
+}
+
+/// Hand-rolled binding for
+/// `-[NSAppleEventDescriptor initWithEventClass:eventID:targetDescriptor:returnID:transactionID:]`
+/// (and the associated `OpenApplication` event constructor) — the selector
+/// is not exposed by `objc2-foundation 0.2.2`.
+mod apple_event {
+ use super::{
+ NSAppleEventDescriptor, NSString, Retained, K_AE_OPEN_APPLICATION,
+ K_ANY_TRANSACTION_ID, K_AUTO_GENERATE_RETURN_ID, K_CORE_EVENT_CLASS,
+ };
+ use objc2::msg_send_id;
+ use objc2::rc::Allocated;
+ use objc2::ClassType;
+
+ /// Build an `aevt/oapp` AppleEvent addressed to the bundle id `bid`.
+ pub fn open_application_event(bid: &str) -> Retained<NSAppleEventDescriptor> {
+ let target_string = NSString::from_str(bid);
+ let target: Retained<NSAppleEventDescriptor> = unsafe {
+ NSAppleEventDescriptor::descriptorWithBundleIdentifier(&target_string)
+ };
+
+ unsafe {
+ let alloc: Allocated<NSAppleEventDescriptor> =
+ NSAppleEventDescriptor::alloc();
+ // initWithEventClass:eventID:targetDescriptor:returnID:transactionID:
+ let event: Retained<NSAppleEventDescriptor> = msg_send_id![
+ alloc,
+ initWithEventClass: K_CORE_EVENT_CLASS,
+ eventID: K_AE_OPEN_APPLICATION,
+ targetDescriptor: &*target,
+ returnID: K_AUTO_GENERATE_RETURN_ID,
+ transactionID: K_ANY_TRANSACTION_ID,
+ ];
+ event
+ }
+ }
+}
+
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/focus_steal.rs b/libs/cua-driver-rs/crates/platform-macos/src/focus_steal.rs
new file mode 100644
index 0000000000..65ccf875eb
--- /dev/null
+++ b/libs/cua-driver-rs/crates/platform-macos/src/focus_steal.rs
@@ -0,0 +1,667 @@
+//! Layer-3 focus-steal preventer — Rust port of Swift's
+//! `SystemFocusStealPreventer.swift` plus the PR #1521 4-layer hardening
+//! (closure scope, RAII lease, 5s monotonic deadline, 1s janitor).
+//!
+//! ## What this protects against
+//!
+//! `NSWorkspace.OpenConfiguration.activates = false` tells LaunchServices
+//! "don't activate the target on launch". LaunchServices honors that.
+//! What it does NOT do is stop the launched app from calling
+//! `NSApp.activate(ignoringOtherApps:)` in its own
+//! `applicationDidFinishLaunching`. Chrome, Electron, Safari, Calculator
+//! all do exactly that — so a "background" launch flashes the target on
+//! top of the user's work for a few frames.
+//!
+//! The preventer subscribes to
+//! `NSWorkspace.didActivateApplicationNotification` and, when an activation
+//! matches a registered suppression entry, immediately re-activates the
+//! prior frontmost app on a background thread. AppKit's
+//! `-[NSRunningApplication activateWithOptions:]` is documented thread-safe
+//! — no main-thread hop required.
+//!
+//! ## Layered design (matches PR #1521)
+//!
+//! 1. **Closure API** — `with_suppression(target, restore_to, origin, f)`
+//! begins an entry, awaits `f`, ends the entry. Use this when the
+//! suppression scope is a single async block.
+//! 2. **RAII API** — `begin_suppression(target, restore_to, origin)`
+//! returns a `SuppressionLease`. `Drop` ends the entry synchronously
+//! (no awaiting). Use this when the caller needs to hold the lease
+//! across multiple branches or when async cancellation may interrupt
+//! the closure path.
+//! 3. **5s monotonic deadline** — every entry stamps an
+//! `Instant::now() + 5s`. The observer prunes expired entries before
+//! matching, so a leaked lease can't cause a stale entry to keep
+//! re-activating the prior frontmost app forever.
+//! 4. **1s janitor** — a tokio interval task wakes up every second
+//! while the dispatcher is non-empty, prunes expired entries, and
+//! stops when the map drains. Re-starts when the next entry is
+//! added. Coordinated via `tokio::sync::watch`.
+//!
+//! ## Singleton
+//!
+//! `FocusStealPreventer::shared()` returns a process-wide
+//! `Arc<FocusStealPreventer>`. The observer registration happens inside
+//! `OnceLock::get_or_init`, so it's safe to call from any thread without
+//! racing on observer install.
+//!
+//! ## Why a fresh background `NSOperationQueue` (not `mainQueue`)
+//!
+//! NSWorkspace's block-based observer fires on the queue you give it. If
+//! the queue is `nil` (Swift default) or `mainQueue`, the block runs on
+//! the main thread — which means it requires a live main run loop.
+//! `cua-driver call` (one-shot subcommand) and `--no-overlay` mode don't
+//! have one, so the activation observer would never fire. A fresh
+//! background `NSOperationQueue` sidesteps that — the block runs on the
+//! queue's own thread regardless of run-loop state.
+
+use std::collections::HashMap;
+use std::sync::{Arc, Mutex, OnceLock};
+use std::time::{Duration, Instant};
+
+use objc2_app_kit::{
+ NSApplicationActivationOptions, NSRunningApplication, NSWorkspace,
+ NSWorkspaceDidActivateApplicationNotification, NSWorkspaceApplicationKey,
+};
+use objc2_foundation::NSOperationQueue;
+use uuid::Uuid;
+
+/// Per-entry deadline. After this much wall-clock time the dispatcher's
+/// observer (and the janitor) treats the entry as leaked and prunes it
+/// without firing. Mirrors Swift PR #1521.
+const ENTRY_DEADLINE: Duration = Duration::from_secs(5);
+
+/// Janitor tick interval. The task wakes up this often while the
+/// dispatcher is non-empty and prunes expired entries.
+const JANITOR_TICK: Duration = Duration::from_secs(1);
+
+/// Identifier for a suppression. `with_suppression` and `begin_suppression`
+/// hand one of these back; `end_suppression` consumes it.
+#[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
+pub struct SuppressionHandle(Uuid);
+
+/// Dispatcher-internal entry shape.
+#[derive(Debug)]
+struct Entry {
+ /// `Some(pid)` matches only that pid's activations. `None` is a
+ /// wildcard — matches any activation whose pid != `restore_to`.
+ /// The wildcard variant is used while a launch is in flight and the
+ /// real pid isn't known yet.
+ target_pid: Option<i32>,
+ /// Pid to restore focus to when an activation matches this entry.
+ restore_to: i32,
+ /// Monotonic deadline. After this, the entry is pruned without
+ /// firing.
+ deadline: Instant,
+ /// Provenance for tracing — e.g. `"LaunchAppTool.pre"`.
+ #[allow(dead_code)]
+ origin: &'static str,
+}
+
+/// Singleton focus-steal preventer.
+///
+/// Constructed lazily on first `shared()` call. Owns the dispatcher state
+/// (Sync via the inner Mutex); the NSWorkspace observer + queue are
+/// intentionally retained-and-forgotten on install so their lifetime is
+/// the whole process and we don't need to thread `!Send` Cocoa handles
+/// through this struct.
+pub struct FocusStealPreventer {
+ dispatcher: Arc<Dispatcher>,
+}
+
+impl FocusStealPreventer {
+ /// Return (or initialize on first call) the process-wide singleton.
+ pub fn shared() -> Arc<Self> {
+ static SINGLETON: OnceLock<Arc<FocusStealPreventer>> = OnceLock::new();
+ SINGLETON
+ .get_or_init(|| {
+ let dispatcher = Arc::new(Dispatcher::new());
+ install_observer(&dispatcher);
+ Arc::new(FocusStealPreventer { dispatcher })
+ })
+ .clone()
+ }
+
+ /// Begin suppressing focus-steals targeting `target_pid` (or any pid
+ /// when `None`, the wildcard). Returns a `SuppressionLease` whose
+ /// `Drop` ends the entry synchronously.
+ ///
+ /// `restore_to` is the pid the preventer re-activates if it matches
+ /// a notification. `origin` is a static label for tracing.
+ pub fn begin_suppression(
+ target_pid: Option<i32>,
+ restore_to: i32,
+ origin: &'static str,
+ ) -> SuppressionLease {
+ let shared = Self::shared();
+ let handle = shared
+ .dispatcher
+ .add(target_pid, restore_to, origin);
+ SuppressionLease {
+ handle,
+ dispatcher: Arc::clone(&shared.dispatcher),
+ released: false,
+ }
+ }
+
+ /// Run `f` with a suppression entry active. Equivalent to
+ /// `begin_suppression(...)` + run `f` + drop the lease — but expressed
+ /// as a single async call site.
+ pub async fn with_suppression<R, F, Fut>(
+ target_pid: Option<i32>,
+ restore_to: i32,
+ origin: &'static str,
+ f: F,
+ ) -> R
+ where
+ F: FnOnce() -> Fut,
+ Fut: std::future::Future<Output = R>,
+ {
+ let _lease = Self::begin_suppression(target_pid, restore_to, origin);
+ f().await
+ }
+
+ /// For tests. Returns the singleton's dispatcher arc.
+ #[cfg(test)]
+ fn dispatcher(&self) -> &Arc<Dispatcher> {
+ &self.dispatcher
+ }
+}
+
+/// Begin-suppression convenience that bounces through the singleton.
+pub fn begin_suppression(
+ target_pid: Option<i32>,
+ restore_to: i32,
+ origin: &'static str,
+) -> SuppressionLease {
+ FocusStealPreventer::begin_suppression(target_pid, restore_to, origin)
+}
+
+/// RAII lease. `Drop` ends the entry synchronously, so the entry is
+/// removed even if a future is cancelled mid-await.
+pub struct SuppressionLease {
+ handle: SuppressionHandle,
+ dispatcher: Arc<Dispatcher>,
+ released: bool,
+}
+
+impl SuppressionLease {
+ /// Explicit release. Useful if the caller wants to drop the lease
+ /// before its scope ends without taking the `Drop` path.
+ pub fn release(mut self) {
+ self.dispatcher.remove(self.handle);
+ self.released = true;
+ }
+}
+
+impl Drop for SuppressionLease {
+ fn drop(&mut self) {
+ if !self.released {
+ self.dispatcher.remove(self.handle);
+ }
+ }
+}
+
+// ── Dispatcher ──────────────────────────────────────────────────────────────
+
+/// Holds the suppression entries plus the janitor lifecycle.
+///
+/// `entries` is a `HashMap<Uuid, Entry>` so add/remove are O(1) by handle.
+/// Lookups by `(target_pid, restore_to)` during a notification are O(N) —
+/// N is at most a handful of in-flight launches at a time so a linear
+/// scan is fine.
+pub(crate) struct Dispatcher {
+ entries: Mutex<HashMap<Uuid, Entry>>,
+ /// `true` while the janitor task should keep running. The janitor
+ /// loop watches for transitions to detect when to start/stop.
+ janitor_active: tokio::sync::watch::Sender<bool>,
+ janitor_started: Mutex<bool>,
+}
+
+impl Dispatcher {
+ fn new() -> Self {
+ let (tx, _rx) = tokio::sync::watch::channel(false);
+ Self {
+ entries: Mutex::new(HashMap::new()),
+ janitor_active: tx,
+ janitor_started: Mutex::new(false),
+ }
+ }
+
+ /// Add an entry, return its handle. Always attempts to start the
+ /// janitor task — `kick_janitor()` is idempotent and is the only
+ /// reliable path to recover if the very first add happened before
+ /// a tokio runtime was ready. Gating the kick on "map was empty"
+ /// (as we used to) lost the janitor permanently in that case:
+ /// subsequent adds would skip the kick and the janitor never
+ /// started, leaving deadline-reaping entirely up to the
+ /// `snapshot_matches` reap fallback (only fires on an activation).
+ fn add(
+ self: &Arc<Self>,
+ target_pid: Option<i32>,
+ restore_to: i32,
+ origin: &'static str,
+ ) -> SuppressionHandle {
+ let id = Uuid::new_v4();
+ let entry = Entry {
+ target_pid,
+ restore_to,
+ deadline: Instant::now() + ENTRY_DEADLINE,
+ origin,
+ };
+ {
+ let mut guard = self.entries.lock().unwrap();
+ guard.insert(id, entry);
+ }
+ // Always kick — idempotent if the task is already running.
+ self.kick_janitor();
+ // Signal the janitor that there's work to do (it will start a
+ // fresh tokio interval on the next tick).
+ let _ = self.janitor_active.send(true);
+ SuppressionHandle(id)
+ }
+
+ /// Remove an entry. When the map drains to empty, signals the janitor
+ /// to stop until the next add.
+ fn remove(&self, handle: SuppressionHandle) {
+ let now_empty = {
+ let mut guard = self.entries.lock().unwrap();
+ guard.remove(&handle.0);
+ guard.is_empty()
+ };
+ if now_empty {
+ let _ = self.janitor_active.send(false);
+ }
+ }
+
+ /// Snapshot the entries (cloned to a small Vec) — used by tests
+ /// and the activation handler to evaluate matches without holding
+ /// the lock across the restore call.
+ fn snapshot_matches(&self, activated_pid: i32) -> Vec<i32> {
+ let mut guard = self.entries.lock().unwrap();
+ // Reap expired entries first — keeps the dispatcher honest even
+ // if the janitor hasn't ticked yet.
+ let now = Instant::now();
+ guard.retain(|_, e| e.deadline > now);
+ guard
+ .values()
+ .filter(|e| {
+ match e.target_pid {
+ Some(p) => p == activated_pid,
+ // Wildcard: match any activation except the restore_to
+ // pid (don't fight ourselves when we re-activate the
+ // prior frontmost).
+ None => activated_pid != e.restore_to,
+ }
+ })
+ .map(|e| e.restore_to)
+ .collect()
+ }
+
+ /// Number of entries (for tests).
+ fn len(&self) -> usize {
+ self.entries.lock().unwrap().len()
+ }
+
+ /// Reap entries whose deadline is past. Returns the number reaped.
+ fn reap_expired(&self) -> usize {
+ let mut guard = self.entries.lock().unwrap();
+ let now = Instant::now();
+ let before = guard.len();
+ guard.retain(|_, e| e.deadline > now);
+ let after = guard.len();
+ let reaped = before - after;
+ if after == 0 && reaped > 0 {
+ let _ = self.janitor_active.send(false);
+ }
+ reaped
+ }
+
+ /// Start the janitor task on the current tokio runtime (idempotent).
+ ///
+ /// Safe to call from `add()` on every entry — returns immediately
+ /// when the task is already up. If the spawn cannot proceed (no
+ /// tokio runtime available — e.g. the first `add()` raced the
+ /// binary's runtime init), the `started` flag is intentionally left
+ /// `false` so the next add from a tokio-aware caller retries.
+ /// Without that retry path the janitor could go permanently
+ /// un-spawned and deadline-reaping would degrade to the
+ /// `snapshot_matches` reap fallback (only runs on an activation).
+ fn kick_janitor(self: &Arc<Self>) {
+ let mut started = self.janitor_started.lock().unwrap();
+ if *started {
+ return;
+ }
+ // If there's no tokio runtime available (e.g. the binary is in
+ // the middle of an init path that runs before Tokio is up), skip
+ // — the next add from a tokio-aware caller will retry. We do NOT
+ // set `*started = true` in this branch so the retry actually
+ // takes the spawn path.
+ if tokio::runtime::Handle::try_current().is_err() {
+ return;
+ }
+ // Mark started ONLY after a successful `tokio::spawn`. The
+ // spawn itself is infallible under the current API but we still
+ // sequence the flag update after the spawn so any future
+ // panic-from-spawn path would leave `started = false` and the
+ // next add would retry.
+ let weak = Arc::downgrade(self);
+ let mut rx = self.janitor_active.subscribe();
+ tokio::spawn(async move {
+ loop {
+ // Block until the dispatcher is non-empty.
+ if !*rx.borrow_and_update() {
+ if rx.changed().await.is_err() {
+ break;
+ }
+ continue;
+ }
+ let mut tick = tokio::time::interval(JANITOR_TICK);
+ tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
+ tick.tick().await; // immediate first tick
+ loop {
+ tokio::select! {
+ _ = tick.tick() => {
+ let Some(d) = weak.upgrade() else { return };
+ let _ = d.reap_expired();
+ if d.len() == 0 {
+ // Map drained — break to outer select, wait
+ // for next add.
+ break;
+ }
+ }
+ ch = rx.changed() => {
+ if ch.is_err() { return; }
+ // Active flag may have flipped; loop top will
+ // re-check via `borrow_and_update`.
+ break;
+ }
+ }
+ }
+ }
+ });
+ *started = true;
+ }
+}
+
+// ── Observer registration ────────────────────────────────────────────────────
+
+/// Register the NSWorkspace.didActivateApplicationNotification observer.
+///
+/// The returned token and the queue are intentionally `mem::forget`-leaked
+/// — the singleton is process-lifetime, so we never tear the observer
+/// down. Forgetting avoids having to thread `!Send` `Retained<...>`
+/// handles through `FocusStealPreventer` (which lives in `Arc<...>` /
+/// `OnceLock<...>` and therefore needs to be `Send + Sync`).
+fn install_observer(dispatcher: &Arc<Dispatcher>) {
+ use block2::RcBlock;
+ use objc2_foundation::NSNotification;
+ use std::ptr::NonNull;
+
+ let ws = unsafe { NSWorkspace::sharedWorkspace() };
+ let center = unsafe { ws.notificationCenter() };
+
+ // Fresh background NSOperationQueue. Critical: with `nil` queue,
+ // AppKit delivers synchronously on the posting thread (typically main);
+ // with `mainQueue`, the block requires a running main run loop. A
+ // fresh queue runs the block on a private background thread no matter
+ // what run loop the binary has up.
+ let queue = unsafe { NSOperationQueue::new() };
+ // setMaxConcurrentOperationCount: 1 means activations are processed
+ // serially — they're cheap so contention isn't a worry, but serial
+ // processing keeps the restore order deterministic if two come in
+ // back to back.
+ unsafe { queue.setMaxConcurrentOperationCount(1) };
+
+ let dispatcher_clone = Arc::clone(dispatcher);
+ let block = RcBlock::new(move |note_ptr: NonNull<NSNotification>| {
+ // SAFETY: AppKit gives us a borrowed NSNotification for the
+ // duration of the block. We don't escape the reference.
+ let note = unsafe { note_ptr.as_ref() };
+ handle_activation(&dispatcher_clone, note);
+ });
+
+ let token = unsafe {
+ center.addObserverForName_object_queue_usingBlock(
+ Some(NSWorkspaceDidActivateApplicationNotification),
+ None,
+ Some(&queue),
+ &block,
+ )
+ };
+
+ // Intentionally leak both — the observer needs to outlive any
+ // particular `Arc<FocusStealPreventer>` and the singleton has
+ // process lifetime.
+ std::mem::forget(token);
+ std::mem::forget(queue);
+}
+
+/// Match a single activation notification against the dispatcher and,
+/// for each matching entry, re-activate the entry's `restore_to` pid.
+///
+/// Runs on the observer queue's background thread — safe to call
+/// blocking system APIs.
+fn handle_activation(
+ dispatcher: &Arc<Dispatcher>,
+ note: &objc2_foundation::NSNotification,
+) {
+ use objc2::msg_send;
+ use objc2::runtime::AnyObject;
+
+ let activated_pid: i32 = unsafe {
+ let info = match note.userInfo() {
+ Some(i) => i,
+ None => return,
+ };
+ // userInfo[NSWorkspaceApplicationKey] -> NSRunningApplication*.
+ // We go through a raw msg_send to avoid Retained generic
+ // bookkeeping for the cross-cast.
+ let app_ptr: *mut AnyObject =
+ msg_send![&*info, objectForKey: NSWorkspaceApplicationKey];
+ if app_ptr.is_null() {
+ return;
+ }
+ let pid: libc::pid_t = msg_send![app_ptr, processIdentifier];
+ pid as i32
+ };
+
+ let restore_pids = dispatcher.snapshot_matches(activated_pid);
+ for pid in restore_pids {
+ restore_focus(pid);
+ }
+}
+
+/// Re-activate `pid` if it's still running. Safe to call from any
+/// thread — Apple documents `activateWithOptions:` as thread-safe.
+fn restore_focus(pid: i32) {
+ unsafe {
+ if let Some(app) =
+ NSRunningApplication::runningApplicationWithProcessIdentifier(pid)
+ {
+ let _ = app.activateWithOptions(NSApplicationActivationOptions(0));
+ }
+ }
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+//
+// These tests exercise the pure-Rust dispatcher half — no Cocoa
+// observers, no real notifications. They run under `cargo test
+// -p platform-macos focus_steal::`.
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::sync::Arc;
+
+ /// Dispatcher::add returns a handle, the entry is reachable by
+ /// match, and remove() drops it.
+ #[test]
+ fn dispatcher_add_match_remove() {
+ let d = Arc::new(Dispatcher::new());
+ let h = d.add(Some(42), 7, "test.add");
+ assert_eq!(d.len(), 1);
+ let matches = d.snapshot_matches(42);
+ assert_eq!(matches, vec![7]);
+ // Non-matching pid: no restore candidates.
+ assert!(d.snapshot_matches(99).is_empty());
+ d.remove(h);
+ assert_eq!(d.len(), 0);
+ }
+
+ /// Wildcard entries (`target_pid = None`) match every activation
+ /// except the entry's own restore_to pid.
+ #[test]
+ fn wildcard_matches_all_but_restore_to() {
+ let d = Arc::new(Dispatcher::new());
+ let _h = d.add(None, 7, "test.wild");
+ // pid 99 != restore_to 7 → should match.
+ assert_eq!(d.snapshot_matches(99), vec![7]);
+ // pid 7 == restore_to → must NOT match (don't fight ourselves).
+ assert!(d.snapshot_matches(7).is_empty());
+ }
+
+ /// Lease Drop is the standard remove path.
+ #[test]
+ fn lease_drop_removes_entry() {
+ // Use a private dispatcher to avoid singleton coupling.
+ let d = Arc::new(Dispatcher::new());
+ let h = d.add(Some(1), 2, "test.lease");
+ let lease = SuppressionLease {
+ handle: h,
+ dispatcher: Arc::clone(&d),
+ released: false,
+ };
+ assert_eq!(d.len(), 1);
+ drop(lease);
+ assert_eq!(d.len(), 0);
+ }
+
+ /// Explicit release() short-circuits the Drop path.
+ #[test]
+ fn lease_release_removes_entry() {
+ let d = Arc::new(Dispatcher::new());
+ let h = d.add(Some(1), 2, "test.lease");
+ let lease = SuppressionLease {
+ handle: h,
+ dispatcher: Arc::clone(&d),
+ released: false,
+ };
+ lease.release();
+ assert_eq!(d.len(), 0);
+ }
+
+ /// Force a leaked entry whose deadline is already past, then call
+ /// reap_expired and snapshot_matches — both must purge it.
+ #[test]
+ fn deadline_reaps_leaked_entry() {
+ let d = Arc::new(Dispatcher::new());
+ // Insert a handle manually with a past deadline.
+ let id = Uuid::new_v4();
+ {
+ let mut guard = d.entries.lock().unwrap();
+ guard.insert(
+ id,
+ Entry {
+ target_pid: Some(42),
+ restore_to: 7,
+ deadline: Instant::now() - Duration::from_secs(1),
+ origin: "test.leak",
+ },
+ );
+ }
+ assert_eq!(d.len(), 1);
+ // snapshot_matches reaps expired entries before matching.
+ let matches = d.snapshot_matches(42);
+ assert!(matches.is_empty(), "expired entry should not fire");
+ assert_eq!(d.len(), 0, "snapshot_matches should purge expired");
+ }
+
+ /// Janitor lifecycle: starts on first add, stops when empty,
+ /// restarts on next add. Spin up a tokio runtime to host the task.
+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+ async fn janitor_starts_stops_restarts() {
+ let d = Arc::new(Dispatcher::new());
+ // First add → janitor starts.
+ let h1 = d.add(Some(1), 2, "test.j1");
+ d.kick_janitor();
+ // Give the janitor task time to spin up.
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ // The dispatcher should still hold the entry.
+ assert_eq!(d.len(), 1);
+ // Now remove → janitor goes idle.
+ d.remove(h1);
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ assert_eq!(d.len(), 0);
+ // Add again — same kick, same lifecycle. (start_janitor is
+ // idempotent — already-started task picks up new adds via watch.)
+ let _h2 = d.add(Some(3), 4, "test.j2");
+ d.kick_janitor();
+ tokio::time::sleep(Duration::from_millis(50)).await;
+ assert_eq!(d.len(), 1);
+ }
+
+ /// Verifies the CodeRabbit #2 fix: `add()` always calls
+ /// `kick_janitor()`, regardless of whether the map was empty.
+ ///
+ /// Scenario: first `add()` happens outside a tokio runtime —
+ /// `kick_janitor()` short-circuits via `Handle::try_current()` and
+ /// leaves `started = false`. A second `add()` from a tokio-aware
+ /// caller (the more common case in practice) must retry the spawn.
+ /// The old code skipped the kick because the map was non-empty,
+ /// stranding the janitor forever.
+ #[test]
+ fn add_always_kicks_janitor_after_initial_runtime_miss() {
+ let d = Arc::new(Dispatcher::new());
+ // Outside any tokio runtime — kick_janitor's `try_current` guard
+ // returns Err, the function returns without setting started.
+ let h1 = d.add(Some(1), 2, "test.no_runtime");
+ assert_eq!(d.len(), 1);
+ assert!(
+ !*d.janitor_started.lock().unwrap(),
+ "kick without a runtime must leave started=false so the next \
+ add retries"
+ );
+
+ // Now spin up a tokio runtime and add a second entry. The fix
+ // is that this *second* add still calls kick_janitor (the old
+ // code skipped because the map was already non-empty). Verify
+ // by asserting started flips to true.
+ let rt = tokio::runtime::Builder::new_current_thread()
+ .enable_all()
+ .build()
+ .expect("build current-thread runtime");
+ let d_in = Arc::clone(&d);
+ rt.block_on(async move {
+ let _h2 = d_in.add(Some(3), 4, "test.with_runtime");
+ assert_eq!(d_in.len(), 2);
+ assert!(
+ *d_in.janitor_started.lock().unwrap(),
+ "second add from inside the runtime must retry the spawn \
+ (regression guard for CodeRabbit #2)"
+ );
+ });
+
+ // Clean up so the dispatcher doesn't outlive the runtime with
+ // a still-armed entry — not strictly needed (Dispatcher is
+ // `Send + Sync` and the spawned task holds only a Weak ref),
+ // but keeps the test self-contained.
+ d.remove(h1);
+ }
+
+ /// Snapshot ordering doesn't matter, but the restore pid set
+ /// must contain every match. Multiple concurrent suppressions
+ /// targeting the same pid should both fire.
+ #[test]
+ fn multiple_entries_match_independently() {
+ let d = Arc::new(Dispatcher::new());
+ let _a = d.add(Some(42), 1, "test.m1");
+ let _b = d.add(Some(42), 2, "test.m2");
+ let matches = d.snapshot_matches(42);
+ assert_eq!(matches.len(), 2);
+ // Set equality — order is HashMap-dependent.
+ assert!(matches.contains(&1));
+ assert!(matches.contains(&2));
+ }
+}
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
index 1b1e9f8048..c3e469faa9 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs
@@ -21,6 +21,8 @@ pub mod capture;
#[cfg(target_os = "macos")]
pub mod browser;
#[cfg(target_os = "macos")]
+pub mod focus_steal;
+#[cfg(target_os = "macos")]
pub mod tools;
use mcp_server::tool::ToolRegistry;
diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/launch_app.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/launch_app.rs
index f15099bc0a..8f3ee54087 100644
--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/launch_app.rs
+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/launch_app.rs
@@ -26,7 +26,10 @@ fn def() -> &'static ToolDef {
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 \
- `get_window_state(pid, window_id)`."
+ `get_window_state(pid, window_id)`. When the focus-steal belt-and-braces \
+ demotion check ran (target pid ≠ prior frontmost), the response also includes \
+ `self_activation_suppressed: bool` — true if focus stayed with the prior \
+ frontmost, false if the launched app held focus despite the re-demote attempt."
.into(),
input_schema: serde_json::json!({
"type": "object",
@@ -119,20 +122,70 @@ impl Tool for LaunchAppTool {
s
};
- // bundle_id wins when both are supplied.
+ // ── Layer-3 focus-steal suppression (3-phase wrap) ───────────────
+ //
+ // Captures the prior frontmost pid, arms a wildcard suppression
+ // BEFORE the launch (covers self-activations the target fires
+ // synchronously during `open()`), then upgrades to a targeted
+ // suppression keyed to the actual launched pid. Briefly holds
+ // BOTH leases so a self-activation arriving in the wildcard→
+ // targeted gap is still caught — that race is what hoang17's
+ // Swift PR #1521 explicitly fixes; we do not regress it here.
+ //
+ // After 500ms (enough for `applicationDidFinishLaunching` +
+ // any reflex `NSApp.activate(...)` to fire and get suppressed)
+ // both leases are dropped. The belt-and-braces step at the end
+ // re-activates the prior frontmost if the target is still
+ // frontmost — handles the intra-`open()` synchronous activation
+ // that fired before we could arm with the real pid.
+ let prior_frontmost = crate::apps::frontmost_pid();
+
+ let wildcard_lease = prior_frontmost.map(|prior| {
+ crate::focus_steal::FocusStealPreventer::begin_suppression(
+ None,
+ prior,
+ "LaunchAppTool.pre",
+ )
+ });
+
+ // Move the launch closure inputs into spawn_blocking. The
+ // blocking task returns (pid, app_info, windows). Suppression
+ // upgrade happens AFTER the blocking call returns (back on the
+ // async runtime), then we sleep 500ms holding the targeted
+ // lease before releasing it.
let launch_result = tokio::task::spawn_blocking(move || {
let pid = if let Some(ref bid) = bundle_id {
- if urls.is_empty() && additional_arguments.is_empty() && env.is_empty() && !creates_new_instance {
+ if urls.is_empty()
+ && additional_arguments.is_empty()
+ && env.is_empty()
+ && !creates_new_instance
+ {
crate::apps::launch_app(bid)?
} else {
- launch_with_urls_by_bundle(bid, &urls, &additional_arguments, &env, creates_new_instance)?
+ crate::apps::launch_with_urls_by_bundle(
+ bid,
+ &urls,
+ &additional_arguments,
+ &env,
+ creates_new_instance,
+ )?
}
} else {
let n = name.as_deref().unwrap();
- if urls.is_empty() && additional_arguments.is_empty() && env.is_empty() && !creates_new_instance {
+ if urls.is_empty()
+ && additional_arguments.is_empty()
+ && env.is_empty()
+ && !creates_new_instance
+ {
crate::apps::launch_app_by_name(n)?
} else {
- launch_with_urls_by_name(n, &urls, &additional_arguments, &env, creates_new_instance)?
+ crate::apps::launch_with_urls_by_name(
+ n,
+ &urls,
+ &additional_arguments,
+ &env,
+ creates_new_instance,
+ )?
}
};
@@ -148,6 +201,74 @@ impl Tool for LaunchAppTool {
Ok::<_, anyhow::Error>((pid, app_info, windows))
}).await;
+ // Upgrade to targeted suppression now that we know the real pid.
+ // Keep the wildcard lease alive until immediately AFTER we've
+ // armed the targeted one — that's the PR #1521 overlap window.
+ //
+ // `self_activation_suppressed` is the outcome of the belt-and-
+ // braces demotion check: `None` when the check didn't run
+ // (no prior frontmost / launch failed / pid == prior), `Some(true)`
+ // when the target was NOT frontmost after the suppression window
+ // (or we successfully re-demoted it), `Some(false)` when the
+ // re-demote failed and the target is still stealing focus.
+ // Surfaced in the structured response so callers can observe
+ // whether focus-steal prevention actually held.
+ let mut self_activation_suppressed: Option<bool> = None;
+ if let Ok(Ok((pid, _, _))) = &launch_result {
+ if let Some(prior) = prior_frontmost {
+ if *pid != prior {
+ let targeted_lease =
+ crate::focus_steal::FocusStealPreventer::begin_suppression(
+ Some(*pid),
+ prior,
+ "LaunchAppTool.post",
+ );
+ // Now safe to drop the wildcard — targeted is armed.
+ drop(wildcard_lease);
+ // 500ms covers `applicationDidFinishLaunching` plus
+ // any reflex `NSApp.activate(...)`. Matches Swift
+ // LaunchAppTool.swift exactly.
+ tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+ drop(targeted_lease);
+
+ // Belt-and-braces: if the target is STILL frontmost
+ // after the suppression window, the intra-`open()`
+ // synchronous activation slipped through. Demote
+ // explicitly by re-activating the prior frontmost.
+ let frontmost_now = crate::apps::frontmost_pid();
+ if frontmost_now == Some(*pid) {
+ let activated = crate::apps::activate_pid(prior);
+ // Re-check; the structured response depends on
+ // whether the demote actually took.
+ let still_frontmost =
+ crate::apps::frontmost_pid() == Some(*pid);
+ if still_frontmost {
+ tracing::warn!(
+ target: "platform_macos::tools::launch_app",
+ launched_pid = *pid,
+ prior_pid = prior,
+ activate_pid_returned = activated,
+ "belt-and-braces demotion failed: launched app \
+ is still frontmost after re-activating prior"
+ );
+ self_activation_suppressed = Some(false);
+ } else {
+ self_activation_suppressed = Some(true);
+ }
+ } else {
+ self_activation_suppressed = Some(true);
+ }
+ } else {
+ // pid == prior frontmost (re-launch of an already-
+ // frontmost app). Just drop the wildcard.
+ drop(wildcard_lease);
+ }
+ }
+ } else {
+ // Launch failed; just drop the lease.
+ drop(wildcard_lease);
+ }
+
match launch_result {
Ok(Ok((pid, app_info, windows))) => {
let app_name = app_info.as_ref().map(|a| a.name.as_str()).unwrap_or("?");
@@ -182,12 +303,22 @@ impl Tool for LaunchAppTool {
"is_on_screen": w.is_on_screen,
})).collect();
- ToolResult::text(summary).with_structured(serde_json::json!({
+ let mut structured = serde_json::json!({
"pid": pid,
"bundle_id": bid,
"name": app_name,
- "windows": windows_json
- }))
+ "windows": windows_json,
+ });
+ // Only emit `self_activation_suppressed` when the
+ // belt-and-braces demotion check actually ran. `None`
+ // means the launch didn't enter the focus-steal path
+ // (no prior frontmost, or pid == prior) — surfacing
+ // a stale `false` would be misleading.
+ if let Some(suppressed) = self_activation_suppressed {
+ structured["self_activation_suppressed"] =
+ serde_json::Value::Bool(suppressed);
+ }
+ ToolResult::text(summary).with_structured(structured)
}
Ok(Err(e)) => ToolResult::error(format!("Launch failed: {e}")),
Err(e) => ToolResult::error(format!("Task error: {e}")),
@@ -197,64 +328,6 @@ impl Tool for LaunchAppTool {
// ── Blocking helpers ──────────────────────────────────────────────────────────
-/// Launch a bundle with optional URLs, extra args, env vars, and new-instance flag.
-fn launch_with_urls_by_bundle(
- bundle_id: &str,
- urls: &[String],
- additional_args: &[String],
- env: &std::collections::HashMap<String, String>,
- new_instance: bool,
-) -> anyhow::Result<i32> {
- let mut cmd = std::process::Command::new("open");
- if new_instance { cmd.arg("-n"); }
- cmd.args(["-g", "-b", bundle_id]);
- for url in urls { cmd.arg(url); }
- if !additional_args.is_empty() {
- cmd.arg("--args");
- for arg in additional_args { cmd.arg(arg); }
- }
- for (k, v) in env { cmd.env(k, v); }
- let status = cmd.status()?;
- if !status.success() {
- anyhow::bail!("Failed to launch {bundle_id}");
- }
- std::thread::sleep(std::time::Duration::from_millis(500));
- let apps = crate::apps::list_running_apps();
- apps.into_iter()
- .find(|a| a.bundle_id.as_deref() == Some(bundle_id))
- .map(|a| a.pid)
- .ok_or_else(|| anyhow::anyhow!("Launched {bundle_id} but could not find its pid"))
-}
-
-/// Launch by name with optional URLs, extra args, env vars, and new-instance flag.
-fn launch_with_urls_by_name(
- name: &str,
- urls: &[String],
- additional_args: &[String],
- env: &std::collections::HashMap<String, String>,
- new_instance: bool,
-) -> anyhow::Result<i32> {
- let mut cmd = std::process::Command::new("open");
- if new_instance { cmd.arg("-n"); }
- cmd.args(["-g", "-a", name]);
- for url in urls { cmd.arg(url); }
- if !additional_args.is_empty() {
- cmd.arg("--args");
- for arg in additional_args { cmd.arg(arg); }
- }
- for (k, v) in env { cmd.env(k, v); }
- let status = cmd.status()?;
- if !status.success() {
- anyhow::bail!("Failed to launch '{name}'");
- }
- std::thread::sleep(std::time::Duration::from_millis(500));
- let apps = crate::apps::list_running_apps();
- apps.into_iter()
- .find(|a| a.name.eq_ignore_ascii_case(name))
- .map(|a| a.pid)
- .ok_or_else(|| anyhow::anyhow!("Launched '{name}' but could not find its pid"))
-}
-
/// Poll for the pid's layer-0 windows, retrying up to 5x100ms to absorb
/// LaunchServices → WindowServer latency (mirrors the Swift reference).
fn resolve_windows_for_pid(pid: i32) -> Vec<crate::windows::WindowInfo> {
diff --git a/libs/cua-driver-rs/tests/integration/test_focus_steal_parity.py b/libs/cua-driver-rs/tests/integration/test_focus_steal_parity.py
new file mode 100644
index 0000000000..5f4dcc5a18
--- /dev/null
+++ b/libs/cua-driver-rs/tests/integration/test_focus_steal_parity.py
@@ -0,0 +1,356 @@
+"""Integration parity tests for macOS focus-steal prevention.
+
+`launch_app` must NOT change the user's frontmost application — that's
+the contract Swift's `SystemFocusStealPreventer` + 3-phase wrap in
+`LaunchAppTool` already enforce. This test suite encodes the same
+contract for Rust `cua-driver-rs` so we can catch regressions and
+verify the Swift↔Rust parity needed to flip macOS Rust BETA → GA.
+
+Each test runs against the Rust binary (`CUA_DRIVER_BINARY`). When
+`CUA_SWIFT_BINARY` is set, the same checks run against the Swift
+binary too — both must pass for parity. Set `FOCUS_STEAL_RUST_ONLY=1`
+to skip the Swift half (useful while iterating on Rust changes
+without a Swift build on the path).
+
+Test cases (mirror the plan's Verification section 1:1):
+
+ 1. test_launch_passive_app_preserves_frontmost — Calculator (passive)
+ 2. test_launch_self_activating_app_preserves_frontmost — Safari
+ 3. test_launch_with_url_preserves_frontmost — Safari + about:blank
+ 4. test_cold_launch_creates_window — kill + relaunch Calculator,
+ assert window appears (verifies the `oapp` AppleEvent on the
+ no-URL path)
+ 5. test_concurrent_launches_independent_suppression — back-to-back
+ launches, both targets suppressed, frontmost unchanged.
+ 6. test_deadline_reaps_leaked_entry — exercised by the Rust unit
+ test `focus_steal::tests::deadline_reaps_leaked_entry`. This file
+ re-asserts the integration-level behavior: a launch followed by
+ a stale-state probe doesn't keep re-activating the prior
+ frontmost.
+
+The frontmost-baseline app is Finder (`com.apple.finder`). It's the
+only app guaranteed to be running on every logged-in macOS session
+and it never self-activates on launch, which gives us a stable,
+predictable "prior" pid between tests. (Earlier iterations of this
+suite used a shared FocusMonitorApp fixture under
+`libs/cua-driver/Tests/FocusMonitorApp/`, but the dependency on a
+built helper made the integration tests flaky to bootstrap on a
+fresh runner — Finder removes that dependency.)
+
+Run:
+ cd libs/cua-driver-rs/tests/integration
+ python3 -m unittest test_focus_steal_parity -v
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import time
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from driver_client import DriverClient, default_binary_path # noqa: E402
+
+
+# ── Paths / fixtures ─────────────────────────────────────────────────────────
+def _swift_binary() -> str | None:
+ """Locate the Swift binary, or None if not available."""
+ from_env = os.environ.get("CUA_SWIFT_BINARY", "")
+ if from_env and os.path.isfile(from_env):
+ return from_env
+ for p in (
+ os.path.expanduser("~/.local/bin/cua-driver"),
+ shutil.which("cua-driver") or "",
+ ):
+ if p and os.path.isfile(p) and os.access(p, os.X_OK):
+ return p
+ return None
+
+
+def _frontmost_bundle_id() -> str | None:
+ """Bundle id of the currently-frontmost app, queried via osascript.
+
+ We deliberately don't use the driver's `list_apps` for this — the
+ driver process itself may not be frontmost yet when invoked via
+ `call`, and we want a host-truth answer that doesn't go through
+ the same driver path we're testing.
+ """
+ try:
+ out = subprocess.run(
+ [
+ "osascript",
+ "-e",
+ 'tell application "System Events" to bundle identifier of first '
+ "application process whose frontmost is true",
+ ],
+ capture_output=True,
+ text=True,
+ timeout=5,
+ )
+ bid = out.stdout.strip()
+ return bid or None
+ except Exception:
+ return None
+
+
+def _activate_bundle(bundle_id: str) -> None:
+ """Bring `bundle_id` to the foreground via osascript."""
+ subprocess.run(
+ ["osascript", "-e", f'tell application id "{bundle_id}" to activate'],
+ timeout=5,
+ check=False,
+ )
+
+
+def _kill_bundle(bundle_id: str) -> None:
+ """pkill the running app for `bundle_id` if any. Idempotent."""
+ name = bundle_id.split(".")[-1]
+ subprocess.run(["pkill", "-x", name], check=False)
+ subprocess.run(["pkill", "-x", name.capitalize()], check=False)
+ # Safari sometimes needs a moment for its child helper processes
+ # (Networking, WebContent) to also exit before LaunchServices will
+ # cleanly relaunch it from the Cryptex path. The 1s settle below
+ # is conservative but cheap relative to the launch time itself.
+ time.sleep(1.0)
+
+
+def _wait_for_frontmost(bundle_id: str, timeout_s: float = 3.0) -> bool:
+ deadline = time.time() + timeout_s
+ while time.time() < deadline:
+ if _frontmost_bundle_id() == bundle_id:
+ return True
+ time.sleep(0.1)
+ return False
+
+
+# ── Skipping logic ───────────────────────────────────────────────────────────
+def _rust_binary() -> str | None:
+ p = default_binary_path()
+ return p if os.path.isfile(p) and os.access(p, os.X_OK) else None
+
+
+_RUST = _rust_binary()
+_SWIFT = _swift_binary()
+_RUST_ONLY = os.environ.get("FOCUS_STEAL_RUST_ONLY", "") == "1"
+
+
+# ── Mixin: the actual test cases ─────────────────────────────────────────────
+class _FocusStealMixin:
+ """Parametrized test cases. Subclasses set `BINARY` and `LABEL`."""
+
+ BINARY: str = ""
+ LABEL: str = ""
+
+ # A stable "prior frontmost" app id we can reasonably expect every
+ # macOS host to have running. Finder is always running on a logged-in
+ # macOS session and never self-activates on launch.
+ PRIOR_BUNDLE = "com.apple.finder"
+
+ def setUp(self) -> None:
+ # Bring the baseline app to the foreground, confirm. We retry a
+ # few times because dev hosts with overlay / focus-grabber apps
+ # (e.g. Gumbranch, screen recorders, status-bar apps that
+ # forcibly steal focus on click) can racily re-steal during the
+ # setup window.
+ for _ in range(3):
+ _activate_bundle(self.PRIOR_BUNDLE)
+ if _wait_for_frontmost(self.PRIOR_BUNDLE, timeout_s=2.0):
+ return
+ time.sleep(0.5)
+ self.skipTest(
+ f"could not bring {self.PRIOR_BUNDLE} to the foreground after "
+ "3 attempts — test host has an aggressive focus-grabber that "
+ "makes the test environment unstable"
+ )
+
+ def _launch(self, args: dict) -> dict:
+ with DriverClient(self.BINARY) as client:
+ return client.call_tool("launch_app", args)
+
+ # ── Case 1: passive app (Calculator) ────────────────────────────────
+ def test_launch_passive_app_preserves_frontmost(self) -> None:
+ _kill_bundle("com.apple.calculator")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+ baseline = _frontmost_bundle_id()
+ self.assertEqual(baseline, self.PRIOR_BUNDLE)
+
+ result = self._launch({"bundle_id": "com.apple.calculator"})
+ self.assertIn("structuredContent", result)
+ self.assertIn("pid", result["structuredContent"])
+
+ # Settle, then assert the prior frontmost is unchanged.
+ time.sleep(1.0)
+ self.assertEqual(
+ _frontmost_bundle_id(),
+ self.PRIOR_BUNDLE,
+ f"{self.LABEL}: Calculator launch stole focus from {self.PRIOR_BUNDLE}",
+ )
+
+ # ── Case 2: self-activating app (Safari, no URLs) ───────────────────
+ def test_launch_self_activating_app_preserves_frontmost(self) -> None:
+ _kill_bundle("com.apple.Safari")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+ self.assertEqual(_frontmost_bundle_id(), self.PRIOR_BUNDLE)
+
+ # No URLs — exercises the `openApplicationAtURL` path with the
+ # `oapp` AppleEvent.
+ self._launch({"bundle_id": "com.apple.Safari"})
+ time.sleep(1.5) # allow Safari's reflex NSApp.activate to fire
+ self.assertEqual(
+ _frontmost_bundle_id(),
+ self.PRIOR_BUNDLE,
+ f"{self.LABEL}: Safari (no URL) launch stole focus from {self.PRIOR_BUNDLE}",
+ )
+
+ # ── Case 3: launch-with-URL preserves frontmost ─────────────────────
+ def test_launch_with_url_preserves_frontmost(self) -> None:
+ _kill_bundle("com.apple.Safari")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+ self.assertEqual(_frontmost_bundle_id(), self.PRIOR_BUNDLE)
+
+ result = self._launch(
+ {"bundle_id": "com.apple.Safari", "urls": ["about:blank"]}
+ )
+ # NOTE: the Swift binary on macOS Sonoma+ fails this launch with
+ # "The application 'Safari' could not be launched because it was
+ # not found" — that's a Cryptex-app + URL-handoff regression on
+ # the Swift side (`AppLauncher.launch` attaches an `oapp`
+ # AppleEvent to the openURLs:withApplicationAtURL: path, which
+ # LaunchServices rejects for Safari). The Rust port fixes this
+ # by skipping `oapp` on the URL-handoff path — see commit body
+ # for `feat(launch_app): wire focus-steal preventer into
+ # LaunchAppTool`. The Swift binary will fail this assertion;
+ # treat that as a pre-existing Swift bug, not a Rust regression,
+ # and surface it via `expectedFailure` on the Swift subclass.
+ self.assertNotIn("isError", result, f"launch_app reported isError={result}")
+
+ time.sleep(1.5)
+ self.assertEqual(
+ _frontmost_bundle_id(),
+ self.PRIOR_BUNDLE,
+ f"{self.LABEL}: Safari (about:blank) launch stole focus",
+ )
+
+ # ── Case 4: cold launch creates a window ────────────────────────────
+ def test_cold_launch_creates_window(self) -> None:
+ _kill_bundle("com.apple.calculator")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+
+ result = self._launch({"bundle_id": "com.apple.calculator"})
+ windows = result["structuredContent"].get("windows", [])
+ self.assertGreater(
+ len(windows),
+ 0,
+ f"{self.LABEL}: cold-launched Calculator had no windows — "
+ "the `oapp` AppleEvent may not be reaching the target",
+ )
+
+ # ── Case 5: back-to-back launches each preserve frontmost ───────────
+ def test_concurrent_launches_independent_suppression(self) -> None:
+ _kill_bundle("com.apple.calculator")
+ _kill_bundle("com.apple.TextEdit")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+ self.assertEqual(_frontmost_bundle_id(), self.PRIOR_BUNDLE)
+
+ # Sequential, not truly concurrent — but each launch reads the
+ # current frontmost (which should still be `PRIOR_BUNDLE` after
+ # the first one succeeded if focus-steal worked). If the first
+ # launch leaked focus, the second's prior would be Calculator
+ # and the assertion below would fail.
+ self._launch({"bundle_id": "com.apple.calculator"})
+ time.sleep(0.7)
+ self.assertEqual(_frontmost_bundle_id(), self.PRIOR_BUNDLE)
+
+ self._launch({"bundle_id": "com.apple.TextEdit"})
+ time.sleep(1.0)
+ self.assertEqual(
+ _frontmost_bundle_id(),
+ self.PRIOR_BUNDLE,
+ f"{self.LABEL}: back-to-back Calculator + TextEdit launches "
+ "leaked focus from one suppression to the next",
+ )
+
+ # ── Case 6: deadline reaper integration probe ───────────────────────
+ def test_deadline_reaps_leaked_entry(self) -> None:
+ # The fine-grained reap behavior is unit-tested in
+ # `focus_steal::tests::deadline_reaps_leaked_entry`. This
+ # integration probe verifies the user-visible consequence:
+ # launching, waiting 6s, then activating the launched app
+ # manually does NOT cause an unsolicited re-activation of the
+ # prior frontmost (which would happen if a leaked entry kept
+ # firing past the 5s deadline).
+ _kill_bundle("com.apple.calculator")
+ time.sleep(0.5)
+ _activate_bundle(self.PRIOR_BUNDLE)
+ time.sleep(0.5)
+
+ result = self._launch({"bundle_id": "com.apple.calculator"})
+ calc_pid = result["structuredContent"]["pid"]
+ self.assertIsInstance(calc_pid, int)
+ # Wait past the 5s deadline.
+ time.sleep(6.0)
+ # Now manually activate Calculator. If the dispatcher leaked an
+ # entry, it would yank focus back to PRIOR_BUNDLE here — and
+ # the assertion below would fail.
+ _activate_bundle("com.apple.calculator")
+ time.sleep(1.0)
+ self.assertEqual(
+ _frontmost_bundle_id(),
+ "com.apple.calculator",
+ f"{self.LABEL}: stale entry yanked focus back after the "
+ "5s deadline — the reaper or the observer skipped the prune",
+ )
+
+
+# ── Concrete subclasses ──────────────────────────────────────────────────────
[email protected](_RUST is None, "Rust cua-driver-rs binary not built")
+class RustFocusStealTests(_FocusStealMixin, unittest.TestCase):
+ BINARY = _RUST or ""
+ LABEL = "rust"
+
+
+ _SWIFT is None or _RUST_ONLY,
+ "Swift cua-driver binary not available (set CUA_SWIFT_BINARY) "
+ "or FOCUS_STEAL_RUST_ONLY=1 set",
+)
+class SwiftFocusStealTests(_FocusStealMixin, unittest.TestCase):
+ BINARY = _SWIFT or ""
+ LABEL = "swift"
+
+ # Pre-existing Swift bug on macOS Sonoma+: launching Safari with
+ # `urls=["about:blank"]` returns "The application 'Safari' could not
+ # be launched because it was not found." The Rust port fixes this
+ # (the `oapp` AppleEvent on the URL-handoff path is incompatible
+ # with Cryptex-installed apps). Re-define the method on this
+ # subclass only (NOT via expectedFailure on the mixin attribute —
+ # that would also taint the Rust subclass) and mark the override
+ # `@expectedFailure`.
+ @unittest.expectedFailure
+ def test_launch_with_url_preserves_frontmost(self) -> None: # type: ignore[override]
+ super().test_launch_with_url_preserves_frontmost()
+
+ # NOTE: `test_deadline_reaps_leaked_entry` is intentionally NOT
+ # marked expectedFailure on Swift. Swift's `SystemFocusStealPreventer`
+ # has no monotonic deadline reaper (PR #1521 is unmerged at port
+ # time), but in practice the Swift `LaunchAppTool.invoke` calls
+ # `endSuppression` cleanly before the integration test's 6s wait
+ # finishes, so the test sometimes passes on Swift anyway. The Rust
+ # subclass is what locks down the reaper-driven contract.
+
+
+if __name__ == "__main__":
+ unittest.main()