Skip to content

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.

23.2 KB
Raw Blame
"""Linux-X11 hotkey backend via ``pynput`` (AD-8).

``pynput`` provides cross-platform global keyboard listeners. This backend maps
the jarvis combo vocabulary onto pynput key objects and tracks the live
pressed-key set so a chord fires its press handler on the down edge and its
release handler on the up edge — push-to-talk (down=start recording, up=submit)
works exactly like the Windows ``global-hotkeys`` path.

Combo translation
-----------------
``HotkeyTrigger`` hands every backend rows whose ``row[0]`` is the combo already
normalized to the ``global-hotkeys`` form (``"control + alt + j"``). That keeps
the Windows path byte-identical (AD-7); here we deterministically translate that
form into the pynput key tokens the listener matches against.

A combo is considered *down* when every one of its keys is currently held; the
press handler fires on the transition into that state and the release handler on
the transition out of it. Each edge runs only its OWN handler, so a row carrying
just one of the two observes just that edge — a toggle binding (``on_release``
only) fires exactly once on key-up here, on Windows and on macOS alike. This is
the documented robust both-edges pynput pattern (a bare ``Listener`` with manual
state), avoiding the press-only limitation of ``GlobalHotKeys``.

macOS permission hint (AD-8 / AD-13)
------------------------------------
On macOS a global listener silently fires nothing until the user grants Input
Monitoring (a listen-only event tap needs that and nothing else). The darwin
branch of ``start`` therefore stays closed until the grant is visible; the
macOS app itself uses ``QuartzHotkeyBackend`` (BUG-077), which carries the
liveness counter. ``received_any_event()`` only reports whether a BOUND chord
has fired.

Import-cleanliness (HN-7): ``pynput`` is imported lazily inside ``start`` so
``import dodaios.trigger.backends.pynput`` succeeds on a box without the package.
A tiny module-level refcount keeps two ``HotkeyTrigger``s (pipeline +
kill-switch) from spawning two OS listeners on the same process.
"""

from __future__ import annotations

import logging
import sys
import threading

from dodaios.trigger.backends.global_hotkeys import MOUSE_BUTTON_TOKENS

log = logging.getLogger(__name__)


def _macos_hotkey_permissions_granted() -> bool:
    """Is Input Monitoring granted, the one grant a listen-only tap needs?

    Silent, lock-free and never prompting: it is ``PermissionService.check``,
    safe from the loop, from the tap callback and at boot. It does not ask the
    OS for anything (the request belongs to a user gesture) and does not look at
    the app's bundle identity: we act on whatever grant exists. ``NOT_REQUIRED``
    (a host without TCC) counts as permitted, like ``EnsureResult.granted``.
    """
    from dodaios.platform.permission_service import (  # noqa: PLC0415
        get_permission_service,
    )
    from dodaios.platform.permissions import (  # noqa: PLC0415
        PermissionId,
        PermissionState,
    )

    state = get_permission_service().check(PermissionId.INPUT_MONITORING)
    return state in (PermissionState.GRANTED, PermissionState.NOT_REQUIRED)


def _macos_layout_guard_ready() -> bool:
    """Prime + install the TIS main-thread layout guard (BUG-077).

    macOS 15 kills the process with an uncatchable SIGILL when pynput's
    listener thread calls the TIS keyboard-layout APIs off the main thread.
    ``True`` only when a main-thread layout snapshot exists and pynput is
    patched to use it, i.e. the listener is safe to start.
    """
    from dodaios.platform.macos_input_source import (  # noqa: PLC0415
        ensure_pynput_layout_guard,
    )

    return ensure_pynput_layout_guard()

# global-hotkeys modifier token -> canonical pynput modifier name (the attribute
# on ``pynput.keyboard.Key``). Anything not here is a literal key (e.g. "j") or
# an F-key (e.g. "f1", which is also a ``Key`` attribute).
_MODIFIER_TO_KEY_ATTR = {
    "control": "ctrl",
    "right_control": "ctrl_r",
    "alt": "alt",
    "shift": "shift",
    "window": "cmd",
    # ``_normalize_combo`` already folds super/meta to ``window``, so these two
    # only matter for a caller that hands us a raw combo. pynput reports the
    # Super/Windows key as ``Key.cmd`` on every platform, hence the same target.
    "super": "cmd",
    "meta": "cmd",
}

# ``pynput`` reports the right-hand modifier keys with side-specific names
# (``alt_r``, ``shift_r``, ``cmd_r``), while a generic configured modifier such
# as ``alt`` must accept either physical side.  The old subset comparison only
# matched the left aliases (which pynput names simply ``alt``/``shift``/etc.),
# so the shipped ``right_alt`` PTT default could never fire on Linux-X11.
_GENERIC_MODIFIER_ALIASES: dict[str, frozenset[str]] = {
    "ctrl": frozenset({"ctrl", "ctrl_l", "ctrl_r"}),
    "alt": frozenset({"alt", "alt_l", "alt_r", "alt_gr"}),
    "shift": frozenset({"shift", "shift_l", "shift_r"}),
    "cmd": frozenset({"cmd", "cmd_l", "cmd_r"}),
    # Super/Meta are the same key pynput calls ``cmd``. Reached only when a
    # combo skipped ``_normalize_combo``; folding them here keeps a legacy
    # config comparing against the right physical key instead of a token that
    # matches nothing.
    "super": frozenset({"cmd", "cmd_l", "cmd_r"}),
    "meta": frozenset({"cmd", "cmd_l", "cmd_r"}),
}

# ``pynput.mouse.Button`` member name -> the shared mouse token. The X11 backend
# numbers the extra buttons (the two side buttons land on 8 and 9); other
# backends name them x1/x2. Matching by NAME keeps this table honest on a
# platform whose pynput build simply has no such member — the button then never
# appears in the held set and the shortcut stays quiet instead of firing on the
# wrong button.
_MOUSE_NAME_TO_TOKEN = {
    "middle": "mouse_middle",
    "button8": "mouse_x1",
    "button9": "mouse_x2",
    "x1": "mouse_x1",
    "x2": "mouse_x2",
}

# --------------------------------------------------------------------------
# Module-level single-listener guard (mirrors the Windows refcount intent):
# two live HotkeyTriggers must share ONE listener thread, else every press
# fires twice.
# --------------------------------------------------------------------------
_LISTENER_LOCK = threading.Lock()
_LISTENER_REFCOUNT = 0


def _reset_listener_state_for_tests() -> None:
    """Reset the shared listener refcount — test-isolation hook only."""
    global _LISTENER_REFCOUNT
    with _LISTENER_LOCK:
        _LISTENER_REFCOUNT = 0


def _parse_combo_tokens(normalized: str) -> tuple[str, ...]:
    """``"control + alt + j"`` -> ``("ctrl", "alt", "j")`` (canonical tokens).

    Modifiers fold to their ``Key`` attribute name; everything else is lowercased
    and kept as a literal token the listener compares case-insensitively.
    """
    parts = [p.strip().lower() for p in normalized.split("+") if p.strip()]
    return tuple(_MODIFIER_TO_KEY_ATTR.get(p, p) for p in parts)


def _combo_is_down(tokens: frozenset[str], held: set[str]) -> bool:
    """Whether every configured token is represented by a held physical key."""
    return all(
        bool(_GENERIC_MODIFIER_ALIASES.get(token, frozenset({token})) & held)
        for token in tokens
    )


class PynputBackend:
    """``pynput`` global-hotkey backend for Linux-X11 (AD-8).

    Satisfies the ``HotkeyBackend`` ``Protocol``. Receives the same normalized
    ``[combo_str, on_press, on_release]`` rows the Windows backend does, so the
    ``HotkeyTrigger`` call site is platform-agnostic.
    """

    def __init__(self) -> None:
        # Each entry: (token_set, on_press|None, on_release|None, currently_down).
        self._combos: list[dict] = []
        # pynput ``keyboard.Listener`` once started; ``None`` until / on degrade.
        # Typed ``object | None`` to avoid a hard module-scope pynput type import.
        self._listener: object | None = None
        # The mouse listener, started only when a bound combo actually contains
        # a mouse button — an idle desktop must not pay for a second OS hook.
        self._mouse_listener: object | None = None
        self._needs_mouse = False
        self._started = False
        self._got_event = False
        self._incremented = False
        self._teardown_failed = False
        # The live set of canonical tokens currently held down.
        self._held: set[str] = set()
        self._permission_check = lambda: True
        # X11 display for unshifting symbol keys; opened on first need, from
        # the listener thread only. ``False`` = tried and unavailable.
        self._x_display: object | None | bool = None

    def register(self, bindings, on_event=None) -> None:
        """Stash binding rows as token-set combos. Never raises (AD-6).

        The real OS listener is built in ``start`` (pynput owns its own thread),
        so here we only translate the rows into the matcher's combo records.
        """
        combos: list[dict] = []
        for row in bindings:
            combo = row[0]
            on_press = row[1] if len(row) > 1 else None
            on_release = row[2] if len(row) > 2 else None
            combos.append(
                {
                    "tokens": frozenset(_parse_combo_tokens(combo)),
                    "on_press": on_press,
                    "on_release": on_release,
                    "down": False,
                }
            )
        self._combos = combos
        self._needs_mouse = any(
            combo["tokens"] & MOUSE_BUTTON_TOKENS for combo in combos
        )

    def chord_is_down(self, combo: str) -> bool | None:
        """Is every token of ``combo`` in the held-set right now? ``None`` = unknown.

        pynput has no "ask the keyboard" primitive, so this is the listener's
        own bookkeeping — the same edge-fed set the matcher reads. It is honest
        about that: while the listener is not running there is no set to
        consult and the answer is ``None``, so a consumer degrades to
        "edges only" instead of trusting a stale view.
        """
        if not self._started or self._listener is None:
            return None
        tokens = frozenset(_parse_combo_tokens(combo))
        if not tokens:
            return None
        return _combo_is_down(tokens, self._held)

    def held_tokens(self) -> frozenset[str] | None:
        """Copy of the listener's held-set. ``None`` while it is not running."""
        if not self._started or self._listener is None:
            return None
        return frozenset(self._held)

    def _token_for(self, key) -> str | None:
        """Map a pynput key event to our canonical token, or ``None``."""
        # ``KeyCode`` for character keys exposes ``.char``; ``Key`` enum members
        # (modifiers, F-keys) expose ``.name``.
        char = getattr(key, "char", None)
        if char:
            if not char.isalnum():
                # X11 reports the SHIFTED symbol: Shift+9 arrives as "(" (US)
                # or ")" (German), so "ctrl+shift+9" never matched. Bindings
                # name the key, so a symbol is mapped back to its base key.
                base = self._unshifted_char(key)
                if base:
                    return base
            return char.lower()
        name = getattr(key, "name", None)
        if name:
            return name.lower()
        return None

    def _unshifted_char(self, key) -> str | None:
        """The base (level 0) character of an X11 key, or ``None``.

        pynput's X11 ``KeyCode.vk`` is the keysym. The key that carries this
        keysym on its SHIFT level, read back one level lower, is the key
        without Shift — layout-correct, because the X server's own keymap does
        the mapping. A keysym can sit on several keys ("(" is also a keypad
        key, on its base level); only a shift-level entry counts. Off X11,
        without Xlib, or for a symbol that is not shifted, ``None`` keeps the
        character as reported.
        """
        vk = getattr(key, "vk", None)
        if not isinstance(vk, int) or not sys.platform.startswith("linux"):
            return None
        display = self._x_display
        if display is None:
            try:
                from Xlib import display as xdisplay  # noqa: PLC0415

                display = xdisplay.Display()
            except Exception:  # noqa: BLE001 - no X server or no Xlib: keep the char
                log.debug("pynput: no X display to unshift symbol keys", exc_info=True)
                display = False
            self._x_display = display
        if display is False:
            return None
        try:
            for keycode, index in display.keysym_to_keycodes(vk):  # type: ignore[union-attr]
                if index % 2 == 0:  # an unshifted level: this IS a base key
                    continue
                base = display.keycode_to_keysym(keycode, index - 1)  # type: ignore[union-attr]
                # Latin-1 keysyms equal their code point; only printable ASCII maps.
                if 0x20 < base < 0x7F:
                    return chr(base).lower()
        except Exception:  # noqa: BLE001 - an odd keysym keeps its reported char
            log.debug("pynput: could not unshift keysym %#x", vk, exc_info=True)
        return None

    def _on_press_key(self, key) -> None:
        token = self._token_for(key)
        if token is None:
            return
        self._held.add(token)
        self._reconcile()

    def _on_release_key(self, key) -> None:
        token = self._token_for(key)
        if token is None:
            return
        self._reconcile()  # check release edges BEFORE dropping the token
        self._held.discard(token)
        self._reconcile()

    def _on_click(self, _x, _y, button, pressed) -> None:  # noqa: ANN001 — pynput callback
        """Feed a mouse button into the same held-set the keyboard uses."""
        token = _MOUSE_NAME_TO_TOKEN.get(str(getattr(button, "name", "")).lower())
        if token is None:
            return
        if pressed:
            self._held.add(token)
            self._reconcile()
            return
        self._reconcile()  # check release edges BEFORE dropping the token
        self._held.discard(token)
        self._reconcile()

    def _start_mouse_listener(self) -> None:
        """Start the mouse hook — only when a combo needs it. Degrades honestly.

        A failure here must not take the KEYBOARD shortcuts down with it: the
        message names what stopped working and what still does, so a user never
        has to guess why one shortcut of two went quiet (AP-23).
        """
        if not self._needs_mouse or self._mouse_listener is not None:
            return
        try:
            from pynput import mouse  # type: ignore[import-untyped]  # lazy (HN-7)

            listener = mouse.Listener(on_click=self._on_click)
            listener.start()
        except Exception as exc:  # noqa: BLE001 — degrade, never crash the pipeline
            log.warning(
                "Mouse-button shortcuts are unavailable on this system (%s) — "
                "shortcuts that use a key combination still work, and voice "
                "still works via the wake word.",
                exc,
            )
            self._mouse_listener = None
            return
        self._mouse_listener = listener

    def _stop_mouse_listener(self) -> None:
        """Tear the mouse hook down. Idempotent, never raises."""
        listener = self._mouse_listener
        self._mouse_listener = None
        if listener is None:
            return
        for step_name, step in (
            ("stop", lambda: listener.stop()),  # type: ignore[attr-defined]
            ("join", lambda: listener.join(timeout=2.0)),  # type: ignore[attr-defined]
        ):
            try:
                step()
            except Exception:  # noqa: BLE001 — teardown must never propagate
                log.debug(
                    "pynput mouse listener %s failed (non-fatal)",
                    step_name,
                    exc_info=True,
                )

    def _reconcile(self) -> None:
        """Fire press/release handlers on chord down/up transitions."""
        if not self._permission_check():
            # A grant can be revoked while the listener thread is alive. Clear
            # every partial chord and refuse the callback before it can activate
            # voice; a later re-grant starts from a clean key state.
            self._held.clear()
            for combo in self._combos:
                combo["down"] = False
            return
        for combo in self._combos:
            is_down = _combo_is_down(combo["tokens"], self._held)
            if is_down and not combo["down"]:
                combo["down"] = True
                self._got_event = True
                # Each edge fires ONLY its own handler. A toggle binding carries
                # on_release alone (HotkeyTrigger._build_bindings) so a held key
                # fires exactly once on the up edge; falling back to it here made
                # every toggle fire on key-DOWN on this backend while the Windows
                # path fired on key-up — one config, two behaviours.
                if combo["on_press"] is not None:
                    combo["on_press"]()
            elif not is_down and combo["down"]:
                combo["down"] = False
                self._got_event = True
                # Push-to-talk (both edges set) and toggle (release only) alike.
                if combo["on_release"] is not None:
                    combo["on_release"]()

    def start(self) -> None:
        """Build + start the shared pynput listener. Degrades, never raises."""
        if self._started:
            return
        if self._teardown_failed:
            log.warning(
                "pynput hotkeys remain disabled after a listener teardown "
                "failure; restart Dodaios to re-arm them safely. Voice still "
                "works via the wake word."
            )
            return
        try:
            from pynput import keyboard  # type: ignore[import-untyped]  # lazy (HN-7)
        except Exception as exc:  # noqa: BLE001 — optional [desktop] extra
            log.warning(
                "pynput unavailable (%s) — hotkeys disabled; voice still works "
                "via wake word. Install the [full] profile to enable global "
                "hotkeys.",
                exc,
            )
            self._listener = None
            return

        if sys.platform == "darwin":
            # pynput's darwin backend creates a Quartz event tap on its own
            # internal thread; without Input Monitoring that native init is
            # useless at best and a process-level abort at worst (uncatchable,
            # BUG-058 class). Preflight the non-prompting grant and fail CLOSED
            # instead of touching pynput.
            granted = False
            try:
                granted = _macos_hotkey_permissions_granted()
            except Exception:  # noqa: BLE001 — the probe must never crash the trigger
                granted = False
            if granted is not True:
                log.warning(
                    "Global hotkeys are off on macOS until Input Monitoring "
                    "is allowed for Dodaios; voice still works via "
                    "the wake word.",
                )
                self._listener = None
                return
            self._permission_check = _macos_hotkey_permissions_granted

            # BUG-077: pynput's listener thread calls the TIS keyboard-layout
            # APIs (HIToolbox) as it starts; on macOS 15 an off-main-thread
            # TIS call is an uncatchable process kill (SIGILL, "Personal
            # Jarvis quit unexpectedly"). Only start the listener once a
            # main-thread layout snapshot is cached and pynput is patched to
            # reuse it; otherwise degrade — voice still works via wake word.
            guard_ready = False
            try:
                guard_ready = _macos_layout_guard_ready()
            except Exception:  # noqa: BLE001 — the guard must never crash the trigger
                guard_ready = False
            if not guard_ready:
                log.warning(
                    "Global hotkeys disabled on macOS: the keyboard-layout "
                    "snapshot could not be captured on the main thread, and "
                    "starting the listener without it would crash the app "
                    "(TIS main-thread assertion). Voice still works via the "
                    "wake word; restarting Dodaios re-attempts the snapshot.",
                )
                self._listener = None
                return

        try:
            listener = keyboard.Listener(
                on_press=self._on_press_key,
                on_release=self._on_release_key,
            )
            listener.start()
        except Exception:  # noqa: BLE001 — degrade, never crash the pipeline
            log.error(
                "pynput Listener failed to start — hotkeys disabled for this "
                "session; voice still works via wake word.",
                exc_info=True,
            )
            self._listener = None
            return
        self._listener = listener
        self._start_mouse_listener()

        with _LISTENER_LOCK:
            global _LISTENER_REFCOUNT
            _LISTENER_REFCOUNT += 1
            self._incremented = True
        self._started = True

    def stop(self) -> None:
        """Stop the pynput listeners. Idempotent."""
        self._stop_mouse_listener()
        listener = self._listener
        if listener is not None:
            try:
                listener.stop()  # type: ignore[attr-defined]  # pynput Listener
            except Exception:  # noqa: BLE001 — teardown must never propagate
                log.debug("pynput listener.stop() failed (non-fatal)",
                          exc_info=True)
            try:
                # A live keybind edit immediately constructs the replacement
                # listener.  Wait for the old hook thread to leave first so it
                # cannot emit a second press/release edge after re-arm.
                listener.join(timeout=2.0)  # type: ignore[attr-defined]
            except Exception:  # noqa: BLE001 — teardown must never propagate
                log.debug("pynput listener.join() failed (non-fatal)",
                          exc_info=True)
            is_alive = getattr(listener, "is_alive", None)
            if callable(is_alive) and is_alive():
                self._teardown_failed = True
                log.warning(
                    "pynput hotkey listener did not stop within two seconds; "
                    "the replacement listener will not be started."
                )
        self._listener = None
        self._held.clear()
        for combo in self._combos:
            combo["down"] = False
        if self._incremented:
            with _LISTENER_LOCK:
                global _LISTENER_REFCOUNT
                _LISTENER_REFCOUNT = max(0, _LISTENER_REFCOUNT - 1)
            self._incremented = False
        self._started = False

    def unregister(self) -> None:
        """Drop the armed bindings. The listener is torn down in ``stop``."""
        self._combos = []
        self._needs_mouse = False

    def received_any_event(self) -> bool:
        """True once any bound chord has fired (AD-8 macOS permission hint)."""
        return self._got_event


__all__ = [
    "PynputBackend",
    "_MOUSE_NAME_TO_TOKEN",
    "_combo_is_down",
    "_parse_combo_tokens",
    "_reset_listener_state_for_tests",
]