elfdeckai 1.0.4__py3-none-any.whl

elfdeckai-1.0.4.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: elfdeckai
+Version: 1.0.4
+Summary: Virtual keyboard, gamepad and mouse for AI agents on Linux / Steam Deck — zero-dependency uinput daemons with an MCP server.
+Author: Garth Elfstrom
+License: MIT
+Project-URL: Homepage, https://github.com/Garthnesss/ElfDeckAI
+Project-URL: Repository, https://github.com/Garthnesss/ElfDeckAI
+Project-URL: Issues, https://github.com/Garthnesss/ElfDeckAI/issues
+Keywords: mcp,model-context-protocol,llm,ai-agent,steam-deck,uinput,gamepad,automation
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 🎮 ElfdeckAI
+
+### Your AI can *see* the game. Now it can hold the controller.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+![Python](https://img.shields.io/badge/python-3.8+-blue.svg)
+![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-146%20passing-brightgreen.svg)
+
+**ElfdeckAI gives an LLM agent hands on real hardware.** Three tiny
+daemons turn one-line commands — from a shell, a script, or native
+**MCP tool calls** — into real keyboard, gamepad and mouse input on a
+Linux machine:
+
+- ⌨️ **ElfKey** — a virtual keyboard on `/dev/uinput`
+- 🕹️ **ElfPad** — a virtual gamepad (Xbox-class: buttons, analog triggers,
+  two sticks, D-pad)
+- 🖱️ **ElfMouse** — a virtual mouse (relative pointer, buttons, wheel)
+
+Every "LLM plays Pokémon" project you've seen plugs into an **emulator's
+API**. ElfdeckAI presses buttons on a **real device** — proven live when an
+LLM played Pokémon FireRed on a physical Steam Deck end-to-end through
+ElfKey: full intro, starter picked, first rival battle won, game saved.
+No emulator *API*, no RAM reading, no capture card — the game runs on
+the real device (inside RetroArch, in that run); the agent's only
+channel in is real input, and its only view is a stream for eyes.
+([How it drives](notes/driving.md))
+
+## ⚡ Run it yourself (60 seconds)
+
+```sh
+pip install git+https://github.com/Garthnesss/ElfDeckAI
+
+elfkey &                     # virtual keyboard   (command: elfkey)
+elfpad &                     # virtual gamepad    (command: elfpad)
+elfmouse &                   # virtual mouse      (command: elfmouse)
+
+echo "key x 150"        > /tmp/elfkey.fifo     # tap X
+echo "press a"          > /tmp/elfpad.fifo     # tap A
+echo "move 300 -100"    > /tmp/elfmouse.fifo   # flick the pointer
+echo "click left"       > /tmp/elfmouse.fifo   # click
+
+grep -E "ElfKey|ElfPad|ElfMouse" /proc/bus/input/devices   # they're really there
+```
+
+That's the whole install. Three single-file Python programs, **standard
+library only** — nothing to build, no dependencies to resolve. State
+lives in `/tmp`; reboot and it's gone. Prefer no pip at all? Clone the
+repo and run `python3 elfkey.py` — same thing.
+
+For your agent, the pip install also provides the MCP server as a
+command: `"command": "elfdeckai-mcp"` (details below).
+
+> **Steam Deck?** You're already done — `/dev/uinput` is user-writable
+> there out of the box. On other Linux machines, install the included
+> udev rule once (see [Install](#install)).
+
+## 🤖 Give it to your agent (MCP)
+
+`elfdeckai_mcp.py` is a zero-dependency [Model Context
+Protocol](https://modelcontextprotocol.io) server that exposes all
+three devices as 18 native tools — `key_tap`, `pad_press`, `pad_stick`,
+`mouse_move`, `mouse_click`, `pad_reset`, `key_release`, … — for Claude,
+Hermes, or any MCP client:
+
+```json
+{"mcpServers": {"elfdeckai": {"command": "elfdeckai-mcp"}}}
+```
+
+(No pip? `"command": "python3", "args": ["/path/to/elfdeckai_mcp.py"]`
+works identically.)
+
+Start the daemons, add that to your client's config, and your agent can
+press buttons the same way it calls any other tool. Every call is
+validated by the daemons' own input contract before it touches a FIFO,
+and a stopped daemon fails the call cleanly instead of hanging your agent.
+
+## 🎛️ Commands
+
+### ElfKey — `/tmp/elfkey.fifo`
+
+| Command | Effect |
+|---|---|
+| `key <name> [ms]` | tap a key (default 120 ms) |
+| `down <name>` / `up <name>` | hold / release |
+| `release` | let go of every held key at once (the unstick command) |
+| `quit` | release everything and exit |
+
+Keys: `a`–`z`, `0`–`9`, arrows, `enter`, `esc`, `space`, `tab`, `shift`,
+`rshift`, `ctrl`, `alt`, punctuation, `f1`–`f10`, `home`, `end`, `insert`,
+`delete`, … (full table in the source).
+
+### ElfPad — `/tmp/elfpad.fifo`
+
+| Command | Effect |
+|---|---|
+| `press <btn> [ms]` | tap a button — or a D-pad direction |
+| `down <btn>` / `up <btn>` | hold / release |
+| `stick left\|right <x> <y> [ms]` | analog stick, −100..100 % per axis; `ms` = auto-recenter after |
+| `trigger left\|right <0..100> [ms]` | analog trigger; `ms` = auto-release after |
+| `center` | sticks, triggers, D-pad to neutral |
+| `reset` | release everything |
+| `quit` | release everything and exit |
+
+Buttons: `a b x y lb rb l2 r2 select start guide l3 r3`. ElfPad presents
+as an Xbox-360-class pad, so SDL, Steam Input and RetroArch map it the
+standard way with zero configuration. `l2`/`r2` are analog-only, exactly
+like the real pad — there are deliberately no digital trigger buttons,
+because declaring them shifts Select/Start/Guide two button indices off
+the stock layout (verified against a real 360 pad on a Deck).
+
+### ElfMouse — `/tmp/elfmouse.fifo`
+
+| Command | Effect |
+|---|---|
+| `move <dx> <dy> [glide_ms]` | move the pointer (relative); `glide_ms` = glide there over time |
+| `click <btn> [ms]` | click `left` / `right` / `middle` |
+| `down <btn>` / `up <btn>` | hold / release a button — drags are `down`, `move`, `up` |
+| `scroll <ticks>` / `hscroll <ticks>` | wheel / horizontal wheel (positive = up / right) |
+| `release` | let go of every held button at once (the unstick command) |
+| `quit` | release any held button and exit |
+
+Movement is relative, like a real mouse — pair it with screenshots and
+the same look → move → verify loop the rest of the set uses. Sign
+convention: negative `dy` is up, positive is down. Units are relative
+counts, not guaranteed screen pixels — pointer acceleration stretches
+fast moves — so small moves plus a fresh screenshot beat one big leap. Per-command
+bounds (±10 000 px, ±120 ticks) keep a confused call from flinging the
+pointer into orbit; chain commands for long travel.
+
+## 🛡️ Built for callers that hallucinate
+
+Letting a language model press buttons is safe only if the keyboard
+itself can't be talked into a bad state. So:
+
+- **Bad input never kills the daemon.** Every line passes a strict
+  parser; malformed commands are logged and refused. (`key x abc` and
+  `key x 999999999` were real crash/wedge bugs in the first version —
+  the tests now pin them shut.)
+- **Holds are bounded.** A tap is at most 5 s. Longer holds use
+  `down`/`up`, which the caller controls.
+- **Nothing gets stuck.** Timed moves restore in a `finally` block; held
+  inputs are tracked; on `quit`, SIGTERM or SIGINT, everything is
+  released and recentered before the device is destroyed.
+- **The FIFO is owner-only (0600).** Only your user can inject input.
+- **The server survives garbage.** Malformed JSON and non-object
+  requests get proper JSON-RPC protocol errors; one bad line — or a
+  caller dying mid-hold — can't wedge the session. `key_release`,
+  `mouse_release` and `pad_reset` are the unstick buttons — a release
+  queues behind at most the one hold currently executing (bounded,
+  ≤ 5 s), and every accepted command is logged to stderr, so what the
+  agent pressed is auditable afterwards.
+- **Scope honesty:** these are real OS-level input devices. They type
+  and click in whatever window has focus — a game, but equally a
+  terminal or a browser. ElfdeckAI makes that input *un-mess-up-able*
+  (bounded, validated, releasable); deciding *where* an agent may act
+  is the operator's call. Run agents you trust, on sessions you'd
+  watch.
+
+## 🤔 Why not…?
+
+| Approach | Why it falls short |
+|---|---|
+| Emulator APIs (PyBoy, mGBA scripting) | Only exists inside an emulator. Your Deck is not an emulator. |
+| Sending keys through Moonlight/streaming | Clicks get forwarded; synthetic keyboard events don't (verified). |
+| xdotool / desktop automation | Can't reach native Wayland clients. |
+| ydotool / dotool | The real incumbents — same uinput trick, keyboard + mouse. But: raw keycodes, a root daemon, no gamepad, and nothing agent-facing (no MCP, no safety bounds, no unstick). |
+| KVM gadget / controller-spoofing hardware | Works, but it's extra hardware on your desk doing what 200 lines of Python do on the device itself. |
+
+## Install
+
+**Requirements:** Linux (64-bit) with `/dev/uinput`, Python 3.8+. Nothing else.
+
+Anywhere `/dev/uinput` isn't user-writable, install the udev rule once:
+
+```sh
+sudo cp 70-elfdeckai-uinput.rules /etc/udev/rules.d/
+sudo udevadm control --reload-rules && sudo udevadm trigger
+getfacl /dev/uinput   # verify: your user should appear in the ACL
+```
+
+Run persistently as user services (expects the repo at `~/elfdeckai/` — clone with `git clone https://github.com/Garthnesss/ElfDeckAI ~/elfdeckai`):
+
+```sh
+cp systemd/*.service ~/.config/systemd/user/
+systemctl --user enable --now elfkey.service elfpad.service elfmouse.service
+```
+
+## Tests
+
+```sh
+python3 -m pytest    # 146 tests: all three input contracts, device behaviour
+                     # against a fake uinput, and the MCP server spoken
+                     # to over real JSON-RPC
+```
+
+## Roadmap
+
+- One combined daemon (keyboard + pad + mouse in a single process).
+- PyPI release, so `pip install elfdeckai` works without the git URL.
+- Demo clip: the Pokémon run, on camera.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Steal it, ship it, teach your agent to
+speedrun something.
+
+## Author
+
+Created and maintained by **Garth Elfstrom**
+([@Garthnesss](https://github.com/Garthnesss)). Issues and PRs welcome
+on the repo.

elfdeckai-1.0.4.dist-info/RECORD

@@ -0,0 +1,10 @@
+elfdeckai_mcp.py,sha256=Lm1OX_FUD2a6XFivaqpD9czvs4lHn18_V3bL8ilS0NI,15168
+elfkey.py,sha256=r1hSMZPLScKD5Liz4SCEe6T6pWW7RWz8h48xuyqdWG8,9895
+elfmouse.py,sha256=ePRELR6Hd24-0Zb7bluK5sh3fUE5y9AOZH4Qza01bpY,11422
+elfpad.py,sha256=KOEb00vxuRdMwWb3qB-8AY7au4YpUc5LzohmfHWYVeA,14980
+elfdeckai-1.0.4.dist-info/licenses/LICENSE,sha256=hfa3D3Ptj_JPKQmCAlOx0A8hRtvFcuUQSELmhEfrkss,1071
+elfdeckai-1.0.4.dist-info/METADATA,sha256=udO1DTB3lS8UEb2NAjtSY4prITIyH0WwiT5gPsJoHJI,10149
+elfdeckai-1.0.4.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+elfdeckai-1.0.4.dist-info/entry_points.txt,sha256=bNwHpIIUX75G1BZ9-b03vaOZUOpDe-_xBFZLmPDdMrQ,120
+elfdeckai-1.0.4.dist-info/top_level.txt,sha256=gGmh3_yCJqjRyKb3hGn-vq37hiC5xPoCebWzMLTPEtE,37
+elfdeckai-1.0.4.dist-info/RECORD,,

elfdeckai-1.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

elfdeckai-1.0.4.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+elfdeckai-mcp = elfdeckai_mcp:main
+elfkey = elfkey:main
+elfmouse = elfmouse:main
+elfpad = elfpad:main

elfdeckai-1.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Garth Elfstrom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elfdeckai-1.0.4.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+elfdeckai_mcp
+elfkey
+elfmouse
+elfpad

elfdeckai_mcp.py

@@ -0,0 +1,331 @@
+#!/usr/bin/env python3
+# Copyright (c) 2026 Garth Elfstrom — MIT License (see LICENSE).
+"""ElfdeckAI as MCP tools: a standard-library-only Model Context Protocol
+server (stdio, JSON-RPC) that exposes ElfKey and ElfPad to any MCP client —
+Claude, Hermes, your own agent — as native tool calls:
+
+    key_tap    {key, hold_ms?}          pad_press   {button, hold_ms?}
+    key_down   {key}                    pad_down    {button}
+    key_up     {key}                    pad_up      {button}
+    mouse_move  {dx, dy, glide_ms?}     pad_stick   {side, x, y, hold_ms?}
+    mouse_click {button, hold_ms?}      pad_trigger {side, percent, hold_ms?}
+    mouse_down  {button}                pad_center  {}
+    mouse_up    {button}                pad_reset   {}
+    mouse_scroll  {clicks}              key_release {}   (unstick everything)
+    mouse_hscroll {clicks}              mouse_release {} (unstick everything)
+
+The server holds no state and injects nothing itself: every call is
+validated by the daemons' own parse_command() (the exact contract the
+FIFOs enforce) and then written as one line to the daemon's FIFO. If a
+daemon isn't running, the call fails cleanly with "daemon not running"
+instead of blocking — opening a FIFO for write with no reader would
+otherwise hang the agent.
+
+Run the daemons first (elfkey.py, elfpad.py, elfmouse.py), then point your MCP client
+at this file, e.g.:
+
+    {"mcpServers": {"elfdeckai": {
+        "command": "python3", "args": ["/path/to/elfdeckai_mcp.py"]}}}
+
+FIFO paths default to the daemons' own constants and can be overridden
+with ELFKEY_FIFO / ELFPAD_FIFO environment variables (used by the tests).
+Standard library only, like everything else in this repo.
+"""
+import errno
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import elfkey
+import elfmouse
+import elfpad
+
+KEY_FIFO = os.environ.get("ELFKEY_FIFO", elfkey.FIFO)
+PAD_FIFO = os.environ.get("ELFPAD_FIFO", elfpad.FIFO)
+MOUSE_FIFO = os.environ.get("ELFMOUSE_FIFO", elfmouse.FIFO)
+PROTOCOL_VERSION = "2024-11-05"
+
+
+def _send(fifo, line, parser):
+    """Validate `line` with the daemon's parser, then hand it to the FIFO.
+    Returns a human-readable confirmation or raises ValueError/OSError."""
+    parser(line)  # raises ValueError on anything the daemon would refuse
+    payload = (line + "\n").encode()
+    fd = os.open(fifo, os.O_WRONLY | os.O_NONBLOCK)
+    try:
+        if os.write(fd, payload) != len(payload):
+            raise OSError(errno.EIO, "short FIFO write")
+    finally:
+        os.close(fd)
+    return "sent: %s" % line
+
+
+def _key_line(cmd, a):
+    if cmd == "key_release":
+        return "release"
+    if cmd == "key_tap":
+        ms = a.get("hold_ms")
+        return "key %s%s" % (a["key"], "" if ms is None else " %s" % ms)
+    return "%s %s" % (cmd.replace("key_", ""), a["key"])  # key_down / key_up
+
+
+def _pad_line(cmd, a):
+    if cmd == "pad_press":
+        ms = a.get("hold_ms")
+        return "press %s%s" % (a["button"], "" if ms is None else " %s" % ms)
+    if cmd in ("pad_down", "pad_up"):
+        return "%s %s" % (cmd.replace("pad_", ""), a["button"])
+    if cmd == "pad_stick":
+        ms = a.get("hold_ms")
+        return "stick %s %s %s%s" % (a["side"], a["x"], a["y"],
+                                     "" if ms is None else " %s" % ms)
+    if cmd == "pad_trigger":
+        ms = a.get("hold_ms")
+        return "trigger %s %s%s" % (a["side"], a["percent"],
+                                    "" if ms is None else " %s" % ms)
+    return cmd.replace("pad_", "")  # pad_center / pad_reset
+
+
+def _mouse_line(cmd, a):
+    if cmd == "mouse_release":
+        return "release"
+    if cmd == "mouse_move":
+        ms = a.get("glide_ms")
+        return "move %s %s%s" % (a["dx"], a["dy"],
+                                 "" if ms is None else " %s" % ms)
+    if cmd == "mouse_click":
+        ms = a.get("hold_ms")
+        return "click %s%s" % (a["button"], "" if ms is None else " %s" % ms)
+    if cmd in ("mouse_down", "mouse_up"):
+        return "%s %s" % (cmd.replace("mouse_", ""), a["button"])
+    if cmd == "mouse_scroll":
+        return "scroll %s" % a["clicks"]
+    return "hscroll %s" % a["clicks"]  # mouse_hscroll
+
+
+TOOLS = [
+    ("key_tap", "Tap a key on the virtual keyboard.",
+     {"key": {"type": "string", "enum": sorted(elfkey.KEYS)},
+      "hold_ms": {"type": "integer", "minimum": 0, "maximum": elfkey.MAX_HOLD_MS}},
+     ["key"]),
+    ("key_down", "Hold a key down (release with key_up, or key_release for all).",
+     {"key": {"type": "string", "enum": sorted(elfkey.KEYS)}}, ["key"]),
+    ("key_up", "Release a held key.",
+     {"key": {"type": "string", "enum": sorted(elfkey.KEYS)}}, ["key"]),
+    ("key_release", "Release every held key at once — the unstick button, for "
+                    "when a caller died mid-hold or state is unknown.",
+     {}, []),
+    ("pad_press", "Tap a gamepad button or D-pad direction.",
+     {"button": {"type": "string",
+                 "enum": sorted(set(elfpad.BUTTONS) | set(elfpad.DPAD) | set(elfpad.TRIGGERS))},
+      "hold_ms": {"type": "integer", "minimum": 0, "maximum": elfpad.MAX_HOLD_MS}},
+     ["button"]),
+    ("pad_down", "Hold a gamepad button or D-pad direction down.",
+     {"button": {"type": "string",
+                 "enum": sorted(set(elfpad.BUTTONS) | set(elfpad.DPAD) | set(elfpad.TRIGGERS))}}, ["button"]),
+    ("pad_up", "Release a held gamepad button or D-pad direction.",
+     {"button": {"type": "string",
+                 "enum": sorted(set(elfpad.BUTTONS) | set(elfpad.DPAD) | set(elfpad.TRIGGERS))}}, ["button"]),
+    ("pad_stick", "Move an analog stick (x/y in percent, -100..100). "
+                  "Without hold_ms the stick stays; with it, it recenters after.",
+     {"side": {"type": "string", "enum": ["left", "right"]},
+      "x": {"type": "integer", "minimum": -100, "maximum": 100},
+      "y": {"type": "integer", "minimum": -100, "maximum": 100},
+      "hold_ms": {"type": "integer", "minimum": 0, "maximum": elfpad.MAX_HOLD_MS}},
+     ["side", "x", "y"]),
+    ("pad_trigger", "Set an analog trigger (percent 0..100). "
+                    "Without hold_ms it stays; with it, it releases after.",
+     {"side": {"type": "string", "enum": ["left", "right"]},
+      "percent": {"type": "integer", "minimum": 0, "maximum": 100},
+      "hold_ms": {"type": "integer", "minimum": 0, "maximum": elfpad.MAX_HOLD_MS}},
+     ["side", "percent"]),
+    ("pad_center", "Return sticks, triggers and D-pad to neutral.", {}, []),
+    ("pad_reset", "Release every button and recenter everything.", {}, []),
+    ("mouse_move", "Move the pointer by (dx, dy) pixels. Optional glide_ms "
+                   "spreads the move over time (smooth drags, human-ish motion).",
+     {"dx": {"type": "integer", "minimum": -elfmouse.MAX_MOVE, "maximum": elfmouse.MAX_MOVE},
+      "dy": {"type": "integer", "minimum": -elfmouse.MAX_MOVE, "maximum": elfmouse.MAX_MOVE},
+      "glide_ms": {"type": "integer", "minimum": 0, "maximum": elfmouse.MAX_HOLD_MS}},
+     ["dx", "dy"]),
+    ("mouse_click", "Click a mouse button.",
+     {"button": {"type": "string", "enum": ["left", "right", "middle"]},
+      "hold_ms": {"type": "integer", "minimum": 0, "maximum": elfmouse.MAX_HOLD_MS}},
+     ["button"]),
+    ("mouse_down", "Hold a mouse button down (start a drag).",
+     {"button": {"type": "string", "enum": ["left", "right", "middle"]}}, ["button"]),
+    ("mouse_up", "Release a mouse button (drop the drag).",
+     {"button": {"type": "string", "enum": ["left", "right", "middle"]}}, ["button"]),
+    ("mouse_scroll", "Scroll the wheel: positive clicks up, negative down.",
+     {"clicks": {"type": "integer", "minimum": -elfmouse.MAX_SCROLL,
+                 "maximum": elfmouse.MAX_SCROLL}}, ["clicks"]),
+    ("mouse_hscroll", "Scroll horizontally: positive clicks right.",
+     {"clicks": {"type": "integer", "minimum": -elfmouse.MAX_SCROLL,
+                 "maximum": elfmouse.MAX_SCROLL}}, ["clicks"]),
+    ("mouse_release", "Release every held mouse button at once — the unstick "
+                      "button, for when a caller died mid-drag.",
+     {}, []),
+]
+TOOL_NAMES = {t[0] for t in TOOLS}
+TOOL_SCHEMAS = {name: (props, required) for name, _d, props, required in TOOLS}
+
+
+def _validate_args(name, args):
+    """Enforce the advertised schema at runtime: arguments must be an
+    object with exactly the known fields, correctly typed (a JSON true is
+    not an integer, whatever Python thinks), in range, and in the enum.
+    The daemon parser remains the final authority; this layer exists so a
+    bad call fails HERE, with a precise reason, before any FIFO write."""
+    if not isinstance(args, dict):
+        raise ValueError("arguments must be an object")
+    props, required = TOOL_SCHEMAS[name]
+    unknown = sorted(set(args) - set(props))
+    if unknown:
+        raise ValueError("unknown argument(s): %s" % ", ".join(unknown))
+    missing = [k for k in required if k not in args]
+    if missing:
+        raise ValueError("missing argument(s): %s" % ", ".join(missing))
+    for key, value in args.items():
+        schema = props[key]
+        if schema.get("type") == "integer":
+            if type(value) is not int:  # bool is an int subclass; exclude it
+                raise ValueError("%s must be an integer" % key)
+            if "minimum" in schema and value < schema["minimum"]:
+                raise ValueError("%s must be >= %d" % (key, schema["minimum"]))
+            if "maximum" in schema and value > schema["maximum"]:
+                raise ValueError("%s must be <= %d" % (key, schema["maximum"]))
+        elif schema.get("type") == "string":
+            if not isinstance(value, str):
+                raise ValueError("%s must be a string" % key)
+        if "enum" in schema and value not in schema["enum"]:
+            raise ValueError("%s must be one of: %s"
+                             % (key, ", ".join(map(str, schema["enum"]))))
+
+
+def tools_list():
+    return {"tools": [
+        {"name": name, "description": desc,
+         "inputSchema": {"type": "object", "properties": props,
+                         "required": required, "additionalProperties": False}}
+        for name, desc, props, required in TOOLS]}
+
+
+def call_tool(name, args):
+    """Returns (text, is_error)."""
+    if name not in TOOL_NAMES:
+        return "unknown tool: %s" % name, True
+    try:
+        _validate_args(name, args)
+    except ValueError as e:
+        return "invalid arguments: %s" % e, True
+    try:
+        if name.startswith("key_"):
+            return _send(KEY_FIFO, _key_line(name, args), elfkey.parse_command), False
+        if name.startswith("mouse_"):
+            return _send(MOUSE_FIFO, _mouse_line(name, args),
+                         elfmouse.parse_command), False
+        return _send(PAD_FIFO, _pad_line(name, args), elfpad.parse_command), False
+    except ValueError as e:
+        return "refused: %s" % e, True
+    except KeyError as e:
+        return "missing argument: %s" % e, True
+    except OSError as e:
+        if e.errno in (errno.ENXIO, errno.ENOENT):
+            return "daemon not running (no reader on the FIFO)", True
+        if e.errno == errno.EAGAIN:
+            return "daemon busy (FIFO full) — retry shortly", True
+        if e.errno in (errno.EACCES, errno.EPERM):
+            return ("permission denied on the FIFO — the daemons create it "
+                    "owner-only (0600); run this server as the same user"), True
+        if e.errno == errno.EPIPE:
+            return "daemon disconnected (broken pipe)", True
+        return "FIFO I/O error: %s" % (e.strerror or e), True
+
+
+def handle(msg):
+    """One JSON-RPC message -> response dict, or None for notifications."""
+    if not isinstance(msg, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {
+            "code": -32600, "message": "invalid request: not a JSON object"}}
+    method = msg.get("method")
+    msg_id = msg.get("id")
+    notification = "id" not in msg  # JSON-RPC: notifications get NO response,
+    if notification and method != "tools/call":  # not even errors or results
+        return None
+    if method == "initialize":
+        return {"jsonrpc": "2.0", "id": msg_id, "result": {
+            "protocolVersion": PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "elfdeckai", "version": "1.0.4"}}}
+    if method == "ping":
+        return {"jsonrpc": "2.0", "id": msg_id, "result": {}}
+    if method == "tools/list":
+        return {"jsonrpc": "2.0", "id": msg_id, "result": tools_list()}
+    if method == "tools/call":
+        params = msg.get("params") or {}
+        if not isinstance(params, dict) or not isinstance(params.get("name"), str) \
+                or ("arguments" in params and not isinstance(params["arguments"], dict)):
+            return {"jsonrpc": "2.0", "id": msg_id, "error": {
+                "code": -32602, "message": "invalid params: tools/call needs a "
+                "string name and an object arguments"}}
+        text, is_error = call_tool(params.get("name"), params.get("arguments") or {})
+        if notification:
+            return None  # the call executed; a notification is never answered
+        return {"jsonrpc": "2.0", "id": msg_id, "result": {
+            "content": [{"type": "text", "text": text}], "isError": is_error}}
+    if msg_id is None:
+        return None  # notification (e.g. notifications/initialized)
+    return {"jsonrpc": "2.0", "id": msg_id,
+            "error": {"code": -32601, "message": "method not found: %s" % method}}
+
+
+def _reject_constant(value):
+    raise ValueError("invalid JSON constant: %s" % value)
+
+
+MAX_REQUEST_BYTES = 1024 * 1024  # one request line; plenty for a tool call
+
+
+def main():
+    stream = sys.stdin.buffer
+    while True:
+        raw = stream.readline(MAX_REQUEST_BYTES + 1)
+        if not raw:
+            break
+        if len(raw) > MAX_REQUEST_BYTES:
+            while raw and not raw.endswith(b"\n"):
+                raw = stream.readline(MAX_REQUEST_BYTES + 1)
+            _emit({"jsonrpc": "2.0", "id": None, "error": {
+                "code": -32600, "message": "request too large"}})
+            continue
+        try:
+            line = raw.decode("utf-8").strip()
+        except UnicodeDecodeError:
+            _emit({"jsonrpc": "2.0", "id": None, "error": {
+                "code": -32700, "message": "parse error"}})
+            continue
+        if not line:
+            continue
+        try:
+            msg = json.loads(line, parse_constant=_reject_constant)
+        except ValueError:
+            _emit({"jsonrpc": "2.0", "id": None, "error": {
+                "code": -32700, "message": "parse error"}})
+            continue
+        try:
+            response = handle(msg)
+        except Exception:
+            response = {"jsonrpc": "2.0",
+                        "id": msg.get("id") if isinstance(msg, dict) else None,
+                        "error": {"code": -32603, "message": "internal error"}}
+        if response is not None:
+            _emit(response)
+
+
+def _emit(response):
+    sys.stdout.write(json.dumps(response) + "\n")
+    sys.stdout.flush()
+
+
+if __name__ == "__main__":
+    main()