Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
feat(platform-macos): WindowChangeDetector + FocusGuard per-action focus suppression (#1526) (#1531)
Francesco Bonaccia91a2fbd15c8
diff --git a/libs/cua-driver-rs/PARITY.md b/libs/cua-driver-rs/PARITY.mdindex 7a3c8d16c7..8c71dc8803 100644--- a/libs/cua-driver-rs/PARITY.md+++ b/libs/cua-driver-rs/PARITY.md@@ -416,12 +416,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` (focus-suppression wrap VERIFIED; full audit pending)- 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: VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); full line-by-line audit pending- linux: OPEN- Test: `crates/platform-windows/examples/click_parity.rs`@@ -579,9 +579,9 @@ Windows's `click` takes `{button: enum}` instead. Rationale:- 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` (focus-suppression wrap VERIFIED; full audit pending)- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)-- Status: windows VERIFIED; macOS / linux OPEN+- Status: windows VERIFIED; macOS VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); linux OPEN- Test: `crates/platform-windows/examples/press_key_parity.rs`### Fixed (Windows)@@ -623,9 +623,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` (focus-suppression wrap VERIFIED; full audit pending)- linux=`crates/platform-linux/src/tools/impl_.rs` (TBD)-- Status: windows VERIFIED; macOS / linux OPEN+- Status: windows VERIFIED; macOS VERIFIED (focus-suppression wrap — see [Per-action focus suppression](#per-action-focus-suppression)); linux OPEN- Test: `crates/platform-windows/examples/hotkey_parity.rs`### Fixed (Windows)@@ -1497,11 +1497,15 @@ Now uses prefix `cua-driver-rs-v` (Rust port's actual tag prefix).## 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.+Cross-cutting infrastructure (not an MCP tool) used by `launch_app` and+by the 7 action tools (`click`, `type_text`, `hotkey`, `press_key`,+`drag`, `scroll`, `set_value`) via the+[Per-action focus suppression](#per-action-focus-suppression) wrap.+Catches apps that self-activate during launch (Chrome, Electron,+Safari) or as a side-effect of an action (Safari opening a new tab in+response to AXPress, autocomplete pulling itself forward), 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)@@ -1549,13 +1553,110 @@ before the user perceives the steal.### 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.+- **`FocusGuard.withFocusSuppressed` ships layer 3 only** — see+ [Per-action focus suppression](#per-action-focus-suppression). The+ reactive suppressor is wired up across the 7 action tools; the+ enablement (`AXManualAccessibility`/`AXEnhancedUserInterface`) and+ synthetic-focus (`AXFocused`/`AXMain` write+restore) layers are+ deferred because the AX assertion + attribute-write plumbing isn't+ yet ported. Empirically the layer-3 guard combined with+ `WindowChangeDetector`'s wildcard catches the majority of+ side-effects on real-world workflows.+- **`WindowChangeDetector` ported and wired** — see+ [Per-action focus suppression](#per-action-focus-suppression).- **Janitor uses `tokio::sync::watch`** — Swift uses Task cancellation;Rust's tokio idiom is the watch-channel select pattern. Behavior isidentical: idle dispatcher → janitor sleeps; new entry → janitorwakes; map drains → janitor exits and waits for the next add.++---++## Per-action focus suppression++Per-action wrap around the 7 macOS action tools (`click`, `type_text`,+`hotkey`, `press_key`, `drag`, `scroll`, `set_value`) that catches+side-effect side-effects of dispatching an action on a backgrounded+app — Safari opening a new tab in response to AXPress, a "Sign In"+button opening a sheet, an autocomplete popover floating into view,+etc. Mirrors Swift's `WindowChangeDetector` + `FocusGuard` cross-cutting+helpers wired into ClickTool / TypeTextTool / SetValueTool.++- Swift:+ - `libs/cua-driver/Sources/CuaDriverServer/Tools/WindowChangeDetector.swift`+ - `libs/cua-driver/Sources/CuaDriverCore/Focus/FocusGuard.swift`+- Rust:+ - `crates/platform-macos/src/window_change_detector.rs`+ - `crates/platform-macos/src/focus_guard.rs`+- Status: macOS VERIFIED (action tools wired up; result-suffix wording+ matches Swift verbatim). windows/linux N/A (different focus model).+- Tests:+ - Rust unit: `window_change_detector::tests` (8 cases — diff ++ result_suffix branches) and `focus_guard::tests` (4 cases —+ arm/skip lifecycle).+ - Integration: existing `tests/integration/test_focus_steal_parity.py`+ + `tests/integration/test_api_parity.py` — confirmed no regression+ after the action-tool wiring (identical pass/fail to main).++### Snapshot → action → detect cycle++Each wrapped action follows the same shape:++```rust+let prior = apps::frontmost_pid();+let snapshot = WindowChangeDetector::snapshot(); // arms wildcard+let result = focus_guard::with_focus_suppressed(+ Some(target_pid), prior, "<tool>.<origin>",+ || async { do_action(...).await }+).await;+let changes = snapshot.detect_async().await; // drops wildcard+// append changes.result_suffix() to success text+```++Two suppression entries are armed in series:++1. **Wildcard** (armed in `snapshot()`, dropped in `detect()`) —+ `target_pid = None`, `restore_to = current frontmost`. Catches any+ activation other than the prior frontmost during the full+ snapshot → action → detect window. Mirrors Swift's+ `WindowChangeDetector.snapshot()` wildcard.+2. **Targeted** (armed by `FocusGuard::with_focus_suppressed` around+ the action call) — `target_pid = Some(action_pid)`,+ `restore_to = prior frontmost`. Catches a target-self-activation+ triggered by the AX call itself. Skipped when target ==+ frontmost (no point fighting ourselves). 50ms post-action settle+ before the lease drops, giving any in-flight reflex activation+ time to be observed.++### Result-suffix verbatim++The `Changes.result_suffix()` wording matches Swift's+`WindowChangeDetector.Changes.resultSuffix`:++- New windows: `"\n\n🪟 Action opened new window(s): App (\"Title\")."`+ (multiple windows grouped by app, titles in quotes, joined with a+ `,` (comma followed by a space); multiple apps joined with a `;`+ (semicolon followed by a space); alphabetical by app name).+- Foreground-only change (no new windows): `"\n\n🔀 Action caused a+ different app to become frontmost."`.+- No change: empty string.++MCP callers can string-match on either lead emoji to detect a+side-effect without per-binary special-casing.++### Intentional simplifications vs Swift++- **FocusGuard layers 1+2 (enablement, synthetic-focus) deferred** —+ Swift's `AXManualAccessibility` / `AXEnhancedUserInterface`+ assertion and `AXFocused`/`AXMain` write+restore aren't ported yet.+ The Rust port ships only layer 3 (reactive suppressor). Empirically+ the wildcard + targeted reactive pair catches the majority of+ side-effects; layers 1+2 are a follow-up when the AX assertion+ plumbing lands.+- **Pure-function diff exposed for tests** — `Snapshot::diff` is+ `pub(crate)` so unit tests can pin down opened/closed semantics+ without driving the live `CGWindowList` enumerator. Swift tests+ the same way via `currentWindowIds()` indirection.+- **`detect_async()` runs on `spawn_blocking`** — Swift's poll loop+ uses `Task.sleep`; Rust's blocking `std::thread::sleep` is cheap to+ offload via `tokio::task::spawn_blocking` and keeps the runtime+ responsive to other in-flight work.diff --git a/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rs b/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rsnew file mode 100644index 0000000000..62f3d25f47--- /dev/null+++ b/libs/cua-driver-rs/crates/platform-macos/src/focus_guard.rs@@ -0,0 +1,205 @@+//! FocusGuard — Rust port of Swift's `FocusGuard.withFocusSuppressed`+//! (`libs/cua-driver/Sources/CuaDriverCore/Focus/FocusGuard.swift`).+//!+//! ## What this does+//!+//! Wraps an individual AX-action call (the inside of a click / type /+//! set_value / drag dispatch) with a **targeted** focus-steal suppression+//! lease. Catches the case where dispatching an AX attribute write+//! triggers a reflexive self-activation in the target app — Safari /+//! WebKit will sometimes pull itself to the front when an+//! `AXSelectedText` write hits a focused input, even when the AX call+//! itself doesn't go through `NSApp.activate(…)`.+//!+//! ## Layering relative to Swift+//!+//! Swift's `FocusGuard.withFocusSuppressed` does three things:+//!+//! 1. **Enablement** — set `AXManualAccessibility` /+//! `AXEnhancedUserInterface` on the app root so Chromium/Electron+//! targets respond to attribute-level dispatch.+//! 2. **Synthetic focus** — write `AXFocused` / `AXMain` on the+//! enclosing window + element before the action, restore after.+//! Makes AppKit behave as if the action came from a focused+//! process, preventing reflex activations.+//! 3. **Reactive** — arm `SystemFocusStealPreventer` with a targeted+//! entry. If the target self-activates anyway, re-activates the+//! prior frontmost.+//!+//! This Rust port only ships **layer 3** (the reactive suppressor).+//! Layers 1+2 require AX assertion + AX attribute write/restore machinery+//! that isn't yet ported — and empirically the layer-3 reactive guard+//! catches the majority of side-effects when combined with+//! `WindowChangeDetector`'s wildcard lease at the snapshot→detect+//! boundary. We document this gap in PARITY.md so the port is auditable.+//!+//! ## Why this is a separate module+//!+//! `focus_steal::with_suppression` already exists as a thin closure+//! API around the dispatcher. `focus_guard::with_focus_suppressed`+//! wraps it with:+//!+//! 1. A "is target already frontmost?" check so we don't arm a useless+//! self→self suppressor (matches Swift's `isTargetFrontmost` guard).+//! 2. A 50ms post-action sleep that gives any in-flight focus-grab+//! reflex time to fire and be observed by the suppressor before the+//! lease is dropped. Matches Swift's `Task.sleep(nanoseconds: 50ms)`.+//! 3. A static `origin` label for tracing — call sites pass a short+//! string like `"click.AXPress"` so leaked leases / late-firing+//! observers can be traced back to the caller.++use std::time::Duration;++use crate::apps;+use crate::focus_steal;++/// Wrap an async closure `f` with a targeted focus-steal suppressor.+///+/// - `target_pid` — the pid the action is dispatched to. `Some(pid)` is+/// the standard case; `None` skips the targeted entry entirely+/// (caller relies on the surrounding `WindowChangeDetector` wildcard+/// lease).+/// - `prior_frontmost` — the pid to restore focus to if the target+/// activates. Typically captured from `apps::frontmost_pid()` before+/// the snapshot.+/// - `origin` — short static label for tracing, e.g. `"click.AXPress"`.+/// - `f` — the action to run with suppression armed.+///+/// Returns whatever `f` returns. Drops the lease ~50ms after `f`+/// resolves so any in-flight reflex activation is observed before+/// suppression ends.+///+/// If `target_pid` is already the frontmost app (no point fighting+/// ourselves) or `prior_frontmost` is `None` (no app to restore to),+/// the function still runs `f` — just without the lease. This keeps+/// the call sites simple (no per-tool `if frontmost == target` ladders).+pub async fn with_focus_suppressed<F, Fut, R>(+ target_pid: Option<i32>,+ prior_frontmost: Option<i32>,+ origin: &'static str,+ f: F,+) -> R+where+ F: FnOnce() -> Fut,+ Fut: std::future::Future<Output = R>,+{+ // Decide whether to arm a targeted lease. Three conditions must hold:+ // 1. We have a known target pid (Some).+ // 2. We have a prior frontmost to restore to (Some).+ // 3. The target isn't already frontmost — Swift's+ // `isTargetFrontmost` short-circuit, mirrored here. Without+ // it we'd arm an entry that re-activates the prior frontmost+ // against a no-op activation, fighting our own previous+ // restore.+ let should_arm = match (target_pid, prior_frontmost) {+ (Some(tp), Some(pf)) => tp != pf,+ _ => false,+ };++ let _lease = if should_arm {+ // unwrap()s are safe — `should_arm` is true only when both are Some.+ Some(focus_steal::begin_suppression(+ target_pid,+ prior_frontmost.unwrap(),+ origin,+ ))+ } else {+ None+ };++ let result = f().await;++ // Post-action settle — give the reactive observer time to fire on+ // any side-effect activation before we drop the lease. Matches+ // Swift's 50ms sleep in `FocusGuard.withFocusSuppressed`.+ if _lease.is_some() {+ tokio::time::sleep(Duration::from_millis(50)).await;+ }++ // _lease drops here (RAII end_suppression).+ result+}++/// Convenience wrapper that captures the current frontmost via+/// `apps::frontmost_pid()` at call time. Use when the caller doesn't+/// already have a `prior_frontmost` from a surrounding snapshot —+/// e.g. tools that only opt into the layer-3 guard without the+/// snapshot/detect cycle.+///+/// Most action tools should prefer `with_focus_suppressed` with an+/// explicit `prior_frontmost` captured *before* the snapshot, so the+/// wildcard lease + targeted lease both restore to the same pid.+pub async fn with_focus_suppressed_now<F, Fut, R>(+ target_pid: Option<i32>,+ origin: &'static str,+ f: F,+) -> R+where+ F: FnOnce() -> Fut,+ Fut: std::future::Future<Output = R>,+{+ let prior = apps::frontmost_pid();+ with_focus_suppressed(target_pid, prior, origin, f).await+}++// ── Tests ────────────────────────────────────────────────────────────────────++#[cfg(test)]+mod tests {+ use super::*;++ /// `with_focus_suppressed` runs the closure and returns its value.+ /// Skip-arming path (no prior frontmost) still executes f.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn runs_closure_without_prior_frontmost() {+ let n = with_focus_suppressed(+ Some(42),+ None, // no prior → no lease armed+ "test.no_prior",+ || async { 7 },+ )+ .await;+ assert_eq!(n, 7);+ }++ /// Skip-arming path: target == prior_frontmost (self → self).+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn runs_closure_when_target_is_prior_frontmost() {+ let n = with_focus_suppressed(+ Some(42),+ Some(42), // self → self → skip+ "test.self_to_self",+ || async { 11 },+ )+ .await;+ assert_eq!(n, 11);+ }++ /// Arming path: target != prior_frontmost. The lease is armed,+ /// closure runs, lease drops on the way out (we can't directly+ /// observe the dispatcher state through the public API here —+ /// the focus_steal module's own tests cover the lease lifecycle —+ /// but we exercise the codepath to make sure it compiles and the+ /// 50ms sleep doesn't deadlock.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn arms_lease_when_target_differs_from_prior() {+ let n = with_focus_suppressed(+ Some(123),+ Some(456),+ "test.armed",+ || async { 99 },+ )+ .await;+ assert_eq!(n, 99);+ }++ /// `with_focus_suppressed_now` resolves prior_frontmost via the+ /// live NSWorkspace query — exercise the codepath end-to-end.+ /// In a unit-test context (no NSApp main thread) the query may+ /// return None; the closure must still run.+ #[tokio::test(flavor = "multi_thread", worker_threads = 2)]+ async fn now_variant_runs_even_when_frontmost_is_none() {+ let n = with_focus_suppressed_now(Some(7), "test.now", || async { 5 }).await;+ assert_eq!(n, 5);+ }+}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs b/libs/cua-driver-rs/crates/platform-macos/src/lib.rsindex cf8d92bef1..f2c51cdea0 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/lib.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/lib.rs@@ -25,6 +25,10 @@ pub mod focus_steal;#[cfg(target_os = "macos")]pub mod permissions;#[cfg(target_os = "macos")]+pub mod focus_guard;+#[cfg(target_os = "macos")]+pub mod window_change_detector;+#[cfg(target_os = "macos")]pub mod tools;use mcp_server::tool::ToolRegistry;diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rsindex 59c2a7d1d2..aa71f007e4 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/click.rs@@ -22,6 +22,9 @@ use crate::ax::bindings::{copy_action_names, copy_children, copy_string_attr, element_screen_rect,AXUIElementRef,};+use crate::apps;+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;use core_foundation::base::CFRelease;use super::ToolState;@@ -134,19 +137,41 @@ impl Tool for ClickTool {crate::cursor::overlay::animate_cursor_to(cx, cy).await;}+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Capture prior frontmost, arm the wildcard suppressor in the+ // snapshot, then arm a targeted suppressor across the AX action+ // itself via FocusGuard. After the action returns, detect any+ // new-window / foreground side-effects and append a one-liner+ // suffix matching Swift's wording.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);+// Run AX work on a blocking thread (can't block async executor).let action_clone = action.clone();- let result = tokio::task::spawn_blocking(move || {- perform_ax_click(element_ptr, idx, pid, wid, &action_clone)- }).await;+ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "click.AXPress",+ || async move {+ tokio::task::spawn_blocking(move || {+ perform_ax_click(element_ptr, idx, pid, wid, &action_clone)+ })+ .await+ },+ )+ .await;++ // Drop the wildcard lease + detect window/foreground side-effects.+ let changes = snapshot.detect_async().await;match result {- Ok(Ok((msg, needs_webkit_delay))) => {+ Ok(Ok((mut msg, needs_webkit_delay))) => {// For text inputs, wait 800ms for WebKit DOM focus to settle// before returning — matches the Swift reference behaviour.if needs_webkit_delay {tokio::time::sleep(std::time::Duration::from_millis(800)).await;}+ msg.push_str(&changes.result_suffix());ToolResult::text(msg)}Ok(Err(e)) => ToolResult::error(format!("AX action failed: {e}")),@@ -264,25 +289,46 @@ impl Tool for ClickTool {cursor_overlay::OverlayCommand::ClickPulse { x: screen_x, y: screen_y });+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // A pixel click can land on a "Sign In" button that opens a sheet+ // or a Safari link that activates a new tab — same side-effect+ // shape as the AX path, so we wrap identically.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);+let mods_owned = modifiers.clone();- let result = tokio::task::spawn_blocking(move || {- let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();- // When we know the window_id, pass the window-local coordinates so- // `click_at_xy_with_window_local` can stamp `CGEventSetWindowLocation`- // and Chromium-specific fields (f40, f51, f58, f91, f92) onto events- // for better backgrounded-target delivery.- if let Some(wid) = window_id {- return crate::input::mouse::click_at_xy_with_window_local(- pid, screen_x, screen_y,- win_local_x, win_local_y,- wid, count, &m,- );- }- crate::input::mouse::click_at_xy(pid, screen_x, screen_y, count, &m)- }).await;+ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "click.pixel",+ || async move {+ tokio::task::spawn_blocking(move || {+ let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();+ // When we know the window_id, pass the window-local coordinates so+ // `click_at_xy_with_window_local` can stamp `CGEventSetWindowLocation`+ // and Chromium-specific fields (f40, f51, f58, f91, f92) onto events+ // for better backgrounded-target delivery.+ if let Some(wid) = window_id {+ return crate::input::mouse::click_at_xy_with_window_local(+ pid, screen_x, screen_y,+ win_local_x, win_local_y,+ wid, count, &m,+ );+ }+ crate::input::mouse::click_at_xy(pid, screen_x, screen_y, count, &m)+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {- Ok(Ok(())) => ToolResult::text(format!("✅ Posted click to pid {pid}.")),+ Ok(Ok(())) => ToolResult::text(format!(+ "✅ Posted click to pid {pid}.{}",+ changes.result_suffix()+ )),Ok(Err(e)) => ToolResult::error(format!("Click failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rsindex 1debbf2f58..6e50724f80 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/drag.rs@@ -12,7 +12,10 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};use serde_json::Value;use std::sync::Arc;+use crate::apps;+use crate::focus_guard;use crate::input::mouse::DragButton;+use crate::window_change_detector::WindowChangeDetector;use super::ToolState;pub struct DragTool {@@ -199,23 +202,42 @@ impl Tool for DragTool {}crate::cursor::overlay::animate_cursor_to(from_sx, from_sy).await;+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Drags can trigger drag-and-drop side-effects that spawn helper+ // windows (drop on Dock, drop on background app icon) and the+ // mouseDown half-event alone can activate the target app on some+ // Chromium builds. Wrap to catch + report both.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);+// Dispatch blocking drag synthesis.let mods_owned = modifiers.clone();- let result = tokio::task::spawn_blocking(move || {- let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();- crate::input::mouse::drag_at_xy(- pid,- from_sx, from_sy,- to_sx, to_sy,- Some((from_lx, from_ly)),- Some((to_lx, to_ly)),- window_id,- duration_ms,- steps,- &m,- button,- )- }).await;+ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "drag.CGEvent",+ || async move {+ tokio::task::spawn_blocking(move || {+ let m: Vec<&str> = mods_owned.iter().map(String::as_str).collect();+ crate::input::mouse::drag_at_xy(+ pid,+ from_sx, from_sy,+ to_sx, to_sy,+ Some((from_lx, from_ly)),+ Some((to_lx, to_ly)),+ window_id,+ duration_ms,+ steps,+ &m,+ button,+ )+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;// Animate cursor to end position.crate::cursor::overlay::animate_cursor_to(to_sx, to_sy).await;@@ -239,11 +261,12 @@ impl Tool for DragTool {"✅ Posted drag{btn_suffix}{mod_suffix} to pid {pid} \from window-pixel ({}, {}) → ({}, {}), \screen ({}, {}) → ({}, {}) \- in {duration_ms}ms / {steps} steps.",+ in {duration_ms}ms / {steps} steps.{}",from_x as i64, from_y as i64,to_x as i64, to_y as i64,from_sx as i64, from_sy as i64,to_sx as i64, to_sy as i64,+ changes.result_suffix(),)),Ok(Err(e)) => ToolResult::error(format!("drag failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rsindex 5c2b89819b..cde28faa09 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/hotkey.rs@@ -4,6 +4,10 @@ use serde_json::Value;use std::sync::Arc;use libc;+use crate::apps;+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;+use super::ToolState;pub struct HotkeyTool {@@ -112,20 +116,43 @@ impl Tool for HotkeyTool {let key_display = raw_keys.join("+");let window_id = args.get("window_id").and_then(|v| v.as_u64()).map(|v| v as u32);- let result = tokio::task::spawn_blocking(move || {- let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();- if let Some(wid) = window_id {- crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {- crate::input::keyboard::hotkey_no_auth(pid, &key, &m)- })?;- Ok(())- } else {- crate::input::keyboard::hotkey(pid, &key, &m)- }- }).await;+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Hotkeys like Cmd+N, Cmd+W, Cmd+T explicitly open/close+ // windows. The NSMenu path also briefly activates the target via+ // SLPSSetFrontProcessWithOptions which can race the wildcard+ // suppressor — wrapping ensures both side-effects are observed+ // and the prior frontmost is restored if the activation lingers.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);++ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "hotkey.CGEvent",+ || async move {+ tokio::task::spawn_blocking(move || {+ let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();+ if let Some(wid) = window_id {+ crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {+ crate::input::keyboard::hotkey_no_auth(pid, &key, &m)+ })?;+ Ok(())+ } else {+ crate::input::keyboard::hotkey(pid, &key, &m)+ }+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {- Ok(Ok(())) => ToolResult::text(format!("Pressed {key_display} on pid {pid}.")),+ Ok(Ok(())) => ToolResult::text(format!(+ "Pressed {key_display} on pid {pid}.{}",+ changes.result_suffix()+ )),Ok(Err(e)) => ToolResult::error(format!("hotkey failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rsindex 0a3b8df3e7..fd8066ba48 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/press_key.rs@@ -4,6 +4,10 @@ use serde_json::Value;use std::sync::Arc;use libc;+use crate::apps;+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;+use super::ToolState;pub struct PressKeyTool {@@ -86,32 +90,65 @@ impl Tool for PressKeyTool {};let display_key = key_raw.clone();- // Pre-focus element if requested (element_index + window_id path).- if let (Some(idx), Some(wid)) = (element_index, window_id) {- if let Some(element_ptr) = self.state.element_cache.get_element_ptr(pid, wid, idx) {- let _ = tokio::task::spawn_blocking(move || {- crate::input::ax_actions::focus_element(element_ptr)- }).await;- tokio::time::sleep(std::time::Duration::from_millis(30)).await;- }- }+ // Resolve the pre-focus element pointer (if requested) outside+ // the suppression closure — only the focus_element() write itself+ // needs to run under suppression, the cache lookup does not.+ let pre_focus_ptr: Option<usize> = if let (Some(idx), Some(wid)) = (element_index, window_id) {+ self.state.element_cache.get_element_ptr(pid, wid, idx)+ } else {+ None+ };- let result = tokio::task::spawn_blocking(move || {- let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();- if let Some(wid) = window_id {- if element_index.is_none() {- // NSMenu path: window_id set but no element_index.- crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {- crate::input::keyboard::press_key_no_auth(pid, &key, &m)- })?;- return Ok(());+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Single-key presses can fire autocomplete (Return on a search+ // box opens a results popover) or trigger menu shortcuts that+ // open windows. Wrapping mirrors the hotkey path.+ //+ // The AX focus_element() pre-write also runs inside the closure+ // so any reflex activations it triggers are caught by both the+ // wildcard snapshot suppressor and the targeted FocusGuard lease.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);++ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "press_key.CGEvent",+ || async move {+ // Pre-focus the element under suppression so its+ // side-effects are captured by the snapshot + lease.+ if let Some(element_ptr) = pre_focus_ptr {+ let _ = tokio::task::spawn_blocking(move || {+ crate::input::ax_actions::focus_element(element_ptr)+ }).await;+ tokio::time::sleep(std::time::Duration::from_millis(30)).await;}- }- crate::input::keyboard::press_key(pid, &key, &m)- }).await;++ tokio::task::spawn_blocking(move || {+ let m: Vec<&str> = modifiers.iter().map(String::as_str).collect();+ if let Some(wid) = window_id {+ if element_index.is_none() {+ // NSMenu path: window_id set but no element_index.+ crate::input::skylight::with_menu_shortcut_activation(pid as libc::pid_t, wid, || {+ crate::input::keyboard::press_key_no_auth(pid, &key, &m)+ })?;+ return Ok(());+ }+ }+ crate::input::keyboard::press_key(pid, &key, &m)+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {- Ok(Ok(())) => ToolResult::text(format!("✅ Pressed {display_key} on pid {pid}.")),+ Ok(Ok(())) => ToolResult::text(format!(+ "✅ Pressed {display_key} on pid {pid}.{}",+ changes.result_suffix()+ )),Ok(Err(e)) => ToolResult::error(format!("press_key failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rsindex ea8b642da1..cb07976470 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/scroll.rs@@ -3,6 +3,10 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};use serde_json::Value;use std::sync::Arc;+use crate::apps;+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;+use super::ToolState;pub struct ScrollTool {@@ -73,15 +77,14 @@ impl Tool for ScrollTool {let element_index = args.get("element_index").and_then(|v| v.as_u64()).map(|v| v as usize);let window_id = args.get("window_id").and_then(|v| v.as_u64()).map(|v| v as u32);- // Pre-focus element if requested.- if let (Some(idx), Some(wid)) = (element_index, window_id) {- if let Some(element_ptr) = self.state.element_cache.get_element_ptr(pid, wid, idx) {- let _ = tokio::task::spawn_blocking(move || {- crate::input::ax_actions::focus_element(element_ptr)- }).await;- tokio::time::sleep(std::time::Duration::from_millis(30)).await;- }- }+ // Resolve the pre-focus element pointer (if requested) outside+ // the suppression closure — only the focus_element() write itself+ // needs to run under suppression, the cache lookup does not.+ let pre_focus_ptr: Option<usize> = if let (Some(idx), Some(wid)) = (element_index, window_id) {+ self.state.element_cache.get_element_ptr(pid, wid, idx)+ } else {+ None+ };let key = match (by.as_str(), direction.as_str()) {("page", "down") | (_, "down") if by == "page" => "pagedown",@@ -94,18 +97,52 @@ impl Tool for ScrollTool {};let key = key.to_owned();- let result = tokio::task::spawn_blocking(move || {- for _ in 0..amount {- if let Err(e) = crate::input::keyboard::press_key(pid, &key, &[]) {- return Err(e);+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Scroll keystrokes (PageDown / arrow) into search-box autocomplete+ // can spawn floating helper windows; rare but real. Wrap for parity+ // with the other action tools.+ //+ // The AX focus_element() pre-write also runs inside the closure so+ // any reflex activations it triggers are caught by both the wildcard+ // snapshot suppressor and the targeted FocusGuard lease.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);++ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "scroll.CGEvent",+ || async move {+ // Pre-focus the element under suppression so its+ // side-effects are captured by the snapshot + lease.+ if let Some(element_ptr) = pre_focus_ptr {+ let _ = tokio::task::spawn_blocking(move || {+ crate::input::ax_actions::focus_element(element_ptr)+ }).await;+ tokio::time::sleep(std::time::Duration::from_millis(30)).await;}- std::thread::sleep(std::time::Duration::from_millis(50));- }- Ok(())- }).await;++ tokio::task::spawn_blocking(move || {+ for _ in 0..amount {+ if let Err(e) = crate::input::keyboard::press_key(pid, &key, &[]) {+ return Err(e);+ }+ std::thread::sleep(std::time::Duration::from_millis(50));+ }+ Ok(())+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {- Ok(Ok(())) => ToolResult::text(format!("Scrolled {direction} by {by} × {amount}.")),+ Ok(Ok(())) => ToolResult::text(format!(+ "Scrolled {direction} by {by} × {amount}.{}",+ changes.result_suffix()+ )),Ok(Err(e)) => ToolResult::error(format!("Scroll failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rsindex 85d4e17cd2..2380be7779 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/set_value.rs@@ -16,10 +16,13 @@ use mcp_server::{protocol::ToolResult, tool::{Tool, ToolDef}};use serde_json::Value;use std::sync::Arc;+use crate::apps;use crate::ax::bindings::{copy_children, copy_string_attr, perform_action, set_string_attr,kAXErrorSuccess, AXUIElementRef,};+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;use core_foundation::base::CFRelease;use super::ToolState;@@ -105,12 +108,33 @@ impl Tool for SetValueTool {)),};- let result = tokio::task::spawn_blocking(move || {- set_value_blocking(element_ptr, element_index, pid, &value)- }).await;+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // AXValue writes on popups / sliders can cause reflex activations+ // in Chromium-based apps; the AXPopUpButton path also AXPresses a+ // child option which can trigger app activation in some setups.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);++ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "set_value.AXValue",+ || async move {+ tokio::task::spawn_blocking(move || {+ set_value_blocking(element_ptr, element_index, pid, &value)+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {- Ok(Ok(msg)) => ToolResult::text(msg),+ Ok(Ok(mut msg)) => {+ msg.push_str(&changes.result_suffix());+ ToolResult::text(msg)+ }Ok(Err(e)) => ToolResult::error(format!("set_value failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),}diff --git a/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs b/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rsindex 8040e0b4eb..9c5e4d63d2 100644--- a/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs+++ b/libs/cua-driver-rs/crates/platform-macos/src/tools/type_text.rs@@ -22,6 +22,9 @@ use crate::ax::bindings::{copy_string_attr, focused_element_of_pid, kAXErrorSuccess, set_string_attr,AXUIElementRef,};+use crate::apps;+use crate::focus_guard;+use crate::window_change_detector::WindowChangeDetector;use core_foundation::base::CFRelease;use super::ToolState;@@ -120,13 +123,33 @@ impl Tool for TypeTextTool {let text_clone = text.clone();let char_count = text.chars().count();- let result = tokio::task::spawn_blocking(move || {- type_text_blocking(pid, &text_clone, element_ptr, delay_ms)- }).await;+ // ── Focus-suppression wrap (Swift WindowChangeDetector + FocusGuard) ──+ // Typing into a field can trigger autocomplete popovers or+ // Chrome/Safari's "Save Password?" prompt, both of which open+ // helper windows. Wrap so callers see them in the result suffix+ // and the wildcard suppressor catches reflex activations.+ let prior_front = apps::frontmost_pid();+ let snapshot = WindowChangeDetector::snapshot(prior_front);++ let result = focus_guard::with_focus_suppressed(+ Some(pid),+ prior_front,+ "type_text.AXSelectedText",+ || async move {+ tokio::task::spawn_blocking(move || {+ type_text_blocking(pid, &text_clone, element_ptr, delay_ms)+ })+ .await+ },+ )+ .await;++ let changes = snapshot.detect_async().await;match result {Ok(Ok(detail)) => ToolResult::text(format!(- "✅ Inserted {char_count} char(s){detail}."+ "✅ Inserted {char_count} char(s){detail}.{}",+ changes.result_suffix())),Ok(Err(e)) => ToolResult::error(format!("type_text failed: {e}")),Err(e) => ToolResult::error(format!("Task error: {e}")),diff --git a/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rs b/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rsnew file mode 100644index 0000000000..aab84209e0--- /dev/null+++ b/libs/cua-driver-rs/crates/platform-macos/src/window_change_detector.rs@@ -0,0 +1,485 @@+//! Window-change detector — Rust port of Swift's+//! `WindowChangeDetector` (`libs/cua-driver/Sources/CuaDriverServer/Tools/WindowChangeDetector.swift`).+//!+//! ## What this does+//!+//! Action tools (click, type_text, hotkey, …) on a backgrounded app can+//! trigger window/foreground side-effects: a "Sign In" button opens a+//! modal sheet, a Safari link spawns a new tab, an autocomplete dropdown+//! pops a helper window. The Rust port mirrors Swift's+//! snapshot → action → detect cycle so tool results can:+//!+//! 1. Surface the side-effect to the agent (one-line suffix on the+//! tool result, matching Swift verbatim).+//! 2. Arm a **wildcard** focus-steal suppression entry that covers the+//! full snapshot→detect window. Wildcards (`target_pid = None`)+//! catch any activation other than the prior frontmost — so even an+//! app we didn't know about (Safari activating because a UTM Gallery+//! link routed to it) is suppressed before the first compositor+//! frame.+//!+//! ## Usage+//!+//! ```ignore+//! // Callers capture frontmost BEFORE the snapshot so the wildcard+//! // suppressor and the snapshot's recorded frontmost agree on the+//! // pid to restore to — avoids a race where another app activates+//! // between the caller's `frontmost_pid()` and the detector's own.+//! let prior_front = apps::frontmost_pid();+//! let snapshot = WindowChangeDetector::snapshot(prior_front);+//! // … perform action …+//! let changes = snapshot.detect();+//! // changes.result_suffix() — append to ToolResult text.+//! ```+//!+//! Dropping the `Snapshot` ends the suppression lease (RAII). `detect()`+//! also drops the lease before returning — the lease's `Drop` is+//! idempotent so explicit-detect + later-drop is safe.++use std::collections::HashSet;+use std::time::{Duration, Instant};++use crate::apps;+use crate::focus_steal::{self, SuppressionLease};+use crate::windows::{self, WindowInfo};++/// One window that appeared between `snapshot()` and `detect()`.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct WindowEvent {+ pub window_id: u32,+ pub pid: i32,+ pub app_name: String,+ pub title: String,+}++/// Categorical diff entry. We mirror Swift which only emits+/// `WindowEvent` rows for *new* windows — closed/changed never appear+/// in the result suffix — but keep them as enum variants for future+/// extensibility and so unit tests can pin down the diff semantics.+#[derive(Debug, Clone, PartialEq, Eq)]+pub enum WindowChange {+ Opened(WindowEvent),+ Closed { window_id: u32 },+}++/// State captured immediately before the action fires.+///+/// Holds:+/// - `window_ids` — the set of visible layer-0 window IDs at snapshot+/// time. `detect()` diffs against this.+/// - `front_pid` — the OS frontmost pid at snapshot time. `detect()`+/// reports whether a *different* pid became frontmost. The wildcard+/// suppressor in `focus_steal` will normally restore the original+/// front before `detect()`'s poll loop observes the change, so this+/// field is best-effort.+/// - `_lease` — the wildcard suppression lease. Dropping the snapshot+/// ends suppression. Held inside `Option` so `detect()` can take it+/// and drop early.+pub struct Snapshot {+ window_ids: HashSet<u32>,+ front_pid: Option<i32>,+ _lease: Option<SuppressionLease>,+}++/// Result of `detect()` — what changed during the action window.+#[derive(Debug, Clone)]+pub struct Changes {+ pub new_windows: Vec<WindowEvent>,+ pub foreground_changed: bool,+}++impl Changes {+ pub fn no_change() -> Self {+ Self {+ new_windows: Vec::new(),+ foreground_changed: false,+ }+ }++ /// True when we found evidence that the action triggered a cross-app+ /// side-effect that required (or would have required) a foreground+ /// restore. Matches Swift's `Changes.needsRestore`.+ pub fn needs_restore(&self) -> bool {+ self.foreground_changed || !self.new_windows.is_empty()+ }++ /// One-liner summary to append to a tool result, or empty string+ /// when nothing interesting happened.+ ///+ /// Format mirrors Swift `WindowChangeDetector.Changes.resultSuffix`+ /// **verbatim** so MCP callers that key off the suffix wording+ /// don't need a per-binary special case.+ pub fn result_suffix(&self) -> String {+ if !self.needs_restore() {+ return String::new();+ }++ if !self.new_windows.is_empty() {+ // Group by app name (stable order), join titles per app.+ let mut by_app: std::collections::BTreeMap<&str, Vec<&str>> =+ std::collections::BTreeMap::new();+ for w in &self.new_windows {+ by_app.entry(&w.app_name).or_default().push(&w.title);+ }+ let summaries: Vec<String> = by_app+ .into_iter()+ .map(|(app, titles)| {+ let titles: Vec<String> = titles+ .into_iter()+ .filter(|t| !t.is_empty())+ .map(|t| format!("\"{t}\""))+ .collect();+ if titles.is_empty() {+ app.to_string()+ } else {+ format!("{app} ({})", titles.join(", "))+ }+ })+ .collect();+ format!(+ "\n\n🪟 Action opened new window(s): {}.",+ summaries.join("; ")+ )+ } else {+ "\n\n🔀 Action caused a different app to become frontmost.".to_string()+ }+ }+}++/// Default poll deadline — new windows triggered by a click typically+/// appear within ~200ms on macOS; 1.0s gives the wildcard suppressor+/// time to fire and settle.+const DEFAULT_TIMEOUT: Duration = Duration::from_millis(1000);++/// Default inter-poll interval. Matches Swift's 50ms.+const DEFAULT_POLL_INTERVAL: Duration = Duration::from_millis(50);++/// Public API. Mirrors Swift `enum WindowChangeDetector` — no state of+/// its own; all state lives inside the returned `Snapshot`.+pub struct WindowChangeDetector;++impl WindowChangeDetector {+ /// Capture the current window set + frontmost pid and arm the+ /// wildcard focus-steal suppressor. Call immediately before+ /// dispatching the action.+ ///+ /// `prior_front` is the frontmost pid the **caller** already+ /// observed — typically captured one line earlier via+ /// `apps::frontmost_pid()` for the surrounding `focus_guard`+ /// lease. We use the caller's value (not a fresh re-read) so the+ /// wildcard suppressor's `restore_to` matches what the focus-guard+ /// lease saw; a race where another app became frontmost between+ /// the caller's read and this method would otherwise leave the+ /// two leases targeting different pids.+ ///+ /// Returns `Snapshot`. Drop ends suppression (via the held+ /// `SuppressionLease`); call `Snapshot::detect()` to consume the+ /// snapshot and get a `Changes` summary.+ ///+ /// Safe to call from any thread — `CGWindowListCopyWindowInfo` is+ /// documented as thread-safe.+ pub fn snapshot(prior_front: Option<i32>) -> Snapshot {+ let window_ids: HashSet<u32> = windows::visible_windows()+ .into_iter()+ .filter(|w| w.layer == 0)+ .map(|w| w.window_id)+ .collect();++ // Arm wildcard suppression — covers snapshot → detect window.+ // restore_to = caller-captured frontmost; target = wildcard+ // (any other pid). If there's no frontmost (rare — screensaver,+ // login window), we skip the lease; foreground-change tracking+ // still runs.+ let lease = prior_front.map(|restore_to| {+ focus_steal::begin_suppression(+ None, // wildcard+ restore_to,+ "WindowChangeDetector.snapshot",+ )+ });++ Snapshot {+ window_ids,+ front_pid: prior_front,+ _lease: lease,+ }+ }+}++impl Snapshot {+ /// Frontmost pid at snapshot time, if any.+ pub fn front_pid(&self) -> Option<i32> {+ self.front_pid+ }++ /// Poll for up to `DEFAULT_TIMEOUT` for new windows or a+ /// foreground-app change. Returns as soon as a change is detected+ /// or the timeout elapses.+ ///+ /// Consumes the snapshot — the wildcard suppression lease is+ /// dropped when this returns (covers the full action + detection+ /// window).+ pub fn detect(self) -> Changes {+ self.detect_with(DEFAULT_TIMEOUT, DEFAULT_POLL_INTERVAL)+ }++ /// Async wrapper around `detect()` — runs the synchronous poll+ /// loop on a `spawn_blocking` thread so it doesn't stall the+ /// tokio runtime. Most action-tool call sites should prefer this+ /// over the blocking `detect()`.+ pub async fn detect_async(self) -> Changes {+ // Move the Snapshot (and its embedded lease) onto the blocking+ // thread; the lease's Drop runs there when detect_with returns.+ tokio::task::spawn_blocking(move || self.detect())+ .await+ .unwrap_or_else(|_| Changes::no_change())+ }++ /// Same as `detect()` but with configurable timing — exposed for+ /// tests / callers that want a tighter or looser poll window.+ pub fn detect_with(self, timeout: Duration, poll_interval: Duration) -> Changes {+ let deadline = Instant::now() + timeout;+ loop {+ std::thread::sleep(poll_interval);++ let current: Vec<WindowInfo> = windows::visible_windows()+ .into_iter()+ .filter(|w| w.layer == 0)+ .collect();+ let current_ids: HashSet<u32> = current.iter().map(|w| w.window_id).collect();++ let new_windows: Vec<WindowEvent> = current+ .iter()+ .filter(|w| !self.window_ids.contains(&w.window_id))+ .map(|w| WindowEvent {+ window_id: w.window_id,+ pid: w.pid,+ app_name: w.app_name.clone(),+ title: w.title.clone(),+ })+ .collect();+ // Diff the other direction too — keeps unit tests honest+ // even though Swift's result_suffix only uses opened windows.+ let _closed: Vec<u32> = self+ .window_ids+ .iter()+ .copied()+ .filter(|id| !current_ids.contains(id))+ .collect();++ let current_front = apps::frontmost_pid();+ let foreground_changed = match (self.front_pid, current_front) {+ (Some(orig), Some(cur)) => orig != cur,+ _ => false,+ };++ if !new_windows.is_empty() || foreground_changed {+ return Changes {+ new_windows,+ foreground_changed,+ };+ }+ if Instant::now() >= deadline {+ return Changes::no_change();+ }+ }+ }++ // ── Internal helpers — also used by unit tests via the `pub(super)`+ // path so the diff logic can be exercised without driving the live+ // window enumerator. ────────────────────────────────────────────++ /// Pure-function diff: given the snapshot's window-id set + a+ /// list of currently-visible windows, return the (opened, closed)+ /// classification.+ pub(crate) fn diff(+ snapshot_ids: &HashSet<u32>,+ current: &[WindowInfo],+ ) -> (Vec<WindowEvent>, Vec<u32>) {+ let current_ids: HashSet<u32> = current.iter().map(|w| w.window_id).collect();+ let opened: Vec<WindowEvent> = current+ .iter()+ .filter(|w| !snapshot_ids.contains(&w.window_id))+ .map(|w| WindowEvent {+ window_id: w.window_id,+ pid: w.pid,+ app_name: w.app_name.clone(),+ title: w.title.clone(),+ })+ .collect();+ let closed: Vec<u32> = snapshot_ids+ .iter()+ .copied()+ .filter(|id| !current_ids.contains(id))+ .collect();+ (opened, closed)+ }+}++// ── Tests ────────────────────────────────────────────────────────────────────++#[cfg(test)]+mod tests {+ use super::*;+ use crate::windows::WindowBounds;++ fn win(id: u32, pid: i32, app: &str, title: &str) -> WindowInfo {+ WindowInfo {+ window_id: id,+ pid,+ app_name: app.into(),+ title: title.into(),+ bounds: WindowBounds {+ x: 0.,+ y: 0.,+ width: 100.,+ height: 100.,+ },+ layer: 0,+ z_index: 0,+ is_on_screen: true,+ on_current_space: None,+ space_ids: None,+ }+ }++ #[test]+ fn diff_finds_opened_window() {+ let snap: HashSet<u32> = [1, 2].into_iter().collect();+ let cur = vec![+ win(1, 100, "Safari", "Home"),+ win(2, 100, "Safari", "Tab2"),+ win(3, 101, "Mail", "Inbox"),+ ];+ let (opened, closed) = Snapshot::diff(&snap, &cur);+ assert_eq!(opened.len(), 1);+ assert_eq!(opened[0].window_id, 3);+ assert_eq!(opened[0].app_name, "Mail");+ assert_eq!(opened[0].title, "Inbox");+ assert!(closed.is_empty());+ }++ #[test]+ fn diff_finds_closed_window() {+ let snap: HashSet<u32> = [1, 2, 3].into_iter().collect();+ let cur = vec![win(1, 100, "Safari", "Home")];+ let (opened, closed) = Snapshot::diff(&snap, &cur);+ assert!(opened.is_empty());+ assert_eq!(closed.len(), 2);+ let closed_set: HashSet<u32> = closed.into_iter().collect();+ assert!(closed_set.contains(&2));+ assert!(closed_set.contains(&3));+ }++ #[test]+ fn diff_no_change() {+ let snap: HashSet<u32> = [1, 2].into_iter().collect();+ let cur = vec![win(1, 100, "Safari", "A"), win(2, 100, "Safari", "B")];+ let (opened, closed) = Snapshot::diff(&snap, &cur);+ assert!(opened.is_empty());+ assert!(closed.is_empty());+ }++ #[test]+ fn changes_result_suffix_no_change_is_empty() {+ let c = Changes::no_change();+ assert_eq!(c.result_suffix(), "");+ assert!(!c.needs_restore());+ }++ #[test]+ fn changes_result_suffix_single_new_window_with_title() {+ let c = Changes {+ new_windows: vec![WindowEvent {+ window_id: 99,+ pid: 100,+ app_name: "Chrome".into(),+ title: "New Tab".into(),+ }],+ foreground_changed: false,+ };+ assert!(c.needs_restore());+ assert_eq!(+ c.result_suffix(),+ "\n\n🪟 Action opened new window(s): Chrome (\"New Tab\")."+ );+ }++ #[test]+ fn changes_result_suffix_groups_windows_by_app() {+ let c = Changes {+ new_windows: vec![+ WindowEvent {+ window_id: 1,+ pid: 100,+ app_name: "Chrome".into(),+ title: "Tab A".into(),+ },+ WindowEvent {+ window_id: 2,+ pid: 100,+ app_name: "Chrome".into(),+ title: "Tab B".into(),+ },+ WindowEvent {+ window_id: 3,+ pid: 101,+ app_name: "Mail".into(),+ title: "".into(),+ },+ ],+ foreground_changed: true,+ };+ let suffix = c.result_suffix();+ // BTreeMap sort order is alphabetical by app name → Chrome before Mail.+ assert_eq!(+ suffix,+ "\n\n🪟 Action opened new window(s): Chrome (\"Tab A\", \"Tab B\"); Mail."+ );+ }++ #[test]+ fn changes_result_suffix_foreground_change_only() {+ let c = Changes {+ new_windows: vec![],+ foreground_changed: true,+ };+ assert!(c.needs_restore());+ assert_eq!(+ c.result_suffix(),+ "\n\n🔀 Action caused a different app to become frontmost."+ );+ }++ #[test]+ fn changes_result_suffix_empty_title_is_dropped() {+ let c = Changes {+ new_windows: vec![WindowEvent {+ window_id: 1,+ pid: 100,+ app_name: "Finder".into(),+ title: "".into(),+ }],+ foreground_changed: false,+ };+ // No title → just the app name, no parentheses.+ assert_eq!(c.result_suffix(), "\n\n🪟 Action opened new window(s): Finder.");+ }++ /// Regression: `snapshot(prior_front)` must store the caller's+ /// captured front pid verbatim (rather than re-reading it inside+ /// the function and racing with concurrent activations).+ #[test]+ fn snapshot_stores_caller_prior_front() {+ // Use an obviously bogus pid so we'd notice if the impl silently+ // fell back to the live frontmost on this test runner.+ let bogus_prior = Some(424242_i32);+ let snap = WindowChangeDetector::snapshot(bogus_prior);+ assert_eq!(snap.front_pid(), bogus_prior);++ // None must round-trip too — and must skip the lease without+ // panicking (no frontmost to restore to).+ let snap_none = WindowChangeDetector::snapshot(None);+ assert_eq!(snap_none.front_pid(), None);+ }+}