Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
"""Reusable, cross-platform window state: enumerate open windows, read the
foreground title, focus a window by title, and detect whether an app is already
running.
This is the single home for the window logic that previously lived only inside
``dodaios/plugins/tool/switch_window.py``. ``switch_window`` now re-exports and
delegates to the focus helpers here, and ``open_app`` / the Computer-Use loop use
``is_app_running`` / ``focus_window`` / ``list_windows`` so CU stops re-launching
apps that are already open and can plan with awareness of what is on screen.
Design contract (matches the platform seam, AD-5/AD-6/AD-13):
* Every public function is best-effort and NEVER raises into a caller — a missing
tool, a denied permission, a headless / Wayland session, or a native-call error
degrades to an empty result, not an exception.
* The Windows ctypes path is moved verbatim from ``switch_window`` (AD-7:
behavior unchanged); macOS uses Quartz/AppKit/Accessibility and Linux/X11
uses wmctrl. Wayland and headless sessions degrade cleanly.
* ``is_app_running`` is conservative: it only reports a match when an app token
(>=3 chars) clearly appears in a window title. When uncertain it returns
``None`` so the caller falls through to a normal launch — a false negative just
reproduces today's behavior; a false positive (focusing instead of launching)
is the worse error, so we bias against it.
Import-cleanliness (HN-7): no platform-only package is imported at module scope;
``ctypes`` and friends are imported lazily inside the function bodies.
"""
from __future__ import annotations
import logging
import os
import re
import shutil
import subprocess
import time
from collections.abc import Callable
from dataclasses import dataclass
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS
from dodaios.core.win32_dpi import per_monitor_dpi_context
from dodaios.platform import detect_platform
from dodaios.platform.macos_ax import decode_ax_point, decode_ax_size
from dodaios.platform.probes import display_present, is_wayland
log = logging.getLogger(__name__)
_MIN_TOKEN_LEN = 3
# Known cases where the app token a user/planner says differs from the window
# title. Most friendly names ARE a substring of the title (chrome → "Google
# Chrome", spotify → "Spotify Premium"), so this stays tiny on purpose.
_TITLE_ALIASES: dict[str, tuple[str, ...]] = {
"calc": ("calculator",),
}
@dataclass(frozen=True)
class WindowInfo:
"""A single visible top-level window.
``handle`` is an opaque platform handle: Win32 ``hwnd``, macOS
``CGWindowID``, or an X11 window id. A degraded title-only probe uses
``None``.
"""
title: str
minimized: bool = False
handle: int | None = None
#: Owning process id, when the platform probe knows it. Native Windows,
#: macOS, and Linux/X11 probes fill it so privacy policy and the CU
#: foreground guard can use app-level identity where handles churn (see
#: ``dodaios.cu.target_guard.window_signature``).
pid: int | None = None
# Cached, process-private DLL instances. Never ``ctypes.windll.user32`` /
# ``ctypes.windll.kernel32``: this module binds pointer-sized argtypes on
# whatever object it gets, and the shared ``windll`` singleton is used by
# every other library in the process (e.g. pywebview's winforms backend,
# which calls SetWindowPos relying on it staying argtypes-free).
_private_user32_dll = None
_private_kernel32_dll = None
def _win32_user32():
"""Return the cached private ``user32`` WinDLL, creating it on first use."""
global _private_user32_dll
import ctypes # noqa: PLC0415
if _private_user32_dll is None:
_private_user32_dll = ctypes.WinDLL("user32", use_last_error=True)
return _private_user32_dll
def _win32_kernel32():
"""Return the cached private ``kernel32`` WinDLL, creating it on first use."""
global _private_kernel32_dll
import ctypes # noqa: PLC0415
if _private_kernel32_dll is None:
_private_kernel32_dll = ctypes.WinDLL("kernel32", use_last_error=True)
return _private_kernel32_dll
def _configure_window_query_api(user32, ctypes, wintypes) -> None:
"""Bind pointer-sized Win32 window-query signatures."""
user32.GetForegroundWindow.argtypes = []
user32.GetForegroundWindow.restype = wintypes.HWND
user32.GetWindowTextLengthW.argtypes = [wintypes.HWND]
user32.GetWindowTextLengthW.restype = ctypes.c_int
user32.GetWindowTextW.argtypes = [wintypes.HWND, wintypes.LPWSTR, ctypes.c_int]
user32.GetWindowTextW.restype = ctypes.c_int
user32.GetWindowThreadProcessId.argtypes = [
wintypes.HWND,
ctypes.POINTER(wintypes.DWORD),
]
user32.GetWindowThreadProcessId.restype = wintypes.DWORD
user32.GetWindowRect.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.RECT)]
user32.GetWindowRect.restype = wintypes.BOOL
user32.GetClientRect.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.RECT)]
user32.GetClientRect.restype = wintypes.BOOL
user32.ClientToScreen.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.POINT)]
user32.ClientToScreen.restype = wintypes.BOOL
user32.IsWindowVisible.argtypes = [wintypes.HWND]
user32.IsWindowVisible.restype = wintypes.BOOL
user32.IsIconic.argtypes = [wintypes.HWND]
user32.IsIconic.restype = wintypes.BOOL
user32.GetSystemMetrics.argtypes = [ctypes.c_int]
user32.GetSystemMetrics.restype = ctypes.c_int
user32.GetClassNameW.argtypes = [wintypes.HWND, wintypes.LPWSTR, ctypes.c_int]
user32.GetClassNameW.restype = ctypes.c_int
user32.GetWindowLongW.argtypes = [wintypes.HWND, ctypes.c_int]
user32.GetWindowLongW.restype = ctypes.c_long
user32.ShowWindow.argtypes = [wintypes.HWND, ctypes.c_int]
user32.ShowWindow.restype = wintypes.BOOL
user32.SetForegroundWindow.argtypes = [wintypes.HWND]
user32.SetForegroundWindow.restype = wintypes.BOOL
user32.SetActiveWindow.argtypes = [wintypes.HWND]
user32.SetActiveWindow.restype = wintypes.HWND
user32.BringWindowToTop.argtypes = [wintypes.HWND]
user32.BringWindowToTop.restype = wintypes.BOOL
user32.AttachThreadInput.argtypes = [
wintypes.DWORD,
wintypes.DWORD,
wintypes.BOOL,
]
user32.AttachThreadInput.restype = wintypes.BOOL
user32.GetWindowPlacement.argtypes = [wintypes.HWND, ctypes.c_void_p]
user32.GetWindowPlacement.restype = wintypes.BOOL
user32.SetWindowPos.argtypes = [
wintypes.HWND,
wintypes.HWND,
ctypes.c_int,
ctypes.c_int,
ctypes.c_int,
ctypes.c_int,
wintypes.UINT,
]
user32.SetWindowPos.restype = wintypes.BOOL
def _rects_intersect(
first: tuple[int, int, int, int], second: tuple[int, int, int, int],
) -> bool:
left, top, width, height = first
other_left, other_top, other_width, other_height = second
return (
width > 0
and height > 0
and other_width > 0
and other_height > 0
and left < other_left + other_width
and other_left < left + width
and top < other_top + other_height
and other_top < top + height
)
def _virtual_desktop_rect_windows(user32) -> tuple[int, int, int, int] | None:
rect = (
int(user32.GetSystemMetrics(76)),
int(user32.GetSystemMetrics(77)),
int(user32.GetSystemMetrics(78)),
int(user32.GetSystemMetrics(79)),
)
if rect[2] <= 0 or rect[3] <= 0:
return None
return rect
# ----------------------------------------------------------------------
# Windows backend (ctypes) — focus path moved verbatim from switch_window (AD-7)
# ----------------------------------------------------------------------
def _find_and_focus_windows(title_contains: str) -> tuple[bool, str]:
"""Looks for a visible window with a title substring and focuses it.
Returns:
(found, message). ``found`` is True when a matching window
was found AND successfully focused. ``message`` contains
either the window title or a failure reason.
"""
if os.name != "nt":
return False, "Window switch is only available on Windows"
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
EnumWindows = user32.EnumWindows
EnumWindowsProc = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
EnumWindows.argtypes = [EnumWindowsProc, wintypes.LPARAM]
EnumWindows.restype = wintypes.BOOL
GetWindowTextW = user32.GetWindowTextW
GetWindowTextLengthW = user32.GetWindowTextLengthW
IsWindowVisible = user32.IsWindowVisible
needle = title_contains.lower()
found_hwnd: list[int] = []
found_title: list[str] = []
def _callback(hwnd: int, _lparam: int) -> bool:
if not IsWindowVisible(hwnd):
return True
length = GetWindowTextLengthW(hwnd)
if length <= 0:
return True
buf = ctypes.create_unicode_buffer(length + 1)
GetWindowTextW(hwnd, buf, length + 1)
title = buf.value or ""
if needle in title.lower():
found_hwnd.append(hwnd)
found_title.append(title)
return False # Stop enumeration
return True
EnumWindows(EnumWindowsProc(_callback), 0)
if not found_hwnd:
return False, f"No visible window found with title substring '{title_contains}'"
hwnd = found_hwnd[0]
title = found_title[0]
# Raise through the HARDENED foreground path (restore-if-minimized +
# AttachThreadInput) — a plain SetForegroundWindow is refused under the
# Windows foreground-lock and left an already-open app behind everything
# (the "WhatsApp opened in the background" report). This unifies every
# foreground site (switch_window, the CU settle fallback, the open_app
# already-running path) on one robust mechanism.
if not _force_foreground_windows(hwnd):
return False, (
f"Window '{title}' found, but setting focus failed "
"(foreground lock — the user must press Alt+Tab manually)"
)
return True, title
def _force_foreground_windows(hwnd: int) -> bool:
"""Forcefully bring a window to the foreground on Windows, defeating the
foreground-lock-steal restriction.
``SetForegroundWindow`` alone is refused for a background process unless
Windows currently grants it foreground privilege (recent user input, or it
launched the target). When it is refused, a freshly launched app is left in
the background — and the Computer-Use foreground-following screenshot then
captures the wrong screen. The robust path attaches our input queue to both
the current-foreground thread and the target window's thread, raises with
``BringWindowToTop`` + ``SetForegroundWindow`` + ``SetActiveWindow``, and
ALWAYS detaches both queues in ``finally`` (a leaked ``AttachThreadInput``
deadlocks input routing).
Returns ``True`` if the foreground was ultimately taken. Best-effort — the
caller treats the result as advisory. Lazy ``ctypes`` import (module
import-cleanliness, HN-7). Separate from ``_find_and_focus_windows`` so the
verbatim ``switch_window`` path (AD-7) stays untouched.
"""
if os.name != "nt":
return False
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
kernel32 = _win32_kernel32()
_configure_window_query_api(user32, ctypes, wintypes)
kernel32.GetCurrentThreadId.argtypes = []
kernel32.GetCurrentThreadId.restype = wintypes.DWORD
_SW_RESTORE = 9
get_thread = user32.GetWindowThreadProcessId
get_thread.restype = wintypes.DWORD
get_thread.argtypes = [wintypes.HWND, ctypes.POINTER(wintypes.DWORD)]
# Restore ONLY if minimized, then try the cheap plain path first — it
# succeeds whenever Jarvis launched the process and input is recent.
#
# The IsIconic guard is load-bearing, not an optimization: SW_RESTORE
# means "restore to the size and position before minimize OR maximize",
# so calling it unconditionally UN-MAXIMIZED every already-maximized
# window this path touches. Every foreground site funnels through here —
# switch_window ("switch to Chrome"), the open_app already-running path,
# raise_after_launch, the CU settle fallback — so asking Jarvis to focus a
# maximized app shrank it back to its restored size as a side effect, and
# for Computer-Use it silently changed the very geometry the next
# screenshot is mapped against.
if user32.IsIconic(hwnd):
user32.ShowWindow(hwnd, _SW_RESTORE)
if user32.SetForegroundWindow(hwnd):
user32.SetActiveWindow(hwnd)
return True
cur_thread = kernel32.GetCurrentThreadId()
fg_hwnd = user32.GetForegroundWindow()
fg_thread = get_thread(fg_hwnd, None) if fg_hwnd else 0
target_thread = get_thread(hwnd, None)
attached_fg = False
attached_target = False
try:
if fg_thread and fg_thread != cur_thread:
attached_fg = bool(user32.AttachThreadInput(cur_thread, fg_thread, True))
if target_thread and target_thread not in (cur_thread, fg_thread):
attached_target = bool(
user32.AttachThreadInput(cur_thread, target_thread, True)
)
user32.BringWindowToTop(hwnd)
if user32.IsIconic(hwnd): # same rule as above: never un-maximize
user32.ShowWindow(hwnd, _SW_RESTORE)
ok = bool(user32.SetForegroundWindow(hwnd))
user32.SetActiveWindow(hwnd)
return ok
finally:
if attached_fg:
user32.AttachThreadInput(cur_thread, fg_thread, False)
if attached_target:
user32.AttachThreadInput(cur_thread, target_thread, False)
def _list_windows_windows() -> list[WindowInfo]:
"""All identifiable visible top-level windows, including untitled ones."""
if os.name != "nt":
return []
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
EnumWindows = user32.EnumWindows
EnumWindowsProc = ctypes.WINFUNCTYPE(wintypes.BOOL, wintypes.HWND, wintypes.LPARAM)
EnumWindows.argtypes = [EnumWindowsProc, wintypes.LPARAM]
EnumWindows.restype = wintypes.BOOL
GetWindowTextW = user32.GetWindowTextW
GetWindowTextLengthW = user32.GetWindowTextLengthW
IsWindowVisible = user32.IsWindowVisible
IsIconic = user32.IsIconic
GetWindowThreadProcessId = user32.GetWindowThreadProcessId
out: list[WindowInfo] = []
def _callback(hwnd: int, _lparam: int) -> bool:
if not IsWindowVisible(hwnd):
return True
pid = wintypes.DWORD()
GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
length = GetWindowTextLengthW(hwnd)
title = ""
if length > 0:
buf = ctypes.create_unicode_buffer(length + 1)
GetWindowTextW(hwnd, buf, length + 1)
title = buf.value or ""
# Privacy enumeration must retain an untitled password-manager or
# authentication window. A native handle/PID is sufficient identity;
# title-only filtering would silently omit it from monitor denylisting.
if title.strip() or hwnd or pid.value:
out.append(
WindowInfo(
title=title,
minimized=bool(IsIconic(hwnd)),
handle=int(hwnd) if hwnd else None,
pid=int(pid.value) or None,
)
)
return True
EnumWindows(EnumWindowsProc(_callback), 0)
return out
def _foreground_title_windows() -> str:
if os.name != "nt":
return ""
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
with per_monitor_dpi_context():
hwnd = user32.GetForegroundWindow()
if not hwnd:
return ""
length = user32.GetWindowTextLengthW(hwnd)
buf = ctypes.create_unicode_buffer(length + 1)
user32.GetWindowTextW(hwnd, buf, length + 1)
return buf.value or ""
# ----------------------------------------------------------------------
# macOS backend (Quartz/AppKit/AX; no System Events Automation grant)
# ----------------------------------------------------------------------
def _macos_window_title(entry: dict) -> str:
return str(entry.get("kCGWindowName") or entry.get("kCGWindowOwnerName") or "")
def _macos_window_pid(entry: dict) -> int:
try:
return int(entry.get("kCGWindowOwnerPID", 0) or 0)
except (TypeError, ValueError):
return 0
def _macos_ax_attr(element: object, attribute: str) -> object | None:
try:
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementCopyAttributeValue,
)
error, value = AXUIElementCopyAttributeValue(element, attribute, None)
return value if error == 0 else None
except Exception: # noqa: BLE001
return None
def _macos_entry_bounds(entry: dict) -> tuple[float, float, float, float] | None:
raw = entry.get("kCGWindowBounds") or {}
try:
rect = (
float(raw["X"]),
float(raw["Y"]),
float(raw["Width"]),
float(raw["Height"]),
)
except (KeyError, TypeError, ValueError):
return None
return rect if rect[2] > 0 and rect[3] > 0 else None
def _macos_ax_window_bounds(window: object) -> tuple[float, float, float, float] | None:
point = decode_ax_point(_macos_ax_attr(window, "AXPosition"))
size = decode_ax_size(_macos_ax_attr(window, "AXSize"))
if point is None or size is None or size[0] <= 0 or size[1] <= 0:
return None
return point[0], point[1], size[0], size[1]
def _macos_rects_match(
first: tuple[float, float, float, float],
second: tuple[float, float, float, float],
*,
tolerance: float = 3.0,
) -> bool:
return all(
abs(left - right) <= tolerance
for left, right in zip(first, second, strict=True)
)
def _select_macos_ax_window(
windows: list[object],
entry: dict,
*,
title_contains: str | None = None,
title_equals: str | None = None,
) -> object | None:
"""Correlate a CGWindow entry to exactly one AX window.
CGWindowID is not exposed as a public AX attribute. Position and size are
therefore the strongest public correlation key. A unique title is a safe
fallback for minimized windows whose geometry is unavailable; duplicate
titles fail closed instead of focusing or resizing an arbitrary sibling.
"""
# Bound EVERY candidate before reading its attributes: the messaging
# timeout is per-element, and this loop reads geometry/titles of N
# windows — with the ~6 s OS default, one busy app with several windows
# blew the CU action budget right here (live 2026-07-21, second
# occurrence: bounding only root+target was not enough).
for window in windows:
_macos_bound_ax_messaging(window)
cg_bounds = _macos_entry_bounds(entry)
if cg_bounds is not None:
geometry_matches = [
window
for window in windows
if (
(ax_bounds := _macos_ax_window_bounds(window)) is not None
and _macos_rects_match(cg_bounds, ax_bounds)
)
]
if len(geometry_matches) == 1:
return geometry_matches[0]
if len(geometry_matches) > 1:
return None
contains = (title_contains or "").strip().casefold()
equals = (title_equals or "").strip().casefold()
title_matches: list[object] = []
for window in windows:
title = str(_macos_ax_attr(window, "AXTitle") or "").strip().casefold()
if (equals and title == equals) or (contains and contains in title):
title_matches.append(window)
if len(title_matches) == 1:
return title_matches[0]
if not title_matches and len(windows) == 1:
return windows[0]
return None
#: Per-call ceiling for AX messages to another app, in seconds. The macOS
#: default is ~6 s PER CALL, so a busy target (Safari mid-page-load) could
#: hold a raise/focus sequence of 4-5 AX calls for well over the CU action
#: timeout — live 2026-07-21: open_app('Safari') burned the full 15 s
#: _ACT_TIMEOUT_S in exactly this path while Safari was already open.
_AX_MESSAGING_TIMEOUT_S = 1.5
def _macos_bound_ax_messaging(
element, timeout_s: float = _AX_MESSAGING_TIMEOUT_S,
) -> None:
"""Cap the AX messaging timeout for calls through ``element`` (best-effort).
Applies to the element it is set on (setting it on the app root bounds the
calls made through that root). A missing symbol or native error is
ignored — the call sequence then simply keeps the OS default.
"""
try:
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementSetMessagingTimeout,
)
AXUIElementSetMessagingTimeout(element, float(timeout_s))
except Exception: # noqa: BLE001 — advisory bound only
log.debug("AXUIElementSetMessagingTimeout unavailable", exc_info=True)
def _permission_gate():
"""The permission layer (``PermissionGate``); a test replaces this seam."""
from dodaios.platform.permission_service import get_permission_service # noqa: PLC0415
return get_permission_service()
def _macos_accessibility_granted() -> bool:
"""Silent Accessibility read for background reads: never asks, never publishes."""
from dodaios.platform.permissions import PermissionId, PermissionState # noqa: PLC0415
state = _permission_gate().check(PermissionId.ACCESSIBILITY)
return state in (PermissionState.GRANTED, PermissionState.NOT_REQUIRED)
def _macos_window_control_refusal() -> str:
"""``""`` when focusing / maximizing may proceed, else the agent-facing refusal.
Called from a worker (the window tools run in ``asyncio.to_thread``) with
``wait_s=0``: the first call makes macOS show its own Accessibility dialog and
returns at once, the grant is picked up by the permission watcher. Only a live
GRANTED proceeds. The sentence starts with ``[permission_needed:accessibility] ``
and forbids retrying, so the computer-use engine can end the mission on it.
"""
from dodaios.platform.permissions import PermissionId # noqa: PLC0415
result = _permission_gate().ensure(
PermissionId.ACCESSIBILITY, feature="window_control", wait_s=0.0
)
if result.granted:
return ""
return result.agent_detail or (
"[permission_needed:accessibility] Accessibility access has not been allowed "
"yet. You must not retry this action; tell the user and stop."
)
def _find_and_focus_macos(title_contains: str) -> tuple[bool, str]:
"""Activate and AX-raise a matching macOS window without AppleScript.
Quartz supplies the stable owner PID/window catalogue, AppKit activates
the owning process, and Accessibility raises the exact window. This avoids
the separate Automation permission that System Events requires.
"""
needle = (title_contains or "").strip().casefold()
if not needle:
return False, "A non-empty window title is required."
matched_entry: dict | None = None
for entry in _quartz_window_list(on_screen_only=False):
try:
if int(entry.get("kCGWindowLayer", 0) or 0) != 0:
continue
except (TypeError, ValueError):
continue
if needle in _macos_window_title(entry).casefold():
matched_entry = entry
break
if matched_entry is None:
return False, f"No window with title containing '{title_contains}' found."
pid = _macos_window_pid(matched_entry)
if not pid:
return False, "The matching macOS window has no owning process identifier."
try:
from AppKit import ( # type: ignore[import-not-found] # noqa: PLC0415
NSApplicationActivateAllWindows,
NSApplicationActivateIgnoringOtherApps,
NSRunningApplication,
)
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementCreateApplication,
AXUIElementPerformAction,
AXUIElementSetAttributeValue,
)
except (ImportError, ModuleNotFoundError) as exc:
return False, f"macOS window APIs are unavailable: {exc}"
# Focusing a window is an ACTION the user asked for: the first one asks macOS
# for Accessibility (wait_s=0, the answer arrives later), a refusal stops it.
denied = _macos_window_control_refusal()
if denied:
return False, denied
app = NSRunningApplication.runningApplicationWithProcessIdentifier_(pid)
if app is None:
return False, "The matching macOS application exited before it could be focused."
options = NSApplicationActivateIgnoringOtherApps | NSApplicationActivateAllWindows
if not bool(app.activateWithOptions_(options)):
# macOS 14+ "cooperative activation" refuses a background app (which a
# tray-launched Jarvis always is during a voice command). The AX raise
# below works regardless with the Accessibility grant, so a refusal
# here is advisory — aborting turned every Sonoma focus into a failure
# for a window the AX calls would have raised anyway.
log.debug(
"NSRunningApplication activation refused (cooperative activation); "
"continuing via the AX raise path"
)
root = AXUIElementCreateApplication(pid)
_macos_bound_ax_messaging(root)
windows = list(_macos_ax_attr(root, "AXWindows") or [])
owner_name = str(matched_entry.get("kCGWindowOwnerName") or "")
target_title = _macos_window_title(matched_entry)
target = _select_macos_ax_window(
windows,
matched_entry,
title_contains=needle if needle not in owner_name.casefold() else None,
)
if target is None:
return False, (
"The application activated, but its matching AX window was "
"unavailable or ambiguous."
)
# The timeout is per-element: bound the window element too, not only root.
_macos_bound_ax_messaging(target)
target_title = str(_macos_ax_attr(target, "AXTitle") or target_title)
minimized = bool(_macos_ax_attr(target, "AXMinimized") or False)
restore_error = (
AXUIElementSetAttributeValue(target, "AXMinimized", False)
if minimized
else 0
)
raise_error = AXUIElementPerformAction(target, "AXRaise")
# AXFocusedWindow on the APPLICATION element is read-only in AppKit — the
# setter returned kAXErrorAttributeUnsupported for every Cocoa app, which
# the old all-must-be-zero rule turned into "refused to focus" for windows
# that were already standing in front. The settable spelling of the same
# intent is AXMain on the WINDOW element; it stays advisory.
main_error = AXUIElementSetAttributeValue(target, "AXMain", True)
front_error = AXUIElementSetAttributeValue(root, "AXFrontmost", True)
if main_error != 0:
log.debug("AXMain could not be set on the target window: %s", main_error)
# Decisive: a window that stayed minimized, or an app that could neither
# raise the window nor come frontmost. One of raise/frontmost succeeding
# puts the window on top in practice; requiring both was the bug above.
if restore_error != 0 or (raise_error != 0 and front_error != 0):
return False, "macOS Accessibility refused to focus the matching window."
return True, target_title
def _list_windows_macos() -> list[WindowInfo]:
"""Identifiable normal-layer Quartz windows, front-to-back."""
entries: list[dict] = []
for entry in _quartz_window_list(on_screen_only=False):
try:
if int(entry.get("kCGWindowLayer", 0) or 0) != 0:
continue
title = _macos_window_title(entry).strip()
except (TypeError, ValueError):
continue
# Quartz frequently withholds titles for password/authentication
# windows. Retain entries carrying a window number or owner PID so
# monitor privacy checks can still resolve and denylist their process.
if title or _macos_window_pid(entry) or entry.get("kCGWindowNumber"):
entries.append(entry)
minimized_by_number: dict[int, bool] = {}
try:
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementCreateApplication,
)
# Listing is a background READ: a silent check, never a prompt. Without
# the grant the minimized flag is simply not read.
if _macos_accessibility_granted():
ax_windows_by_pid: dict[int, list[object]] = {}
for entry in entries:
pid = _macos_window_pid(entry)
number = int(entry.get("kCGWindowNumber", 0) or 0)
if not pid or not number:
continue
if pid not in ax_windows_by_pid:
root = AXUIElementCreateApplication(pid)
ax_windows_by_pid[pid] = list(
_macos_ax_attr(root, "AXWindows") or [],
)
ax_windows = ax_windows_by_pid[pid]
title_key = _macos_window_title(entry).strip().casefold()
target = _select_macos_ax_window(
ax_windows,
entry,
title_equals=title_key,
)
if target is not None:
native_minimized = _macos_ax_attr(target, "AXMinimized")
if native_minimized is not None:
minimized_by_number[number] = bool(native_minimized)
except Exception: # noqa: BLE001 — minimized state is advisory
log.debug("macOS AX minimized-state lookup failed", exc_info=True)
result: list[WindowInfo] = []
for entry in entries:
try:
number = int(entry.get("kCGWindowNumber", 0) or 0)
except (TypeError, ValueError):
number = 0
result.append(
WindowInfo(
title=_macos_window_title(entry).strip(),
minimized=minimized_by_number.get(number, False),
handle=number or None,
pid=_macos_window_pid(entry) or None,
)
)
return result
def _foreground_title_macos() -> str:
try:
from AppKit import NSWorkspace # type: ignore[import-not-found] # noqa: PLC0415
app = NSWorkspace.sharedWorkspace().frontmostApplication()
if app is None:
return ""
pid = int(app.processIdentifier())
for entry in _quartz_window_list():
if (
_macos_window_pid(entry) == pid
and int(entry.get("kCGWindowLayer", 0) or 0) == 0
):
title = _macos_window_title(entry).strip()
if title:
return title
return str(app.localizedName() or "")
except Exception: # noqa: BLE001
return ""
# ----------------------------------------------------------------------
# Linux/X11 backend (wmctrl) — focus path moved verbatim from switch_window (AD-7)
# ----------------------------------------------------------------------
def _find_and_focus_linux(title_contains: str) -> tuple[bool, str]:
"""Activate the first window whose title contains the substring via wmctrl
on X11 (H2). Returns a clear message when wmctrl is absent (the user should
install it, e.g. ``apt install wmctrl``) or nothing matches. Wayland/headless
are handled by the caller before this runs.
"""
if shutil.which("wmctrl") is None:
return False, (
"wmctrl not found — install it (e.g. `apt install wmctrl`) to switch "
"windows on X11."
)
listing = subprocess.run(
["wmctrl", "-l"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if listing.returncode != 0:
detail = (listing.stderr or "").strip() or f"exit code {listing.returncode}"
return False, f"wmctrl could not list windows: {detail}"
needle = title_contains.lower()
win_id = ""
win_title = ""
for line in (listing.stdout or "").splitlines():
# wmctrl -l format: <id> <desktop> <host> <title...>
parts = line.split(None, 3)
if len(parts) < 4:
continue
if needle in parts[3].lower():
win_id, win_title = parts[0], parts[3]
break
if not win_id:
return False, f"No visible window with title containing '{title_contains}' found."
activate = subprocess.run(
["wmctrl", "-i", "-a", win_id],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if activate.returncode != 0:
detail = (activate.stderr or "").strip()
return False, f"wmctrl could not activate window '{win_title}': {detail}"
return True, win_title
def _list_windows_linux() -> list[WindowInfo]:
if shutil.which("wmctrl") is None:
return []
listing = subprocess.run(
["wmctrl", "-lp"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if listing.returncode != 0:
return []
out: list[WindowInfo] = []
for line in (listing.stdout or "").splitlines():
parts = line.split(None, 4)
# ``wmctrl -lp`` may end after the host column for an untitled window.
# Keep it when its native id or PID is usable for privacy identity.
if len(parts) < 4:
continue
try:
pid = int(parts[2])
except ValueError: # Invalid PID stays unknown; privacy callers fail closed.
pid = 0
try:
handle = int(parts[0], 16)
except ValueError: # Invalid native id cannot identify a capture surface.
handle = 0
if handle or pid:
out.append(
WindowInfo(
title=parts[4] if len(parts) >= 5 else "",
handle=handle or None,
pid=pid or None,
)
)
return out
def _foreground_title_linux() -> str:
if shutil.which("xdotool") is None:
return ""
proc = subprocess.run(
["xdotool", "getactivewindow", "getwindowname"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if proc.returncode != 0:
return ""
return (proc.stdout or "").strip()
# ----------------------------------------------------------------------
# Public API (platform dispatch + graceful degrade; never raises)
# ----------------------------------------------------------------------
def list_windows() -> list[WindowInfo]:
"""Every visible top-level window. Empty list on headless/Wayland/error."""
try:
plat = detect_platform()
if plat == "win32":
return _list_windows_windows()
if plat == "darwin":
return _list_windows_macos()
if plat == "linux":
if is_wayland() or not display_present():
return []
return _list_windows_linux()
return []
except Exception: # noqa: BLE001 — best-effort, must never raise into a caller
log.debug("list_windows failed", exc_info=True)
return []
def get_foreground_title() -> str:
"""Title of the current foreground window, or "" if unknown."""
try:
plat = detect_platform()
if plat == "win32":
return _foreground_title_windows()
if plat == "darwin":
return _foreground_title_macos()
if plat == "linux":
if is_wayland() or not display_present():
return ""
return _foreground_title_linux()
return ""
except Exception: # noqa: BLE001
log.debug("get_foreground_title failed", exc_info=True)
return ""
def focus_window(title_contains: str) -> tuple[bool, str]:
"""Bring the first window whose title contains the substring to the front.
Returns ``(found_and_focused, message)``. Degrades cleanly (no raise) on
Wayland / headless / missing tool / native error.
"""
try:
plat = detect_platform()
if plat == "win32":
return _find_and_focus_windows(title_contains)
if plat == "darwin":
return _find_and_focus_macos(title_contains)
if plat == "linux":
if is_wayland():
return False, (
"Window switching is unavailable on Wayland by OS design — "
"switch with the dock/overview or the app's own controls."
)
if not display_present():
return False, (
"Window switching needs a graphical display; this looks like "
"a headless session."
)
return _find_and_focus_linux(title_contains)
return False, f"Window switching is not supported on this platform ({plat})."
except Exception as exc: # noqa: BLE001
log.debug("focus_window failed", exc_info=True)
return False, f"Window focus failed: {exc}"
def _app_token(app_name: str) -> str:
"""The matching token for an app name — its basename stem if it looks like a
path/exe, else the trimmed name itself."""
name = (app_name or "").strip()
if not name:
return ""
if ("\\" in name) or ("/" in name) or name.lower().endswith(".exe"):
# Split on BOTH separators: a Windows-style path must resolve to its
# basename on macOS/Linux too (os.path.basename only splits the
# host's own separator, leaving the full path as a dead token).
base = re.split(r"[\\/]", name)[-1]
stem = base.rsplit(".", 1)[0] if "." in base else base
name = stem or name
return name.strip()
def _match_window(app_name: str, windows: list[WindowInfo]) -> WindowInfo | None:
"""Conservative match of an app name against open window titles."""
token = _app_token(app_name).lower()
if len(token) < _MIN_TOKEN_LEN:
return None
needles = [token, *_TITLE_ALIASES.get(token, ())]
needles = [n for n in needles if len(n) >= _MIN_TOKEN_LEN]
for w in windows:
title = (w.title or "").lower()
if any(n in title for n in needles):
return w
return None
def is_app_running(app_name: str) -> WindowInfo | None:
"""The matching open window if ``app_name`` is already running, else ``None``.
Conservative by design (see module docstring): an uncertain / short token
returns ``None`` so the caller launches normally rather than wrongly focusing
an unrelated window.
"""
try:
return _match_window(app_name, list_windows())
except Exception: # noqa: BLE001
log.debug("is_app_running failed", exc_info=True)
return None
def raise_window(win: WindowInfo) -> tuple[bool, str]:
"""Bring a specific already-known window to the foreground via the hardened
path. On Windows it raises by the window handle directly (precise, no
re-enumeration, and it works even when the title path would match a sibling
window); off-Windows it falls back to title-based :func:`focus_window`.
Best-effort, never raises.
This is the already-open sibling of :func:`raise_after_launch`: the open_app
"app is already running -> focus it" path and the CU window-switch use it so
an already-open-but-backgrounded app (the WhatsApp report) is actually pulled
to the front instead of left behind.
"""
try:
if detect_platform() == "win32" and win.handle:
return _force_foreground_windows(int(win.handle)), win.title
return focus_window(win.title)
except Exception: # noqa: BLE001 — best-effort, must never raise into a caller
log.debug("raise_window failed", exc_info=True)
return False, ""
#: Poll budget for raising a freshly launched app's window to the foreground.
#: A fast-raising app exits on the first poll; only a backgrounded / secondary-
#: monitor / minimized launch consumes the full budget.
_RAISE_POLL_TIMEOUT_S = 3.0
_RAISE_POLL_INTERVAL_S = 0.25
def raise_after_launch(
app_name: str,
*,
timeout_s: float = _RAISE_POLL_TIMEOUT_S,
poll_s: float = _RAISE_POLL_INTERVAL_S,
maximize: bool = False,
) -> tuple[bool, str]:
"""Poll until a window matching ``app_name`` appears, then actively bring it
to the foreground. Returns ``(raised, title_or_reason)``. Best-effort, never
raises — a miss just leaves things as they were.
A fresh launch (``subprocess.Popen`` / ``os.startfile``) is fire-and-forget:
the new window is frequently left in the background (Windows foreground-lock-
steal, a secondary monitor, or restored-minimized). The Computer-Use
screenshot follows the *foreground* window, so it then captures the wrong
screen and the mission fails. This closes that gap. Cross-platform: Windows
raises by ``hwnd`` through the hardened :func:`_force_foreground_windows`
path; macOS/Linux reuse :func:`focus_window` (by title). Synchronous and
blocking by design — an async caller wraps it in ``asyncio.to_thread`` (as
the speech/CU paths already do for :func:`focus_window`).
When ``maximize`` is set, a successfully raised window is also filled to its
own monitor via :func:`maximize_window` (user request 2026-07-23: a freshly
launched app — e.g. Chrome — must not sit tiny in the middle of a big
desktop). Applied to the EXACT window just found (not the foreground), so it
never depends on a readable maximized-state and never touches a sibling
window. A fixed-size dialog, Wayland, or a headless session is left as-is by
that call, and its result never changes the returned raise status.
"""
token = _app_token(app_name)
if len(token) < _MIN_TOKEN_LEN:
return False, ""
try:
deadline = time.monotonic() + max(0.0, timeout_s)
while True:
win = _match_window(app_name, list_windows())
if win is not None:
raised, msg = raise_window(win)
if raised and maximize:
max_ok, max_msg = maximize_window(win)
if max_ok:
log.info("raise_after_launch maximized '%s': %s", token, max_msg)
return raised, msg
if time.monotonic() >= deadline:
return False, (
f"no window matching '{token}' appeared within {timeout_s:.0f}s"
)
time.sleep(max(0.0, poll_s))
except Exception: # noqa: BLE001 — best-effort, must never raise into a caller
log.debug("raise_after_launch failed", exc_info=True)
return False, ""
# ----------------------------------------------------------------------
# G8b — move a window onto the primary monitor
# ----------------------------------------------------------------------
def window_is_on_monitor(rect: tuple[int, int, int, int], monitor: dict) -> bool:
"""True when the window's CENTER lies within ``monitor`` (an mss-style dict
with left/top/width/height). Center-based, so a window straddling two screens
counts as being on the one showing most of it. Pure; never raises."""
left, top, width, height = rect
cx, cy = left + width // 2, top + height // 2
ml, mt = int(monitor.get("left", 0)), int(monitor.get("top", 0))
mw, mh = int(monitor.get("width", 0)), int(monitor.get("height", 0))
return ml <= cx < ml + mw and mt <= cy < mt + mh
def window_rect(win: WindowInfo) -> tuple[int, int, int, int] | None:
"""A window's ``(left, top, width, height)`` in virtual-desktop coordinates,
or ``None`` when it cannot be read. Windows: ``GetWindowRect`` by hwnd.
macOS/Linux: not read today (the move path queries position differently).
Best-effort; never raises."""
try:
if detect_platform() == "win32" and win.handle:
return _window_rect_windows(int(win.handle))
return None
except Exception: # noqa: BLE001
log.debug("window_rect failed", exc_info=True)
return None
def foreground_window() -> WindowInfo | None:
"""The current foreground window as a :class:`WindowInfo`, or ``None``.
Carries the platform window id in ``handle`` on ALL three platforms
(Win32 hwnd; macOS CGWindowID via Quartz; X11 window id via xdotool) —
the id the window-centric capture pipeline resolves rects and native
grabs through. Hosts without the native backend (no Quartz, no xdotool,
Wayland) degrade to a title-only WindowInfo or ``None``. Best-effort;
never raises.
"""
try:
plat = detect_platform()
if plat == "win32":
return _foreground_window_windows()
if plat == "darwin":
return _foreground_window_macos()
if plat == "linux":
return _foreground_window_linux()
title = get_foreground_title()
return WindowInfo(title=title) if title else None
except Exception: # noqa: BLE001
log.debug("foreground_window failed", exc_info=True)
return None
def _foreground_window_windows() -> WindowInfo | None:
if os.name != "nt":
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
with per_monitor_dpi_context():
hwnd = user32.GetForegroundWindow()
if not hwnd:
return None
length = int(user32.GetWindowTextLengthW(hwnd))
buf = ctypes.create_unicode_buffer(length + 1)
user32.GetWindowTextW(hwnd, buf, length + 1)
pid = wintypes.DWORD()
user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
return WindowInfo(
title=buf.value or "", handle=int(hwnd), pid=int(pid.value) or None
)
# Win32 constants for telling Jarvis's own floating overlays (the bar, the
# mascot, the transcription bubble) apart from the app window under them.
_GWL_EXSTYLE = -20
_GW_HWNDNEXT = 2
_WS_EX_TOOLWINDOW = 0x00000080
_WS_EX_NOACTIVATE = 0x08000000
_DWMWA_CLOAKED = 14
#: A window smaller than this in either direction is no app window a person
#: works in (helper and message windows are often 0x0 or 1x1).
_MIN_APP_WINDOW_PX = 64
#: Hard stop for the Z-order walk; a real desktop has far fewer top-level windows.
_MAX_Z_ORDER_STEPS = 512
#: The wallpaper windows sit at the bottom of the Z-order: reaching one means no
#: app window is open under the overlay. The taskbar is NOT here — it is a
#: topmost tool window that sits between the overlays and the apps, and the
#: walk steps over it like any other non-app window.
_DESKTOP_WINDOW_CLASSES = frozenset({"Progman", "WorkerW"})
def foreground_app_window() -> WindowInfo | None:
"""The app window the person is working in, looking past Jarvis's overlays.
Clicking the Jarvis bar or the mascot gives that small topmost overlay the
Windows focus, so the plain foreground window is the overlay itself — and a
"front window" capture photographs a square of mascot instead of the app.
When the foreground window is one of this process's overlays, this walks
down the Z-order to the first real app window under it. That is the window
the person used last, because activating a window raises it to the top of
the normal band.
Other platforms return :func:`foreground_window` unchanged: the macOS probe
already skips windows above the normal layer, where the overlays float, and
X11 never hands focus to the override-redirect overlay windows. Returns
``None`` when no app window sits under the overlay (only the desktop), so
callers degrade to monitor scope. Best-effort; never raises.
"""
try:
if detect_platform() == "win32":
return _foreground_app_window_windows()
return foreground_window()
except Exception: # noqa: BLE001
log.debug("foreground_app_window failed", exc_info=True)
return None
def _pick_app_window(
foreground: int,
*,
next_below: Callable[[int], int],
is_own_overlay: Callable[[int], bool],
is_app_window: Callable[[int], bool],
is_desktop: Callable[[int], bool],
) -> int | None:
"""Pure Z-order walk behind :func:`foreground_app_window`.
The foreground window wins unless it is one of our overlays. Otherwise the
first app window below it wins; reaching the wallpaper (or the end of the
list) means there is no app window, which is ``None``.
"""
if not is_own_overlay(foreground):
return foreground
below = next_below(foreground)
for _ in range(_MAX_Z_ORDER_STEPS):
if not below:
return None
if is_desktop(below):
return None
if not is_own_overlay(below) and is_app_window(below):
return below
below = next_below(below)
return None
def _foreground_app_window_windows() -> WindowInfo | None:
if os.name != "nt":
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
user32.GetWindow.argtypes = [wintypes.HWND, wintypes.UINT]
user32.GetWindow.restype = wintypes.HWND
user32.GetWindowDisplayAffinity.argtypes = [
wintypes.HWND,
ctypes.POINTER(wintypes.DWORD),
]
user32.GetWindowDisplayAffinity.restype = wintypes.BOOL
own_pid = os.getpid()
def _pid_of(hwnd: int) -> int:
pid = wintypes.DWORD()
user32.GetWindowThreadProcessId(hwnd, ctypes.byref(pid))
return int(pid.value)
def _is_own_process(pid: int) -> bool:
if pid == own_pid:
return True
# The bar can run in a child process (subprocess overlay host).
try:
import psutil # noqa: PLC0415
return int(psutil.Process(pid).ppid()) == own_pid
except Exception: # noqa: BLE001 - no psutil / dead pid: not ours
return False
def _ex_style(hwnd: int) -> int:
return int(user32.GetWindowLongW(hwnd, _GWL_EXSTYLE)) & 0xFFFFFFFF
def _is_own_overlay(hwnd: int) -> bool:
ex_style = _ex_style(hwnd)
floating = bool(ex_style & (_WS_EX_TOOLWINDOW | _WS_EX_NOACTIVATE))
if not floating:
affinity = wintypes.DWORD()
floating = bool(
user32.GetWindowDisplayAffinity(hwnd, ctypes.byref(affinity))
and affinity.value
)
return floating and _is_own_process(_pid_of(hwnd))
def _is_cloaked(hwnd: int) -> bool:
cloaked = wintypes.DWORD()
try:
get_attribute = ctypes.windll.dwmapi.DwmGetWindowAttribute
get_attribute.argtypes = [
wintypes.HWND,
wintypes.DWORD,
ctypes.c_void_p,
wintypes.DWORD,
]
get_attribute.restype = ctypes.c_long
res = get_attribute(
wintypes.HWND(hwnd),
wintypes.DWORD(_DWMWA_CLOAKED),
ctypes.byref(cloaked),
ctypes.sizeof(cloaked),
)
except (OSError, AttributeError):
return False # no DWM: nothing can be cloaked
return res == 0 and bool(cloaked.value)
def _is_app_window(hwnd: int) -> bool:
if not user32.IsWindowVisible(hwnd) or user32.IsIconic(hwnd):
return False
if _ex_style(hwnd) & _WS_EX_TOOLWINDOW or _is_cloaked(hwnd):
return False
rect = wintypes.RECT()
if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
return False
return (
rect.right - rect.left >= _MIN_APP_WINDOW_PX
and rect.bottom - rect.top >= _MIN_APP_WINDOW_PX
)
with per_monitor_dpi_context():
foreground = user32.GetForegroundWindow()
if not foreground:
return None
chosen = _pick_app_window(
int(foreground),
next_below=lambda hwnd: int(user32.GetWindow(hwnd, _GW_HWNDNEXT) or 0),
is_own_overlay=_is_own_overlay,
is_app_window=_is_app_window,
is_desktop=lambda hwnd: _window_class_windows(hwnd) in _DESKTOP_WINDOW_CLASSES,
)
if chosen is None:
log.info("foreground is a Dodaios overlay with no app window under it")
return None
length = int(user32.GetWindowTextLengthW(chosen))
buf = ctypes.create_unicode_buffer(length + 1)
user32.GetWindowTextW(chosen, buf, length + 1)
return WindowInfo(
title=buf.value or "", handle=int(chosen), pid=_pid_of(chosen) or None
)
def _quartz_window_list(*, on_screen_only: bool = True) -> list:
"""Quartz window info dicts, front-to-back, or ``[]`` when unavailable.
Foreground/capture callers use the default on-screen catalogue. Window
enumeration and switching request the all-windows catalogue so minimized
and other-Space windows can still be found and restored. Bounds and ids
use the same global point space as Quartz input and mss capture rects.
"""
try:
import Quartz # type: ignore[import-not-found] # noqa: PLC0415
except Exception: # noqa: BLE001 — pyobjc not installed
return []
try:
scope = (
Quartz.kCGWindowListOptionOnScreenOnly
if on_screen_only
else getattr(Quartz, "kCGWindowListOptionAll", 0)
)
return list(Quartz.CGWindowListCopyWindowInfo(
scope | Quartz.kCGWindowListExcludeDesktopElements,
Quartz.kCGNullWindowID,
) or [])
except Exception: # noqa: BLE001 — permission / transient CG error
log.debug("CGWindowListCopyWindowInfo failed", exc_info=True)
return []
def _foreground_window_macos() -> WindowInfo | None:
"""Frontmost normal-layer window with its CGWindowID.
``CGWindowListCopyWindowInfo`` returns windows ordered front-to-back, so
the first entry on layer 0 is the frontmost app window (status items,
the Dock and overlays live on higher layers). ``kCGWindowName`` needs
the Screen-Recording permission — without it the owning app's name still
identifies the window. Falls back to the native foreground-title probe
(without a handle) when Quartz is unavailable.
"""
front_pid = 0
try:
from AppKit import NSWorkspace # type: ignore[import-not-found] # noqa: PLC0415
app = NSWorkspace.sharedWorkspace().frontmostApplication()
front_pid = int(app.processIdentifier()) if app is not None else 0
except Exception: # noqa: BLE001
log.debug("frontmost macOS process lookup failed", exc_info=True)
for entry in _quartz_window_list():
try:
if int(entry.get("kCGWindowLayer", 0) or 0) != 0:
continue
if front_pid and _macos_window_pid(entry) != front_pid:
continue
number = int(entry.get("kCGWindowNumber", 0) or 0)
title = str(
entry.get("kCGWindowName")
or entry.get("kCGWindowOwnerName")
or ""
)
owner_pid = front_pid or _macos_window_pid(entry)
return WindowInfo(
title=title, handle=number or None, pid=owner_pid or None,
)
except (TypeError, ValueError):
continue
title = get_foreground_title()
if not title:
return None
return WindowInfo(title=title, pid=front_pid or None)
def _foreground_window_linux() -> WindowInfo | None:
"""Active X11 window with its window id via xdotool.
Wayland and headless sessions return ``None`` (no global window identity
by design there); a missing xdotool degrades to the title-only path.
"""
if is_wayland() or not display_present():
return None
if shutil.which("xdotool") is None:
title = get_foreground_title()
return WindowInfo(title=title) if title else None
proc = subprocess.run(
["xdotool", "getactivewindow"],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if proc.returncode != 0:
return None
try:
win_id = int((proc.stdout or "").strip() or "0")
except ValueError:
return None
if not win_id:
return None
name = subprocess.run(
["xdotool", "getwindowname", str(win_id)],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
title = (name.stdout or "").strip() if name.returncode == 0 else ""
pid_probe = subprocess.run(
["xdotool", "getwindowpid", str(win_id)],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
try:
pid = (
int((pid_probe.stdout or "").strip())
if pid_probe.returncode == 0
else 0
)
except ValueError: # Invalid active PID stays unknown; privacy callers fail closed.
pid = 0
return WindowInfo(title=title, handle=win_id, pid=pid or None)
def move_window_to_primary(
win: WindowInfo, primary: dict
) -> tuple[bool, str]:
"""Bring ``win`` onto the primary monitor ``primary`` (mss-style geometry
dict) so Computer-Use acts on the main screen (audit G8b).
Returns ``(moved, message)``. Windows restores a maximized window, moves it
onto the primary, then re-maximizes there. macOS/Linux-X11 are best-effort;
Wayland and headless sessions REFUSE honestly with a clear message rather
than acting on the wrong screen blind. Never raises."""
try:
plat = detect_platform()
if plat == "win32":
return _move_to_primary_windows(win, primary)
if plat == "darwin":
# AX kAXPositionAttribute needs pyobjc + Accessibility permission; the
# real impl is a tracked follow-up. Honest refusal, no fake pass.
return False, (
"Moving a window to the main screen is not supported on macOS yet "
"— please drag it to your main display, then retry."
)
if plat == "linux":
if is_wayland():
return False, (
"Cannot move the window on Wayland (no global window "
"positioning by OS design) — drag it to your main screen "
"manually, then retry."
)
if not display_present():
return False, (
"Cannot move the window: this looks like a headless session "
"with no display."
)
return _move_to_primary_linux(win, primary)
return False, f"Moving windows is not supported on this platform ({plat})."
except Exception as exc: # noqa: BLE001
log.debug("move_window_to_primary failed", exc_info=True)
return False, f"Window move failed: {exc}"
def _window_rect_windows(hwnd: int) -> tuple[int, int, int, int] | None:
if os.name != "nt":
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
with per_monitor_dpi_context():
rect = wintypes.RECT()
if not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
return None
result = (rect.left, rect.top, rect.right - rect.left, rect.bottom - rect.top)
virtual = _virtual_desktop_rect_windows(user32)
if virtual is not None and not _rects_intersect(result, virtual):
return None
return result
def _window_client_rect_windows(hwnd: int) -> tuple[int, int, int, int] | None:
if os.name != "nt":
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
with per_monitor_dpi_context():
rect = wintypes.RECT()
origin = wintypes.POINT()
if not user32.GetClientRect(hwnd, ctypes.byref(rect)):
return None
if not user32.ClientToScreen(hwnd, ctypes.byref(origin)):
return None
width = rect.right - rect.left
height = rect.bottom - rect.top
if width <= 0 or height <= 0:
return None
return (int(origin.x), int(origin.y), width, height)
def _move_to_primary_windows(win: WindowInfo, primary: dict) -> tuple[bool, str]:
"""Restore-if-maximized → SetWindowPos onto the primary → re-maximize there."""
if not win.handle:
return False, "no window handle to move"
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
hwnd = int(win.handle)
class _WINDOWPLACEMENT(ctypes.Structure):
_fields_ = [
("length", wintypes.UINT), ("flags", wintypes.UINT),
("showCmd", wintypes.UINT), ("ptMinPosition", wintypes.POINT),
("ptMaxPosition", wintypes.POINT), ("rcNormalPosition", wintypes.RECT),
]
_SW_RESTORE, _SW_MAXIMIZE, _SW_SHOWMAXIMIZED = 9, 3, 3
_SWP_NOSIZE, _SWP_NOZORDER, _SWP_NOACTIVATE = 0x0001, 0x0004, 0x0010
wp = _WINDOWPLACEMENT()
wp.length = ctypes.sizeof(_WINDOWPLACEMENT)
was_maximized = False
if user32.GetWindowPlacement(hwnd, ctypes.byref(wp)):
was_maximized = wp.showCmd == _SW_SHOWMAXIMIZED
if was_maximized:
user32.ShowWindow(hwnd, _SW_RESTORE)
# Inset a little so the title bar is fully on the primary (never off-screen).
px = int(primary.get("left", 0)) + 40
py = int(primary.get("top", 0)) + 40
moved = bool(user32.SetWindowPos(
hwnd, 0, px, py, 0, 0, _SWP_NOSIZE | _SWP_NOZORDER | _SWP_NOACTIVATE,
))
if was_maximized:
user32.ShowWindow(hwnd, _SW_MAXIMIZE) # re-maximizes on the primary now
if not moved:
return False, "SetWindowPos failed"
return True, f"moved '{(win.title or 'window')[:40]}' onto the primary monitor"
# ----------------------------------------------------------------------
# Window-scoped Computer-Use helpers (industry practice: the model sees the
# TARGET WINDOW, not a whole monitor) — precise frame rect, shell detection,
# and in-place maximize. All best-effort; never raise into a caller.
# ----------------------------------------------------------------------
#: Top-level window classes that are the Windows shell itself (desktop /
#: taskbar). Capturing or "normalizing" these would act on the wallpaper.
_SHELL_WINDOW_CLASSES = frozenset({
"Progman", "WorkerW", "Shell_TrayWnd", "Shell_SecondaryTrayWnd",
"SHELLDLL_DefView",
})
def _window_class_windows(hwnd: int) -> str:
if os.name != "nt":
return ""
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
buf = ctypes.create_unicode_buffer(256)
if not user32.GetClassNameW(hwnd, buf, 256):
return ""
return buf.value or ""
def is_shell_window(win: WindowInfo) -> bool:
"""True when ``win`` is the desktop/taskbar shell rather than an app window.
Clicking "into" these means clicking the wallpaper — a Computer-Use
capture or window-normalize must fall back to monitor scope instead.
"""
try:
if detect_platform() == "win32" and win.handle:
return _window_class_windows(int(win.handle)) in _SHELL_WINDOW_CLASSES
return (win.title or "").strip() == "Program Manager"
except Exception: # noqa: BLE001
log.debug("is_shell_window failed", exc_info=True)
return False
def window_frame_rect(win: WindowInfo) -> tuple[int, int, int, int] | None:
"""The window's VISIBLE frame ``(left, top, width, height)`` in the
platform's INPUT UNITS on the virtual desktop, or ``None`` when
unavailable. This is the rect the window-centric Computer-Use pipeline
captures and maps clicks into, so each backend MUST report the same
coordinate space the platform's input APIs consume:
* Windows — ``DwmGetWindowAttribute(DWMWA_EXTENDED_FRAME_BOUNDS)`` (the
rect the user actually sees; plain ``GetWindowRect`` includes the
invisible resize-shadow border, which would leak wallpaper into the
capture and skew every mapped click), physical virtual-desktop pixels.
Mixed-DPI correctness requires the calling thread to hold a
per-monitor DPI context — CU callers invoke this inside
:func:`dodaios.cu.geometry.input_space`.
* macOS — Quartz ``kCGWindowBounds`` by CGWindowID: global POINTS with a
top-left origin, exactly the space Quartz mouse events and mss rects
use (Retina backing pixels never appear here).
* Linux/X11 — ``xdotool getwindowgeometry`` by window id: root-window
pixels (the client-area rect; WM decorations are not part of it).
Wayland and headless sessions return ``None`` — callers fall back to
monitor scope and the engine's X11/XWayland refusal explains why.
"""
try:
plat = detect_platform()
if plat == "darwin":
return _window_frame_rect_macos(win)
if plat == "linux":
return _window_frame_rect_linux(win)
if plat != "win32" or not win.handle:
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
hwnd = int(win.handle)
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
with per_monitor_dpi_context():
rect = wintypes.RECT()
_DWMWA_EXTENDED_FRAME_BOUNDS = 9
try:
get_attribute = ctypes.windll.dwmapi.DwmGetWindowAttribute
get_attribute.argtypes = [
wintypes.HWND,
wintypes.DWORD,
ctypes.c_void_p,
wintypes.DWORD,
]
get_attribute.restype = ctypes.c_long
res = get_attribute(
wintypes.HWND(hwnd),
wintypes.DWORD(_DWMWA_EXTENDED_FRAME_BOUNDS),
ctypes.byref(rect),
ctypes.sizeof(rect),
)
except (OSError, AttributeError):
res = 1 # dwmapi missing — fall through to GetWindowRect
if res != 0 and not user32.GetWindowRect(hwnd, ctypes.byref(rect)):
return None
result = (
rect.left,
rect.top,
rect.right - rect.left,
rect.bottom - rect.top,
)
virtual = _virtual_desktop_rect_windows(user32)
if virtual is not None and not _rects_intersect(result, virtual):
return None
return result
except Exception: # noqa: BLE001
log.debug("window_frame_rect failed", exc_info=True)
return None
def _window_frame_rect_macos(win: WindowInfo) -> tuple[int, int, int, int] | None:
"""Window bounds by CGWindowID (or the frontmost layer-0 window when the
:class:`WindowInfo` carries no handle). Global points, top-left origin."""
target: dict | None = None
for entry in _quartz_window_list():
try:
if win.handle:
if int(entry.get("kCGWindowNumber", -1) or -1) == int(win.handle):
target = entry
break
elif int(entry.get("kCGWindowLayer", 0) or 0) == 0:
target = entry
break
except (TypeError, ValueError):
continue
if target is None:
return None
bounds = target.get("kCGWindowBounds") or {}
try:
left = int(bounds.get("X", 0))
top = int(bounds.get("Y", 0))
width = int(bounds.get("Width", 0))
height = int(bounds.get("Height", 0))
except (TypeError, ValueError):
return None
if width <= 0 or height <= 0:
return None
return (left, top, width, height)
def _window_frame_rect_linux(win: WindowInfo) -> tuple[int, int, int, int] | None:
"""Window geometry by X11 window id via ``xdotool getwindowgeometry
--shell`` (root-relative pixels). ``None`` on Wayland/headless/no tool."""
if is_wayland() or not display_present():
return None
if not win.handle or shutil.which("xdotool") is None:
return None
proc = subprocess.run(
["xdotool", "getwindowgeometry", "--shell", str(int(win.handle))],
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=10,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if proc.returncode != 0:
return None
fields: dict[str, int] = {}
for line in (proc.stdout or "").splitlines():
key, sep, value = line.strip().partition("=")
if not sep:
continue
try:
fields[key.strip().upper()] = int(value.strip())
except ValueError:
continue
try:
left, top = fields["X"], fields["Y"]
width, height = fields["WIDTH"], fields["HEIGHT"]
except KeyError:
return None
if width <= 0 or height <= 0:
return None
return _trim_gtk_frame_extents(int(win.handle), (left, top, width, height))
def _trim_gtk_frame_extents(
window_id: int, rect: tuple[int, int, int, int]
) -> tuple[int, int, int, int]:
"""Drop a GTK client-side-decoration shadow from an X11 window rect.
GTK windows that draw their own title bar (GNOME apps) make the X window
larger than what the user sees, by the invisible shadow margins they
publish in ``_GTK_FRAME_EXTENTS`` (left, right, top, bottom). Without the
trim a window appshot showed a band of desktop around the window. A
window without the property, or a host without python-xlib, keeps the
rect as it is.
"""
try:
from Xlib import X, display # type: ignore[import-not-found] # noqa: PLC0415
except ImportError: # python-xlib is optional; without it the rect stays as it is
return rect
conn = None
try:
conn = display.Display()
window = conn.create_resource_object("window", window_id)
prop = window.get_full_property(conn.intern_atom("_GTK_FRAME_EXTENTS"), X.AnyPropertyType)
values = list(getattr(prop, "value", []) or [])
except Exception: # noqa: BLE001 - an unreadable property keeps the plain rect
log.debug("GTK frame extents unreadable for window %s", window_id, exc_info=True)
return rect
finally:
if conn is not None:
conn.close()
if len(values) != 4:
return rect
left_m, right_m, top_m, bottom_m = (max(0, int(v)) for v in values)
left, top, width, height = rect
trimmed_w = width - left_m - right_m
trimmed_h = height - top_m - bottom_m
if trimmed_w <= 0 or trimmed_h <= 0:
return rect
return (left + left_m, top + top_m, trimmed_w, trimmed_h)
def _resolve_macos_ax_window(win: WindowInfo) -> tuple[object | None, str]:
"""Resolve a Quartz ``WindowInfo`` to its owning native AX window."""
try:
from AppKit import NSWorkspace # type: ignore[import-not-found] # noqa: PLC0415
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementCreateApplication,
)
except (ImportError, ModuleNotFoundError) as exc:
return None, f"macOS window APIs are unavailable: {exc}"
pid = 0
catalog_match = False
matched_entry: dict | None = None
title_key = (win.title or "").strip().casefold()
for entry in _quartz_window_list(on_screen_only=False):
try:
number = int(entry.get("kCGWindowNumber", 0) or 0)
title = _macos_window_title(entry).strip().casefold()
except (TypeError, ValueError):
continue
if (win.handle and number == int(win.handle)) or (
not win.handle and title_key and title == title_key
):
catalog_match = True
pid = _macos_window_pid(entry)
matched_entry = entry
break
if win.handle and not catalog_match:
return None, "The requested macOS window no longer exists."
if not pid:
try:
app = NSWorkspace.sharedWorkspace().frontmostApplication()
pid = int(app.processIdentifier()) if app is not None else 0
except Exception: # noqa: BLE001
pid = 0
if not pid:
return None, "The macOS window has no owning process identifier."
root = AXUIElementCreateApplication(pid)
windows = list(_macos_ax_attr(root, "AXWindows") or [])
target = (
_select_macos_ax_window(
windows,
matched_entry,
title_equals=title_key,
)
if matched_entry is not None
else None
)
if target is None and matched_entry is None and len(windows) == 1:
target = windows[0]
if target is None:
return None, "The matching macOS AX window is unavailable or ambiguous."
return target, ""
def _window_is_maximized_macos(win: WindowInfo) -> bool | None:
# A background READ: a silent check, never a prompt (None = cannot be read).
if not _macos_accessibility_granted():
return None
target, _error = _resolve_macos_ax_window(win)
if target is None:
return None
full_screen = _macos_ax_attr(target, "AXFullScreen")
if full_screen is not None and bool(full_screen):
return True
zoomed = _macos_ax_attr(target, "AXZoomed")
if zoomed is not None:
return bool(zoomed)
return None if full_screen is None else bool(full_screen)
def window_is_maximized(win: WindowInfo) -> bool | None:
"""Whether the window is maximized; ``None`` when it cannot be read."""
try:
platform_name = detect_platform()
if platform_name == "darwin":
return _window_is_maximized_macos(win)
if platform_name != "win32" or not win.handle:
return None
import ctypes # noqa: PLC0415
from ctypes import wintypes # noqa: PLC0415
class _WINDOWPLACEMENT(ctypes.Structure):
_fields_ = [
("length", wintypes.UINT), ("flags", wintypes.UINT),
("showCmd", wintypes.UINT), ("ptMinPosition", wintypes.POINT),
("ptMaxPosition", wintypes.POINT),
("rcNormalPosition", wintypes.RECT),
]
_SW_SHOWMAXIMIZED = 3
wp = _WINDOWPLACEMENT()
wp.length = ctypes.sizeof(_WINDOWPLACEMENT)
user32 = _win32_user32()
_configure_window_query_api(user32, ctypes, wintypes)
if not user32.GetWindowPlacement(int(win.handle), ctypes.byref(wp)):
return None
return wp.showCmd == _SW_SHOWMAXIMIZED
except Exception: # noqa: BLE001
log.debug("window_is_maximized failed", exc_info=True)
return None
def _maximize_window_macos(win: WindowInfo) -> tuple[bool, str]:
"""Set the native AXZoomed attribute without Apple Events automation."""
# Maximizing is an ACTION: the first one asks macOS for Accessibility.
denied = _macos_window_control_refusal()
if denied:
return False, denied
try:
from ApplicationServices import ( # type: ignore[import-not-found] # noqa: PLC0415
AXUIElementSetAttributeValue,
)
except (ImportError, ModuleNotFoundError) as exc:
return False, f"macOS window APIs are unavailable: {exc}"
target, error = _resolve_macos_ax_window(win)
if target is None:
return False, error
error = AXUIElementSetAttributeValue(target, "AXZoomed", True)
if error != 0:
return False, (
"macOS Accessibility could not zoom this window; it may be a "
"fixed-size dialog or not expose AXZoomed."
)
return True, f"zoomed '{(win.title or 'window')[:40]}' to fill its display"
def maximize_window(win: WindowInfo) -> tuple[bool, str]:
"""Maximize ``win`` ON ITS CURRENT monitor (never a cross-monitor move —
moving across a DPI boundary is what shrinks/mangles windows).
Windows: only windows that advertise a maximize box are touched — a fixed
dialog ("Save as…") must never be blown up. macOS/Linux-X11 are
best-effort; Wayland/headless refuse honestly. Returns ``(ok, message)``,
never raises.
"""
try:
plat = detect_platform()
if plat == "win32":
if not win.handle:
return False, "no window handle to maximize"
import ctypes # noqa: PLC0415
user32 = _win32_user32()
hwnd = int(win.handle)
_GWL_STYLE, _WS_MAXIMIZEBOX = -16, 0x00010000
_SW_MAXIMIZE = 3
from ctypes import wintypes # noqa: PLC0415
_configure_window_query_api(user32, ctypes, wintypes)
style = int(user32.GetWindowLongW(hwnd, _GWL_STYLE))
if not style & _WS_MAXIMIZEBOX:
return False, "window has no maximize box (fixed-size dialog)"
user32.ShowWindow(hwnd, _SW_MAXIMIZE)
return True, f"maximized '{(win.title or 'window')[:40]}'"
if plat == "darwin":
return _maximize_window_macos(win)
if plat == "linux":
if is_wayland() or not display_present():
return False, "cannot maximize on Wayland/headless"
if shutil.which("wmctrl") is None:
return False, "wmctrl not installed"
res = subprocess.run(
["wmctrl", "-r", (win.title or ""),
"-b", "add,maximized_vert,maximized_horz"],
capture_output=True, timeout=5.0,
creationflags=NO_WINDOW_CREATIONFLAGS,
)
if res.returncode != 0:
return False, "wmctrl could not maximize the window"
return True, f"maximized '{(win.title or 'window')[:40]}' (X11)"
return False, f"maximize not supported on {plat}"
except Exception as exc: # noqa: BLE001
log.debug("maximize_window failed", exc_info=True)
return False, f"maximize failed: {exc}"
def normalize_foreground_window() -> tuple[bool, str]:
"""Bring the CURRENT foreground window into the state professional
computer-use setups act on: maximized on its own monitor.
Every reference harness normalizes its environment before pixel-grounded
clicking (OpenAI CUA: fixed viewport; Anthropic: one small display with
the app filling it; Microsoft UFO: per-application scope). On a live
desktop the equivalent is "the target window fills its monitor": a small
floating window on a 4K screen turns into stamp-sized UI in the model's
downscaled frame, and every grounding error lands on the wallpaper
(live incident 2026-07-02: three clicks in a row hit the desktop next
to a restored Chrome and stole its focus).
Shell windows and windows that cannot maximize are left untouched.
Synchronous — CU calls it via ``asyncio.to_thread``. Never raises.
"""
try:
win = foreground_window()
if win is None:
return False, "no foreground window"
if is_shell_window(win):
return False, "foreground is the desktop shell"
if window_is_maximized(win) is not False:
return False, "already maximized (or unknown state)"
return maximize_window(win)
except Exception as exc: # noqa: BLE001
log.debug("normalize_foreground_window failed", exc_info=True)
return False, f"normalize failed: {exc}"
def _move_to_primary_linux(win: WindowInfo, primary: dict) -> tuple[bool, str]:
"""Best-effort X11 move via ``wmctrl`` (un-maximize, then reposition by title).
Unverified on a real desktop; returns honest status."""
import subprocess # noqa: PLC0415
from dodaios.core.process_utils import NO_WINDOW_CREATIONFLAGS # noqa: PLC0415
title = (win.title or "").strip()
if not title:
return False, "no window title to target"
px, py = int(primary.get("left", 0)), int(primary.get("top", 0))
try:
subprocess.run(
["wmctrl", "-r", title, "-b", "remove,maximized_vert,maximized_horz"],
capture_output=True, timeout=3.0, creationflags=NO_WINDOW_CREATIONFLAGS,
)
res = subprocess.run(
["wmctrl", "-r", title, "-e", f"0,{px},{py},-1,-1"],
capture_output=True, timeout=3.0, creationflags=NO_WINDOW_CREATIONFLAGS,
)
except FileNotFoundError:
return False, "wmctrl not installed — cannot move the window on X11"
except Exception as exc: # noqa: BLE001
return False, f"wmctrl move failed: {exc}"
if res.returncode != 0:
return False, f"wmctrl could not find/move a window titled '{title[:40]}'"
return True, f"moved '{title[:40]}' onto the primary monitor (X11/wmctrl)"
__all__ = [
"WindowInfo",
"list_windows",
"get_foreground_title",
"focus_window",
"raise_window",
"is_app_running",
"raise_after_launch",
"window_is_on_monitor",
"window_rect",
"foreground_window",
"move_window_to_primary",
]