pitwall-agents 0.1.0__py3-none-any.whl

pitwall/__init__.py

@@ -0,0 +1,2 @@
+"""pitwall: a pit wall for your coding agents."""
+__version__ = "0.1.0"

pitwall/agents/__init__.py

@@ -0,0 +1 @@
+"""Agent plug-ins: map an agent's own events to pitwall session events."""

pitwall/agents/claude_code.py

@@ -0,0 +1,50 @@
+"""Claude Code hooks → pitwall session events.
+
+Only ids, the folder and the terminal tab leave this module. Prompts, tool input
+and output, and assistant messages are never read.
+"""
+from __future__ import annotations
+
+import os
+from typing import Mapping
+
+AGENT = "claude-code"
+
+_EVENT_STATE = {
+    "UserPromptSubmit": "green",
+    "PreToolUse": "green",
+    "PostToolUse": "green",
+    "PermissionRequest": "box",
+    "Stop": "done",
+    "StopFailure": "red",
+    "SessionStart": "done",
+    "SessionEnd": "end",
+}
+_NOTIFICATION_STATE = {"permission_prompt": "box", "elicitation_dialog": "box",
+                       # Stop doesn't run when the user interrupts a turn; idle_prompt covers it
+                       "idle_prompt": "done"}
+
+
+def iterm_ref(env: Mapping[str, str]) -> dict | None:
+    raw = env.get("ITERM_SESSION_ID") or ""
+    ref = raw.split(":", 1)[-1].strip()
+    return {"kind": "iterm2", "ref": ref} if ref else None
+
+
+def map_hook(payload: dict, env: Mapping[str, str]) -> dict | None:
+    if not isinstance(payload, dict):
+        return None
+    sid = payload.get("session_id")
+    event = payload.get("hook_event_name")
+    if not isinstance(sid, str) or not sid:
+        return None
+    if event == "Notification":
+        state = _NOTIFICATION_STATE.get(payload.get("notification_type"))
+    else:
+        state = _EVENT_STATE.get(event)
+    if state is None:
+        return None
+    cwd = payload.get("cwd") if isinstance(payload.get("cwd"), str) else ""
+    label = os.path.basename(cwd.rstrip("/")) or "session"
+    return {"type": "session", "agent": AGENT, "id": sid, "state": state,
+            "label": label, "cwd": cwd, "terminal": iterm_ref(env)}

pitwall/agents/claude_settings.py

@@ -0,0 +1,119 @@
+"""Add or remove pitwall's hooks in Claude Code's settings.json, safely."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+EVENTS = ("SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest",
+          "Notification", "Stop", "StopFailure", "SessionEnd")
+_MATCHER_EVENTS = {"PreToolUse", "PostToolUse", "PermissionRequest"}
+
+
+class SettingsError(Exception):
+    pass
+
+
+@dataclass
+class InstallResult:
+    changed: bool
+    backup: Path | None
+
+
+def default_settings_path() -> Path:
+    return Path.home() / ".claude" / "settings.json"
+
+
+def hook_command() -> str:
+    return shutil.which("pitwall-hook") or "pitwall-hook"
+
+
+def _is_pitwall(cmd: str) -> bool:
+    return "pitwall-hook" in cmd or cmd.rstrip().endswith("pitwall hook")
+
+
+def _load(path: Path) -> dict:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text() or "{}")
+    except ValueError as e:
+        raise SettingsError(f"{path} is not valid JSON ({e}); fix it first, nothing was changed") from e
+    if not isinstance(data, dict):
+        raise SettingsError(f"{path} must contain a JSON object; nothing was changed")
+    hooks = data.get("hooks", {})
+    if not isinstance(hooks, dict):
+        raise SettingsError(f'"hooks" in {path} must be an object; nothing was changed')
+    return data
+
+
+def _strip(hooks: dict) -> dict:
+    """Return hooks with every pitwall command removed (and emptied entries dropped)."""
+    out = {}
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            out[event] = entries
+            continue
+        kept = []
+        for entry in entries:
+            if not isinstance(entry, dict) or not isinstance(entry.get("hooks"), list):
+                kept.append(entry)
+                continue
+            inner = [h for h in entry["hooks"]
+                     if not (isinstance(h, dict) and _is_pitwall(str(h.get("command", ""))))]
+            if inner:
+                kept.append({**entry, "hooks": inner})
+            elif not entry["hooks"]:
+                kept.append(entry)
+        if kept:
+            out[event] = kept
+    return out
+
+
+def _write(path: Path, original: str | None, data: dict) -> Path | None:
+    link = path
+    path = path.resolve()  # keep a symlinked settings.json a symlink (dotfiles)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mode = path.stat().st_mode & 0o777 if path.exists() else 0o644
+    backup = None
+    if original is not None:
+        backup = link.with_name(f"{link.name}.pitwall-bak-{time.strftime('%Y%m%d-%H%M%S')}")
+        backup.write_text(original)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".settings.", suffix=".tmp")
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    os.chmod(tmp, mode)
+    os.replace(tmp, path)
+    return backup
+
+
+def install(settings_path: Path, command: str) -> InstallResult:
+    data = _load(settings_path)
+    original = settings_path.read_text() if settings_path.exists() else None
+    hooks = _strip(data.get("hooks", {}))
+    for event in EVENTS:
+        entry: dict = {"hooks": [{"type": "command", "command": command, "timeout": 5}]}
+        if event in _MATCHER_EVENTS:
+            entry = {"matcher": "", **entry}
+        hooks.setdefault(event, []).append(entry)
+    new = {**data, "hooks": hooks}
+    if new == data:
+        return InstallResult(False, None)
+    return InstallResult(True, _write(settings_path, original, new))
+
+
+def uninstall(settings_path: Path) -> InstallResult:
+    if not settings_path.exists():
+        return InstallResult(False, None)
+    data = _load(settings_path)
+    original = settings_path.read_text()
+    hooks = _strip(data.get("hooks", {}))
+    new = {**data, "hooks": hooks} if hooks else {k: v for k, v in data.items() if k != "hooks"}
+    if new == data:
+        return InstallResult(False, None)
+    return InstallResult(True, _write(settings_path, original, new))

pitwall/badge_app/__init__.py

@@ -0,0 +1,239 @@
+# pitwall: a pit wall for your coding agents, on the GitHub Universe badge.
+# Shows every agent session's state and focuses its terminal tab on a button press.
+import math
+
+import links
+import model
+
+badge.mode(HIRES | VSYNC)
+
+try:
+    import missing_details
+    FONT = missing_details.mona_sans()
+except Exception:
+    FONT = None
+
+UID = badge.uid if isinstance(badge.uid, str) else "".join("%02x" % b for b in badge.uid)
+CAPS = {"display": [320, 240], "color": True,
+        "buttons": ["up", "down", "left", "right", "select"], "keys": 0, "led": True}
+
+bg = color.rgb(12, 14, 20)
+panel = color.rgb(30, 34, 46)
+white = color.rgb(238, 240, 246)
+dim = color.rgb(238, 240, 246, 110)
+faint = color.rgb(238, 240, 246, 50)
+sub = color.rgb(238, 240, 246, 165)
+amber = color.rgb(255, 196, 40)
+red = color.rgb(240, 70, 70)
+green = color.rgb(80, 210, 110)
+black = color.rgb(20, 20, 20)
+
+STATE_PEN = {"box": amber, "red": red, "green": green}
+STATE_WORD = {"red": "failed", "done": "done", "green": "working"}
+
+ROW_TOP, ROW_H, ROWS = 27, 31, 6
+FOOT_Y = 215
+
+view = model.View()
+usb = links.Usb()
+try:
+    ble = links.Ble(UID, {"type": "hello", "device": "badger2350", "uid": UID, "transport": "ble", "caps": CAPS})
+except Exception as e:
+    print("pitwall: bluetooth unavailable", e)
+    ble = None
+
+last_rx = {"usb": None, "ble": None}
+last_hello_ms = -10000
+
+
+def hello(transport):
+    return {"type": "hello", "device": "badger2350", "uid": UID, "transport": transport, "caps": CAPS}
+
+
+def active_transport(now):
+    if last_rx["usb"] is not None and now - last_rx["usb"] <= model.STALE_MS:
+        return "usb"
+    if ble is not None and ble.authed:
+        return "ble"
+    return None
+
+
+def send(msg, now):
+    t = active_transport(now)
+    if t == "usb":
+        usb.send(msg)
+    elif t == "ble":
+        ble.send(msg)
+
+
+def handle(msg, transport, now):
+    kind = msg.get("type")
+    if kind == "hello":
+        if transport == "usb":
+            usb.send(hello("usb"))
+        return
+    if kind == "pair_key" and transport == "usb":
+        # USB is a local cable: the helper hands over its Bluetooth key here
+        try:
+            host, key = msg["host"], bytes.fromhex(msg["key"])
+        except Exception:
+            return
+        if len(key) == 32:
+            if ble is not None:
+                ble.add_key(host, key)
+            else:
+                keys = links.load_keys()
+                keys[host] = key
+                links.save_keys(keys)
+            usb.send({"type": "paired", "host": host})
+        return
+    if kind in ("board", "alert"):
+        last_rx[transport] = now
+        # while USB is live, ignore a stale BLE board (the helper only talks on one anyway)
+        if transport == "ble" and active_transport(now) == "usb":
+            return
+        view.on_message(msg, now)
+
+
+def text(s, x, y, size, pen):
+    screen.pen = pen
+    screen.text(s, x, y, size)
+
+
+def text_w(s, size):
+    return screen.measure_text(s, size)[0]
+
+
+def chip(state, x, y, s, flash):
+    if state == "done":
+        half = s / 2
+        for i in range(2):
+            for j in range(2):
+                screen.pen = white if (i + j) % 2 == 0 else black
+                screen.shape(shape.rectangle(x + i * half, y + j * half, half, half))
+        return
+    pen = STATE_PEN.get(state, dim)
+    if state == "box" and flash:
+        pen = white
+    screen.pen = pen
+    screen.shape(shape.rounded_rectangle(x, y, s, s, 3))
+
+
+def draw_header(now):
+    screen.pen = panel
+    screen.shape(shape.rectangle(0, 0, 320, 24))
+    x = 8
+    for state in ("box", "red", "done", "green"):
+        chip(state, x, 6, 12, False)
+        n = str(view.counts.get(state, 0))
+        text(n, x + 16, 4, 14, white)
+        x += 26 + text_w(n, 14)
+    t = active_transport(now)
+    link = "USB" if t == "usb" else ("BT" if t == "ble" else "--")
+    try:
+        level = int(badge.battery_level())
+    except Exception:
+        level = None
+    right = link + ("  %d%%" % level if level is not None else "")
+    if len(view.sessions) > ROWS:
+        right = "%d/%d   " % (view.cursor + 1, len(view.sessions)) + right
+    text(right, 312 - text_w(right, 12), 6, 12, dim if t else red)
+
+
+def fit(s, size, max_w):
+    """Cut text to fit max_w pixels, with an ellipsis."""
+    s = str(s)
+    if text_w(s, size) <= max_w:
+        return s
+    while s and text_w(s + "…", size) > max_w:
+        s = s[:-1]
+    return s + "…"
+
+
+def draw_rows(now, stale):
+    rows = view.rows(ROWS)
+    if not rows:
+        msg = "No agent sessions yet" if not stale else "Waiting for pit wall…"
+        text(msg, 160 - text_w(msg, 16) / 2, 105, 16, dim)
+        return
+    flash = view.alerting(now) and (now // 250) % 2 == 0
+    for idx, (i, s, selected) in enumerate(rows):
+        y = ROW_TOP + idx * ROW_H
+        if selected:
+            screen.pen = panel
+            screen.shape(shape.rounded_rectangle(4, y, 312, ROW_H - 2, 6))
+        state = s.get("state", "")
+        chip(state, 12, y + 8, 13, flash and s.get("id") == view.alert_id)
+        if state == "box":
+            right, rpen = model.fmt_age(s.get("age_s", 0)), amber
+        else:
+            right, rpen = STATE_WORD.get(state, ""), dim
+        rw = text_w(right, 12)
+        text(right, 308 - rw, y + 9, 12, rpen if not stale else faint)
+        max_w = 308 - rw - 10 - 34
+        live = s.get("focusable", True) and not stale
+        title, folder = s.get("title"), str(s.get("label", ""))
+        if title and title.strip().lower() != folder.strip().lower():
+            text(fit(title, 14, max_w), 34, y + 2, 14, white if live else dim)
+            text(fit(folder, 11, max_w), 34, y + 17, 11, sub if live else faint)
+        else:
+            text(fit(title or folder, 14, max_w), 34, y + 8, 14, white if live else dim)
+
+
+def draw_footer(stale):
+    screen.pen = red if stale else panel
+    screen.shape(shape.rectangle(0, FOOT_Y + 2, 320, 240 - FOOT_Y - 2))
+    if stale:
+        msg = "No connection to pit wall"
+        text(msg, 160 - text_w(msg, 12) / 2, FOOT_Y + 5, 12, white)
+        return
+    x = 8
+    for key, what in (("SELECT", "focus"), ("RIGHT", "next box box"), ("LEFT", "top")):
+        text(key, x, FOOT_Y + 5, 12, amber)
+        x += text_w(key, 12) + 4
+        text(what, x, FOOT_Y + 5, 12, white)
+        x += text_w(what, 12) + 12
+
+
+def update():
+    global last_hello_ms
+    now = badge.ticks
+    for m in usb.read():
+        handle(m, "usb", now)
+    if ble is not None:
+        for m in ble.read():
+            handle(m, "ble", now)
+
+    if badge.pressed(BUTTON_UP):
+        view.move(-1)
+    elif badge.pressed(BUTTON_DOWN):
+        view.move(1)
+    elif badge.pressed(BUTTON_LEFT):
+        view.move(-len(view.sessions))
+    elif badge.pressed(BUTTON_SELECT):
+        sid = view.selected_id()
+        if sid:
+            send({"type": "focus", "id": sid}, now)
+    elif badge.pressed(BUTTON_RIGHT):
+        send({"type": "focus_next_waiting"}, now)
+
+    stale = view.stale(now)
+    if stale and now - last_hello_ms > 5000:
+        usb.send(hello("usb"))  # the helper may have missed our first hello
+        last_hello_ms = now
+
+    try:
+        badge.caselights((0.5 + 0.5 * math.sin(now / 120)) if view.alerting(now) else 0)
+    except Exception:
+        pass
+
+    if FONT is not None:
+        screen.font = FONT
+    screen.pen = bg
+    screen.clear()
+    draw_header(now)
+    draw_rows(now, stale)
+    draw_footer(stale)
+
+
+run(update)

pitwall/badge_app/links.py

@@ -0,0 +1,179 @@
+# pitwall badge: USB serial and Bluetooth LE links.
+import json
+import os
+import select
+import sys
+import time
+
+import bluetooth
+import model
+import seal
+
+KEYS_FILE = "/state/pitwall_keys.json"
+
+_SERVICE = bluetooth.UUID("6f1c0001-9b2a-4c55-8f3e-70697477616c")
+_RX = (bluetooth.UUID("6f1c0002-9b2a-4c55-8f3e-70697477616c"), 0x0008 | 0x0004)  # write, write-no-response
+_TX = (bluetooth.UUID("6f1c0003-9b2a-4c55-8f3e-70697477616c"), 0x0010)           # notify
+
+_IRQ_CENTRAL_CONNECT = 1
+_IRQ_CENTRAL_DISCONNECT = 2
+_IRQ_GATTS_WRITE = 3
+_IRQ_MTU_EXCHANGED = 21
+
+
+def _line(msg):
+    m = dict(msg)
+    m["v"] = 1
+    return json.dumps(m).encode() + b"\n"
+
+
+class Usb:
+    transport = "usb"
+
+    def __init__(self):
+        self.poll = select.poll()
+        self.poll.register(sys.stdin, select.POLLIN)
+        self.dec = model.Decoder()
+        self.stdin = getattr(sys.stdin, "buffer", sys.stdin)
+
+    def read(self):
+        data = b""
+        while len(data) < 2048 and self.poll.poll(0):
+            c = self.stdin.read(1)
+            if not c:
+                break
+            data += c if isinstance(c, bytes) else c.encode()
+        return self.dec.feed(data) if data else []
+
+    def send(self, msg):
+        try:
+            sys.stdout.write(_line(msg).decode())
+        except Exception:
+            pass
+
+
+def load_keys():
+    try:
+        with open(KEYS_FILE) as f:
+            return {h: bytes.fromhex(k) for h, k in json.load(f).items()}
+    except Exception:
+        return {}
+
+
+def save_keys(keys):
+    try:
+        with open(KEYS_FILE, "w") as f:
+            json.dump({h: k.hex() for h, k in keys.items()}, f)
+    except Exception as e:
+        print("pitwall: could not save keys", e)
+
+
+def _adv(adv_type, value):
+    return bytes((len(value) + 1, adv_type)) + value
+
+
+class Ble:
+    transport = "ble"
+
+    def __init__(self, uid, hello):
+        self.uid = uid
+        self.hello = hello
+        self.name = "pitwall-" + uid[:8]
+        self.keys = load_keys()
+        self.ble = bluetooth.BLE()
+        self.ble.active(True)
+        try:
+            self.ble.config(gap_name=self.name, mtu=247)
+        except Exception:
+            self.ble.config(gap_name=self.name)
+        self.ble.irq(self._irq)
+        ((self.h_tx, self.h_rx),) = self.ble.gatts_register_services(((_SERVICE, (_TX, _RX)),))
+        self.ble.gatts_set_buffer(self.h_rx, 512, True)
+        self.conn = None
+        self.mtu = 23
+        self.inbox = b""
+        self._reset()
+        self._advertise()
+
+    def _reset(self):
+        self.dec = model.Decoder()
+        self.auth = seal.DeviceAuth(self.uid, self.keys, os.urandom)
+        self.sealer = None
+        self.opener = None
+
+    def add_key(self, host, key):
+        """Called when the helper sends this Mac's key over USB."""
+        if self.keys.get(host) != key:
+            self.keys[host] = key
+            save_keys(self.keys)
+
+    @property
+    def authed(self):
+        return self.sealer is not None
+
+    def _advertise(self):
+        flags = _adv(0x01, b"\x06")
+        uuid = _adv(0x07, bytes(reversed(bytes.fromhex("6f1c00019b2a4c558f3e70697477616c"))))
+        name = _adv(0x09, self.name.encode())
+        try:
+            self.ble.gap_advertise(200_000, adv_data=flags + uuid, resp_data=name)
+        except Exception as e:
+            print("pitwall: advertise failed", e)
+
+    def _irq(self, event, data):
+        if event == _IRQ_CENTRAL_CONNECT:
+            self.conn = data[0]
+            self._reset()
+        elif event == _IRQ_CENTRAL_DISCONNECT:
+            self.conn = None
+            self._reset()
+            self._advertise()
+        elif event == _IRQ_GATTS_WRITE:
+            self.inbox += self.ble.gatts_read(self.h_rx)
+        elif event == _IRQ_MTU_EXCHANGED:
+            self.mtu = data[1]
+
+    def _notify(self, data):
+        if self.conn is None:
+            return
+        size = max(20, self.mtu - 3)
+        for i in range(0, len(data), size):
+            for _ in range(20):
+                try:
+                    self.ble.gatts_notify(self.conn, self.h_tx, data[i:i + size])
+                    break
+                except OSError:
+                    time.sleep_ms(5)
+
+    def _raw(self, msg):
+        self._notify(_line(msg))
+
+    def send(self, msg):
+        if self.sealer is not None:
+            self._notify(_line(self.sealer.seal(_line(msg).rstrip(b"\n"))))
+
+    def read(self):
+        """Returns app messages (only after auth). Handles the handshake itself."""
+        if not self.inbox:
+            return []
+        data, self.inbox = self.inbox, b""
+        out = []
+        for m in self.dec.feed(data):
+            kind = m.get("type")
+            if kind == "sealed":
+                if self.opener is not None:
+                    line = self.opener.open(m)
+                    if line is not None:
+                        out += model.Decoder().feed(line + b"\n")
+            elif kind == "hello" and not self.authed:
+                self._raw(self.hello)
+                self._raw(self.auth.challenge())
+            elif kind == "auth" and not self.authed:
+                dn = self.auth.nonce
+                reply, host, skey = self.auth.handle(m)
+                self._raw(reply)
+                if host:
+                    hn = bytes.fromhex(m["hn"])
+                    self.sealer = seal.Sealer(skey, dn + hn, "d2h")
+                    self.opener = seal.Opener(skey, dn + hn, "h2d")
+        return out

pitwall/badge_app/model.py

@@ -0,0 +1,98 @@
+# pitwall badge: pure state (no hardware). Runs on MicroPython and CPython (tests).
+import json
+
+STALE_MS = 15000
+ALERT_MS = 3000
+
+
+class Decoder:
+    """Bytes in, protocol messages out. Skips anything that isn't a v1 JSON object."""
+
+    def __init__(self):
+        self.buf = b""
+
+    def feed(self, data):
+        self.buf += data
+        out = []
+        while b"\n" in self.buf:
+            line, self.buf = self.buf.split(b"\n", 1)
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                msg = json.loads(line.decode("utf-8"))
+            except Exception:
+                continue
+            if isinstance(msg, dict) and msg.get("v") == 1:
+                out.append(msg)
+        if len(self.buf) > 16384:
+            self.buf = b""
+        return out
+
+
+def fmt_age(s):
+    s = max(0, int(s))
+    if s < 60:
+        return "%ds" % s
+    if s < 3600:
+        return "%dm" % (s // 60)
+    return "%dh%02d" % (s // 3600, (s % 3600) // 60)
+
+
+class View:
+    def __init__(self):
+        self.sessions = []
+        self.counts = {"box": 0, "red": 0, "done": 0, "green": 0}
+        self.cursor = 0
+        self.top = 0
+        self.last_board_ms = None
+        self.alert_ms = None
+        self.alert_id = None
+
+    def on_message(self, msg, now_ms):
+        kind = msg.get("type")
+        if kind == "board":
+            keep = self.selected_id()
+            self.sessions = msg.get("sessions") or []
+            self.counts = msg.get("counts") or self.counts
+            self.last_board_ms = now_ms
+            ids = [s.get("id") for s in self.sessions]
+            if keep in ids:
+                self.cursor = ids.index(keep)
+            self._clamp()
+        elif kind == "alert":
+            self.alert_ms = now_ms
+            self.alert_id = msg.get("id")
+
+    def _clamp(self):
+        n = len(self.sessions)
+        self.cursor = 0 if n == 0 else max(0, min(self.cursor, n - 1))
+
+    def move(self, delta):
+        self.cursor += delta
+        self._clamp()
+
+    def selected_id(self):
+        if not self.sessions:
+            return None
+        return self.sessions[self.cursor].get("id")
+
+    def rows(self, max_rows=8):
+        n = len(self.sessions)
+        if n == 0:
+            return []
+        if self.cursor < self.top:
+            self.top = self.cursor
+        elif self.cursor >= self.top + max_rows:
+            self.top = self.cursor - max_rows + 1
+        self.top = max(0, min(self.top, max(0, n - max_rows)))
+        out = []
+        for i in range(self.top, min(n, self.top + max_rows)):
+            out.append((i, self.sessions[i], i == self.cursor))
+        return out
+
+    def stale(self, now_ms):
+        return self.last_board_ms is None or now_ms - self.last_board_ms > STALE_MS
+
+    def alerting(self, now_ms):
+        return self.alert_ms is not None and now_ms - self.alert_ms < ALERT_MS