voxa-code 0.1.0__py3-none-any.whl

server/relay.py

@@ -0,0 +1,157 @@
+"""Self-hosted relay: pairs a phone and a laptop by a short code and pipes their
+audio + control frames, so you don't need Tailscale or a per-laptop tunnel.
+
+Topology (all on YOUR server):
+  - Laptop connects OUTBOUND to  wss://you/agent?code=<code>&token=<relay-token>
+  - Phone connects to            wss://you/ws?code=<code>&token=<pair-token>
+  - The relay matches them by `code` and copies frames both ways (bytes + text).
+
+Because the laptop dials out, there's no NAT/inbound problem on the laptop side.
+The relay is a dumb, encrypted pipe; the V2V brain + Claude stay where they are.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+
+
+async def _notify_down(agent: WebSocket) -> None:
+    with contextlib.suppress(Exception):
+        await agent.send_text('{"type":"__peer","state":"down"}')
+
+
+async def _notify_phone_offline(phone: WebSocket) -> None:
+    """Tell the phone the laptop isn't bridged for its code, so it can stop showing
+    a live session and prompt the user to re-scan (the laptop stopped or the saved
+    code is stale)."""
+    with contextlib.suppress(Exception):
+        await phone.send_text('{"type":"status","status":"laptop offline"}')
+
+
+async def _notify_up(agent: WebSocket, account: str, voice: str = "") -> None:
+    """Tell the laptop a phone is here, carrying the phone's account id (for metering)
+    and chosen voice. Both come from the phone's own connection, never from the QR."""
+    msg = {"type": "__peer", "state": "up"}
+    if account:
+        msg["account"] = account
+    if voice:
+        msg["voice"] = voice
+    with contextlib.suppress(Exception):
+        await agent.send_text(json.dumps(msg))
+
+
+class _Pair:
+    def __init__(self) -> None:
+        self.agent: WebSocket | None = None
+        self.phone: WebSocket | None = None
+        self.account: str = ""
+        self.voice: str = ""
+
+
+def add_relay_routes(app: FastAPI, relay_token: str | None = None) -> None:
+    """Register /agent and /ws relay endpoints on an existing app (used by the
+    combined voxa_cloud app and by create_relay_app)."""
+    pairs: dict[str, _Pair] = {}
+    if relay_token is None:
+        relay_token = os.environ.get("VOXA_RELAY_TOKEN", "").strip()
+    app.state.pairs = pairs
+
+    async def _pipe(src: WebSocket, get_dst, on_close) -> None:
+        try:
+            while True:
+                msg = await src.receive()
+                if msg["type"] == "websocket.disconnect":
+                    break
+                dst = get_dst()
+                if dst is None:
+                    continue  # peer not connected yet; drop (audio) / nothing to do
+                try:
+                    if msg.get("bytes") is not None:
+                        await dst.send_bytes(msg["bytes"])
+                    elif msg.get("text") is not None:
+                        await dst.send_text(msg["text"])
+                except Exception:
+                    break
+        except (WebSocketDisconnect, RuntimeError):
+            pass
+        finally:
+            on_close()
+
+    @app.websocket("/agent")
+    async def agent(ws: WebSocket):
+        code = ws.query_params.get("code", "")
+        if (relay_token and ws.query_params.get("token") != relay_token) or not code:
+            await ws.close(code=4401)
+            return
+        await ws.accept()
+        pair = pairs.setdefault(code, _Pair())
+        pair.agent = ws
+        # If a phone is already waiting, tell the agent right away (account + voice).
+        if pair.phone is not None:
+            await _notify_up(ws, pair.account, pair.voice)
+
+        def on_close():
+            if pair.agent is ws:
+                pair.agent = None
+            # Laptop went away while a phone is connected -> let the phone know so
+            # it disconnects and offers to re-scan.
+            if pair.phone is not None:
+                asyncio.create_task(_notify_phone_offline(pair.phone))
+            if pair.agent is None and pair.phone is None:
+                pairs.pop(code, None)
+
+        await _pipe(ws, lambda: pairs.get(code, pair).phone, on_close)
+
+    @app.websocket("/ws")
+    async def phone(ws: WebSocket):
+        code = ws.query_params.get("code", "")
+        # The pair token is validated by the laptop end (it owns the auth token);
+        # the relay only needs a code to match. A relay_token (optional) gates who
+        # may open agent/phone sockets at all.
+        if (relay_token and ws.query_params.get("relay") not in (None, relay_token)) or not code:
+            await ws.close(code=4401)
+            return
+        await ws.accept()
+        pair = pairs.setdefault(code, _Pair())
+        pair.phone = ws
+        pair.account = ws.query_params.get("account", "")
+        pair.voice = ws.query_params.get("voice", "")
+        # Tell the laptop a phone is here so it only spins up the (paid) V2V session
+        # when someone is actually connected.
+        if pair.agent is not None:
+            await _notify_up(pair.agent, pair.account, pair.voice)
+        else:
+            # No laptop bridged this code. Give it a moment to dial in (the laptop
+            # reconnects continuously); if still absent, tell the phone it's offline.
+            async def _grace_check():
+                await asyncio.sleep(4)
+                cur = pairs.get(code)
+                if cur is not None and cur.agent is None and cur.phone is ws:
+                    await _notify_phone_offline(ws)
+            asyncio.create_task(_grace_check())
+
+        def on_close():
+            if pair.phone is ws:
+                pair.phone = None
+            if pair.agent is not None:
+                asyncio.create_task(_notify_down(pair.agent))
+            if pair.agent is None and pair.phone is None:
+                pairs.pop(code, None)
+
+        await _pipe(ws, lambda: pairs.get(code, pair).agent, on_close)
+
+
+def create_relay_app() -> FastAPI:
+    app = FastAPI()
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"ok": True}
+
+    add_relay_routes(app)
+    return app

server/relay_client.py

@@ -0,0 +1,89 @@
+"""Laptop-side relay bridge.
+
+Dials OUT to your cloud relay's /agent socket and pipes it to the laptop's own
+local /ws, so the phone reaches the laptop through your relay with no inbound
+port, tunnel, or Tailscale. The local server (server.app) runs unchanged.
+
+The laptop only opens the local /ws (and thus a paid V2V session) when the relay
+signals a phone is actually connected (`__peer up`), and tears it down on `down`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+
+import websockets
+
+logger = logging.getLogger(__name__)
+
+
+async def run_bridge(relay_ws_url: str, code: str, local_ws_url: str,
+                     relay_token: str = "") -> None:
+    agent_url = f"{relay_ws_url}/agent?code={code}"
+    if relay_token:
+        agent_url += f"&token={relay_token}"
+    while True:
+        try:
+            async with websockets.connect(agent_url, max_size=None, ping_interval=20) as agent:
+                logger.info("relay bridge connected (code=%s)", code)
+                await _serve(agent, local_ws_url)
+        except Exception as e:
+            logger.warning("relay bridge dropped: %s", e)
+        await asyncio.sleep(2)  # reconnect
+
+
+async def _serve(agent, local_ws_url: str) -> None:
+    local = None
+    pump: asyncio.Task | None = None
+
+    async def open_local(account: str = "", voice: str = ""):
+        nonlocal local, pump
+        if local is not None:
+            return
+        url = local_ws_url
+        # Pass the phone's account (for metering) and chosen voice through to the
+        # laptop's local /ws so they reach the metered /live session.
+        for key, val in (("account", account), ("voice", voice)):
+            if val:
+                sep = "&" if "?" in url else "?"
+                url = f"{url}{sep}{key}={val}"
+        local = await websockets.connect(url, max_size=None, ping_interval=20)
+        pump = asyncio.create_task(_pump(local, agent))
+
+    async def close_local():
+        nonlocal local, pump
+        if pump:
+            pump.cancel()
+            pump = None
+        if local:
+            with contextlib.suppress(Exception):
+                await local.close()
+            local = None
+
+    try:
+        async for msg in agent:                 # phone -> laptop
+            if isinstance(msg, str) and '"__peer"' in msg:
+                try:
+                    data = json.loads(msg)
+                except ValueError:
+                    data = {}
+                if data.get("type") == "__peer":
+                    if data.get("state") == "up":
+                        await open_local(data.get("account", ""), data.get("voice", ""))
+                    elif data.get("state") == "down":
+                        await close_local()
+                    continue
+            if local is not None:
+                await local.send(msg)
+    finally:
+        await close_local()
+
+
+async def _pump(local, agent) -> None:
+    """Laptop -> phone: forward everything from the local /ws to the relay agent."""
+    with contextlib.suppress(Exception):
+        async for msg in local:
+            await agent.send(msg)

server/remote_operator.py

@@ -0,0 +1,128 @@
+"""RemoteOperator: drop-in replacement for GeminiOperator that routes V2V through
+the cloud `/live` proxy instead of talking to Gemini directly.
+
+Why: the metered/paid model runs Gemini with YOUR key on the cloud (so the key
+isn't on customer laptops) and counts minutes there. The laptop streams the
+phone's mic to `/live`, plays back the audio it returns, and EXECUTES the tool
+calls the cloud's Gemini decides (start_claude_session, send_to_claude, ...) via
+the same `handle_tool_call` the local operator would use.
+
+Enabled on the laptop by setting VOXA_LIVE_PROXY (+ VOXA_PROXY_TOKEN, VOXA_ACCOUNT).
+Same interface as GeminiOperator: async context manager + set_audio_out /
+set_text_out / send_audio / speak / run.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+from typing import Awaitable, Callable, Optional
+
+import websockets
+
+logger = logging.getLogger(__name__)
+
+
+class RemoteOperator:
+    def __init__(self, config, handle_tool_call: Callable[[str, dict], Awaitable[dict]],
+                 *, proxy_url: str, account: str, token: str = "", voice: str = ""):
+        self._handle = handle_tool_call
+        url = f"{proxy_url}?account={account}"
+        if token:
+            url += f"&token={token}"
+        if voice:
+            url += f"&voice={voice}"
+        self._url = url
+        self._audio_out: Optional[Callable[[bytes], Awaitable[None]]] = None
+        self._text_out: Optional[Callable[[dict], Awaitable[None]]] = None
+        self._ws = None
+        self._suppress_pending = False
+        self._stack = contextlib.AsyncExitStack()
+
+    async def __aenter__(self) -> "RemoteOperator":
+        # The cloud /live can briefly refuse mid-deploy/restart; retry a few times with
+        # a longer handshake timeout so a momentary blip doesn't drop the session.
+        last_err: Exception | None = None
+        for attempt in range(4):
+            try:
+                self._ws = await self._stack.enter_async_context(
+                    websockets.connect(self._url, max_size=None,
+                                       ping_interval=20, open_timeout=20))
+                return self
+            except Exception as e:
+                last_err = e
+                logger.warning("/live connect attempt %d failed: %s", attempt + 1, e)
+                if attempt < 3:
+                    await asyncio.sleep(1.5)
+        raise last_err
+
+    async def __aexit__(self, *exc) -> bool:
+        await self._stack.aclose()
+        self._ws = None
+        return False
+
+    def set_audio_out(self, cb): self._audio_out = cb
+    def set_text_out(self, cb): self._text_out = cb
+
+    async def send_audio(self, pcm: bytes) -> None:
+        if self._ws is None:
+            return
+        try:
+            await self._ws.send(pcm)
+        except Exception:
+            return  # cloud link closed (e.g. out of minutes); run()'s loop handles the end
+
+    async def speak(self, text: str, immediate: bool = False) -> None:
+        if self._ws is None:
+            return
+        try:
+            # Flush a pending greeting suppression FIRST, in-order on this single writer
+            # (a separate task could interleave a concurrent send on the same socket).
+            if self._suppress_pending:
+                self._suppress_pending = False
+                await self._ws.send(json.dumps({"type": "suppress_greeting"}))
+            await self._ws.send(json.dumps(
+                {"type": "speak", "text": text, "immediate": immediate}))
+        except Exception:
+            return  # cloud link closed; don't crash the answer flow
+
+    def suppress_greeting(self) -> None:
+        # Ask the cloud brain not to speak its generic opening (the laptop supplies a
+        # contextual one on answer-attach). Sent in-order before the next speak().
+        self._suppress_pending = True
+
+    async def send_text(self, text: str) -> None:
+        # A typed user turn from the phone. Forward it to the cloud brain the same way
+        # audio is; without this, a `say` during a metered call raised AttributeError
+        # and tore the whole call down.
+        if self._ws is None:
+            return
+        try:
+            await self._ws.send(json.dumps({"type": "user_text", "text": text}))
+        except Exception:
+            return  # cloud link closed; run()'s loop handles the end
+
+    async def run(self) -> None:
+        if self._ws is None:
+            raise RuntimeError("RemoteOperator is not open; use 'async with'.")
+        async for msg in self._ws:
+            if isinstance(msg, (bytes, bytearray)):
+                if self._audio_out is not None:
+                    await self._audio_out(bytes(msg))
+                continue
+            try:
+                data = json.loads(msg)
+            except ValueError:
+                continue
+            if data.get("type") == "tool":            # cloud Gemini -> run a tool here
+                try:
+                    result = await self._handle(data.get("name", ""), data.get("args") or {})
+                except Exception as e:
+                    result = {"error": str(e)}
+                with contextlib.suppress(Exception):
+                    await self._ws.send(json.dumps(
+                        {"type": "tool_result", "id": data.get("id"), "result": result}))
+            elif self._text_out is not None:           # transcripts / status -> phone
+                await self._text_out(data)

server/session_hub.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import inspect
+
+
+class SessionHub:
+    def __init__(self, controller, call_manager):
+        self._c = controller
+        self._cm = call_manager
+        self._speak = None
+        # Ring on finish when no line is attached. Disabled once Claude Code hooks are
+        # live, so the hook becomes the single offline-ring source (no double-report).
+        self._offline_ring = True
+        controller.on_final(self.on_final)
+
+    def set_offline_ring(self, on: bool) -> None:
+        self._offline_ring = on
+
+    def attach(self, speak_fn) -> list[str]:
+        self._speak = speak_fn
+        return self._cm.attach()
+
+    def detach(self) -> None:
+        self._speak = None
+        self._cm.detach()
+
+    async def on_final(self, text: str) -> None:
+        if self._speak is not None:
+            result = self._speak(text)
+            if inspect.isawaitable(result):
+                await result
+        elif self._offline_ring:
+            await self._cm.on_update(text)

server/terminal_watcher.py

@@ -0,0 +1,241 @@
+"""Background watcher: ring the phone when ANY open Claude terminal finishes.
+
+Voxa's main loop only follows the one terminal you're attached to. This watcher
+runs alongside it and watches EVERY open Claude session it can discover (tmux
+sessions and iTerm2 windows, including ones you started yourself). When any of
+them goes working -> done, it reports a one-line summary.
+
+It reuses the same completion detector as the controllers (``monitor_loop``):
+a session is "done" when its screen stops changing after having been active.
+
+Routing of the report (speak on the line if a phone is connected, else fire a
+CallKit ring) is the caller's job, passed in as ``on_done``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+from typing import Awaitable, Callable, Optional
+
+from .terminals import _osa, _shell, discover_claude_sessions, _iterm_capture_script
+from .tmux_controller import monitor_loop, looks_actionable, _ACTIVE_MARKERS
+from .transcript_monitor import TranscriptMonitor
+from .transcripts import PROJECTS_DIR
+
+logger = logging.getLogger(__name__)
+
+# on_done(label, cwd, summary) -> awaitable | None
+DoneCallback = Callable[[str, str, str], object]
+
+
+class _PassiveWatch:
+    """A read-only stand-in a session that exposes exactly what monitor_loop needs.
+
+    Unlike the real controllers it never sends input, it only captures the pane
+    and emits when the screen stabilises after activity."""
+
+    # Claude shows these only while actively working; their ABSENCE (plus a stable
+    # screen) is what tells us a task truly finished, not just paused mid-step.
+    _WORKING_MARKERS = ("esc to interrupt", "esc to cancel", "tokens", "thinking…",
+                        "thinking...", "running…", "running...")
+
+    def __init__(self, session: dict, on_emit, run=_shell, osa=_osa,
+                 poll_interval: float = 2.0, idle_polls: int = 5):
+        self._session = session
+        self._on_emit = on_emit
+        self._run = run
+        self._osa = osa
+        self._poll = poll_interval
+        self._idle_polls = idle_polls
+        self.status = "idle"
+        self._started = True
+        # True once we've actually seen this session WORKING since the last report. A
+        # fresh session that merely booted to its idle prompt never shows the working
+        # markers, so it won't ring the phone on startup.
+        self._saw_work = False
+
+    def _capture(self) -> str:
+        backend = self._session.get("backend")
+        raw = self._session.get("raw_id", "")
+        if backend == "tmux":
+            screen = self._run(["tmux", "capture-pane", "-p", "-t", raw])
+        elif backend == "iterm":
+            screen = self._osa(_iterm_capture_script(raw))
+        elif backend == "terminal_app":
+            wid, _, tab = raw.partition(":")
+            screen = self._osa(
+                f'tell application "Terminal" to return history of '
+                f'tab {tab or "1"} of window id {wid}'
+            )
+        else:
+            screen = ""
+        if any(m in screen.lower() for m in _ACTIVE_MARKERS):
+            self._saw_work = True
+        return screen
+
+    async def _emit(self, text: str) -> None:
+        # Only report once this session actually worked (then went quiet), or when it
+        # is showing a real prompt waiting on the user. A fresh session that just booted
+        # to its idle prompt must not ring (that would call the user on session start).
+        if not (self._saw_work or looks_actionable(text)):
+            return
+        # Don't report "done" if Claude is still working (stable screen but a
+        # spinner/"esc to interrupt" is showing) -> avoids calling before the task
+        # actually finishes.
+        screen = self._capture().lower()
+        if any(m in screen for m in self._WORKING_MARKERS):
+            return
+        self._saw_work = False
+        result = self._on_emit(self._session, text)
+        if inspect.isawaitable(result):
+            await result
+
+
+class TerminalWatcher:
+    """Polls for open Claude sessions and watches each for completion."""
+
+    def __init__(self, on_done: DoneCallback, *,
+                 on_resumed=None,
+                 discover=discover_claude_sessions, run=_shell, osa=_osa,
+                 should_skip: Optional[Callable[[dict], bool]] = None,
+                 rediscover_interval: float = 5.0,
+                 poll_interval: float = 2.0, idle_polls: int = 5,
+                 dedupe_window: float = 90.0, clock=None,
+                 resume_window: float = 30.0, resume_poll: float = 2.0,
+                 monitor=monitor_loop, projects_dir: str | None = None):
+        self._on_done = on_done
+        self._on_resumed = on_resumed
+        self._resume_window = resume_window
+        self._resume_poll = resume_poll
+        self._discover = discover
+        self._run = run
+        self._osa = osa
+        self._should_skip = should_skip or (lambda s: False)
+        self._rediscover = rediscover_interval
+        self._poll = poll_interval
+        self._idle_polls = idle_polls
+        self._monitor = monitor
+        self._dedupe_window = dedupe_window
+        self._projects = projects_dir
+        self._quiet = 5.0
+        import time as _t
+        self._clock = clock or _t.monotonic
+        self._last_fired: dict[str, float] = {}   # cwd -> last report time
+        self._watchers: dict[str, asyncio.Task] = {}
+
+    async def _handle_emit(self, session: dict, text: str) -> None:
+        # A session we're actively driving is reported by the main loop already.
+        if self._should_skip(session):
+            return
+        # Dedupe: don't report the same terminal again within the window (the
+        # monitor can re-fire on minor screen changes -> avoids ringing twice).
+        cwd = session.get("cwd", "") or session.get("id", "")
+        now = self._clock()
+        if now - self._last_fired.get(cwd, -1e9) < self._dedupe_window:
+            return
+        self._last_fired[cwd] = now
+        kind, summary = classify_screen(text)
+        if kind == "needs_input" and summary:
+            summary = f"needs input: {summary}"
+        result = self._on_done(session.get("label", ""), cwd, summary)
+        if inspect.isawaitable(result):
+            await result
+        if self._on_resumed is not None:
+            asyncio.ensure_future(self._watch_resume(session))
+
+    def _spawn(self, session: dict) -> None:
+        if session.get("backend") == "ax":
+            mon = TranscriptMonitor(
+                session.get("cwd", ""),
+                lambda text, s=session: self._handle_emit(s, text),
+                poll_interval=self._poll, quiet_secs=self._quiet,
+                projects_dir=self._projects or PROJECTS_DIR)
+            mon._started = True
+            self._watchers[session["id"]] = asyncio.ensure_future(mon.run())
+            return
+        watch = _PassiveWatch(session, self._handle_emit, run=self._run, osa=self._osa,
+                              poll_interval=self._poll, idle_polls=self._idle_polls)
+        self._watchers[session["id"]] = asyncio.ensure_future(self._monitor(watch))
+
+    def _capture_session(self, session: dict) -> str:
+        backend = session.get("backend")
+        raw = session.get("raw_id", "")
+        if backend == "tmux":
+            return self._run(["tmux", "capture-pane", "-p", "-t", raw])
+        if backend == "iterm":
+            return self._osa(_iterm_capture_script(raw))
+        if backend == "terminal_app":
+            wid, _, tab = raw.partition(":")
+            return self._osa(
+                f'tell application "Terminal" to return history of '
+                f'tab {tab or "1"} of window id {wid}'
+            )
+        return ""
+
+    async def _watch_resume(self, session: dict) -> None:
+        """After a ring fires, poll this session briefly. If working markers reappear
+        (the user acted on the laptop), tell the caller to cancel the ring."""
+        if self._on_resumed is None:
+            return
+        elapsed = 0.0
+        while elapsed < self._resume_window:
+            screen = (self._capture_session(session) or "").lower()
+            if any(m in screen for m in _PassiveWatch._WORKING_MARKERS):
+                result = self._on_resumed(session.get("label", ""), session.get("cwd", ""))
+                if inspect.isawaitable(result):
+                    await result
+                return
+            await asyncio.sleep(self._resume_poll)
+            elapsed += self._resume_poll
+
+    async def reconcile_once(self) -> None:
+        """One discovery pass: start watchers for new sessions, drop gone ones."""
+        try:
+            sessions = await asyncio.to_thread(self._discover, self._run, self._osa)
+        except Exception:
+            logger.exception("terminal discovery failed")
+            return
+        live_ids = set()
+        for s in sessions:
+            sid = s.get("id")
+            if not sid:
+                continue
+            live_ids.add(sid)
+            task = self._watchers.get(sid)
+            if task is None or task.done():
+                self._spawn(s)
+        for sid in [s for s in self._watchers if s not in live_ids]:
+            self._watchers.pop(sid).cancel()
+
+    async def run(self) -> None:
+        try:
+            while True:
+                await self.reconcile_once()
+                await asyncio.sleep(self._rediscover)
+        finally:
+            for t in self._watchers.values():
+                t.cancel()
+            self._watchers.clear()
+
+
+def _first_meaningful_line(text: str) -> str:
+    """Pull a short human summary from the freshly-stable screen delta."""
+    for ln in (text or "").splitlines():
+        s = ln.strip()
+        if len(s) > 2:
+            return s[:200]
+    return ""
+
+
+def classify_screen(text: str) -> tuple[str, str]:
+    """Decide whether a freshly-stable screen is Claude WAITING FOR INPUT (a menu, a
+    y/n, a question) or a FINISHED result, and return (kind, summary)."""
+    body = text or ""
+    # A trailing question mark on the last meaningful line is a question to the user.
+    last = _first_meaningful_line("\n".join(reversed(body.splitlines())))
+    if looks_actionable(body) or last.endswith("?"):
+        q = _first_meaningful_line(body) or last
+        return "needs_input", q
+    return "finished", _first_meaningful_line(body)