hypruse 0.1.0__py3-none-any.whl

hypruse/__init__.py

@@ -0,0 +1,3 @@
+"""hypruse — computer use for Hyprland over MCP."""
+
+__version__ = "0.1.0"

hypruse/__main__.py

@@ -0,0 +1,3 @@
+from hypruse.server import main
+
+main()

hypruse/hyprctl.py

@@ -0,0 +1,125 @@
+"""Thin layer over Hyprland's hyprctl IPC.
+
+Everything hypruse knows about the desktop comes through here, and every
+workspace/window action goes back out through dispatch(). It shells out to
+the hyprctl binary rather than opening the .socket directly so behaviour
+always matches what the user's own shell would do.
+
+Coordinates everywhere in hypruse are Hyprland's global *logical* layout
+coordinates — the same space `hyprctl cursorpos`, client `at`, and
+`dispatch movecursor` use.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+
+class HyprctlError(RuntimeError):
+    """hyprctl failed, returned an error, or is unreachable."""
+
+
+def _run(*args: str) -> str:
+    if shutil.which("hyprctl") is None:
+        raise HyprctlError("hyprctl not found — hypruse needs a running Hyprland session")
+    try:
+        proc = subprocess.run(
+            ["hyprctl", *args], capture_output=True, text=True, timeout=5
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise HyprctlError(f"hyprctl {' '.join(args)} timed out") from exc
+    out = proc.stdout.strip()
+    if proc.returncode != 0:
+        raise HyprctlError(f"hyprctl {' '.join(args)}: {proc.stderr.strip() or out}")
+    return out
+
+
+def query(command: str) -> Any:
+    """Run a JSON query: monitors, workspaces, clients, activewindow, cursorpos, ..."""
+    out = _run("-j", command)
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise HyprctlError(f"unparseable hyprctl -j {command} output: {out[:200]!r}") from exc
+
+
+def dispatch(name: str, *args: str) -> None:
+    """Run a dispatcher; Hyprland answers 'ok' on success, an error string otherwise."""
+    out = _run("dispatch", name, *args)
+    if out != "ok":
+        raise HyprctlError(f"dispatch {name} {' '.join(args)}: {out}")
+
+
+def cursor_pos() -> tuple[int, int]:
+    pos = query("cursorpos")
+    return int(pos["x"]), int(pos["y"])
+
+
+def _window(c: dict[str, Any]) -> dict[str, Any]:
+    """Trim a hyprctl client to what a model needs to reason and act."""
+    win: dict[str, Any] = {
+        "address": c["address"],
+        "workspace": c.get("workspace", {}).get("id"),
+        "class": c.get("class", ""),
+        "title": c.get("title", ""),
+        "at": c.get("at"),
+        "size": c.get("size"),
+        "floating": c.get("floating", False),
+        "pid": c.get("pid"),
+    }
+    # int enum since Hyprland 0.42 (0 none / 1 maximized / 2 fullscreen), bool before
+    if c.get("fullscreen"):
+        win["fullscreen"] = True
+    if c.get("hidden"):
+        win["hidden"] = True
+    return win
+
+
+def snapshot_from(
+    monitors: list[dict[str, Any]],
+    workspaces: list[dict[str, Any]],
+    clients: list[dict[str, Any]],
+    active_window: dict[str, Any] | None,
+    cursor: tuple[int, int] | None,
+) -> dict[str, Any]:
+    """Pure assembly of the desktop state — separated from IPC for testability."""
+    visible = {m.get("activeWorkspace", {}).get("id") for m in monitors}
+    return {
+        "monitors": [
+            {
+                "name": m["name"],
+                "geometry": [m["x"], m["y"], m["width"], m["height"]],
+                "scale": m.get("scale", 1.0),
+                "focused": m.get("focused", False),
+                "active_workspace": m.get("activeWorkspace", {}).get("id"),
+            }
+            for m in monitors
+        ],
+        "workspaces": [
+            {
+                "id": w["id"],
+                "name": w.get("name", ""),
+                "monitor": w.get("monitor", ""),
+                "windows": w.get("windows", 0),
+                "visible": w["id"] in visible,
+            }
+            for w in sorted(workspaces, key=lambda w: w["id"])
+        ],
+        "windows": [_window(c) for c in clients if c.get("mapped", True)],
+        "active_window": (active_window or {}).get("address"),
+        "cursor": list(cursor) if cursor else None,
+    }
+
+
+def snapshot() -> dict[str, Any]:
+    """Compact, token-lean view of the whole desktop."""
+    return snapshot_from(
+        query("monitors"),
+        query("workspaces"),
+        query("clients"),
+        query("activewindow") or None,
+        cursor_pos(),
+    )

hypruse/input.py

@@ -0,0 +1,199 @@
+"""Synthetic input.
+
+Pointer: positioning goes through `hyprctl dispatch movecursor` (global
+logical coordinates, authoritative on any monitor layout); only button and
+axis events go through the virtual-pointer wire client. This split
+sidesteps the known multi-monitor mapping bugs of absolute virtual-pointer
+motion (hyprwm/Hyprland#6749).
+
+Keyboard: wtype, which uploads its own XKB keymap over
+zwp_virtual_keyboard_v1 — text lands layout-correct including unicode,
+with no uinput scancode guessing.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import time
+from collections.abc import Callable
+from typing import Any
+
+from hypruse import hyprctl
+from hypruse.wire import BUTTONS, PRESSED, RELEASED, VirtualPointer, WireError
+
+
+class InputError(RuntimeError):
+    """Invalid input request or missing input backend."""
+
+
+MODS = {
+    "ctrl": "ctrl",
+    "control": "ctrl",
+    "shift": "shift",
+    "alt": "alt",
+    "super": "logo",
+    "meta": "logo",
+    "win": "logo",
+    "cmd": "logo",
+    "altgr": "altgr",
+}
+
+KEY_ALIASES = {
+    "enter": "Return",
+    "return": "Return",
+    "esc": "Escape",
+    "escape": "Escape",
+    "tab": "Tab",
+    "space": "space",
+    "backspace": "BackSpace",
+    "delete": "Delete",
+    "del": "Delete",
+    "insert": "Insert",
+    "home": "Home",
+    "end": "End",
+    "pgup": "Page_Up",
+    "pageup": "Page_Up",
+    "pgdn": "Page_Down",
+    "pagedown": "Page_Down",
+    "up": "Up",
+    "down": "Down",
+    "left": "Left",
+    "right": "Right",
+}
+
+
+def parse_combo(combo: str) -> tuple[list[str], str | None]:
+    """'ctrl+shift+t' → (['ctrl','shift'], 't'); 'super' alone is a bare-mod tap."""
+    parts = [p.strip() for p in combo.split("+") if p.strip()]
+    if not parts:
+        raise InputError("empty key combo")
+    mods: list[str] = []
+    key: str | None = None
+    for i, part in enumerate(parts):
+        lower = part.lower()
+        last = i == len(parts) - 1
+        if lower in MODS:
+            mods.append(MODS[lower])
+            if last:
+                key = None
+        elif not last:
+            raise InputError(f"unknown modifier {part!r} in {combo!r}")
+        elif lower in KEY_ALIASES:
+            key = KEY_ALIASES[lower]
+        elif len(part) == 1:
+            key = part
+        elif lower.startswith("f") and lower[1:].isdigit():
+            key = part.upper()
+        else:
+            key = part  # assume a literal XKB keysym name (case-sensitive)
+    return mods, key
+
+
+def combo_to_wtype_args(mods: list[str], key: str | None) -> list[str]:
+    args: list[str] = []
+    for m in mods:
+        args += ["-M", m]
+    if key:
+        args += ["-k", key]
+    for m in reversed(mods):
+        args += ["-m", m]
+    if not args:
+        raise InputError("combo resolved to nothing")
+    return args
+
+
+def _wtype(args: list[str], stdin: str | None = None) -> None:
+    if shutil.which("wtype") is None:
+        raise InputError("wtype not found — install wtype for keyboard input")
+    proc = subprocess.run(
+        ["wtype", *args], input=stdin, text=True, capture_output=True, timeout=15
+    )
+    if proc.returncode != 0:
+        raise InputError(f"wtype failed: {proc.stderr.strip()}")
+
+
+def type_text(text: str) -> None:
+    if text:
+        _wtype(["-"], stdin=text)  # '-' reads stdin: safe for any content
+
+
+def key_combo(combo: str) -> None:
+    mods, key = parse_combo(combo)
+    _wtype(combo_to_wtype_args(mods, key))
+
+
+# --- pointer ----------------------------------------------------------------
+
+_vp: VirtualPointer | None = None
+
+
+def _with_pointer(fn: Callable[[VirtualPointer], Any]) -> Any:
+    """Run fn with the shared virtual pointer, reconnecting once if stale."""
+    global _vp
+    for attempt in (0, 1):
+        if _vp is None:
+            _vp = VirtualPointer()
+        try:
+            return fn(_vp)
+        except WireError:
+            _vp = None
+            if attempt:
+                raise
+
+
+def _check_button(button: str) -> None:
+    if button not in BUTTONS:
+        raise InputError(f"unknown button {button!r}; one of {sorted(BUTTONS)}")
+
+
+def _check_xy(x: float | None, y: float | None) -> bool:
+    if (x is None) != (y is None):
+        raise InputError("give both x and y, or neither")
+    return x is not None
+
+
+def move(x: float, y: float) -> None:
+    hyprctl.dispatch("movecursor", str(int(round(x))), str(int(round(y))))
+
+
+def click(
+    x: float | None = None,
+    y: float | None = None,
+    button: str = "left",
+    double: bool = False,
+) -> None:
+    _check_button(button)
+    if _check_xy(x, y):
+        move(x, y)  # type: ignore[arg-type]
+        time.sleep(0.02)
+    _with_pointer(lambda p: p.click(button, double=double))
+
+
+def drag(x1: float, y1: float, x2: float, y2: float, button: str = "left") -> None:
+    _check_button(button)
+    move(x1, y1)
+    time.sleep(0.03)
+
+    def run(p: VirtualPointer) -> None:
+        p.button(button, PRESSED)
+        try:
+            steps = 12
+            for i in range(1, steps + 1):
+                move(x1 + (x2 - x1) * i / steps, y1 + (y2 - y1) * i / steps)
+                time.sleep(0.015)
+        finally:
+            p.button(button, RELEASED)
+
+    _with_pointer(run)
+
+
+def scroll(
+    dy: float = 0.0, dx: float = 0.0, x: float | None = None, y: float | None = None
+) -> None:
+    if not dy and not dx:
+        raise InputError("scroll needs a non-zero dy or dx")
+    if _check_xy(x, y):
+        move(x, y)  # type: ignore[arg-type]
+        time.sleep(0.02)
+    _with_pointer(lambda p: p.scroll(dy=dy, dx=dx))

hypruse/safety.py

@@ -0,0 +1,83 @@
+"""Activity beacon and kill-switch support.
+
+The seat — cursor, keyboard focus — is shared between the agent and the
+human at the desk. hypruse therefore keeps a runtime beacon at
+$XDG_RUNTIME_DIR/hypruse/state.json:
+
+    {"pid": 1234, "started": 1789...,
+     "last_action": "pointer:click", "last_ts": 1789...}
+
+written at startup, updated on every acting tool call, removed on clean
+shutdown. Anything can watch it — the shipped Waybar module (waybar/)
+shows a red indicator while an agent has hands on the desktop, and its
+click action (or a Hyprland keybind) runs `pkill -f hypruse`: the
+process dies mid-action at worst, never holding a button down, because
+button press/release pairs are sent inside one tool call.
+"""
+
+from __future__ import annotations
+
+import atexit
+import contextlib
+import json
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+_state_path: Path | None = None
+_started: float = 0.0
+
+
+def state_path() -> Path:
+    base = os.environ.get("XDG_RUNTIME_DIR", "/tmp")
+    d = Path(base) / "hypruse"
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "state.json"
+
+
+def _write(payload: dict) -> None:
+    if _state_path is None:
+        return
+    tmp = _state_path.with_suffix(".tmp")
+    tmp.write_text(json.dumps(payload))
+    tmp.replace(_state_path)
+
+
+def init() -> None:
+    """Start the beacon; safe to call once at server startup."""
+    global _state_path, _started
+    _state_path = state_path()
+    _started = time.time()
+    _write({"pid": os.getpid(), "started": _started, "last_action": "", "last_ts": 0})
+    atexit.register(shutdown)
+    for sig in (signal.SIGTERM, signal.SIGINT):
+        signal.signal(sig, _die)
+
+
+def touch(action: str) -> None:
+    """Record an acting tool call (no-op if init() was never called)."""
+    if _state_path is None:
+        return
+    _write(
+        {
+            "pid": os.getpid(),
+            "started": _started,
+            "last_action": action,
+            "last_ts": time.time(),
+        }
+    )
+
+
+def shutdown() -> None:
+    global _state_path
+    if _state_path is not None:
+        with contextlib.suppress(OSError):
+            _state_path.unlink(missing_ok=True)
+        _state_path = None
+
+
+def _die(signum: int, _frame: object) -> None:
+    shutdown()
+    sys.exit(128 + signum)

hypruse/screenshot.py

@@ -0,0 +1,203 @@
+"""Screenshots via grim (wlroots screencopy).
+
+grim captures in *pixel* space while hypruse coordinates are global
+*logical* pixels; on monitors with fractional scaling the two differ.
+Every capture therefore returns metadata with its origin and scale so an
+image pixel maps back to a clickable point:
+
+    global_x = geometry[0] + pixel_x / scale
+    global_y = geometry[1] + pixel_y / scale
+"""
+
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+from typing import Any
+
+from hypruse import hyprctl
+
+
+class ScreenshotError(RuntimeError):
+    """grim failed or the capture target does not exist."""
+
+
+_REGION = re.compile(r"^\s*(-?\d+)\s*,\s*(-?\d+)\s*[, ]\s*(\d+)\s*x\s*(\d+)\s*$")
+
+
+def parse_region(region: str) -> tuple[int, int, int, int]:
+    """Accepts 'x,y,WxH' or 'x,y WxH' (grim's own format)."""
+    m = _REGION.match(region)
+    if not m:
+        raise ScreenshotError(f"bad region {region!r}, expected 'x,y,WxH'")
+    x, y, w, h = map(int, m.groups())
+    if w <= 0 or h <= 0:
+        raise ScreenshotError(f"bad region {region!r}: empty size")
+    return x, y, w, h
+
+
+def _grim(args: list[str]) -> bytes:
+    if shutil.which("grim") is None:
+        raise ScreenshotError("grim not found — install grim for screenshots")
+    proc = subprocess.run(["grim", *args, "-"], capture_output=True, timeout=10)
+    if proc.returncode != 0 or not proc.stdout:
+        raise ScreenshotError(f"grim failed: {proc.stderr.decode(errors='replace').strip()}")
+    return proc.stdout
+
+
+def _fit_ladder(start_scale: float) -> list[tuple[str, int | None, float]]:
+    """(format, jpeg-quality, scale) attempts from a starting scale, best
+    fidelity first. Full-resolution JPEG beats half-resolution PNG for
+    reading UI text, so format degrades before resolution does.
+    """
+    s = start_scale
+    return [
+        ("png", None, s),
+        ("jpeg", 85, s),
+        ("jpeg", 85, s * 0.75),
+        ("jpeg", 80, s * 0.5),
+    ]
+
+
+def _grab_fitting(
+    base_args: list[str], start_scale: float, max_bytes: int | None
+) -> tuple[bytes, str, float]:
+    """Capture within a byte budget; returns (data, format, applied_scale)."""
+    for fmt, quality, s in _fit_ladder(start_scale):
+        args = list(base_args)
+        if abs(s - 1.0) > 1e-6:
+            args = ["-s", f"{s:g}", *args]
+        if fmt == "jpeg":
+            args = ["-t", "jpeg", "-q", str(quality), *args]
+        data = _grim(args)
+        if max_bytes is None or len(data) <= max_bytes:
+            return data, fmt, s
+    raise ScreenshotError(
+        f"even a downscaled JPEG exceeds the {max_bytes}-byte result budget — "
+        "capture a window or region instead of the whole monitor"
+    )
+
+
+_SOF_MARKERS = {0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF}
+
+
+def image_size(data: bytes) -> tuple[int, int]:
+    """(width, height) of PNG or JPEG bytes, without a decode library.
+
+    The model reasons about the image it is actually shown, so hypruse
+    reports the true output dimensions rather than assuming the geometry
+    it asked grim for.
+    """
+    if data[:8] == b"\x89PNG\r\n\x1a\n":
+        w = int.from_bytes(data[16:20], "big")
+        h = int.from_bytes(data[20:24], "big")
+        return w, h
+    if data[:2] == b"\xff\xd8":  # JPEG: find a Start-Of-Frame segment
+        i, n = 2, len(data)
+        while i + 9 < n:
+            if data[i] != 0xFF:
+                i += 1
+                continue
+            marker = data[i + 1]
+            if marker == 0xD8 or marker == 0xD9 or 0xD0 <= marker <= 0xD7:
+                i += 2
+                continue
+            seg = int.from_bytes(data[i + 2 : i + 4], "big")
+            if marker in _SOF_MARKERS:
+                h = int.from_bytes(data[i + 5 : i + 7], "big")
+                w = int.from_bytes(data[i + 7 : i + 9], "big")
+                return w, h
+            i += 2 + seg
+    raise ScreenshotError("could not read image dimensions")
+
+
+def _cap_scale(physical_long_edge: float, max_edge: int | None) -> float:
+    """Downscale factor so the output's long edge fits max_edge, capped at 1.0.
+
+    Prevents the API from silently downscaling a too-large image *under* the
+    model, which would desync the reported scale from what the model sees.
+    """
+    if not max_edge or physical_long_edge <= max_edge:
+        return 1.0
+    return max_edge / physical_long_edge
+
+
+def _scale_at(x: int, y: int, monitors: list[dict[str, Any]]) -> float:
+    for m in monitors:
+        if m["x"] <= x < m["x"] + m["width"] and m["y"] <= y < m["y"] + m["height"]:
+            return float(m.get("scale", 1.0))
+    return 1.0
+
+
+def _find_window(window: str, clients: list[dict[str, Any]], active: str | None) -> dict[str, Any]:
+    target = active if window == "active" else window
+    if not target:
+        raise ScreenshotError("no active window")
+    for c in clients:
+        if c.get("address") == target:
+            return c
+    raise ScreenshotError(
+        f"window {target!r} not found — call desktop() for current addresses"
+    )
+
+
+def capture(
+    window: str = "",
+    region: str = "",
+    scale: float = 0.0,
+    max_bytes: int | None = None,
+    max_edge: int | None = None,
+) -> tuple[bytes, dict[str, Any]]:
+    """Returns (image_bytes, metadata). Exactly one of window/region, or
+    neither for the focused monitor. `scale` (0 = auto) forces a capture
+    scale; `max_edge` caps the output's long edge (so the API never
+    downscales it under the model); `max_bytes` fits a transport budget by
+    degrading format before resolution. Any applied downscale is folded into
+    the metadata `scale`, so the pixel→global mapping stays exact."""
+    if window and region:
+        raise ScreenshotError("pass window OR region, not both")
+    if scale and not 0.1 <= scale <= 1.0:
+        raise ScreenshotError(f"scale {scale} out of range (0.1–1.0, or 0 for auto)")
+
+    monitors = hyprctl.query("monitors")
+
+    if region:
+        x, y, w, h = parse_region(region)
+        base = ["-g", f"{x},{y} {w}x{h}"]
+        meta: dict[str, Any] = {"target": "region", "geometry": [x, y, w, h]}
+        base_scale = _scale_at(x, y, monitors)
+        physical_long = max(w, h) * base_scale
+    elif window:
+        active = (hyprctl.query("activewindow") or {}).get("address")
+        c = _find_window(window, hyprctl.query("clients"), active)
+        (x, y), (w, h) = c["at"], c["size"]
+        base = ["-g", f"{x},{y} {w}x{h}"]
+        meta = {
+            "target": "window",
+            "window": c["address"],
+            "class": c.get("class", ""),
+            "geometry": [x, y, w, h],
+        }
+        base_scale = _scale_at(x, y, monitors)
+        physical_long = max(w, h) * base_scale
+    else:
+        m = next((m for m in monitors if m.get("focused")), monitors[0])
+        base = ["-o", m["name"]]
+        meta = {
+            "target": "monitor",
+            "monitor": m["name"],
+            "geometry": [m["x"], m["y"], m["width"], m["height"]],
+        }
+        base_scale = float(m.get("scale", 1.0))
+        physical_long = max(m["width"], m["height"])
+
+    # explicit scale wins; otherwise fit the long edge to keep the mapping honest
+    start_scale = scale or _cap_scale(physical_long, max_edge)
+    data, fmt, applied = _grab_fitting(base, start_scale, max_bytes)
+    iw, ih = image_size(data)
+    meta["image"] = [iw, ih]
+    meta["format"] = fmt
+    meta["scale"] = round(base_scale * applied, 6)
+    meta["coords"] = "click a target at global = geometry[:2] + image_pixel / scale"
+    return data, meta