voxa-code 0.1.0__py3-none-any.whl

server/hooks.py

@@ -0,0 +1,202 @@
+"""Claude Code hook integration.
+
+The reliable, terminal-agnostic way to know a Claude session finished or needs
+input is Claude Code's own lifecycle hooks (Stop / Notification), not screen
+scraping. We install a global hook in ~/.claude/settings.json that POSTs the
+hook's stdin JSON to the local Voxa server's /hook endpoint; the server then
+rings the phone (or speaks, if a line is attached) exactly like the watcher did.
+
+This module is pure/host-agnostic so it is fully unit-testable:
+  - last_assistant_text: pull a spoken summary from a transcript JSONL
+  - route_hook: decide what (if anything) to announce for a hook event
+  - merge_hook / install_claude_hook / uninstall_claude_hook: edit settings.json
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+
+# Identifies OUR hook entries inside settings.json so install is idempotent and
+# uninstall is precise (it is a shell comment on the command, ignored at runtime).
+MARKER = "voxa-hook"
+
+# Events we register globally. Stop = finished a turn; Notification = needs
+# permission / input; UserPromptSubmit = turn start (lets us time the turn so a
+# quick interactive exchange doesn't ring the phone).
+HOOK_EVENTS = ("Stop", "Notification", "UserPromptSubmit")
+
+
+def last_assistant_text(transcript_path: str, max_len: int = 240) -> str:
+    """Return the last assistant message's text from a Claude transcript JSONL, as a
+    short spoken summary. Empty string if unreadable or none found."""
+    if not transcript_path or not os.path.exists(transcript_path):
+        return ""
+    last = ""
+    try:
+        with open(transcript_path, "r", encoding="utf-8", errors="ignore") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    continue
+                if obj.get("type") != "assistant":
+                    continue
+                msg = obj.get("message") or {}
+                content = msg.get("content")
+                if isinstance(content, str):
+                    text = content
+                elif isinstance(content, list):
+                    text = " ".join(
+                        b.get("text", "") for b in content
+                        if isinstance(b, dict) and b.get("type") == "text"
+                    )
+                else:
+                    text = ""
+                text = " ".join(text.split())
+                if text:
+                    last = text
+    except OSError:
+        return ""
+    return last[:max_len]
+
+
+def _label_for(cwd: str) -> str:
+    return os.path.basename((cwd or "").rstrip("/"))
+
+
+def route_hook(body: dict, *, turn_start: dict, hook_last: dict, now: float,
+               min_seconds: float = 30.0, cooldown: float = 8.0,
+               read_transcript=last_assistant_text):
+    """Decide the announcement for a Claude Code hook event, or None to stay silent.
+
+    Mutates ``turn_start`` (per-session turn start time) and ``hook_last`` (per-session
+    last-announced time, for debounce). Pure otherwise, so it is easy to unit test.
+
+    - UserPromptSubmit -> record turn start, announce nothing.
+    - Stop -> announce "finished" UNLESS the turn was shorter than ``min_seconds`` (a
+      quick interactive exchange) or within the debounce ``cooldown``.
+    - Notification -> announce "needs input" (debounced).
+    """
+    event = body.get("hook_event_name") or body.get("hook_event") or ""
+    session = body.get("session_id") or ""
+    label = _label_for(body.get("cwd") or "")
+
+    if event == "UserPromptSubmit":
+        turn_start[session] = now
+        return None
+
+    if event == "Stop":
+        start = turn_start.pop(session, None)
+        if start is not None and (now - start) < min_seconds:
+            return None  # quick interactive turn: don't call
+        if now - hook_last.get(session, float("-inf")) < cooldown:
+            return None  # debounce repeated stops
+        hook_last[session] = now
+        summary = read_transcript(body.get("transcript_path", ""))
+        return f"{label or 'a session'} finished" + (f": {summary}" if summary else "")
+
+    if event == "Notification":
+        if now - hook_last.get(session, float("-inf")) < cooldown:
+            return None
+        hook_last[session] = now
+        summary = (body.get("message") or "").strip()
+        return f"{label or 'Claude'} needs input" + (f": {summary}" if summary else "")
+
+    return None
+
+
+# --------------------------------------------------------------------------
+# settings.json install / uninstall
+# --------------------------------------------------------------------------
+
+
+def hook_command(url: str) -> str:
+    """The shell command Claude Code runs for the hook: POST the event's stdin JSON to
+    the Voxa server. `; true` keeps the hook exit code 0 (a down server never blocks
+    Claude); the trailing comment is our MARKER for idempotent install/uninstall."""
+    return (f"curl -s -m 5 -X POST {shlex.quote(url)} "
+            f"-H 'Content-Type: application/json' --data-binary @- >/dev/null 2>&1 "
+            f"; true  # {MARKER}")
+
+
+def _is_ours(entry: dict) -> bool:
+    try:
+        return any(MARKER in (h.get("command") or "") for h in entry.get("hooks", []))
+    except (AttributeError, TypeError):
+        return False
+
+
+def merge_hook(settings: dict, url: str) -> dict:
+    """Return settings with our Stop/Notification/UserPromptSubmit hooks merged in,
+    replacing any prior Voxa entries and preserving every other hook. Pure."""
+    out = dict(settings or {})
+    hooks = {k: list(v) for k, v in (out.get("hooks") or {}).items()}
+    entry = {"hooks": [{"type": "command", "command": hook_command(url)}]}
+    for event in HOOK_EVENTS:
+        kept = [e for e in hooks.get(event, []) if not _is_ours(e)]
+        kept.append(entry)
+        hooks[event] = kept
+    out["hooks"] = hooks
+    return out
+
+
+def remove_hook(settings: dict) -> dict:
+    """Return settings with all Voxa hook entries removed; other hooks untouched."""
+    out = dict(settings or {})
+    hooks = {k: [e for e in v if not _is_ours(e)] for k, v in (out.get("hooks") or {}).items()}
+    hooks = {k: v for k, v in hooks.items() if v}  # drop now-empty event lists
+    if hooks:
+        out["hooks"] = hooks
+    else:
+        out.pop("hooks", None)
+    return out
+
+
+def _load(settings_path: str) -> dict:
+    """Load settings.json. Missing/empty -> {}. A malformed EXISTING file RAISES rather
+    than returning {}, so callers never overwrite (and destroy) a real config they
+    couldn't parse."""
+    if not os.path.exists(settings_path):
+        return {}
+    with open(settings_path, "r", encoding="utf-8") as f:
+        raw = f.read()
+    if not raw.strip():
+        return {}
+    data = json.loads(raw)  # raises ValueError on malformed -> do NOT clobber
+    if not isinstance(data, dict):
+        raise ValueError("settings.json is not a JSON object")
+    return data
+
+
+def _save(settings_path: str, data: dict) -> None:
+    os.makedirs(os.path.dirname(settings_path) or ".", exist_ok=True)
+    tmp = settings_path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    os.replace(tmp, settings_path)
+
+
+def install_claude_hook(settings_path: str, url: str) -> None:
+    """Idempotently install the Voxa hooks into a Claude Code settings.json."""
+    _save(settings_path, merge_hook(_load(settings_path), url))
+
+
+def uninstall_claude_hook(settings_path: str) -> None:
+    """Remove the Voxa hooks from a Claude Code settings.json (leaves others)."""
+    if os.path.exists(settings_path):
+        _save(settings_path, remove_hook(_load(settings_path)))
+
+
+def default_settings_path() -> str:
+    return os.path.expanduser("~/.claude/settings.json")
+
+
+def hook_url(host: str, port: int, token: str) -> str:
+    """The local /hook URL the installed hook POSTs to (always loopback)."""
+    from urllib.parse import quote
+    return f"http://127.0.0.1:{port}/hook?token={quote(token, safe='')}"

server/orchestrator.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from typing import Awaitable, Callable
+
+logger = logging.getLogger(__name__)
+
+Speak = Callable[[str], Awaitable[None]]
+NotifyUI = Callable[[dict], Awaitable[None]]
+
+
+def suggest_dirs(path: str, limit: int = 12) -> tuple[str, list[str]]:
+    """Find the deepest existing ancestor of ``path`` and list its subdirectories.
+
+    Used to help the user when a spoken folder path is wrong: the operator can
+    read these back as suggestions.
+    """
+    p = os.path.abspath(os.path.expanduser(path or "~"))
+    while p and not os.path.isdir(p):
+        parent = os.path.dirname(p)
+        if parent == p:
+            break
+        p = parent
+    try:
+        names = sorted(
+            n for n in os.listdir(p)
+            if os.path.isdir(os.path.join(p, n)) and not n.startswith(".")
+        )
+    except OSError:
+        names = []
+    return p, names[:limit]
+
+
+class Orchestrator:
+    def __init__(self, controller, speak: Speak, notify_ui: NotifyUI):
+        self._c = controller
+        self._speak = speak
+        self._notify = notify_ui
+        self._bg: set[asyncio.Task] = set()
+        self._last_terminals: list[dict] = []
+        self._final_cb = self._on_final
+        controller.on_final(self._final_cb)
+        self._wire_output(controller)
+
+    async def _on_final(self, text: str) -> None:
+        await self._speak(text)
+        await self._notify({"type": "status", "status": "finished"})
+
+    def _wire_output(self, controller) -> None:
+        """Stream Claude's live screen to the phone UI (text), if the controller
+        supports it. Not spoken — purely a visual 'what Claude is doing' feed. The
+        colour variant is optional (tmux only); the getattr guard no-ops elsewhere."""
+        register = getattr(controller, "on_output", None)
+        if register:
+            register(self._on_output)
+        register_color = getattr(controller, "on_output_color", None)
+        if register_color:
+            register_color(self._on_output_color)
+
+    async def _on_output(self, text: str) -> None:
+        await self._notify({"type": "claude_output", "text": text})
+
+    async def _on_output_color(self, text: str) -> None:
+        await self._notify({"type": "claude_output_color", "text": text})
+
+    async def send_scrollback(self) -> None:
+        """Push Claude's full scrollback (coloured) to the phone's full-screen view.
+        On-demand (the view requests it); tmux-only — a no-op for other controllers."""
+        cap = getattr(self._c, "capture_scrollback", None)
+        if not cap:
+            return
+        text = await asyncio.to_thread(cap)
+        if text:
+            await self._notify({"type": "claude_scrollback", "text": text})
+
+    @property
+    def controller(self):
+        """The controller currently being driven (swaps when attaching to a terminal)."""
+        return self._c
+
+    def set_final(self, cb) -> None:
+        """Set the final-output callback (e.g. the session hub's handler) so it is
+        preserved across controller swaps when attaching to a different terminal."""
+        self._final_cb = cb
+        self._c.on_final(cb)
+
+    # --- attaching to an already-open terminal -----------------------------
+
+    def _build_controller(self, sess: dict):
+        if sess.get("backend") == "iterm":
+            from server.terminals import ItermController
+            return ItermController(sess["raw_id"])
+        if sess.get("backend") == "terminal_app":
+            from server.terminals import TerminalAppController
+            return TerminalAppController(sess["raw_id"])
+        if sess.get("backend") == "tmux":
+            from server.tmux_controller import TmuxController
+            return TmuxController(
+                session_name=sess["raw_id"], socket=sess.get("socket"),
+                launch_terminal=False,
+            )
+        if sess.get("backend") == "ax" and sess.get("app_pid"):
+            from server.ax_controller import AXController
+            return AXController(sess["app_pid"], sess.get("cwd", ""))
+        return None
+
+    async def _swap_controller(self, new) -> None:
+        try:
+            # detach_only: stop the old monitor but do NOT send Escape, otherwise
+            # attaching to terminal B would cancel the in-flight generation in the
+            # session we're leaving. (Escape is reserved for the explicit stop_claude.)
+            await self._c.stop(detach_only=True)
+        except Exception:
+            pass
+        self._c = new
+        new.on_final(self._final_cb)
+        self._wire_output(new)
+
+    def _resolve_terminal(self, args: dict):
+        items = self._last_terminals
+        if not items:
+            return None
+        tid = args.get("id")
+        if tid:
+            for s in items:
+                if s["id"] == tid:
+                    return s
+        idx = args.get("index")
+        if isinstance(idx, int) and 1 <= idx <= len(items):
+            return items[idx - 1]
+        match = (args.get("match") or args.get("target") or "").lower().strip()
+        if match:
+            for s in items:
+                if match in s["label"].lower() or match in s.get("cwd", "").lower():
+                    return s
+        return None
+
+    async def _attach(self, sess: dict) -> dict:
+        new = self._build_controller(sess)
+        if new is None:
+            return {"error": f"cannot control a {sess.get('app','')} terminal directly"}
+        await self._swap_controller(new)
+        try:
+            await new.start(sess.get("cwd") or None)
+        except PermissionError as e:
+            return {"error": str(e)}
+        await self._notify({"type": "status", "working_dir": new.working_dir or sess.get("cwd", "")})
+        if getattr(new, "mirrors_screen", True) is False:
+            await self._notify({
+                "type": "claude_output",
+                "text": "Live view isn't available for this terminal.",
+            })
+        # Recap what this terminal was working on, read from Claude's own transcript.
+        recap = ""
+        try:
+            from server.transcripts import recap as build_recap
+            recap = await asyncio.to_thread(build_recap, sess.get("cwd", ""))
+        except Exception:
+            pass
+        result = {"attached": sess["label"], "working_dir": sess.get("cwd", "")}
+        if recap:
+            result["recap"] = recap
+        return result
+
+    async def attach_source(self, cwd: str) -> dict:
+        """Attach to the open Claude terminal running in ``cwd`` (the session that
+        triggered a call), so answering continues THAT session with its context.
+        Returns the attach result (with recap) or an error dict."""
+        cwd = (cwd or "").rstrip("/")
+        if not cwd:
+            return {"error": "no cwd"}
+        from server.terminals import discover_claude_sessions
+        sessions = await asyncio.to_thread(discover_claude_sessions)
+        self._last_terminals = list(sessions)
+        match = next((s for s in sessions if (s.get("cwd") or "").rstrip("/") == cwd), None)
+        if match is None:
+            return {"error": "source terminal not open or not discoverable"}
+        if not match.get("controllable"):
+            return {"error": f"{match.get('app', '')} terminal can't be driven (use tmux/iTerm2)"}
+        return await self._attach(match)
+
+    async def cancel_all(self) -> None:
+        """Cancel any in-flight Claude send task and stop the controller."""
+        pending = list(self._bg)
+        for task in pending:
+            task.cancel()
+        await asyncio.gather(*pending, return_exceptions=True)
+        await self._c.stop()
+
+    def set_terminal_app(self, app: str) -> None:
+        fn = getattr(self._c, "set_terminal_app", None)
+        if fn:
+            fn(app)
+
+    def remember_terminals(self, sessions: list[dict]) -> None:
+        """Cache the terminals the phone is shown (its tappable list) so a later
+        attach_terminal by id resolves against the same set the user sees."""
+        self._last_terminals = list(sessions or [])
+
+    async def send_direct(self, text: str) -> None:
+        """Type text straight into the live Claude session (raw terminal chat from the
+        phone's full-screen view), bypassing the voice operator. Non-blocking like
+        send_to_claude; the result streams back through the live-output feed."""
+        text = (text or "").strip()
+        if not text:
+            return
+        if not getattr(self._c, "_started", True):
+            await self._notify({"type": "status",
+                                "status": "Open a folder first to chat with Claude."})
+            return
+        task = asyncio.create_task(self._c.send(text))
+        self._bg.add(task)
+
+        def _done(t: asyncio.Task) -> None:
+            self._bg.discard(t)
+            if t.exception():
+                logger.warning("claude_input send failed: %s", t.exception())
+        task.add_done_callback(_done)
+        await self._notify({"type": "status", "status": "Claude working (mic paused)"})
+
+    async def _start(self, working_dir: str) -> dict:
+        try:
+            await self._c.start(working_dir)
+        except Exception as e:
+            # Help the user recover from a wrong spoken path with suggestions.
+            base, options = suggest_dirs(working_dir)
+            return {"error": str(e), "searched_in": base, "suggestions": options}
+        await self._notify({"type": "status", "working_dir": self._c.working_dir})
+        # If the visible terminal window couldn't be opened, tell the user how to
+        # attach manually instead of leaving them with an invisible session.
+        hint = getattr(self._c, "window_hint", "")
+        if hint:
+            await self._notify({"type": "status", "status": hint})
+        return {"status": self._c.status, "working_dir": self._c.working_dir}
+
+    async def handle_tool_call(self, name: str, args: dict) -> dict:
+        if name in ("start_claude_session", "set_working_dir"):
+            key = "working_dir" if name == "start_claude_session" else "path"
+            return await self._start(args.get(key, ""))
+        if name == "list_dirs":
+            base, options = suggest_dirs(args.get("parent", "~"))
+            return {"path": base, "dirs": options}
+        if name == "make_dir":
+            target = os.path.abspath(os.path.expanduser(args.get("path", "")))
+            if not target:
+                return {"error": "no path given"}
+            try:
+                os.makedirs(target, exist_ok=True)
+            except OSError as e:
+                return {"error": str(e)}
+            return await self._start(target)
+        if name == "send_to_claude":
+            # Guard: if no Claude session is running yet, tell Gemini so it asks the
+            # user for a folder (the system prompt handles this) instead of firing a
+            # background send() that crashes with "call start() before send()".
+            if not getattr(self._c, "_started", True):
+                return {"error": "no_session",
+                        "hint": "No Claude session is running. Ask the user which "
+                                "folder to work in (or to create one) before sending."}
+            task = asyncio.create_task(self._c.send(args.get("text", "")))
+            self._bg.add(task)
+
+            def _send_done(t: asyncio.Task) -> None:
+                self._bg.discard(t)
+                exc = t.exception()              # retrieve so it isn't an orphan warning
+                if exc:
+                    logger.warning("send_to_claude failed: %s", exc)
+            task.add_done_callback(_send_done)
+            await self._notify({"type": "status", "status": "Claude working (mic paused)"})
+            return {"accepted": True, "status": "working"}
+        if name == "list_terminals":
+            from server.terminals import discover_claude_sessions
+            self._last_terminals = await asyncio.to_thread(discover_claude_sessions)
+            items = [
+                {"id": s["id"], "label": s["label"], "app": s["app"],
+                 "cwd": s.get("cwd", ""), "controllable": s["controllable"]}
+                for s in self._last_terminals
+            ]
+            # Send both keys: the phone reads `terminals`, the web client reads `items`.
+            await self._notify({"type": "terminals", "terminals": items, "items": items})
+            return {"terminals": items}
+        if name == "attach_terminal":
+            sess = self._resolve_terminal(args)
+            if sess is None:
+                # The phone's tappable list is pushed by a direct discovery, which
+                # doesn't populate _last_terminals (and it resets on every reconnect,
+                # since the orchestrator is rebuilt). Re-discover and retry so tapping
+                # an open terminal works without a prior list_terminals tool call.
+                from server.terminals import discover_claude_sessions
+                self._last_terminals = await asyncio.to_thread(discover_claude_sessions)
+                sess = self._resolve_terminal(args)
+            if sess is None:
+                return {"error": "terminal not found; call list_terminals first"}
+            if not sess.get("controllable"):
+                return {"error": f"that {sess.get('app','')} terminal can't be driven; "
+                                 "run Claude inside tmux and I can attach"}
+            return await self._attach(sess)
+        if name == "get_claude_status":
+            return {"status": self._c.status, "working_dir": self._c.working_dir}
+        if name == "stop_claude":
+            await self.cancel_all()
+            return {"status": "idle"}
+        if name == "read_session":
+            import server.transcripts as transcripts
+            cwd = self._c.working_dir or ""
+            kwargs = {}
+            if args.get("last") is not None:
+                kwargs["last"] = args["last"]
+            if args.get("search"):
+                kwargs["search"] = args["search"]
+            return await asyncio.to_thread(
+                lambda: transcripts.read_session(cwd, **kwargs))
+        return {"error": f"unknown tool: {name}"}

server/push_routes.py

@@ -0,0 +1,50 @@
+"""Device registration + ring + call-decline endpoints, shared by the laptop
+server and the cloud. In production these live on the cloud (so your APNs key
+isn't on every customer's laptop).
+
+Security model: these routes are scoped by the ACCOUNT id (an unguessable UUID),
+NOT by a shared secret. In the hosted/relay model the phone and each laptop hold
+the laptop's per-machine pairing token, which the cloud cannot verify (it never
+sees it), so requiring a shared token here would break zero-config pairing. That
+is why `auth_check` is accepted for compatibility but not enforced. The intended
+hardening is per-ACCOUNT authentication (device attestation / a cloud-issued,
+cloud-verifiable account token), which does not exist yet, see SECURITY.md.
+"""
+
+from __future__ import annotations
+
+from fastapi import Request
+
+
+def add_push_routes(app, registry, call_manager, auth_check=None) -> None:
+    @app.post("/register")
+    async def register(request: Request):
+        body = await request.json() or {}
+        registry.register(body.get("token", ""), body.get("account", ""))
+        return {"ok": True}
+
+    @app.post("/unregister")
+    async def unregister(request: Request):
+        body = await request.json() or {}
+        registry.remove(body.get("token", ""))
+        return {"ok": True}
+
+    @app.post("/notify")
+    async def notify(request: Request):
+        """Ring or cancel an account's registered phone(s). Called by the laptop:
+        ring when a Claude terminal finishes, cancel when it is no longer relevant
+        (the user already handled it)."""
+        body = await request.json() or {}
+        account = body.get("account", "")
+        if not account:
+            return {"ok": True}
+        if body.get("cancel"):
+            await call_manager.cancel(account)
+        else:
+            await call_manager.ring(account, body.get("summary", "A task finished."))
+        return {"ok": True}
+
+    @app.post("/call/decline")
+    async def decline(request: Request):
+        await call_manager.decline((await request.json() or {}).get("call_id", ""))
+        return {"ok": True}

server/ratelimit.py

@@ -0,0 +1,41 @@
+"""A tiny in-memory sliding-window rate limiter.
+
+Used to throttle creation of NEW anonymous device accounts (the free-trial grant),
+so a client cannot farm unlimited free minutes by claiming many `d-<uuid>` ids.
+It bounds new-account creation per client IP and globally. This is a mitigation,
+not a substitute for device attestation (App Attest), which is the complete fix.
+"""
+
+from __future__ import annotations
+
+import threading
+import time
+
+
+class SlidingWindowLimiter:
+    def __init__(self, max_events: int, window_seconds: float, clock=time.monotonic):
+        self._max = max_events
+        self._window = window_seconds
+        self._clock = clock
+        self._events: dict[str, list[float]] = {}
+        self._lock = threading.Lock()
+
+    def allow(self, key: str) -> bool:
+        """Record an event for `key` and return True if it is within the limit."""
+        now = self._clock()
+        cutoff = now - self._window
+        with self._lock:
+            bucket = [t for t in self._events.get(key, ()) if t > cutoff]
+            if len(bucket) >= self._max:
+                self._events[key] = bucket  # prune, but do not record the rejected event
+                return False
+            bucket.append(now)
+            self._events[key] = bucket
+            # Opportunistic cleanup so idle keys don't accumulate forever.
+            if len(self._events) > 10000:
+                self._events = {
+                    k: [t for t in v if t > cutoff]
+                    for k, v in self._events.items()
+                    if any(t > cutoff for t in v)
+                }
+            return True