AutoMonkey 0.4.1__py3-none-any.whl

automonkey/ai/screen.py

@@ -0,0 +1,202 @@
+"""Screen capture, coordinate mapping and change detection for AI agents.
+
+Three coordinate spaces exist:
+  * capture pixels - what the screenshot backend returns (physical pixels)
+  * input pixels   - what pyautogui uses for mouse moves
+  * image pixels   - the downscaled screenshot the AI actually looks at
+
+The AI only ever deals with *image pixels*. Everything here converts for it.
+"""
+from __future__ import annotations
+
+import io
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+import numpy as np
+import pyautogui
+from PIL import Image, ImageDraw, ImageFont
+
+DEFAULT_MAX_SIDE = int(os.environ.get("AUTOMONKEY_AI_MAX_SIDE", "1280"))
+
+
+def session_type() -> str:
+    """'wayland', 'x11', 'win32' or 'darwin'."""
+    if sys.platform.startswith("linux"):
+        return "wayland" if os.environ.get("WAYLAND_DISPLAY") else "x11"
+    return sys.platform
+
+
+def grab() -> Image.Image:
+    """Full-resolution RGB screenshot. Uses grim on Wayland, pyautogui elsewhere."""
+    if session_type() == "wayland" and shutil.which("grim"):
+        # Capturing full size and resizing in PIL is ~3x faster than `grim -s`.
+        out = subprocess.run(["grim", "-t", "ppm", "-"], capture_output=True, check=True).stdout
+        return Image.open(io.BytesIO(out)).convert("RGB")
+    return pyautogui.screenshot().convert("RGB")
+
+
+class View:
+    """Maps between image pixels (what the AI sees) and input pixels (pyautogui)."""
+
+    def __init__(self, capture_size: tuple[int, int], max_side: int = DEFAULT_MAX_SIDE):
+        self.capture_w, self.capture_h = capture_size
+        self.input_w, self.input_h = pyautogui.size()
+        self.scale = min(1.0, max_side / max(self.capture_w, self.capture_h))
+        self.image_w = round(self.capture_w * self.scale)
+        self.image_h = round(self.capture_h * self.scale)
+
+    def to_input(self, x: float, y: float) -> tuple[int, int]:
+        return (round(x * self.input_w / self.image_w), round(y * self.input_h / self.image_h))
+
+    def to_image(self, x: float, y: float) -> tuple[int, int]:
+        return (round(x * self.image_w / self.input_w), round(y * self.image_h / self.input_h))
+
+    def capture_to_image(self, x: float, y: float) -> tuple[int, int]:
+        return (round(x * self.scale), round(y * self.scale))
+
+    def describe(self) -> str:
+        return f"image {self.image_w}x{self.image_h} (screen {self.input_w}x{self.input_h})"
+
+
+_view: View | None = None
+
+
+def view() -> View:
+    """The current coordinate mapping (created from a fresh capture if needed)."""
+    global _view
+    if _view is None:
+        _view = View(grab().size)
+    return _view
+
+
+def _font(size: int):
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:  # Pillow < 10.1
+        return ImageFont.load_default()
+
+
+def draw_grid(img: Image.Image, step: int, origin: tuple[int, int] = (0, 0), unit: float = 1.0) -> Image.Image:
+    """Overlay a labelled grid. Labels are in image coordinates of the full view,
+    so `origin` and `unit` let zoomed crops show the same numbers as the full shot."""
+    img = img.convert("RGBA")
+    layer = Image.new("RGBA", img.size, (0, 0, 0, 0))
+    d = ImageDraw.Draw(layer)
+    font = _font(11)
+    ox, oy = origin
+    first_x = (-ox) % step
+    for vx in range(ox + first_x, ox + int(img.width / unit) + 1, step):
+        px = round((vx - ox) * unit)
+        d.line([(px, 0), (px, img.height)], fill=(255, 0, 255, 90), width=1)
+        d.text((px + 2, 2), str(vx), fill=(255, 0, 255, 255), font=font, stroke_width=2, stroke_fill=(0, 0, 0, 255))
+    first_y = (-oy) % step
+    for vy in range(oy + first_y, oy + int(img.height / unit) + 1, step):
+        py = round((vy - oy) * unit)
+        d.line([(0, py), (img.width, py)], fill=(255, 0, 255, 90), width=1)
+        d.text((2, py + 2), str(vy), fill=(255, 0, 255, 255), font=font, stroke_width=2, stroke_fill=(0, 0, 0, 255))
+    return Image.alpha_composite(img, layer).convert("RGB")
+
+
+def draw_mouse(img: Image.Image, at: tuple[int, int], radius: int = 7) -> Image.Image:
+    """Mark the mouse position with a red ring (screenshots don't include the cursor)."""
+    d = ImageDraw.Draw(img)
+    x, y = at
+    d.ellipse([x - radius, y - radius, x + radius, y + radius], outline=(255, 0, 0), width=2)
+    return img
+
+
+def shot(grid: int = 0, max_side: int = DEFAULT_MAX_SIDE, show_mouse: bool = True,
+         full: Image.Image | None = None) -> Image.Image:
+    """Screenshot scaled for the AI. All coordinates the AI reads off it are valid input."""
+    global _view
+    full = full or grab()
+    _view = View(full.size, max_side)
+    img = full.resize((_view.image_w, _view.image_h), Image.LANCZOS) if _view.scale < 1 else full
+    if show_mouse:
+        img = draw_mouse(img, _view.to_image(*pyautogui.position()))
+    if grid:
+        img = draw_grid(img, grid)
+    return img
+
+
+def zoom(x: int, y: int, w: int, h: int, grid: int = 0) -> Image.Image:
+    """Full-resolution crop of an image-coordinate region, enlarged for reading
+    small text. Grid labels (if any) are in the same image coordinates."""
+    v = view()
+    full = grab()
+    s = 1 / v.scale
+    box = (round(x * s), round(y * s), round((x + w) * s), round((y + h) * s))
+    crop = full.crop(box)
+    factor = max(1.0, min(4.0, 800 / max(crop.width, crop.height, 1)))
+    crop = crop.resize((round(crop.width * factor), round(crop.height * factor)), Image.LANCZOS)
+    if grid:
+        crop = draw_grid(crop, grid, origin=(x, y), unit=crop.width / max(w, 1))
+    return crop
+
+
+def to_png(img: Image.Image) -> bytes:
+    buf = io.BytesIO()
+    img.save(buf, format="PNG", optimize=False, compress_level=1)
+    return buf.getvalue()
+
+
+# --- change detection -------------------------------------------------------
+
+def _small(img: Image.Image) -> np.ndarray:
+    return np.asarray(img.resize((img.width // 8, img.height // 8), Image.NEAREST).convert("L"), dtype=np.int16)
+
+
+def changed_fraction(a: np.ndarray, b: np.ndarray, threshold: int = 24) -> float:
+    if a.shape != b.shape:
+        return 1.0
+    return float((np.abs(a - b) > threshold).mean())
+
+
+# A blinking text caret or a spinner changes ~0.05% of the screen; ignore that.
+NOISE = 0.002
+
+
+def wait_stable(stable_for: float = 1.0, timeout: float = 15.0, poll: float = 0.15) -> tuple[bool, float]:
+    """Wait until the screen stops changing. Returns (stable?, seconds waited)."""
+    start = time.monotonic()
+    last = _small(grab())
+    same_since = time.monotonic()
+    while time.monotonic() - start < timeout:
+        time.sleep(poll)
+        cur = _small(grab())
+        if changed_fraction(last, cur) > NOISE:
+            last, same_since = cur, time.monotonic()
+        elif time.monotonic() - same_since >= stable_for:
+            return True, time.monotonic() - start
+    return False, time.monotonic() - start
+
+
+def wait_change(baseline: Image.Image | None = None, timeout: float = 15.0, poll: float = 0.15) -> tuple[bool, float]:
+    """Wait until the screen differs from `baseline` (default: now)."""
+    start = time.monotonic()
+    base = _small(baseline or grab())
+    while time.monotonic() - start < timeout:
+        time.sleep(poll)
+        if changed_fraction(base, _small(grab())) > NOISE:
+            return True, time.monotonic() - start
+    return False, time.monotonic() - start
+
+
+def diff_summary(before: Image.Image, after: Image.Image) -> str:
+    """Human/AI readable description of what changed, in image coordinates."""
+    a, b = _small(before), _small(after)
+    if a.shape != b.shape:
+        return "screen size changed"
+    mask = np.abs(a - b) > 24
+    frac = float(mask.mean())
+    if frac <= NOISE:
+        return "screen did NOT change"
+    ys, xs = np.nonzero(mask)
+    v = view()
+    x0, y0 = v.capture_to_image(xs.min() * 8, ys.min() * 8)
+    x1, y1 = v.capture_to_image((xs.max() + 1) * 8, (ys.max() + 1) * 8)
+    return f"screen changed: {frac:.0%} of pixels, region x={x0}..{x1} y={y0}..{y1}"

automonkey/ai/script.py

@@ -0,0 +1,190 @@
+"""A tiny action language so an AI can do many steps in ONE tool call.
+
+One command per line (or separated by ';'; write '\\;' for a literal ';').
+Coordinates are image pixels of the latest screenshot.
+
+    click X Y [left|right|middle] [N]   dclick X Y    rclick X Y    move X Y
+    drag X1 Y1 X2 Y2                    scroll N [X Y]   (N>0 up, N<0 down)
+    type TEXT...                        key K [K...]     hotkey ctrl+shift+t
+    wait SECONDS                        stable [TIMEOUT]   change [TIMEOUT]
+    launch COMMAND...                   focus WINDOW     maximize [WINDOW]   close WINDOW
+    url ADDRESS                         (focus address bar, type, Enter, wait for load)
+    click_text TEXT...                  wait_text TEXT...   (OCR, needs tesseract)
+    click_image PATH                    (template match)
+    press [BUTTON]                      release [BUTTON]
+    path X1 Y1 X2 Y2 ...                (freehand: press, glide through every point, release)
+"""
+from __future__ import annotations
+
+import re
+import time
+
+import pyautogui
+
+from . import ocr, screen, windows
+from ..key_funcs import hotkey, press, write
+
+pyautogui.PAUSE = 0.03  # default 0.1s per call adds up quickly
+
+INPUT_COMMANDS = {"click", "dclick", "rclick", "move", "drag", "scroll", "type", "key", "hotkey",
+                  "url", "click_text", "click_image", "press", "release", "path"}
+
+
+class StepError(Exception):
+    pass
+
+
+def split_script(script: str) -> list[str]:
+    lines = []
+    for raw in script.splitlines():
+        for part in re.split(r"(?<!\\);", raw):
+            part = part.replace("\\;", ";").strip()
+            if part and not part.startswith("#"):
+                lines.append(part)
+    return lines
+
+
+def _xy(args: list[str], i: int = 0) -> tuple[int, int]:
+    try:
+        return screen.view().to_input(float(args[i]), float(args[i + 1]))
+    except (IndexError, ValueError):
+        raise StepError("expected X Y coordinates")
+
+
+def _keys(spec: str) -> list[str]:
+    return [k.strip().lower() for k in re.split(r"[+\s]+", spec) if k.strip()]
+
+
+def _click_text(text: str):
+    hits = ocr.find_text(text)
+    if not hits:
+        raise StepError(f"text {text!r} not found on screen")
+    h = hits[0]
+    pyautogui.click(*screen.view().to_input(h["cx"], h["cy"]))
+    return f"clicked {h['text']!r} at {h['cx']},{h['cy']}" + (f" ({len(hits)} matches)" if len(hits) > 1 else "")
+
+
+def run_step(line: str) -> str:
+    cmd, _, rest = line.partition(" ")
+    cmd = cmd.lower()
+    args = rest.split()
+    if cmd == "click":
+        x, y = _xy(args)
+        button = args[2] if len(args) > 2 else "left"
+        clicks = int(args[3]) if len(args) > 3 else 1
+        pyautogui.click(x, y, clicks=clicks, interval=0.05, button=button)
+    elif cmd == "dclick":
+        pyautogui.doubleClick(*_xy(args))
+    elif cmd == "rclick":
+        pyautogui.rightClick(*_xy(args))
+    elif cmd == "move":
+        pyautogui.moveTo(*_xy(args))
+    elif cmd == "drag":
+        x1, y1 = _xy(args)
+        x2, y2 = _xy(args, 2)
+        pyautogui.moveTo(x1, y1)
+        pyautogui.dragTo(x2, y2, duration=0.4, button="left")
+    elif cmd == "press":
+        pyautogui.mouseDown(button=args[0] if args else "left")
+    elif cmd == "release":
+        pyautogui.mouseUp(button=args[0] if args else "left")
+    elif cmd == "path":
+        if len(args) < 4 or len(args) % 2:
+            raise StepError("path needs an even number of X Y values (at least two points)")
+        pts = [_xy(args, i) for i in range(0, len(args), 2)]
+        pyautogui.moveTo(*pts[0])
+        pyautogui.mouseDown()
+        try:
+            for p in pts[1:]:
+                pyautogui.moveTo(*p, duration=0.02)
+        finally:
+            pyautogui.mouseUp()
+        return f"drew through {len(pts)} points"
+    elif cmd == "scroll":
+        if len(args) >= 3:
+            pyautogui.moveTo(*_xy(args, 1))
+        pyautogui.scroll(int(args[0]))
+    elif cmd == "type":
+        write(rest)
+    elif cmd == "key":
+        press(args)
+    elif cmd == "hotkey":
+        hotkey(*_keys(rest))
+    elif cmd == "wait":
+        time.sleep(float(args[0]) if args else 1.0)
+    elif cmd == "stable":
+        ok, t = screen.wait_stable(timeout=float(args[0]) if args else 15)
+        return f"stable after {t:.1f}s" if ok else f"still changing after {t:.1f}s"
+    elif cmd == "change":
+        ok, t = screen.wait_change(timeout=float(args[0]) if args else 15)
+        return f"changed after {t:.1f}s" if ok else f"no change within {t:.1f}s"
+    elif cmd == "url":
+        hotkey("ctrl", "l")
+        time.sleep(0.15)
+        write(rest)
+        time.sleep(0.3)  # let the address bar's suggestion list catch up before Enter
+        before = screen.grab()  # after typing, so the typed text alone doesn't count as "loaded"
+        press("enter")
+        changed, _ = screen.wait_change(before, timeout=30)
+        if not changed:
+            return "no visible change 30s after Enter (still loading, or not navigated)"
+        ok, t = screen.wait_stable(timeout=20)
+        return f"loaded{'' if ok else ' (still changing)'}"
+    elif cmd == "launch":
+        w = windows.launch(rest)
+        windows.focus(w["id"])
+        screen.wait_stable(timeout=20)
+        return f"window {w['id']} {w['title']!r}"
+    elif cmd == "focus":
+        w = windows.focus(rest)
+        return f"focused {w['title']!r}"
+    elif cmd == "maximize":
+        w = windows.maximize(rest or None)
+        screen.wait_stable(stable_for=0.5, timeout=5)
+        return f"maximized {w['title']!r}"
+    elif cmd == "close":
+        w = windows.close(rest)
+        return f"closed {w['title']!r}"
+    elif cmd == "click_text":
+        return _click_text(rest)
+    elif cmd == "wait_text":
+        deadline = time.monotonic() + 20
+        while time.monotonic() < deadline:
+            if ocr.find_text(rest):
+                return "text appeared"
+            time.sleep(0.5)
+        raise StepError(f"text {rest!r} did not appear within 20s")
+    elif cmd == "click_image":
+        box = pyautogui.locate(rest, screen.grab(), grayscale=True)
+        if not box:
+            raise StepError(f"image {rest!r} not found on screen")
+        cx, cy = screen.view().capture_to_image(box.left + box.width / 2, box.top + box.height / 2)
+        pyautogui.click(*screen.view().to_input(cx, cy))
+        return f"clicked image at {cx},{cy}"
+    else:
+        raise StepError(f"unknown command {cmd!r}")
+    return "ok"
+
+
+def run(script: str, settle: bool = True) -> tuple[list[str], bool]:
+    """Run every step, stopping at the first failure. Returns (log, success).
+    With `settle`, waits for the screen to stop changing after input steps."""
+    log, steps = [], split_script(script)
+    for n, line in enumerate(steps, 1):
+        t0 = time.monotonic()
+        try:
+            result = run_step(line)
+            log.append(f"{n}. {line} -> {result} ({time.monotonic() - t0:.1f}s)")
+        except pyautogui.FailSafeException:
+            log.append(f"{n}. {line} -> ABORTED: mouse in a screen corner (pyautogui fail-safe)")
+            return log, False
+        except Exception as e:  # report and stop; the AI decides what to do next
+            log.append(f"{n}. {line} -> FAILED: {e}")
+            if n < len(steps):
+                log.append(f"   skipped {len(steps) - n} remaining step(s)")
+            return log, False
+    last = steps[-1].split()[0].lower() if steps else ""
+    if settle and last in INPUT_COMMANDS:
+        ok, t = screen.wait_stable(stable_for=0.6, timeout=10)
+        log.append(f"settled in {t:.1f}s" if ok else f"screen still changing after {t:.1f}s")
+    return log, True

automonkey/ai/windows.py

@@ -0,0 +1,185 @@
+"""Launching apps and finding / focusing windows.
+
+Linux uses xdotool + wmctrl. On Wayland, pyautogui input only reaches X11
+(XWayland) windows, so `launch` forces apps onto X11 automatically.
+"""
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+import time
+
+from .screen import session_type
+
+# Env vars that make common toolkits use X11 instead of native Wayland.
+X11_ENV = {
+    "MOZ_ENABLE_WAYLAND": "0",           # Firefox / Thunderbird
+    "GDK_BACKEND": "x11",                # GTK
+    "QT_QPA_PLATFORM": "xcb",            # Qt
+    "SDL_VIDEODRIVER": "x11",            # SDL
+    "ELECTRON_OZONE_PLATFORM_HINT": "x11",
+}
+FIREFOX_LIKE = ("firefox", "firefox-esr", "thunderbird")
+CHROMIUM_LIKE = ("chromium", "chromium-browser", "google-chrome", "chrome", "code", "brave-browser")
+
+
+def _run(*args: str) -> str:
+    return subprocess.run(args, capture_output=True, text=True).stdout
+
+
+def _require_linux_tools():
+    missing = [t for t in ("xdotool", "wmctrl") if not shutil.which(t)]
+    if missing:
+        raise RuntimeError(f"missing tools: {', '.join(missing)} (sudo apt install {' '.join(missing)})")
+
+
+def list_windows() -> list[dict]:
+    """Visible top-level windows: id, title, wm_class, x, y, w, h, active."""
+    if sys.platform == "win32":
+        import pygetwindow as gw
+        active = gw.getActiveWindow()
+        return [dict(id=w._hWnd, title=w.title, wm_class="", x=w.left, y=w.top, w=w.width, h=w.height,
+                     active=active is not None and w._hWnd == active._hWnd)
+                for w in gw.getAllWindows() if w.title and w.visible]
+    _require_linux_tools()
+    active = _run("xdotool", "getactivewindow").strip()
+    wins = []
+    for line in _run("wmctrl", "-lGx").splitlines():
+        parts = line.split(None, 8)
+        if len(parts) < 8:
+            continue
+        wid, _desk, x, y, w, h, wm_class = parts[:7]
+        title = parts[8] if len(parts) > 8 else ""
+        wins.append(dict(id=int(wid, 16), title=title, wm_class=wm_class, x=int(x), y=int(y),
+                         w=int(w), h=int(h), active=active.isdigit() and int(active) == int(wid, 16)))
+    return wins
+
+
+def find_window(query: str | int) -> dict:
+    """Window whose id equals `query`, or whose title / class contains it (case-insensitive)."""
+    wins = list_windows()
+    if isinstance(query, int) or str(query).isdigit():
+        for w in wins:
+            if w["id"] == int(query):
+                return w
+    q = str(query).lower()
+    matches = [w for w in wins if q in w["title"].lower() or q in w["wm_class"].lower()]
+    if not matches:
+        titles = "; ".join(w["title"] for w in wins) or "none"
+        raise LookupError(f"no window matching {query!r}. Open windows: {titles}")
+    return next((w for w in matches if w["active"]), matches[-1])
+
+
+def focus(query: str | int) -> dict:
+    w = find_window(query)
+    if sys.platform == "win32":
+        import pygetwindow as gw
+        gw.Win32Window(w["id"]).activate()
+    else:
+        subprocess.run(["xdotool", "windowactivate", "--sync", str(w["id"])], capture_output=True, timeout=5)
+    time.sleep(0.2)
+    return w
+
+
+def maximize(query: str | int | None = None) -> dict:
+    w = find_window(query) if query is not None else active_window()
+    if sys.platform == "win32":
+        import pygetwindow as gw
+        gw.Win32Window(w["id"]).maximize()
+    else:
+        subprocess.run(["wmctrl", "-i", "-r", hex(w["id"]), "-b", "add,maximized_vert,maximized_horz"],
+                       capture_output=True)
+    time.sleep(0.5)
+    return find_window(w["id"])
+
+
+def close(query: str | int) -> dict:
+    w = find_window(query)
+    if sys.platform == "win32":
+        import pygetwindow as gw
+        gw.Win32Window(w["id"]).close()
+    else:
+        subprocess.run(["wmctrl", "-i", "-c", hex(w["id"])], capture_output=True)
+    return w
+
+
+def active_window() -> dict:
+    for w in list_windows():
+        if w["active"]:
+            return w
+    raise LookupError("no active window")
+
+
+PROFILE_DIR = os.path.join(os.path.expanduser("~"), ".cache", "automonkey", "profiles")
+
+# Quiet automation profile: no first-run tabs, default-browser nags or translation popups.
+FIREFOX_PREFS = """\
+user_pref("browser.aboutwelcome.enabled", false);
+user_pref("browser.shell.checkDefaultBrowser", false);
+user_pref("browser.startup.homepage_override.mstone", "ignore");
+user_pref("startup.homepage_welcome_url", "");
+user_pref("startup.homepage_welcome_url.additional", "");
+user_pref("datareporting.policy.dataSubmissionPolicyBypassNotification", true);
+user_pref("datareporting.policy.firstRunURL", "");
+user_pref("toolkit.telemetry.reportingpolicy.firstRun", false);
+user_pref("browser.translations.automaticallyPopup", false);
+user_pref("browser.translations.panelShown", true);
+user_pref("browser.tabs.warnOnClose", false);
+user_pref("browser.sessionstore.resume_from_crash", false);
+"""
+
+
+def _separate_browser_instance(args: list[str]) -> list[str]:
+    """Browsers hand a launch over to an already running instance of the same profile.
+    If the user's own browser runs as a native Wayland window, our window would end
+    up there and be uncontrollable, so use a dedicated automation profile instead.
+    Relaunching later reuses that (X11) instance, which is what we want."""
+    name = os.path.basename(args[0])
+    if name in FIREFOX_LIKE and not {"-P", "--profile", "-profile"} & set(args):
+        path = os.path.join(PROFILE_DIR, name)
+        os.makedirs(path, exist_ok=True)
+        user_js = os.path.join(path, "user.js")
+        if not os.path.exists(user_js):
+            with open(user_js, "w", encoding="utf-8") as f:
+                f.write(FIREFOX_PREFS)
+        return [args[0], "--profile", path, *args[1:]]
+    if name in CHROMIUM_LIKE:
+        extra = ["--ozone-platform=x11"]
+        if not any(a.startswith("--user-data-dir") for a in args):
+            path = os.path.join(PROFILE_DIR, name)
+            os.makedirs(path, exist_ok=True)
+            extra.append(f"--user-data-dir={path}")
+        return [args[0], *extra, *args[1:]]
+    return args
+
+
+def launch(command: str, timeout: float = 60.0) -> dict:
+    """Start `command` detached and return its first new window once it is visible."""
+    before = {w["id"] for w in list_windows()}
+    args = shlex.split(command)
+    env = dict(os.environ)
+    if session_type() == "wayland":
+        env.update(X11_ENV)
+        args = _separate_browser_instance(args)
+    kwargs = dict(stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, env=env)
+    if sys.platform == "win32":
+        kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kwargs["start_new_session"] = True
+    subprocess.Popen(args, **kwargs)
+    start = time.monotonic()
+    while time.monotonic() - start < timeout:
+        new = [w for w in list_windows() if w["id"] not in before]
+        if new:
+            return new[-1]
+        time.sleep(0.3)
+    raise TimeoutError(f"no new window appeared within {timeout:.0f}s after launching {command!r} "
+                       f"(on Wayland the app may have opened as a native window that can't be controlled)")
+
+
+def format_windows(wins: list[dict]) -> str:
+    return "\n".join(f"{'*' if w['active'] else ' '} {w['id']:>10}  {w['wm_class'][:30]:<30} {w['title']}"
+                     for w in wins) or "no windows"