cursor-agent-beacon 0.3.1__py3-none-any.whl

cursor_agent_beacon/__init__.py

@@ -0,0 +1,3 @@
+"""Cursor Agent Beacon — deterministic agent status via Cursor hooks."""
+
+__version__ = "0.3.1"

cursor_agent_beacon/bridge/__init__.py

@@ -0,0 +1,7 @@
+"""Local bridge service: HTTP status intake and serial output for ESP32."""
+
+from cursor_agent_beacon.bridge.config import BridgeConfig
+from cursor_agent_beacon.bridge.server import run_bridge_server
+from cursor_agent_beacon.bridge.service import BridgeService
+
+__all__ = ["BridgeConfig", "BridgeService", "run_bridge_server"]

cursor_agent_beacon/bridge/config.py

@@ -0,0 +1,54 @@
+"""Environment-driven configuration for the local bridge service."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+from cursor_agent_beacon.paths import default_themes_dir
+
+
+def default_bridge_url(host: str = "127.0.0.1", port: int = 8765) -> str:
+    return f"http://{host}:{port}/status"
+
+
+@dataclass(frozen=True, slots=True)
+class BridgeConfig:
+    """Runtime configuration for the bridge HTTP + serial service."""
+
+    host: str = "127.0.0.1"
+    port: int = 8765
+    serial_port: str | None = None
+    serial_baud: int = 115200
+    theme_id: str = "standard"
+    themes_dir: Path = Path("themes")
+
+    @property
+    def status_url(self) -> str:
+        return default_bridge_url(self.host, self.port)
+
+    @classmethod
+    def from_env(cls) -> BridgeConfig:
+        port_raw = os.environ.get("CURSOR_AGENT_BEACON_BRIDGE_PORT", "8765")
+        baud_raw = os.environ.get("CURSOR_AGENT_BEACON_SERIAL_BAUD", "115200")
+        serial_port = os.environ.get("CURSOR_AGENT_BEACON_SERIAL_PORT") or None
+
+        try:
+            port = int(port_raw)
+        except ValueError:
+            port = 8765
+
+        try:
+            baud = int(baud_raw)
+        except ValueError:
+            baud = 115200
+
+        return cls(
+            host=os.environ.get("CURSOR_AGENT_BEACON_BRIDGE_HOST", "127.0.0.1"),
+            port=port,
+            serial_port=serial_port,
+            serial_baud=baud,
+            theme_id=os.environ.get("CURSOR_AGENT_BEACON_THEME", "standard"),
+            themes_dir=default_themes_dir(),
+        )

cursor_agent_beacon/bridge/serial_writer.py

@@ -0,0 +1,88 @@
+"""Single-owner serial output for ESP32 commands."""
+
+from __future__ import annotations
+
+import queue
+import sys
+import threading
+from typing import Protocol
+
+
+class SerialWriter(Protocol):
+    def write_line(self, line: str) -> None: ...
+
+    def close(self) -> None: ...
+
+
+class DryRunSerialWriter:
+    """Log serial lines to stderr when no hardware port is configured."""
+
+    def write_line(self, line: str) -> None:
+        print(
+            f"[cursor-agent-beacon-bridge] serial: {line}",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    def close(self) -> None:
+        return
+
+
+class QueuedSerialWriter:
+    """Background thread that owns the USB serial port and drains a write queue."""
+
+    def __init__(self, port: str, baud: int) -> None:
+        try:
+            import serial
+        except ImportError as exc:
+            raise RuntimeError(
+                "pyserial is required for serial output. "
+                'Install with: pip install -e ".[bridge]"'
+            ) from exc
+
+        self._queue: queue.Queue[str | None] = queue.Queue()
+        self._serial = serial.Serial(port, baud, timeout=0.1)
+        self._closed = False
+        self._thread = threading.Thread(
+            target=self._run,
+            name="cursor-agent-beacon-serial",
+            daemon=True,
+        )
+        self._thread.start()
+
+    def write_line(self, line: str) -> None:
+        if self._closed:
+            return
+        self._queue.put(line)
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._queue.put(None)
+        self._thread.join(timeout=2.0)
+        self._serial.close()
+
+    def _run(self) -> None:
+        while True:
+            line = self._queue.get()
+            if line is None:
+                return
+            try:
+                self._serial.write(f"{line}\n".encode())
+                self._serial.flush()
+            except OSError as exc:
+                print(
+                    f"[cursor-agent-beacon-bridge] serial write failed: {exc}",
+                    file=sys.stderr,
+                    flush=True,
+                )
+
+
+def build_serial_writer(
+    serial_port: str | None,
+    baud: int,
+) -> SerialWriter:
+    if serial_port:
+        return QueuedSerialWriter(serial_port, baud)
+    return DryRunSerialWriter()

cursor_agent_beacon/bridge/server.py

@@ -0,0 +1,137 @@
+"""HTTP server exposing POST /status for the hook handler."""
+
+from __future__ import annotations
+
+import json
+import sys
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cursor_agent_beacon.bridge.service import BridgeService
+
+_MAX_BODY_BYTES = 64 * 1024
+
+
+def run_bridge_server(service: BridgeService, host: str, port: int) -> None:
+    handler = _make_handler(service)
+    server = ThreadingHTTPServer((host, port), handler)
+    server.daemon_threads = True
+
+    print(
+        f"[cursor-agent-beacon-bridge] listening on http://{host}:{port}",
+        file=sys.stderr,
+        flush=True,
+    )
+    print(
+        f"[cursor-agent-beacon-bridge] POST status to {service.config.status_url}",
+        file=sys.stderr,
+        flush=True,
+    )
+    if service.config.serial_port:
+        print(
+            f"[cursor-agent-beacon-bridge] serial port {service.config.serial_port} "
+            f"@ {service.config.serial_baud} baud",
+            file=sys.stderr,
+            flush=True,
+        )
+    else:
+        print(
+            "[cursor-agent-beacon-bridge] serial dry-run (set "
+            "CURSOR_AGENT_BEACON_SERIAL_PORT to enable hardware)",
+            file=sys.stderr,
+            flush=True,
+        )
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print(
+            "\n[cursor-agent-beacon-bridge] shutting down",
+            file=sys.stderr,
+            flush=True,
+        )
+    finally:
+        server.shutdown()
+        server.server_close()
+        service.close()
+
+
+def _make_handler(service: BridgeService) -> type[BaseHTTPRequestHandler]:
+    class BridgeHTTPRequestHandler(BaseHTTPRequestHandler):
+        server_version = "CursorAgentBeaconBridge/0.2"
+
+        def log_message(self, format: str, *args) -> None:  # noqa: A003
+            print(
+                f"[cursor-agent-beacon-bridge] {self.address_string()} - "
+                f"{format % args}",
+                file=sys.stderr,
+                flush=True,
+            )
+
+        def do_GET(self) -> None:  # noqa: N802
+            if self.path == "/health":
+                self._json_response(200, service.health())
+                return
+            if self.path == "/status":
+                latest = service.latest_status
+                if latest is None:
+                    self._json_response(404, {"ok": False, "error": "no status yet"})
+                    return
+                self._json_response(200, {"ok": True, "status": latest.to_dict()})
+                return
+            self._json_response(404, {"ok": False, "error": "not found"})
+
+        def do_POST(self) -> None:  # noqa: N802
+            if self.path != "/status":
+                self._json_response(404, {"ok": False, "error": "not found"})
+                return
+
+            length_raw = self.headers.get("Content-Length", "0")
+            try:
+                length = int(length_raw)
+            except ValueError:
+                self._json_response(
+                    400,
+                    {"ok": False, "error": "invalid Content-Length"},
+                )
+                return
+
+            if length > _MAX_BODY_BYTES:
+                self._json_response(
+                    413,
+                    {"ok": False, "error": "request body too large"},
+                )
+                return
+
+            raw = self.rfile.read(length)
+            try:
+                payload = json.loads(raw.decode("utf-8") or "{}")
+            except json.JSONDecodeError:
+                self._json_response(400, {"ok": False, "error": "invalid JSON"})
+                return
+
+            if "state" not in payload:
+                self._json_response(400, {"ok": False, "error": "missing state"})
+                return
+
+            try:
+                result = service.handle_status(payload)
+            except ValueError as exc:
+                self._json_response(400, {"ok": False, "error": str(exc)})
+                return
+            except Exception as exc:  # noqa: BLE001
+                self._json_response(500, {"ok": False, "error": str(exc)})
+                return
+
+            self._json_response(200, result)
+
+        def _json_response(self, code: int, payload: dict) -> None:
+            body = json.dumps(payload).encode("utf-8")
+            self.send_response(code)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(body)))
+            self.end_headers()
+            self.wfile.write(body)
+
+    return BridgeHTTPRequestHandler

cursor_agent_beacon/bridge/service.py

@@ -0,0 +1,88 @@
+"""Bridge business logic: theme resolution and serial command emission."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any
+
+from cursor_agent_beacon.bridge.config import BridgeConfig
+from cursor_agent_beacon.bridge.serial_writer import SerialWriter, build_serial_writer
+from cursor_agent_beacon.models import AgentStatus
+from cursor_agent_beacon.theme import ThemePack, load_theme
+
+
+class BridgeService:
+    """Resolve theme GIFs and forward normalized status to the serial writer."""
+
+    def __init__(
+        self,
+        config: BridgeConfig,
+        theme: ThemePack | None = None,
+        serial_writer: SerialWriter | None = None,
+    ) -> None:
+        self._config = config
+        self._theme = theme or load_theme(config.theme_id, config.themes_dir)
+        self._serial = serial_writer or build_serial_writer(
+            config.serial_port,
+            config.serial_baud,
+        )
+        self._lock = threading.Lock()
+        self._latest: AgentStatus | None = None
+        self._serial.write_line(f"THEME|{self._theme.theme_id}")
+
+    @property
+    def config(self) -> BridgeConfig:
+        return self._config
+
+    @property
+    def theme(self) -> ThemePack:
+        return self._theme
+
+    @property
+    def latest_status(self) -> AgentStatus | None:
+        return self._latest
+
+    def close(self) -> None:
+        self._serial.close()
+
+    def handle_status(self, payload: dict[str, Any]) -> dict[str, Any]:
+        status = AgentStatus.from_dict(payload)
+        animation = self._theme.animation_for(
+            status.state.value,
+            hook_event_name=status.hook_event_name,
+        )
+
+        serial_line = status.serial_line()
+        self._serial.write_line(serial_line)
+
+        with self._lock:
+            self._latest = status
+
+        gif_path: str | None = None
+        if animation is not None:
+            try:
+                gif_path = str(animation.path.relative_to(self._theme.root))
+            except ValueError:
+                gif_path = str(animation.path)
+
+        return {
+            "ok": True,
+            "serial": serial_line,
+            "theme_id": self._theme.theme_id,
+            "state": status.state.value,
+            "message": status.message,
+            "gif": gif_path,
+            "caption": animation.caption if animation else None,
+            "loop": animation.loop if animation else None,
+        }
+
+    def health(self) -> dict[str, Any]:
+        latest = self._latest
+        return {
+            "ok": True,
+            "theme_id": self._theme.theme_id,
+            "serial_port": self._config.serial_port,
+            "serial_baud": self._config.serial_baud,
+            "status_url": self._config.status_url,
+            "latest": latest.to_dict() if latest else None,
+        }

cursor_agent_beacon/cli.py

@@ -0,0 +1,289 @@
+"""CLI utilities for local testing and installation."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from cursor_agent_beacon.handler import (
+    handle_hook_event,
+    parse_hook_input,
+    run_hook_handler,
+)
+from cursor_agent_beacon.mapper import map_hook_event
+from cursor_agent_beacon.models import AgentStatus
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Cursor Agent Beacon hook utilities",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser(
+        "run",
+        help="Run the hook handler (reads JSON from stdin)",
+    )
+    run_parser.set_defaults(func=_run_handler)
+
+    map_parser = subparsers.add_parser(
+        "map",
+        help="Map a sample hook JSON file to agent status",
+    )
+    map_parser.add_argument("event_file", type=Path)
+    map_parser.set_defaults(func=_map_event)
+
+    bridge_parser = subparsers.add_parser(
+        "bridge",
+        help="Run the local HTTP + serial bridge service",
+    )
+    bridge_parser.set_defaults(func=_run_bridge)
+
+    install_hooks = subparsers.add_parser(
+        "install-hooks",
+        help="Install merge-safe user-level Cursor hooks",
+    )
+    install_hooks.set_defaults(func=_install_hooks)
+
+    install_gnome = subparsers.add_parser(
+        "install-gnome",
+        help="Install the GNOME Shell status panel extension",
+    )
+    install_gnome.set_defaults(func=_install_gnome)
+
+    install_desktop = subparsers.add_parser(
+        "install-desktop",
+        help="Install user hooks and GNOME panel",
+    )
+    install_desktop.set_defaults(func=_install_desktop)
+
+    setup_parser = subparsers.add_parser(
+        "setup",
+        help="Install user hooks and GNOME panel (after pip install)",
+    )
+    setup_parser.add_argument(
+        "--no-gnome",
+        action="store_true",
+        help="Skip GNOME Shell extension",
+    )
+    setup_parser.add_argument(
+        "--hooks-only",
+        action="store_true",
+        help="Install user hooks only",
+    )
+    setup_parser.add_argument(
+        "--beacon-bin",
+        type=Path,
+        default=None,
+        help="Path to cursor-agent-beacon executable for the hook wrapper",
+    )
+    setup_parser.set_defaults(func=_setup)
+
+    doctor_parser = subparsers.add_parser(
+        "doctor",
+        help="Verify hooks, wrapper, and status directory",
+    )
+    doctor_parser.add_argument(
+        "--probe",
+        action="store_true",
+        help="Run a sample hook event and verify status.json updates",
+    )
+    doctor_parser.set_defaults(func=_doctor)
+
+    status_parser = subparsers.add_parser(
+        "status",
+        help="Show the latest agent status snapshot",
+    )
+    status_parser.add_argument(
+        "--file",
+        type=Path,
+        default=None,
+        help="Status JSON path (default: user status file)",
+    )
+    status_parser.set_defaults(func=_status)
+
+    uninstall_parser = subparsers.add_parser(
+        "uninstall",
+        help="Remove user hooks and optional GNOME panel",
+    )
+    uninstall_parser.add_argument(
+        "--hooks-only",
+        action="store_true",
+        help="Remove hooks only (skip GNOME extension)",
+    )
+    uninstall_parser.add_argument(
+        "--no-gnome",
+        action="store_true",
+        help="Skip GNOME extension removal",
+    )
+    uninstall_parser.add_argument(
+        "--purge-status",
+        action="store_true",
+        help="Delete ~/.local/share/cursor-agent-beacon/",
+    )
+    uninstall_parser.set_defaults(func=_uninstall)
+
+    args = parser.parse_args()
+    return int(args.func(args))
+
+
+def _run_handler(_args: argparse.Namespace) -> int:
+    return run_hook_handler()
+
+
+def _map_event(args: argparse.Namespace) -> int:
+    payload = json.loads(args.event_file.read_text(encoding="utf-8"))
+    event = parse_hook_input(json.dumps(payload))
+    status = map_hook_event(event)
+    response = handle_hook_event(event, sink=_NullSink())
+
+    if status is None:
+        print("No status mapping for this hook.", file=sys.stderr)
+        return 1
+
+    print(json.dumps(status.to_dict(), indent=2))
+    print(json.dumps(response, indent=2))
+    return 0
+
+
+def _run_bridge(_args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.bridge.config import BridgeConfig
+    from cursor_agent_beacon.bridge.server import run_bridge_server
+    from cursor_agent_beacon.bridge.service import BridgeService
+
+    config = BridgeConfig.from_env()
+    service = BridgeService(config)
+    run_bridge_server(service, config.host, config.port)
+    return 0
+
+
+def _install_hooks(_args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.install import verify_package_installed, write_user_hooks
+
+    try:
+        verify_package_installed()
+        hooks_path = write_user_hooks()
+    except (RuntimeError, FileNotFoundError) as exc:
+        print(f"[cursor-agent-beacon] install-hooks failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"Hooks: {hooks_path}")
+    print("Restart Cursor after install.")
+    return 0
+
+
+def _install_gnome(_args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.install import install_gnome_extension
+
+    try:
+        dest = install_gnome_extension()
+    except FileNotFoundError as exc:
+        print(f"[cursor-agent-beacon] install-gnome failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"GNOME extension: {dest}")
+    print("Reload GNOME Shell if the panel does not update.")
+    return 0
+
+
+def _install_desktop(_args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.setup import format_next_steps, run_setup
+
+    try:
+        result = run_setup()
+    except (RuntimeError, FileNotFoundError) as exc:
+        print(f"[cursor-agent-beacon] install-desktop failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(format_next_steps(result))
+    return 0
+
+
+def _setup(args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.setup import format_next_steps, run_setup
+
+    try:
+        result = run_setup(
+            skip_gnome=args.no_gnome,
+            hooks_only=args.hooks_only,
+            beacon_bin=args.beacon_bin,
+        )
+    except (RuntimeError, FileNotFoundError) as exc:
+        print(f"[cursor-agent-beacon] setup failed: {exc}", file=sys.stderr)
+        return 1
+
+    print(format_next_steps(result))
+    return 0
+
+
+def _doctor(args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.doctor import (
+        doctor_exit_code,
+        format_doctor_report,
+        run_doctor,
+    )
+
+    results = run_doctor(probe=args.probe)
+    print(format_doctor_report(results))
+    return doctor_exit_code(results)
+
+
+def _status(args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.doctor import format_status_report, read_status_payload
+    from cursor_agent_beacon.install import DEFAULT_STATUS_FILE
+    from cursor_agent_beacon.session_registry import SessionRegistry
+
+    path = args.file or DEFAULT_STATUS_FILE
+    SessionRegistry(path.parent).reconcile()
+    try:
+        payload = read_status_payload(path)
+    except FileNotFoundError:
+        print(
+            f"[cursor-agent-beacon] no status at {path}\n"
+            "Run an Agent chat in Cursor, or: cursor-agent-beacon doctor --probe",
+            file=sys.stderr,
+        )
+        return 1
+    except json.JSONDecodeError as exc:
+        print(f"[cursor-agent-beacon] invalid JSON in {path}: {exc}", file=sys.stderr)
+        return 1
+
+    print(format_status_report(payload, status_file=path))
+    return 0
+
+
+def _uninstall(args: argparse.Namespace) -> int:
+    from cursor_agent_beacon.install import uninstall_desktop
+
+    result = uninstall_desktop(
+        hooks_only=args.hooks_only,
+        skip_gnome=args.no_gnome,
+        keep_status=not args.purge_status,
+    )
+
+    lines = ["Uninstall complete.", ""]
+    if result["hooks_path"] is not None:
+        lines.append(f"Removed hooks from: {result['hooks_path']}")
+    else:
+        lines.append("Hooks: no beacon entries found")
+    if result["gnome_path"] is not None:
+        lines.append(f"Removed GNOME panel: {result['gnome_path']}")
+    elif not args.hooks_only and not args.no_gnome:
+        lines.append("GNOME panel: not installed")
+    if result["status_dir"] is not None:
+        lines.append(f"Removed status data: {result['status_dir']}")
+    lines.append("")
+    lines.append("Restart Cursor to stop loading beacon hooks.")
+    print("\n".join(lines))
+    return 0
+
+
+class _NullSink:
+    def publish(self, status: AgentStatus) -> None:
+        return
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cursor_agent_beacon/compat.py

@@ -0,0 +1,13 @@
+"""Python version compatibility helpers."""
+
+from __future__ import annotations
+
+import sys
+from enum import Enum
+
+if sys.version_info >= (3, 11):
+    from enum import StrEnum
+else:
+
+    class StrEnum(str, Enum):
+        """Backport of enum.StrEnum for Python 3.10."""