Skip to content

armgit / cua

Public Imported from GitHub
0

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

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.swift
index 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.swift
index 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.swift
index 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 {
guard
let event = CGEvent(
@@ -116,15 +126,20 @@ public enum KeyboardInput {
}
event.flags = flags
if 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.swift
index 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? = {
guard
let 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 extraction
diff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/HotkeyTool.swift
index 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 CoreGraphics
import CuaDriverCore
import Foundation
import 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 same
vocabulary 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"]?.intValue
do {
- 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.swift
index 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 are
given, 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-frontmost
app if the target self-activates. If suppression fails the
returned 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 app
with `--remote-debugging-port=<N>`, activating its Chrome
diff --git a/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift b/libs/cua-driver/Sources/CuaDriverServer/Tools/PressKeyTool.swift
index 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 CoreGraphics
import CuaDriverCore
import Foundation
import 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.swift
index 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-encoded
image 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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()