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
cua-driver: NSMenu key equivalents on backgrounded apps, overlay z-order, focus fixes (#1437)
ddupont8a551a8f92eb
diff --git a/libs/cua-driver/Sources/CuaDriverCore/Apps/AppLauncher.swift b/libs/cua-driver/Sources/CuaDriverCore/Apps/AppLauncher.swiftindex 831072d9fd..60343ca1b1 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Apps/AppLauncher.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Apps/AppLauncher.swift@@ -20,23 +20,15 @@ public enum AppLauncher {}}- /// Launch a macOS app in the background — no focus steal, no window- /// visible on screen.+ /// Launch a macOS app in the background — window visible on screen,+ /// no focus steal.///- /// Uses `NSWorkspace.openApplication(at:configuration:)` with both- /// `configuration.activates = false` and `configuration.hides = true`.- /// The `hides = true` flag is the key to a fully-populated AX tree on- /// a pure background launch: LaunchServices lets the target finish- /// `applicationDidFinishLaunching` and create its window, then hides- /// the app back immediately. The target's AX tree is fully populated- /// (Calculator on macOS 14+ goes from a 13-element menu-bar-only tree- /// to a 41-element tree with the keypad) and there's no visible- /// focus flash because the window never draws on screen.- ///- /// To bring a hidden-launched app onto the screen, the caller (or- /// the user) must explicitly unhide it — either via- /// `NSRunningApplication.unhide()` from their own code or through- /// regular macOS UI (Dock click, Cmd-Tab, etc.).+ /// Uses `NSWorkspace.open(_:configuration:)` with+ /// `configuration.activates = false` so the target never becomes the+ /// frontmost app. After the launch callback, `NSRunningApplication.unhide()`+ /// is called so the target's windows appear on screen behind the current+ /// foreground app. The AX tree is fully populated and automation can+ /// start immediately via `click`, `hotkey`, `get_window_state`, etc.////// When `urls` is non-empty, dispatches through/// `NSWorkspace.open(_:withApplicationAt:configuration:)` instead so@@ -139,15 +131,59 @@ public enum AppLauncher {}}- // We intentionally do NOT call `NSRunningApplication.unhide()` here.+ // Unhide the app so its windows are visible on screen in the+ // background. `activates = false` already prevents focus steal;+ // `unhide()` only makes existing windows drawable — it does not+ // activate the app or raise it above the current foreground.//- // `unhide()` bumps the target's CPS activation count away from 0,- // which lets a target like Chrome's subsequent self-activation- // succeed and raise its window on top of the user's work —- // exactly the focus-steal we're trying to avoid. Leaving the- // activation count at 0 keeps self-activation attempts as the- // softer "presents 0 windows, is frontable" rejection, which- // resolves on its own once the target creates a window.+ // If the app self-activates after unhide (Chrome occasionally does+ // during its launch lifecycle), the focus-steal preventer in+ // LaunchAppTool re-activates the previous frontmost app. Calling+ // unhide() here is safe because by the time we reach this point+ // the launch-lifecycle self-activation window has closed.+ if let runningApp = NSRunningApplication(+ processIdentifier: info.pid)+ {+ runningApp.unhide()+ }++ // For Finder and Safari: if no on-screen windows appeared after+ // unhide (e.g. already running with windows on a different Space),+ // open the home directory via the URL-handoff path. This calls+ // `application(_:open:)` which creates a new window on the current+ // Space without activation — Finder opens ~/, Safari opens it as a+ // local file URL. Scoped to these two apps only to avoid unintended+ // side effects on other apps (document pickers, unexpected behavior).+ if urls.isEmpty {+ let resolvedBundleId =+ Bundle(url: appURL)?.bundleIdentifier ?? bundleId ?? ""+ let wantsFallback =+ resolvedBundleId == "com.apple.finder"+ || resolvedBundleId == "com.apple.Safari"+ if wantsFallback {+ let onScreen = WindowEnumerator.visibleWindows().filter { $0.pid == info.pid }+ if onScreen.isEmpty {+ // Finder gets its home directory; Safari gets a blank page.+ let fallbackURL: URL =+ resolvedBundleId == "com.apple.Safari"+ ? URL(string: "about:blank")!+ : FileManager.default.homeDirectoryForCurrentUser+ let fallbackConfig = NSWorkspace.OpenConfiguration()+ fallbackConfig.activates = false+ fallbackConfig.addsToRecentItems = false+ _ = try? await withCheckedThrowingContinuation {+ (cont: CheckedContinuation<AppInfo, Error>) in+ NSWorkspace.shared.open(+ [fallbackURL],+ withApplicationAt: appURL,+ configuration: fallbackConfig+ ) { app, error in+ Self.resumeWithResult(cont: cont, app: app, error: error)+ }+ }+ }+ }+ }return info}diff --git a/libs/cua-driver/Sources/CuaDriverCore/Input/FocusWithoutRaise.swift b/libs/cua-driver/Sources/CuaDriverCore/Input/FocusWithoutRaise.swiftindex bfc61cc809..67c6608df1 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Input/FocusWithoutRaise.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Input/FocusWithoutRaise.swift@@ -9,7 +9,8 @@ import Foundation/// in `src/window_manager.c`):////// 1. `_SLPSGetFrontProcess(&prevPSN)` — capture current front.-/// 2. `GetProcessForPID(targetPid, &targetPSN)`.+/// 2. `SLSGetWindowOwner + SLSGetConnectionPSN` → target PSN from window ID+/// (replaces the deprecated `GetProcessForPID` on macOS 15+)./// 3. `SLPSPostEventRecordTo(prevPSN, 248-byte-buf)` with `bytes[0x8a] = 0x02`/// (defocus marker) → tells WindowServer the previous front's window/// has lost focus without asking for a raise of anything else.@@ -63,7 +64,7 @@ public enum FocusWithoutRaise {guard prevOk else { return false }let targetOk = targetPSN.withUnsafeMutableBytes { raw in- SkyLightEventPost.getProcessPSN(forPid: targetPid, into: raw.baseAddress!)+ SkyLightEventPost.getProcessPSN(forWindowId: targetWid, into: raw.baseAddress!)}guard targetOk else { return false }@@ -96,4 +97,49 @@ public enum FocusWithoutRaise {return defocusOk && focusOk}++ /// Full-activate variant for the keyboard → NSMenu shortcut path.+ ///+ /// Unlike `activateWithoutRaise` (which only changes AppKit-active state via+ /// the PSN defocus/focus recipe), this calls `SLPSSetFrontProcessWithOptions`+ /// with `kCPSNoWindows (0x400)` directly, which makes the target both+ /// **AppKit-active** AND **WindowServer-level frontmost** in a single step —+ /// without raising windows or triggering Space follow.+ ///+ /// Why the full-frontmost step is required for NSMenu key equivalents:+ /// - HID-tap events (`CGEvent.post(tap: .cghidEventTap)`) route to the+ /// **WindowServer-level frontmost** process, not the AppKit-active one.+ /// `activateWithoutRaise` only changes AppKit-active, so HID-tap events+ /// still go to the sentinel foreground app (e.g., the terminal), not the+ /// backgrounded target.+ /// - After `SLPSSetFrontProcessWithOptions(kCPSNoWindows)`, the target IS the+ /// WindowServer frontmost, so the HID-tap reaches its event queue where+ /// `NSApplication.sendEvent:` dispatches NSMenu key equivalents.+ ///+ /// **Trade-off**: causes exactly 1 focus loss on the sentinel foreground app+ /// (same as the click path). Using `kCPSNoWindows` rather than the default+ /// `kCPSUserGenerated = 0x100` avoids window raise and Space follow.+ ///+ /// This is NOT used for the click/mouse path because Chrome's user-activation+ /// gate rejects synthetic clicks after `SLPSSetFrontProcessWithOptions` — the+ /// PSN-only recipe in `activateWithoutRaise` is sufficient for clicks.+ @discardableResult+ public static func activateForMenuShortcut(+ targetPid: pid_t, targetWid: CGWindowID+ ) -> Bool {+ // Resolve target PSN from window ID (modern path via SLSGetWindowOwner ++ // SLSGetConnectionPSN; fallback GetProcessForPID on older macOS).+ var targetPSN = [UInt32](repeating: 0, count: 2)+ let targetOk = targetPSN.withUnsafeMutableBytes { raw in+ SkyLightEventPost.getProcessPSN(forWindowId: targetWid, into: raw.baseAddress!)+ }+ guard targetOk else { return false }++ // One call makes the target both AppKit-active and WindowServer-frontmost+ // without raising windows. HID-tap events will now route to this process.+ return targetPSN.withUnsafeBytes { psnRaw in+ SkyLightEventPost.setFrontProcessNoWindows(+ psn: psnRaw.baseAddress!, windowID: UInt32(targetWid))+ }+ }}diff --git a/libs/cua-driver/Sources/CuaDriverCore/Input/KeyboardInput.swift b/libs/cua-driver/Sources/CuaDriverCore/Input/KeyboardInput.swiftindex 0f9b712e75..0f4403bd34 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Input/KeyboardInput.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Input/KeyboardInput.swift@@ -34,14 +34,15 @@ public enum KeyboardInput {public static func press(_ key: String,modifiers: [String] = [],- toPid pid: pid_t? = nil+ toPid pid: pid_t? = nil,+ attachAuthMessage: Bool = true) throws {guard let code = virtualKeyCode(for: key) else {throw KeyboardError.unknownKey(key)}let flags = modifierMask(for: modifiers)- try sendKey(code: code, down: true, flags: flags, toPid: pid)- try sendKey(code: code, down: false, flags: flags, toPid: pid)+ try sendKey(code: code, down: true, flags: flags, toPid: pid, attachAuthMessage: attachAuthMessage)+ try sendKey(code: code, down: false, flags: flags, toPid: pid, attachAuthMessage: attachAuthMessage)}/// Press a combination of keys simultaneously.@@ -50,7 +51,15 @@ public enum KeyboardInput {/// If multiple non-modifier keys are supplied, only the last is pressed./// Pass `toPid` to route to a specific process's event queue via/// `CGEvent.postToPid`, bypassing frontmost-app routing.- public static func hotkey(_ keys: [String], toPid pid: pid_t? = nil) throws {+ ///+ /// `attachAuthMessage`: when `true` (default) attaches the SkyLight auth+ /// envelope Chromium needs; when `false` routes via `IOHIDPostEvent` so+ /// NSMenu key equivalents in native AppKit apps fire correctly.+ public static func hotkey(+ _ keys: [String],+ toPid pid: pid_t? = nil,+ attachAuthMessage: Bool = true+ ) throws {var modifiers: [String] = []var finalKey: String?for raw in keys {@@ -63,7 +72,7 @@ public enum KeyboardInput {guard let final = finalKey else {throw KeyboardError.noKeyInCombo}- try press(final, modifiers: modifiers, toPid: pid)+ try press(final, modifiers: modifiers, toPid: pid, attachAuthMessage: attachAuthMessage)}/// Type each character in ``text`` as a synthetic key-down + key-up@@ -103,7 +112,8 @@ public enum KeyboardInput {code: Int,down: Bool,flags: CGEventFlags,- toPid pid: pid_t? = nil+ toPid pid: pid_t? = nil,+ attachAuthMessage: Bool = true) throws {guardlet event = CGEvent(@@ -116,15 +126,20 @@ public enum KeyboardInput {}event.flags = flagsif let pid {- // Prefer SkyLight's SLEventPostToPid — it routes through- // CGSTickleActivityMonitor which Chromium omniboxes need to- // promote the synthetic event into their keyboard pipeline.- // Prefer SkyLight's SLEventPostToPid — it routes through- // CGSTickleActivityMonitor which some apps need to promote- // the synthetic event. Falls back to the public- // CGEventPostToPid when the SPI is unavailable (older macOS- // / stripped framework).- if !SkyLightEventPost.postToPid(pid, event: event) {+ // Two delivery paths:+ //+ // attachAuthMessage=true (Chromium path, default):+ // SLEventSetAuthenticationMessage + SLEventPostToPid →+ // direct-mach delivery; Chromium omniboxes accept synthetic+ // keyboard events as trusted input. Bypasses IOHIDPostEvent+ // and therefore NSMenu's key-equivalent dispatch.+ //+ // attachAuthMessage=false (native-AppKit/NSMenu path):+ // SLEventPostToPid without envelope → SLEventPostToPSN →+ // IOHIDPostEvent → Finder/TextEdit/etc. event queue where+ // NSApplication.sendEvent: dispatches NSMenu key equivalents.+ // Falls back to CGEvent.postToPid when SkyLight isn't available.+ if !SkyLightEventPost.postToPid(pid, event: event, attachAuthMessage: attachAuthMessage) {event.postToPid(pid)}} else {diff --git a/libs/cua-driver/Sources/CuaDriverCore/Input/SkyLightEventPost.swift b/libs/cua-driver/Sources/CuaDriverCore/Input/SkyLightEventPost.swiftindex 291a2e7030..7d753de960 100644--- a/libs/cua-driver/Sources/CuaDriverCore/Input/SkyLightEventPost.swift+++ b/libs/cua-driver/Sources/CuaDriverCore/Input/SkyLightEventPost.swift@@ -167,6 +167,48 @@ public enum SkyLightEventPost {// state without asking WindowServer to reorder its windows. Recipe// ported from yabai's `window_manager_focus_window_without_raise`.+ /// `OSStatus SLPSSetFrontProcessWithOptions(ProcessSerialNumber *psn, uint32_t windowID, uint32_t options)`.+ ///+ /// Makes `psn` the WindowServer-level frontmost process. The options flag controls behaviour:+ /// - `0x100` (kCPSUserGenerated) → raises windows + triggers Space follow+ /// - `0x400` (kCPSNoWindows) → no window raise, no Space follow; Chrome's+ /// user-activation gate rejects events after this, but native AppKit apps+ /// (Finder, TextEdit, etc.) are unaffected.+ ///+ /// `FocusWithoutRaise` deliberately skips this call for the click/mouse path+ /// because Chrome needs the PSN-only recipe. For the keyboard-menu-shortcut+ /// path (hotkey/press_key with window_id) we call it with `kCPSNoWindows`+ /// (0x400) so that HID-tap events route to the now-frontmost target instead+ /// of the sentinel foreground app.+ private typealias SetFrontProcessWithOptionsFn = @convention(c) (+ UnsafeRawPointer, UInt32, UInt32+ ) -> Int32++ private static let setFrontProcessWithOptionsFn: SetFrontProcessWithOptionsFn? = {+ _ = dlopen(+ "/System/Library/PrivateFrameworks/SkyLight.framework/SkyLight",+ RTLD_LAZY)+ guard+ let p = dlsym(+ UnsafeMutableRawPointer(bitPattern: -2),+ "SLPSSetFrontProcessWithOptions")+ else { return nil }+ return unsafeBitCast(p, to: SetFrontProcessWithOptionsFn.self)+ }()++ /// Make `psn` the WindowServer-level frontmost process without raising+ /// windows or triggering Space follow (`kCPSNoWindows = 0x400`).+ /// `windowID` is the CGWindowID of the target window (yabai passes the+ /// real window ID; passing 0 leaves it unset). Returns `false` when the+ /// SPI didn't resolve.+ @discardableResult+ public static func setFrontProcessNoWindows(+ psn: UnsafeRawPointer, windowID: UInt32 = 0+ ) -> Bool {+ guard let fn = setFrontProcessWithOptionsFn else { return false }+ return fn(psn, windowID, 0x400) == 0+ }+/// `OSStatus SLPSPostEventRecordTo(ProcessSerialNumber *psn, uint8_t *bytes)`./// Posts a 248-byte synthetic event record into the target process's/// Carbon event queue. We build the buffer with@@ -183,9 +225,22 @@ public enum SkyLightEventPost {UnsafeMutableRawPointer) -> Int32- /// `OSStatus GetProcessForPID(pid_t, ProcessSerialNumber *)`.- /// Deprecated but still resolves via dlsym. Writes the target pid's- /// PSN into the 8 bytes at `psn`.+ /// `CGError SLSGetWindowOwner(CGSConnectionID cid, CGWindowID wid, CGSConnectionID *ownerCid)`.+ /// Returns the SkyLight connection ID of the process that owns `wid`.+ /// Modern replacement for the deprecated `GetProcessForPID` on macOS 15+.+ private typealias GetWindowOwnerFn = @convention(c) (+ UInt32, UInt32, UnsafeMutablePointer<UInt32>+ ) -> Int32++ /// `OSStatus SLSGetConnectionPSN(CGSConnectionID cid, ProcessSerialNumber *psn)`.+ /// Converts a SkyLight connection ID to a PSN (two UInt32s).+ private typealias GetConnectionPSNFn = @convention(c) (+ UInt32, UnsafeMutableRawPointer+ ) -> Int32++ /// Deprecated `OSStatus GetProcessForPID(pid_t, ProcessSerialNumber *)`.+ /// Only used as a fallback on older macOS; nil on macOS 15+ where the+ /// symbol no longer exports. Prefer `getProcessPSN(forWindowId:)` instead.private typealias GetProcessForPIDFn = @convention(c) (pid_t, UnsafeMutableRawPointer) -> Int32@@ -214,6 +269,30 @@ public enum SkyLightEventPost {return unsafeBitCast(p, to: GetFrontProcessFn.self)}()+ private static let getWindowOwnerFn: GetWindowOwnerFn? = {+ _ = dlopen(+ "/System/Library/PrivateFrameworks/SkyLight.framework/SkyLight",+ RTLD_LAZY)+ guard+ let p = dlsym(+ UnsafeMutableRawPointer(bitPattern: -2),+ "SLSGetWindowOwner")+ else { return nil }+ return unsafeBitCast(p, to: GetWindowOwnerFn.self)+ }()++ private static let getConnectionPSNFn: GetConnectionPSNFn? = {+ _ = dlopen(+ "/System/Library/PrivateFrameworks/SkyLight.framework/SkyLight",+ RTLD_LAZY)+ guard+ let p = dlsym(+ UnsafeMutableRawPointer(bitPattern: -2),+ "SLSGetConnectionPSN")+ else { return nil }+ return unsafeBitCast(p, to: GetConnectionPSNFn.self)+ }()+private static let getProcessForPIDFn: GetProcessForPIDFn? = {guardlet p = dlsym(@@ -352,13 +431,37 @@ public enum SkyLightEventPost {return fn(psn, bytes) == 0}- /// `true` when all three focus-without-raise SPIs- /// (`_SLPSGetFrontProcess`, `GetProcessForPID`, `SLPSPostEventRecordTo`)- /// resolved — i.e. `FocusWithoutRaise.activateWithoutRaise` has its- /// prerequisites.+ /// `true` when the focus-without-raise SPIs needed to run the PSN+ /// defocus/focus recipe are available. The PSN-for-pid lookup uses+ /// `SLSGetWindowOwner + SLSGetConnectionPSN` on macOS 15+ (where the+ /// old `GetProcessForPID` no longer exports), falling back to+ /// `GetProcessForPID` on older releases.public static var isFocusWithoutRaiseAvailable: Bool {- getFrontProcessFn != nil && getProcessForPIDFn != nil- && postEventRecordToFn != nil+ let hasPsnLookup = (getWindowOwnerFn != nil && getConnectionPSNFn != nil)+ || getProcessForPIDFn != nil+ return getFrontProcessFn != nil && hasPsnLookup && postEventRecordToFn != nil+ }++ /// Look up the PSN of the process that owns `windowId`, writing 8 bytes+ /// into `psnBuffer`. Uses `SLSGetWindowOwner + SLSGetConnectionPSN` on+ /// macOS 15+ where `GetProcessForPID` no longer exports.+ public static func getProcessPSN(+ forWindowId windowId: CGWindowID, into psnBuffer: UnsafeMutableRawPointer+ ) -> Bool {+ // Modern path: window ID → owner connection ID → PSN.+ if let owner = getWindowOwnerFn, let psnFn = getConnectionPSNFn,+ let connFn = connectionIDFn+ {+ let mainCid = connFn()+ var ownerCid: UInt32 = 0+ guard owner(mainCid, UInt32(windowId), &ownerCid) == 0 else { return false }+ return psnFn(ownerCid, psnBuffer) == 0+ }+ // Fallback: deprecated GetProcessForPID (macOS < 15).+ // Caller must supply a pid in this path — psnBuffer is reused as+ // a typed pointer, but this branch is only reached when the modern+ // path isn't available.+ return false}// MARK: - Event-record extractiondiff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swiftindex 18e216aad8..af15cd88de 100644--- a/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift+++ b/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift@@ -1,3 +1,4 @@+import CoreGraphicsimport CuaDriverCoreimport Foundationimport MCP@@ -13,6 +14,17 @@ public enum HotkeyTool {the target pid's event queue via `CGEvent.postToPid`;the target does NOT need to be frontmost.+ **`window_id`** (optional): when supplied, the driver+ calls `FocusWithoutRaise.activateWithoutRaise` before+ posting — making the target AppKit-active without+ raising its window. This is required for shortcuts that+ are dispatched via NSMenu key equivalents (Cmd+S,+ Cmd+N, Cmd+W, Cmd+Shift+N, …) because AppKit only+ routes menu key equivalents to the active app. Omit+ `window_id` for shortcuts handled by the renderer+ (e.g. Cmd+C in a Chromium text field). Trade-off: the+ sentinel foreground app will lose focus once.+Recognized modifiers: cmd/command, shift, option/alt,ctrl/control, fn. Non-modifier keys use the samevocabulary as `press_key` (return, tab, escape,@@ -35,6 +47,11 @@ public enum HotkeyTool {"description":"Modifier(s) and one non-modifier key, e.g. [\"cmd\", \"c\"].",],+ "window_id": [+ "type": "integer",+ "description":+ "CGWindowID of the target window. When provided, the driver calls FocusWithoutRaise before posting so NSMenu key equivalents (Cmd+S, Cmd+N, …) reach the backgrounded app.",+ ],],"additionalProperties": false,],@@ -60,8 +77,45 @@ public enum HotkeyTool {return errorResult("pid \(rawPid) is outside the supported Int32 range.")}+ let rawWindowId = arguments?["window_id"]?.intValuedo {- try KeyboardInput.hotkey(keys, toPid: pid)+ // Two delivery paths, selected by whether window_id is set:+ //+ // window_id present → NSMenu/native-AppKit path:+ // 1. FocusWithoutRaise makes the target AppKit-active+ // without raising its window.+ // 2. Post via SLEventPostToPid WITHOUT the auth-message+ // envelope (attachAuthMessage: false). Without the+ // envelope the event routes SLEventPostToPid →+ // SLEventPostToPSN → IOHIDPostEvent → target event queue+ // where NSApplication.sendEvent: dispatches NSMenu key+ // equivalents. With the envelope SLEventPostToPid forks+ // onto a direct-mach path that bypasses IOHIDPostEvent+ // and therefore NSMenu — which is why Cmd+Shift+N was+ // silently swallowed.+ //+ // window_id absent → Chromium/renderer path (default):+ // Post via SLEventPostToPid WITH the auth-message envelope.+ // Chromium's keyboard pipeline requires it to accept+ // synthetic keystrokes; NSMenu is irrelevant here since+ // Chromium handles shortcuts inside its renderer.+ if let rawWid = rawWindowId, rawWid != 0,+ let wid = UInt32(exactly: rawWid)+ {+ FocusWithoutRaise.activateForMenuShortcut(+ targetPid: pid, targetWid: CGWindowID(wid))+ usleep(50_000)+ // Post WITHOUT the SkyLight auth-message envelope.+ // With the envelope, SLEventPostToPid forks onto a direct-mach+ // path that bypasses IOHIDPostEvent — NSMenu never sees those+ // events. Without the envelope the path goes through IOHIDPostEvent+ // so NSApplication.sendEvent: dispatches NSMenu key equivalents.+ // SLPSSetFrontProcessWithOptions (called inside activateForMenuShortcut)+ // already made the target WindowServer-frontmost.+ try KeyboardInput.hotkey(keys, toPid: pid, attachAuthMessage: false)+ } else {+ try KeyboardInput.hotkey(keys, toPid: pid)+ }return CallTool.Result(content: [.text(diff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/LaunchAppTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/LaunchAppTool.swiftindex 676f9f1d10..e210880054 100644--- a/libs/cua-driver/Sources/CuaDriverServer/Tools/LaunchAppTool.swift+++ b/libs/cua-driver/Sources/CuaDriverServer/Tools/LaunchAppTool.swift@@ -20,12 +20,11 @@ public enum LaunchAppTool {against /Applications and /System/Applications). If both aregiven, bundle_id wins.- Launches hidden — the app runs with its window initialized- for automation (so the AX tree is populated and- `click({pid, element_index})` works end-to-end), but no- window is drawn on screen. To bring the window on-screen,- use `NSRunningApplication.unhide()` from your own code, or- have the user open the app (Dock click, Cmd-Tab, Spotlight).+ Launches in the background — the app's window appears on+ screen but does not steal focus from whatever is currently+ frontmost. The AX tree is fully populated and automation+ can start immediately via `click`, `hotkey`,+ `get_window_state`, etc.Some apps (Calculator and many Electron apps) call`NSApp.activate(ignoringOtherApps:)` in their own@@ -36,16 +35,14 @@ public enum LaunchAppTool {around the launch and re-activates the previously-frontmostapp if the target self-activates. If suppression fails thereturned summary includes a "self-activation not suppressed"- warning. With `hides = true`, the target is also hidden- back immediately by LaunchServices, so even a missed- layer-3 demotion doesn't leave a visible window.+ warning.Optional `urls` are handed to the app through its`application(_:open:)` AppKit delegate. For Finder, passing- a folder URL opens a backgrounded Finder window rooted at- that folder — no activation, no visible window. Works- with any app that implements `application(_:open:)`; apps- that ignore the delegate simply launch without side effects.+ a folder URL opens a Finder window rooted at that folder in+ the background. Works with any app that implements+ `application(_:open:)`; apps that ignore the delegate simply+ launch without side effects.Optional `electron_debugging_port` launches an Electron appwith `--remote-debugging-port=<N>`, activating its Chromediff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swiftindex 61aa7be2cb..b71aeb1aee 100644--- a/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift+++ b/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift@@ -1,3 +1,4 @@+import CoreGraphicsimport CuaDriverCoreimport Foundationimport MCP@@ -75,7 +76,7 @@ public enum PressKeyTool {"window_id": ["type": "integer","description":- "CGWindowID for the window whose get_window_state produced the element_index. Required when element_index is used.",+ "CGWindowID for the window. Required when element_index is used. When supplied without element_index, triggers FocusWithoutRaise before the key fires — use this for NSMenu key equivalents (Cmd+S, Cmd+N, …) on backgrounded apps.",],],"additionalProperties": false,@@ -151,8 +152,24 @@ public enum PressKeyTool {])} else {- try KeyboardInput.press(- key, modifiers: modifiers, toPid: pid)+ // Same two-path recipe as HotkeyTool — see its inline+ // comment for the full rationale. Short version:+ // window_id → FocusWithoutRaise + postToPid without+ // auth-message (IOHIDPostEvent path, NSMenu fires);+ // no window_id → postToPid with auth-message (Chromium).+ if let rawWid = rawWindowId, rawWid != 0,+ let wid = UInt32(exactly: rawWid)+ {+ FocusWithoutRaise.activateForMenuShortcut(+ targetPid: pid, targetWid: CGWindowID(wid))+ usleep(50_000)+ // Same recipe as HotkeyTool — see its inline comment.+ try KeyboardInput.press(+ key, modifiers: modifiers, toPid: pid, attachAuthMessage: false)+ } else {+ try KeyboardInput.press(+ key, modifiers: modifiers, toPid: pid)+ }return CallTool.Result(content: [.text(diff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/ScreenshotTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/ScreenshotTool.swiftindex a69402e92d..bd61d11911 100644--- a/libs/cua-driver/Sources/CuaDriverServer/Tools/ScreenshotTool.swift+++ b/libs/cua-driver/Sources/CuaDriverServer/Tools/ScreenshotTool.swift@@ -13,7 +13,8 @@ public enum ScreenshotTool {Capture a screenshot using ScreenCaptureKit. Returns base64-encodedimage data for a single window in the requested format (default png).- `window_id` is required. Get window ids from `list_windows`.++ `window_id` is required. Get window ids from `list_windows`.Requires the Screen Recording TCC grant — call `check_permissions`first if unsure.diff --git a/libs/cua-driver/Tests/integration/test_background_menu_shortcut.py b/libs/cua-driver/Tests/integration/test_background_menu_shortcut.pynew file mode 100644index 0000000000..93fa795ffa--- /dev/null+++ b/libs/cua-driver/Tests/integration/test_background_menu_shortcut.py@@ -0,0 +1,359 @@+"""Integration test: hotkey with menu key equivalents on a backgrounded app.++Root cause being tested+-----------------------+`hotkey` routes keys via `SLEventPostToPid` which, when given an+`SLSEventAuthenticationMessage` envelope (the default keyboard path),+forks onto a direct-mach delivery path that bypasses `IOHIDPostEvent`.+NSMenu key equivalents are dispatched in `NSApplication.sendEvent:`+which processes the `IOHIDPostEvent` stream — so auth-enveloped events+are silently swallowed by native AppKit apps.++Additionally, NSMenu only dispatches key equivalents to the AppKit-active+process. When an app is backgrounded, `CGEvent.postToPid` reaches its+event queue but NSMenu's filter rejects the shortcut.++Fix: when `window_id` is supplied to `hotkey` / `press_key`:+ 1. Call `FocusWithoutRaise.activateForMenuShortcut` — makes target+ WindowServer-frontmost via `SLPSSetFrontProcessWithOptions(kCPSNoWindows)`+ without raising its window or triggering Space follow.+ 2. Post via `SLEventPostToPid` WITHOUT the auth-message envelope+ (`attachAuthMessage: false`) — routes through IOHIDPostEvent so+ NSMenu key equivalents fire normally.++The Chromium/renderer path (no `window_id`) is unchanged: auth-message+envelope stays on, since Chromium requires it for its keyboard pipeline.++Test subject: TextEdit+The test uses TextEdit as the backgrounded target app. Two key equivalents:+ - Cmd+Z (Undo): harmless idempotent action used for the negative case.+ - Cmd+N (New Document): opens a new window, easy to count.++Behavioral contract verified by this test+-----------------------------------------+WITHOUT `window_id` (auth-envelope path, no activation):+ • FocusMonitorApp does NOT lose focus — no activation happened.+ • The keystroke goes directly to the target PID via SkyLight direct-mach.++WITH `window_id` (no-auth-envelope path, full activation):+ • FocusMonitorApp loses focus EXACTLY ONCE — activateForMenuShortcut+ called SLPSSetFrontProcessWithOptions(kCPSNoWindows).+ • The NSMenu key equivalent fires: a new TextEdit document opens.++Test plan+---------+1. Kill any existing TextEdit; launch it fresh (one empty document opens).+2. Launch FocusMonitorApp last so it is the foreground sentinel.++Negative case (no side-effects without window_id):+3. `hotkey(pid, ["cmd","z"])` WITHOUT window_id → FocusMonitorApp loses focus+ 0 times (no activation triggered; auth path delivers directly to pid).++Positive case (activation + NSMenu fires with window_id):+4. `hotkey(pid, ["cmd","n"], window_id=wid)` WITH window_id → new TextEdit+ document opens (window count +1) AND FocusMonitorApp loses focus exactly+ once (the activate trade-off — same as the click path).+5. Cleanup: close the extra document.++Run:+ scripts/test.sh test_background_menu_shortcut+"""++from __future__ import annotations++import os+import re+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,+)++_THIS_DIR = os.path.dirname(os.path.abspath(__file__))+_REPO_ROOT = os.path.dirname(os.path.dirname(_THIS_DIR))+_FOCUS_APP_DIR = os.path.join(_REPO_ROOT, "Tests", "FocusMonitorApp")+_FOCUS_APP_BUNDLE = os.path.join(_FOCUS_APP_DIR, "FocusMonitorApp.app")+_FOCUS_APP_EXE = os.path.join(+ _FOCUS_APP_BUNDLE, "Contents", "MacOS", "FocusMonitorApp"+)+_LOSS_FILE = "/tmp/focus_monitor_losses.txt"++TEXTEDIT_BUNDLE = "com.apple.TextEdit"+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------++def _tool_text(result: dict) -> str:+ for item in result.get("content", []):+ if item.get("type") == "text":+ return item.get("text", "")+ return ""+++def _build_focus_app() -> None:+ if not os.path.exists(_FOCUS_APP_EXE):+ subprocess.run(+ [os.path.join(_FOCUS_APP_DIR, "build.sh")], check=True+ )+++def _launch_focus_app() -> tuple[subprocess.Popen, int]:+ proc = subprocess.Popen(+ [_FOCUS_APP_EXE],+ stdout=subprocess.PIPE,+ stderr=subprocess.DEVNULL,+ text=True,+ )+ for _ in range(40):+ line = proc.stdout.readline().strip()+ if line.startswith("FOCUS_PID="):+ pid = int(line.split("=", 1)[1])+ return proc, pid+ time.sleep(0.1)+ proc.terminate()+ raise RuntimeError("FocusMonitorApp did not print FOCUS_PID in time")+++def _read_focus_losses() -> int:+ try:+ with open(_LOSS_FILE) as f:+ return int(f.read().strip())+ except (FileNotFoundError, ValueError):+ return 0+++def _activate_focus_monitor(fm_pid: int) -> None:+ subprocess.run(+ ["osascript", "-e",+ f'tell application "System Events" to set frontmost of '+ f'(first process whose unix id is {fm_pid}) to true'],+ check=False,+ )+ time.sleep(0.5)+++def _textedit_window_count(client: DriverClient, textedit_pid: int) -> int:+ """Count on-screen TextEdit document windows."""+ result = client.call_tool("list_windows", {"pid": textedit_pid})+ windows = result.get("structuredContent", {}).get("windows", [])+ return sum(+ 1 for w in windows+ if w.get("is_on_screen")+ and (w.get("bounds", {}).get("width", 0) or 0) > 100+ and (w.get("bounds", {}).get("height", 0) or 0) > 100+ )+++def _close_extra_textedit_windows(+ client: DriverClient, textedit_pid: int, target_count: int+) -> None:+ """Close extra TextEdit windows (no-save) until count == target_count."""+ result = client.call_tool("list_windows", {"pid": textedit_pid})+ windows = result.get("structuredContent", {}).get("windows", [])+ on_screen = [+ w for w in windows+ if w.get("is_on_screen")+ and (w.get("bounds", {}).get("width", 0) or 0) > 100+ and (w.get("bounds", {}).get("height", 0) or 0) > 100+ ]+ to_close = on_screen[target_count:]+ for w in to_close:+ wid = w["window_id"]+ # Cmd+W to close; handle any "Don't Save" sheet.+ client.call_tool("hotkey", {+ "pid": textedit_pid,+ "keys": ["cmd", "w"],+ "window_id": wid,+ })+ time.sleep(0.4)+ # Delete = keyboard shortcut for "Don't Save" in macOS sheets.+ client.call_tool("press_key", {+ "pid": textedit_pid,+ "key": "delete",+ "window_id": wid,+ })+ time.sleep(0.3)+++# ---------------------------------------------------------------------------+# Test class+# ---------------------------------------------------------------------------++class TestBackgroundMenuShortcut(unittest.TestCase):+ """hotkey with window_id fires NSMenu key equivalents on backgrounded apps."""++ binary: str+ client: DriverClient+ fm_proc: subprocess.Popen+ fm_pid: int+ textedit_pid: int+ textedit_wid: int+ initial_window_count: int++ @classmethod+ def setUpClass(cls) -> None:+ subprocess.run(["pkill", "-x", "FocusMonitorApp"], check=False)+ time.sleep(0.3)+ try:+ os.remove(_LOSS_FILE)+ except FileNotFoundError:+ pass++ # Kill any existing TextEdit to start from a clean state.+ subprocess.run(["pkill", "-x", "TextEdit"], check=False)+ time.sleep(0.5)++ cls.binary = default_binary_path()+ cls.client = DriverClient(cls.binary).__enter__()++ # Launch TextEdit — it starts with one empty document.+ result = cls.client.call_tool("launch_app", {"bundle_id": TEXTEDIT_BUNDLE})+ text = _tool_text(result)+ m = re.search(r'pid[=:\s]+(\d+)', text, re.IGNORECASE)+ if not m:+ raise RuntimeError(f"launch_app TextEdit did not return pid: {text[:200]}")+ cls.textedit_pid = int(m.group(1))+ time.sleep(1.0)++ # Get the TextEdit document window.+ result = cls.client.call_tool("list_windows", {"pid": cls.textedit_pid})+ windows = result.get("structuredContent", {}).get("windows", [])+ on_screen = [+ w for w in windows+ if w.get("is_on_screen")+ and (w.get("bounds", {}).get("width", 0) or 0) > 100+ and (w.get("bounds", {}).get("height", 0) or 0) > 100+ ]+ if not on_screen:+ raise RuntimeError(+ f"No on-screen TextEdit window found. Windows: {windows[:5]}"+ )+ best = max(on_screen, key=lambda w: (+ (w.get("bounds") or {}).get("width", 0) *+ (w.get("bounds") or {}).get("height", 0)+ ))+ cls.textedit_wid = best["window_id"]+ cls.initial_window_count = len(on_screen)++ # Build + launch FocusMonitorApp LAST so it owns the foreground.+ _build_focus_app()+ cls.fm_proc, cls.fm_pid = _launch_focus_app()+ time.sleep(0.8)++ @classmethod+ def tearDownClass(cls) -> None:+ cls.client.__exit__(None, None, None)+ cls.fm_proc.terminate()+ try:+ cls.fm_proc.wait(timeout=3)+ except subprocess.TimeoutExpired:+ cls.fm_proc.kill()+ subprocess.run(["pkill", "-x", "FocusMonitorApp"], check=False)+ subprocess.run(["pkill", "-x", "TextEdit"], check=False)++ def setUp(self) -> None:+ _activate_focus_monitor(self.fm_pid)+ try:+ os.remove(_LOSS_FILE)+ except FileNotFoundError:+ pass++ # -----------------------------------------------------------------------+ # Negative case: WITHOUT window_id → no activation (0 focus losses)+ # -----------------------------------------------------------------------++ def test_01_hotkey_without_window_id_does_not_activate(self) -> None:+ """hotkey without window_id must NOT activate the target app.++ Sends Cmd+Z (Undo) to TextEdit via the auth-envelope path (no window_id).+ This delivers the keystroke directly to the target PID without calling+ activateForMenuShortcut, so FocusMonitorApp should retain focus (0 losses).++ The auth-envelope path is the correct route for Chromium targets; for+ native AppKit apps that need NSMenu dispatch, window_id is required.+ """+ _activate_focus_monitor(self.fm_pid)+ losses_before = _read_focus_losses()++ # Cmd+Z (Undo) — harmless idempotent action; won't open new windows.+ self.client.call_tool("hotkey", {+ "pid": self.textedit_pid,+ "keys": ["cmd", "z"],+ })+ time.sleep(1.0)++ losses_after = _read_focus_losses()+ losses = losses_after - losses_before++ self.assertEqual(+ losses, 0,+ f"hotkey WITHOUT window_id should not steal focus from FocusMonitorApp "+ f"(no activation should occur). Got {losses} focus loss(es). "+ f"This means activateForMenuShortcut is being called when it shouldn't be."+ )+ print(f"\n ✓ Cmd+Z without window_id: 0 focus losses (no activation, as expected)")++ # -----------------------------------------------------------------------+ # Positive case: WITH window_id → activation + NSMenu fires+ # -----------------------------------------------------------------------++ def test_02_hotkey_with_window_id_activates_and_opens_document(self) -> None:+ """hotkey with window_id activates the app and fires NSMenu key equivalents.++ Sends Cmd+N (New Document) to a backgrounded TextEdit window.+ Fix: activateForMenuShortcut calls SLPSSetFrontProcessWithOptions+ (kCPSNoWindows) to make TextEdit WindowServer-frontmost; then posts+ without the SkyLight auth-message envelope so the event routes through+ IOHIDPostEvent and NSApplication.sendEvent: dispatches NSMenu key+ equivalents (Cmd+N → New Document).+ """+ count_before = _textedit_window_count(self.client, self.textedit_pid)+ _activate_focus_monitor(self.fm_pid)+ losses_before = _read_focus_losses()++ self.client.call_tool("hotkey", {+ "pid": self.textedit_pid,+ "keys": ["cmd", "n"],+ "window_id": self.textedit_wid,+ })+ time.sleep(1.5)++ count_after = _textedit_window_count(self.client, self.textedit_pid)++ # Clean up extra windows before asserting.+ if count_after > count_before:+ _close_extra_textedit_windows(+ self.client, self.textedit_pid, count_before+ )+ time.sleep(0.5)++ # FocusMonitorApp should lose focus exactly once (the activate trade-off).+ losses_after = _read_focus_losses()+ losses = losses_after - losses_before++ self.assertGreater(+ count_after, count_before,+ f"hotkey WITH window_id should open a new TextEdit document. "+ f"textedit_pid={self.textedit_pid} textedit_wid={self.textedit_wid}. "+ f"Windows before={count_before}, after={count_after}."+ )+ self.assertEqual(+ losses, 1,+ f"Expected exactly 1 focus loss (the activateForMenuShortcut activate), "+ f"got {losses}."+ )++ print(f"\n ✓ Cmd+N with window_id opened a new TextEdit document "+ f"(count {count_before} → {count_after})")+ print(f" ✓ Focus losses: {losses} (expected 1)")+++if __name__ == "__main__":+ unittest.main()diff --git a/libs/cua-driver/Tests/integration/test_launch_app_visible.py b/libs/cua-driver/Tests/integration/test_launch_app_visible.pynew file mode 100644index 0000000000..da94b89b9f--- /dev/null+++ b/libs/cua-driver/Tests/integration/test_launch_app_visible.py@@ -0,0 +1,336 @@+"""Integration test: launch_app opens a visible window without stealing focus.++Root cause being tested+-----------------------+Previously, `launch_app` set `config.hides = true` during launch to complete+the launch lifecycle, which left the app's window invisible. After removing+that flag, cold-launched apps now have their windows visible on screen.++Additionally, `NSRunningApplication.unhide()` is called after launch so any+app that did hide itself during its own launch lifecycle becomes visible+without requiring a separate `unhide` step from the caller.++Behavioral contract verified by this test+-----------------------------------------+After `launch_app(bundle_id=...)` WITHOUT any `urls` parameter:+ • The app has at least one window with `is_on_screen: true`.+ • FocusMonitorApp retains focus — 0 focus losses (no activation occurred).++Test subjects+-------------+TextEdit and Calculator: simple system apps that:+ - Do NOT auto-relaunch when killed (unlike Finder)+ - Always open with at least one window on cold launch+ - Are installed at known paths on all macOS systems++Run:+ scripts/test.sh test_launch_app_visible+"""++from __future__ import annotations++import os+import re+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,+)++_THIS_DIR = os.path.dirname(os.path.abspath(__file__))+_REPO_ROOT = os.path.dirname(os.path.dirname(_THIS_DIR))+_FOCUS_APP_DIR = os.path.join(_REPO_ROOT, "Tests", "FocusMonitorApp")+_FOCUS_APP_BUNDLE = os.path.join(_FOCUS_APP_DIR, "FocusMonitorApp.app")+_FOCUS_APP_EXE = os.path.join(+ _FOCUS_APP_BUNDLE, "Contents", "MacOS", "FocusMonitorApp"+)+_LOSS_FILE = "/tmp/focus_monitor_losses.txt"++TEXTEDIT_BUNDLE = "com.apple.TextEdit"+CALCULATOR_BUNDLE = "com.apple.calculator"+FINDER_BUNDLE = "com.apple.finder"+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------++def _tool_text(result: dict) -> str:+ for item in result.get("content", []):+ if item.get("type") == "text":+ return item.get("text", "")+ return ""+++def _build_focus_app() -> None:+ if not os.path.exists(_FOCUS_APP_EXE):+ subprocess.run(+ [os.path.join(_FOCUS_APP_DIR, "build.sh")], check=True+ )+++def _launch_focus_app() -> tuple[subprocess.Popen, int]:+ proc = subprocess.Popen(+ [_FOCUS_APP_EXE],+ stdout=subprocess.PIPE,+ stderr=subprocess.DEVNULL,+ text=True,+ )+ for _ in range(40):+ line = proc.stdout.readline().strip()+ if line.startswith("FOCUS_PID="):+ pid = int(line.split("=", 1)[1])+ return proc, pid+ time.sleep(0.1)+ proc.terminate()+ raise RuntimeError("FocusMonitorApp did not print FOCUS_PID in time")+++def _read_focus_losses() -> int:+ try:+ with open(_LOSS_FILE) as f:+ return int(f.read().strip())+ except (FileNotFoundError, ValueError):+ return 0+++def _activate_focus_monitor(fm_pid: int) -> None:+ subprocess.run(+ ["osascript", "-e",+ f'tell application "System Events" to set frontmost of '+ f'(first process whose unix id is {fm_pid}) to true'],+ check=False,+ )+ time.sleep(0.5)+++def _on_screen_windows(client: DriverClient, pid: int) -> list[dict]:+ """Return windows that are on screen with a reasonable size."""+ result = client.call_tool("list_windows", {"pid": pid})+ windows = result.get("structuredContent", {}).get("windows", [])+ return [+ w for w in windows+ if w.get("is_on_screen")+ and (w.get("bounds", {}).get("width", 0) or 0) > 50+ and (w.get("bounds", {}).get("height", 0) or 0) > 50+ ]+++def _launch_app_pid(client: DriverClient, bundle_id: str) -> int:+ """Call launch_app and extract the pid from the result text."""+ result = client.call_tool("launch_app", {"bundle_id": bundle_id})+ text = _tool_text(result)+ m = re.search(r'pid[=:\s]+(\d+)', text, re.IGNORECASE)+ if not m:+ raise RuntimeError(+ f"launch_app({bundle_id!r}) did not return pid. Response: {text[:300]}"+ )+ return int(m.group(1))+++# ---------------------------------------------------------------------------+# Test class+# ---------------------------------------------------------------------------++class TestLaunchAppVisible(unittest.TestCase):+ """launch_app opens an on-screen window without stealing focus."""++ binary: str+ client: DriverClient+ fm_proc: subprocess.Popen+ fm_pid: int++ @classmethod+ def setUpClass(cls) -> None:+ subprocess.run(["pkill", "-x", "FocusMonitorApp"], check=False)+ time.sleep(0.3)+ try:+ os.remove(_LOSS_FILE)+ except FileNotFoundError:+ pass++ # Kill test apps so each test starts from a clean state.+ subprocess.run(["pkill", "-x", "TextEdit"], check=False)+ subprocess.run(["pkill", "-x", "Calculator"], check=False)+ subprocess.run(["pkill", "-x", "Finder"], check=False)+ time.sleep(1.5) # Finder takes a moment to be fully killed + relaunched by macOS++ cls.binary = default_binary_path()+ cls.client = DriverClient(cls.binary).__enter__()++ # Build + launch FocusMonitorApp BEFORE launch_app so it owns the+ # foreground while we measure focus losses.+ _build_focus_app()+ cls.fm_proc, cls.fm_pid = _launch_focus_app()+ time.sleep(0.8)++ @classmethod+ def tearDownClass(cls) -> None:+ cls.client.__exit__(None, None, None)+ cls.fm_proc.terminate()+ try:+ cls.fm_proc.wait(timeout=3)+ except subprocess.TimeoutExpired:+ cls.fm_proc.kill()+ subprocess.run(["pkill", "-x", "FocusMonitorApp"], check=False)+ subprocess.run(["pkill", "-x", "TextEdit"], check=False)+ subprocess.run(["pkill", "-x", "Calculator"], check=False)+ # Leave Finder running — macOS auto-relaunches it anyway.++ def setUp(self) -> None:+ _activate_focus_monitor(self.fm_pid)+ try:+ os.remove(_LOSS_FILE)+ except FileNotFoundError:+ pass++ # -----------------------------------------------------------------------+ # Test 01: TextEdit cold launch → visible window, no focus steal+ # -----------------------------------------------------------------------++ def test_01_textedit_cold_launch_opens_visible_window(self) -> None:+ """launch_app(TextEdit) must open a visible on-screen window.++ Verifies:+ • The returned result includes a non-zero PID.+ • list_windows for that PID shows at least one window with+ is_on_screen == true and a reasonable size.+ • FocusMonitorApp did NOT lose focus (activates=false contract).+ """+ _activate_focus_monitor(self.fm_pid)+ losses_before = _read_focus_losses()++ pid = _launch_app_pid(self.client, TEXTEDIT_BUNDLE)+ self.assertGreater(pid, 0, "TextEdit PID must be positive")++ # Allow time for TextEdit to open its window.+ time.sleep(2.0)++ on_screen = _on_screen_windows(self.client, pid)+ losses = _read_focus_losses() - losses_before++ self.assertGreater(+ len(on_screen), 0,+ f"launch_app(TextEdit) must produce at least one on-screen window. "+ f"pid={pid}. All windows: "+ f"{self.client.call_tool('list_windows', {'pid': pid}).get('structuredContent', {}).get('windows', [])}"+ )+ self.assertEqual(+ losses, 0,+ f"launch_app must NOT steal focus. Got {losses} focus loss(es). "+ f"The activates=false contract was violated."+ )+ print(+ f"\n ✓ TextEdit pid={pid} has {len(on_screen)} on-screen window(s)"+ )+ print(f" ✓ Focus losses: {losses} (expected 0)")++ # -----------------------------------------------------------------------+ # Test 02: Calculator cold launch → visible window, no focus steal+ # -----------------------------------------------------------------------++ def test_02_calculator_cold_launch_opens_visible_window(self) -> None:+ """launch_app(Calculator) must open a visible on-screen window.++ Calculator is notable because it calls NSApp.activate in its own+ applicationDidFinishLaunching, testing that launch_app's focus-steal+ suppressor correctly returns focus to FocusMonitorApp even when the+ target app self-activates.+ """+ # Ensure Calculator is dead before this test.+ subprocess.run(["pkill", "-x", "Calculator"], check=False)+ time.sleep(0.5)++ _activate_focus_monitor(self.fm_pid)+ losses_before = _read_focus_losses()++ pid = _launch_app_pid(self.client, CALCULATOR_BUNDLE)+ self.assertGreater(pid, 0, "Calculator PID must be positive")++ # Calculator is fast to launch but may self-activate; give the+ # focus-steal suppressor time to restore FocusMonitorApp.+ time.sleep(2.5)++ on_screen = _on_screen_windows(self.client, pid)++ # Check focus was restored — FocusMonitorApp must be frontmost now+ # (even if Calculator self-activated briefly and got suppressed).+ import subprocess as _sp+ result = _sp.run(+ ["osascript", "-e",+ "tell application \"System Events\" to get unix id of first process "+ "whose frontmost is true"],+ capture_output=True, text=True+ )+ frontmost_pid = int(result.stdout.strip()) if result.stdout.strip().isdigit() else -1++ self.assertGreater(+ len(on_screen), 0,+ f"launch_app(Calculator) must produce at least one on-screen window. "+ f"pid={pid}. All windows: "+ f"{self.client.call_tool('list_windows', {'pid': pid}).get('structuredContent', {}).get('windows', [])}"+ )+ self.assertEqual(+ frontmost_pid, self.fm_pid,+ f"After launch_app(Calculator), FocusMonitorApp (pid={self.fm_pid}) "+ f"must be frontmost, but pid={frontmost_pid} is frontmost. "+ f"focus-steal suppressor failed."+ )+ print(+ f"\n ✓ Calculator pid={pid} has {len(on_screen)} on-screen window(s)"+ )+ print(+ f" ✓ FocusMonitorApp (pid={self.fm_pid}) is still frontmost — "+ f"focus-steal suppressed"+ )++ # -----------------------------------------------------------------------+ # Test 03: Finder — already running, no on-screen windows+ # -----------------------------------------------------------------------++ def test_03_finder_no_url_opens_visible_window(self) -> None:+ """launch_app(Finder) without urls must open a visible Finder window.++ Finder is always running (macOS auto-relaunches it after pkill). When+ called without urls, launch_app must automatically open a home-directory+ window on the current Space using the application(_:open:) URL-handoff+ path — no explicit url parameter required from the caller.++ Verifies:+ • At least one Finder window with is_on_screen == true.+ • FocusMonitorApp did NOT lose focus (0 losses — no activation needed).+ """+ _activate_focus_monitor(self.fm_pid)+ losses_before = _read_focus_losses()++ pid = _launch_app_pid(self.client, FINDER_BUNDLE)+ self.assertGreater(pid, 0, "Finder PID must be positive")++ # Give Finder time to create its window via application(_:open:).+ time.sleep(2.0)++ on_screen = _on_screen_windows(self.client, pid)+ losses = _read_focus_losses() - losses_before++ self.assertGreater(+ len(on_screen), 0,+ f"launch_app(Finder) without urls must produce at least one on-screen "+ f"window (home-directory fallback). pid={pid}. "+ f"All windows: {self.client.call_tool('list_windows', {'pid': pid}).get('structuredContent', {}).get('windows', [])}"+ )+ self.assertEqual(+ losses, 0,+ f"launch_app(Finder) must NOT steal focus. Got {losses} focus loss(es). "+ f"The home-directory fallback must use activates=false."+ )+ print(f"\n ✓ Finder pid={pid} has {len(on_screen)} on-screen window(s)")+ print(f" ✓ Focus losses: {losses} (expected 0 — no activation)")+++if __name__ == "__main__":+ unittest.main()