voxa-code 0.1.0__py3-none-any.whl

server/apns.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import logging
+
+import httpx
+import jwt
+
+logger = logging.getLogger(__name__)
+
+
+def build_apns_jwt(key_pem: str, key_id: str, team_id: str, issued_at: int) -> str:
+    return jwt.encode(
+        {"iss": team_id, "iat": issued_at},
+        key_pem,
+        algorithm="ES256",
+        headers={"alg": "ES256", "kid": key_id},
+    )
+
+
+def build_voip_payload(call_id: str, summary: str) -> dict:
+    return {"call_id": call_id, "summary": summary, "aps": {"content-available": 1}}
+
+
+def build_cancel_payload(call_id: str) -> dict:
+    return {"call_id": call_id, "type": "cancel", "aps": {"content-available": 1}}
+
+
+class ApnsClient:
+    """Sends VoIP pushes via APNs HTTP/2. One per server process."""
+
+    PROD_HOST = "https://api.push.apple.com"
+    SANDBOX_HOST = "https://api.sandbox.push.apple.com"
+
+    def __init__(self, config, now_fn=None):
+        self._cfg = config
+        # Xcode/dev-signed builds get sandbox push tokens, which only work
+        # against the sandbox host; TestFlight/App Store builds use production.
+        self._host = self.SANDBOX_HOST if getattr(config, "apns_sandbox", False) else self.PROD_HOST
+        import time
+        self._now = now_fn or (lambda: int(time.time()))
+        self._jwt = ""
+        self._jwt_at = 0
+
+    def _token(self) -> str:
+        now = self._now()
+        if not self._jwt or now - self._jwt_at > 50 * 60:
+            # Prefer the key contents (set as a secret on container hosts); fall
+            # back to a file path for local/dev use.
+            key_pem = getattr(self._cfg, "apns_key", "") or open(self._cfg.apns_key_path).read()
+            self._jwt = build_apns_jwt(
+                key_pem, self._cfg.apns_key_id, self._cfg.apns_team_id, now
+            )
+            self._jwt_at = now
+        return self._jwt
+
+    async def send_voip(self, device_token: str, call_id: str, summary: str) -> bool | int:
+        """Send a VoIP ring. Returns True on success, or the HTTP status code on
+        failure (so the caller can prune a 410 Gone / dead token)."""
+        url = f"{self._host}/3/device/{device_token}"
+        headers = {
+            "apns-topic": f"{self._cfg.apns_bundle_id}.voip",
+            "apns-push-type": "voip",
+            "apns-priority": "10",
+            "authorization": f"bearer {self._token()}",
+        }
+        payload = build_voip_payload(call_id, summary)
+        async with httpx.AsyncClient(http2=True, timeout=10) as client:
+            resp = await client.post(url, headers=headers, content=json.dumps(payload))
+            if resp.status_code != 200:
+                # 410 = the token is dead (app deleted/reinstalled); other codes are
+                # transient/config. Log the reason so silent no-rings are diagnosable.
+                logger.warning("APNs voip push failed: status=%s body=%s token=%s",
+                               resp.status_code, resp.text[:200], device_token[:8])
+                return resp.status_code
+            return True
+
+    async def send_voip_cancel(self, device_token: str, call_id: str) -> bool:
+        url = f"{self._host}/3/device/{device_token}"
+        headers = {
+            "apns-topic": f"{self._cfg.apns_bundle_id}.voip",
+            "apns-push-type": "voip",
+            "apns-priority": "10",
+            "authorization": f"bearer {self._token()}",
+        }
+        payload = build_cancel_payload(call_id)
+        async with httpx.AsyncClient(http2=True, timeout=10) as client:
+            resp = await client.post(url, headers=headers, content=json.dumps(payload))
+            return resp.status_code == 200

server/app.py

@@ -0,0 +1,589 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import tempfile
+import time
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI, Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, JSONResponse
+
+from dotenv import load_dotenv
+
+from server.config import Config, load_config
+from server.claude_controller import ClaudeController
+from server.tmux_controller import TmuxController
+from server.orchestrator import Orchestrator
+
+STATIC = Path(__file__).resolve().parent.parent / "static"
+
+
+def should_suppress_greeting(pending_updates: list) -> bool:
+    """Suppress Voxa's generic opening when there is a queued update to relay on
+    answer, so the answer opening is the contextual update spoken once."""
+    return bool(pending_updates)
+
+
+def _strip_finished_prefix(summary: str) -> str:
+    """Turn a finish summary ('<project> finished: <result>') into just the result,
+    since the opening phrases the 'finished' part itself. '<project> finished' with no
+    result becomes ''. Other summaries (e.g. 'needs input: ...') pass through."""
+    s = (summary or "").strip()
+    low = s.lower()
+    i = low.find("finished:")
+    if i != -1:
+        return s[i + len("finished:"):].strip()
+    if low.endswith(" finished") or low == "finished":
+        return ""
+    return s
+
+
+def compose_opening(project: str, updates: list) -> str:
+    """Voxa's spoken opening when a call is answered: lead with the project and what
+    its last task actually did, then ask what's next, instead of a bare greeting
+    followed by the raw update. `project` is '' when we couldn't attach to a folder."""
+    detail = " ".join(_strip_finished_prefix(u) for u in (updates or []) if u and u.strip()).strip()
+    if project and detail:
+        body = f"Your last task in {project} just finished. Here's what it did: {detail}."
+    elif project:
+        body = f"You're back in {project} — your last task there just finished."
+    elif detail:
+        body = f"Your last task just finished. Here's what it did: {detail}."
+    else:
+        body = "You're back."
+    return f"Hi. {body} What would you like to do next?"
+
+
+def suppress_greeting_if_supported(operator) -> bool:
+    """Suppress the operator's generic opening, but only if it supports it. The metered
+    RemoteOperator greets cloud-side and has no suppress_greeting, so this no-ops there
+    instead of raising (which would kill the answer flow)."""
+    fn = getattr(operator, "suppress_greeting", None)
+    if callable(fn):
+        fn()
+        return True
+    return False
+
+
+def apply_greeting_suppression(operator, pending_updates: list) -> bool:
+    """Suppress the operator's generic opening when there is a queued update to relay.
+    Safe when the operator has no suppress_greeting (the metered RemoteOperator greets
+    cloud-side); never raises on that path."""
+    if not should_suppress_greeting(pending_updates):
+        return False
+    return suppress_greeting_if_supported(operator)
+
+
+def _default_operator_factory(config, handle_tool_call, voice="", account=""):
+    # Metered mode: route V2V through the cloud /live proxy (your key + minute
+    # metering live there). Direct mode: talk to Gemini locally with your own key.
+    proxy = os.environ.get("VOXA_LIVE_PROXY", "").strip()
+    if proxy:
+        from server.remote_operator import RemoteOperator
+        # Account precedence: the paired phone's id (per-connection) wins, so each
+        # phone meters its own balance; fall back to env/auth_token for solo runs.
+        acct = account or os.environ.get("VOXA_ACCOUNT", "") or config.auth_token
+        return RemoteOperator(
+            config, handle_tool_call, proxy_url=proxy, account=acct,
+            token=os.environ.get("VOXA_PROXY_TOKEN", ""), voice=voice)
+    from server.gemini_operator import GeminiOperator
+    return GeminiOperator(config, handle_tool_call, voice=voice)
+
+
+def create_app(config: Config | None = None, operator_factory=None) -> FastAPI:
+    if config is None:
+        load_dotenv()
+        config = load_config()
+    operator_factory = operator_factory or _default_operator_factory
+    # "attach" = visible interactive claude in a tmux/Terminal you can also type in;
+    # "drive" = headless SDK session with a read-only watch log.
+    mode = os.environ.get("VOXA_MODE", "attach").strip().lower()
+    app = FastAPI()
+
+    from server.device_registry import DeviceRegistry
+    from server.call_manager import CallManager
+    registry = DeviceRegistry(os.environ.get("VOXA_DEVICES_FILE", "devices.json"))
+    if config.push_enabled:
+        from server.apns import ApnsClient
+        pusher = ApnsClient(config)
+    else:
+        class _NoPush:
+            async def send_voip(self, *a, **k):
+                logging.warning("push disabled; dropping call %r", a)
+                return False
+        pusher = _NoPush()
+    call_manager = CallManager(pusher, registry)
+    app.state.registry = registry
+    app.state.call_manager = call_manager
+
+    def _check(request: Request):
+        return request.query_params.get("token") == config.auth_token
+
+    from server.push_routes import add_push_routes
+    add_push_routes(app, registry, call_manager, _check)
+
+    app.state.turn_start = {}    # session_id -> turn start (Claude Code UserPromptSubmit)
+    app.state.hook_last = {}     # session_id -> last announced time (debounce)
+    app.state.hooks_live = False # flips true once a real Claude Code hook arrives
+
+    async def _ring_via_cloud(summary):
+        # The laptop holds no APNs key (zero-config); ask the cloud to ring the
+        # last-paired account's phone. The cloud has the key + device registry.
+        relay = os.environ.get("VOXA_RELAY_URL", "").strip().rstrip("/")
+        account = getattr(app.state, "last_account", "")
+        if not relay or not account:
+            return
+        try:
+            import httpx
+            async with httpx.AsyncClient(timeout=10) as c:
+                # Account-scoped: the unguessable account id is the authorization
+                # (the cloud has no per-laptop token it could verify here).
+                await c.post(f"{relay}/notify", json={"account": account, "summary": summary})
+        except Exception:
+            logging.exception("ring via cloud failed")
+
+    async def report(summary: str):
+        """Surface a background/hook update.
+
+        - Line attached (a metered session is live): stay silent; that session
+          narrates its own result on the line, so we don't talk over it.
+        - App open but no line yet (connected for setup, not started): queue the
+          update so it's spoken when the user taps Start, but don't ring.
+        - App closed: queue + ring (CallKit / cloud)."""
+        if call_manager.line_open:
+            return
+        if getattr(app.state, "phone_clients", 0) > 0:
+            call_manager.queue(summary)   # spoken on begin/attach; no ring while app is open
+            return
+        await call_manager.on_update(summary)
+        if not config.push_enabled:
+            # Avoid a double call: with a local APNs key, on_update already rang.
+            await _ring_via_cloud(summary)
+
+    def _stand_down_watcher():
+        # The first real Claude Code hook event proves hooks are live: stop the screen
+        # scraper, and make hooks the SOLE offline-ring source (so the driven session's
+        # own monitor doesn't also ring) — the two would otherwise double-report.
+        app.state.hooks_live = True
+        t = getattr(app.state, "bg_watcher", None)
+        if t is not None and not t.done():
+            t.cancel()
+        app.state.bg_watcher = None
+        hub = getattr(app.state, "hub", None)
+        if hub is not None:
+            hub.set_offline_ring(False)
+
+    @app.post("/hook")
+    async def claude_hook(request: Request):
+        # Claude Code Stop / Notification / UserPromptSubmit hooks POST their stdin JSON
+        # here (installed globally by the voxa launcher). This is the reliable,
+        # terminal-agnostic signal that a session finished or needs input.
+        if request.query_params.get("token") != config.auth_token:
+            return JSONResponse({"ok": False}, status_code=401)
+        try:
+            body = await request.json()
+        except Exception:
+            return {"ok": True}
+        from server.hooks import route_hook
+        _stand_down_watcher()
+        # Default 0 = call on EVERY finish (matches "call me when Claude finishes"). Set
+        # VOXA_HOOK_MIN_SECONDS to a positive value to suppress quick interactive turns
+        # (only call for tasks that took at least that many seconds).
+        msg = route_hook(
+            body or {},
+            turn_start=app.state.turn_start,
+            hook_last=app.state.hook_last,
+            now=time.monotonic(),
+            min_seconds=float(os.environ.get("VOXA_HOOK_MIN_SECONDS", "0")),
+        )
+        if msg:
+            # Remember WHICH session triggered this call so answering attaches to it
+            # and continues that work (instead of opening an empty default session).
+            cwd = (body or {}).get("cwd", "")
+            if cwd:
+                app.state.pending_source = {"cwd": cwd}
+            await report(msg)
+        return {"ok": True}
+
+    # Background watcher: ring the phone when ANY open Claude terminal finishes,
+    # not just the one Voxa is attached to. Routes through the hub so it speaks on
+    # the line when a phone is connected and rings (CallKit) when it isn't. Off by
+    # setting VOXA_WATCH_TERMINALS=0.
+    if os.environ.get("VOXA_WATCH_TERMINALS", "1").strip() not in ("0", "false", ""):
+        from server.terminal_watcher import TerminalWatcher
+
+        # Fallback screen-scraper for terminals without hooks. It stands down (see
+        # _stand_down_watcher) the moment a real Claude Code hook arrives, so the hook
+        # path and the scraper never double-report the same finish.
+        async def _on_bg_done(label, cwd, summary):
+            msg = f"{label or 'a terminal'} finished" + (f": {summary}" if summary else "")
+            await report(msg)
+
+        async def _on_bg_resumed(label, cwd):
+            # The user picked the task back up on the laptop before answering: cancel
+            # the ring so the phone stops buzzing for something already handled.
+            account = getattr(app.state, "last_account", "")
+            if config.push_enabled:
+                await call_manager.cancel(account or None)
+                return
+            relay = os.environ.get("VOXA_RELAY_URL", "").strip().rstrip("/")
+            if not relay or not account:
+                return
+            try:
+                import httpx
+                async with httpx.AsyncClient(timeout=10) as c:
+                    await c.post(f"{relay}/notify", json={"account": account, "cancel": True})
+            except Exception:
+                logging.exception("cancel via cloud failed")
+
+        def _skip(session):
+            # The terminal we're actively driving is reported by the main loop;
+            # skip it here only while a phone line is open (to avoid double-report).
+            ctrl = getattr(app.state, "controller", None)
+            return bool(call_manager.line_open and ctrl is not None
+                        and getattr(ctrl, "working_dir", None) == session.get("cwd"))
+
+        watcher = TerminalWatcher(_on_bg_done, on_resumed=_on_bg_resumed, should_skip=_skip)
+
+        @app.on_event("startup")
+        async def _start_watcher():
+            app.state.bg_watcher = asyncio.ensure_future(watcher.run())
+
+        @app.on_event("shutdown")
+        async def _stop_watcher():
+            t = getattr(app.state, "bg_watcher", None)
+            if t:
+                t.cancel()
+
+    @app.get("/healthz")
+    async def healthz():
+        return {"ok": True}
+
+    @app.get("/", response_class=HTMLResponse)
+    async def index():
+        return (STATIC / "index.html").read_text()
+
+    @app.websocket("/ws")
+    async def ws(websocket: WebSocket):
+        if websocket.query_params.get("token") != config.auth_token:
+            await websocket.close(code=4401)
+            return
+        await websocket.accept()
+        logging.getLogger("voxa").info("ws: phone connected")
+        # Count live connections so background/hook events know the app is OPEN
+        # (don't call, surface on the line) vs CLOSED (place a call).
+        app.state.phone_clients = getattr(app.state, "phone_clients", 0) + 1
+        try:
+            await _serve_ws(websocket)
+        finally:
+            app.state.phone_clients = max(0, getattr(app.state, "phone_clients", 1) - 1)
+
+    async def _serve_ws(websocket: WebSocket):
+        # The controller (and the Claude session it owns) persists across
+        # connections via the hub. Build it once, then reuse it so Claude keeps
+        # running when the phone hangs up.
+        hub = getattr(app.state, "hub", None)
+        if hub is None:
+            if mode == "drive":
+                watch_path = os.path.join(
+                    tempfile.gettempdir(), f"loop-watch-{os.getpid()}.log"
+                )
+                controller = ClaudeController(
+                    watch_log_path=watch_path, launch_terminal=True
+                )
+            else:
+                controller = TmuxController(
+                    launch_terminal=True,
+                    terminal_app=os.environ.get("VOXA_TERMINAL_APP", "auto"),
+                )
+            from server.session_hub import SessionHub
+            hub = SessionHub(controller, call_manager)
+            if getattr(app.state, "hooks_live", False):
+                hub.set_offline_ring(False)   # hooks already drive offline rings
+            app.state.hub = hub
+            app.state.controller = controller
+        else:
+            controller = app.state.controller
+
+        # Conversational-activity clock for the idle auto-disconnect (below). Raw mic
+        # frames don't count (the phone streams continuously); only real speech /
+        # spoken replies / a working task do.
+        activity = {"t": time.monotonic()}
+        def touch(): activity["t"] = time.monotonic()
+
+        async def speak(text): await operator.speak(text)
+        async def notify(msg):
+            if isinstance(msg, dict) and msg.get("type") == "transcript":
+                touch()
+            await websocket.send_json(msg)
+        orchestrator = Orchestrator(controller, speak, notify)
+        # Route finals through the hub (spoken when a line is attached, ring via the
+        # call manager otherwise). set_final keeps this wired across controller swaps
+        # when the user attaches to a different open terminal.
+        orchestrator.set_final(hub.on_final)
+
+        _log = logging.getLogger("voxa")
+        _counts = {"in": 0, "out": 0}
+        voice = websocket.query_params.get("voice", "")
+        # The bridge appends ?account=<paired phone's id> so the metered session
+        # bills that balance. Only pass it to factories that accept it.
+        import inspect
+        _kwargs = {"voice": voice}
+        _account = websocket.query_params.get("account", "")
+        if "account" in inspect.signature(operator_factory).parameters:
+            _kwargs["account"] = _account
+        # Remember who's paired so the background watcher can ring this account's
+        # phone (via the cloud) when a terminal finishes while they're away.
+        if _account:
+            app.state.last_account = _account
+
+        # Pre-session gate: do NOT open the (metered) /live voice session until the
+        # user taps Start ("begin") or starts talking. Until then we only do FREE
+        # setup, listing terminals and setting the folder/terminal, so idle pairing
+        # and choosing a project never cost the user a minute.
+        await websocket.send_json(
+            {"type": "status", "status": "ready",
+             "working_dir": getattr(controller, "working_dir", "") or ""})
+
+        async def _push_terminals():
+            try:
+                from server.terminals import discover_claude_sessions
+                sessions = await asyncio.to_thread(discover_claude_sessions)
+                # Seed the orchestrator with the SAME list the phone is shown, so
+                # tapping a terminal (attach_terminal by id) resolves correctly.
+                orchestrator.remember_terminals(sessions)
+                await websocket.send_json({"type": "terminals", "terminals": sessions})
+            except Exception:
+                pass
+        asyncio.ensure_future(_push_terminals())
+
+        first_audio = None
+        while True:
+            msg = await websocket.receive()
+            if msg["type"] == "websocket.disconnect":
+                return  # hung up during setup; nothing was attached or metered
+            if msg.get("bytes") is not None:
+                first_audio = msg["bytes"]   # talking implicitly begins the session
+                break
+            if msg.get("text"):
+                try:
+                    data = json.loads(msg["text"])
+                except ValueError:
+                    continue
+                if data.get("type") == "begin":
+                    break
+                # Folder/terminal selection is free, handle it before metering.
+                await handle_client_control(msg["text"], orchestrator, websocket, None)
+
+        async with _as_cm(operator_factory(config, orchestrator.handle_tool_call, **_kwargs)) as operator:
+            async def audio_out(pcm):
+                touch()  # Gemini is speaking -> the line is active
+                _counts["out"] += 1
+                if _counts["out"] % 50 == 1:
+                    _log.info("ws: sent %d audio chunks -> phone", _counts["out"])
+                await websocket.send_bytes(pcm)
+            operator.set_audio_out(audio_out)
+            operator.set_text_out(notify)
+
+            # Attach this operator's voice to the line and speak anything that
+            # queued up while no phone was connected.
+            pending_updates = hub.attach(lambda t: operator.speak(t))
+            # Everything from here runs with the line attached; detach() MUST run even on
+            # cancellation (uvicorn reload/shutdown) or an exception, otherwise line_open
+            # stays True and every later background finish is silently dropped.
+            try:
+                # If this call was triggered by a specific Claude terminal, attach to THAT
+                # terminal so Voxa continues that session instead of an empty default one,
+                # and OPEN with that context so it knows where you are.
+                source = getattr(app.state, "pending_source", None)
+                app.state.pending_source = None
+                attached_folder = None
+                if source and source.get("cwd"):
+                    try:
+                        res = await orchestrator.attach_source(source["cwd"])
+                        if "attached" in res:
+                            controller = orchestrator.controller   # follow the swap
+                            app.state.controller = controller      # persist for reconnects
+                            attached_folder = (os.path.basename(source["cwd"].rstrip("/"))
+                                               or source["cwd"])
+                            await websocket.send_json(
+                                {"type": "status",
+                                 "working_dir": res.get("working_dir", source["cwd"])})
+                        else:
+                            _log.info("auto-attach to %s skipped: %s",
+                                      source["cwd"], res.get("error"))
+                    except Exception:
+                        logging.exception("auto-attach on answer failed")
+
+                # Voxa's opening is ALWAYS driven from here. Suppress the operator's own
+                # auto-greet: on the metered path the cloud brain would otherwise race
+                # ahead and speak a generic "what would you like to do?" the instant the
+                # /live socket opens, before this contextual opening arrives.
+                suppress_greeting_if_supported(operator)
+                if attached_folder:
+                    opening = compose_opening(attached_folder, pending_updates)
+                elif pending_updates:
+                    opening = compose_opening("", pending_updates)
+                else:
+                    opening = "Hi! What would you like to work on?"
+                await operator.speak(opening, immediate=True)
+
+                # If the session began because the user started talking, don't drop
+                # that first frame.
+                if first_audio is not None:
+                    await operator.send_audio(first_audio)
+
+                paused = False
+
+                async def recv_loop():
+                    nonlocal paused
+                    try:
+                        while True:
+                            msg = await websocket.receive()
+                            if msg["type"] == "websocket.disconnect":
+                                break
+                            if msg.get("bytes") is not None:
+                                _counts["in"] += 1
+                                # Read the CURRENTLY-driven controller (it swaps when the
+                                # user attaches to another terminal mid-call); the loop's
+                                # local `controller` would be stale after a swap.
+                                cur = orchestrator.controller
+                                if _counts["in"] % 50 == 1:
+                                    _log.info(
+                                        "ws: recv %d mic frames (status=%s)",
+                                        _counts["in"], getattr(cur, "status", "?"),
+                                    )
+                                # Cost saver: while Claude is working, stop forwarding mic
+                                # audio to Gemini. Gemini bills per audio token, so no
+                                # audio in == no charge during the wait. Resume when idle.
+                                if getattr(cur, "status", "idle") == "working":
+                                    paused = True
+                                else:
+                                    if paused:
+                                        paused = False
+                                        await websocket.send_json(
+                                            {"type": "status", "status": "listening"}
+                                        )
+                                    await operator.send_audio(msg["bytes"])
+                            elif msg.get("text"):
+                                await handle_client_control(
+                                    msg["text"], orchestrator, websocket, operator
+                                )
+                    except (WebSocketDisconnect, RuntimeError):
+                        pass
+
+                # Idle auto-disconnect: hang up after a quiet stretch (no speech, not
+                # working) so an idle line stops burning V2V minutes. Off if 0.
+                idle_timeout = float(os.environ.get("VOXA_IDLE_TIMEOUT", "180"))
+
+                async def idle_watchdog():
+                    if idle_timeout <= 0:
+                        return await asyncio.Event().wait()  # disabled
+                    while True:
+                        await asyncio.sleep(5)
+                        # Follow controller swaps: a mid-call attach must not leave the
+                        # watchdog reading the old (idle) controller and hang up mid-task.
+                        if getattr(orchestrator.controller, "status", "idle") == "working":
+                            touch()  # an active task is not idle
+                            continue
+                        if time.monotonic() - activity["t"] > idle_timeout:
+                            try:
+                                await websocket.send_json(
+                                    {"type": "status",
+                                     "status": "idle, disconnecting to save minutes"})
+                            except Exception:
+                                pass
+                            return
+
+                run_task = asyncio.ensure_future(operator.run())
+                recv_task = asyncio.ensure_future(recv_loop())
+                idle_task = asyncio.ensure_future(idle_watchdog())
+                done, pending = await asyncio.wait(
+                    [run_task, recv_task, idle_task],
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                    try:
+                        await task
+                    except asyncio.CancelledError:
+                        pass
+                    except Exception:
+                        logging.exception("loop task raised during cancellation")
+                for task in done:
+                    exc = task.exception()
+                    if exc is not None:
+                        logging.error("loop task raised: %r", exc)
+            finally:
+                # Detach the line but keep Claude running. Only an explicit stop_claude
+                # (via the orchestrator) tears the session down. Persist the
+                # currently-driven controller so the next connection reuses it.
+                app.state.controller = orchestrator.controller
+                _log.info("ws: phone disconnected (mic_in=%d audio_out=%d)",
+                          _counts["in"], _counts["out"])
+                hub.detach()
+
+    # mount static assets (js/worklet) under /static
+    from fastapi.staticfiles import StaticFiles
+    app.mount("/static", StaticFiles(directory=str(STATIC)), name="static")
+    return app
+
+
+async def handle_client_control(raw: str, orchestrator, websocket, operator=None) -> None:
+    """Handle a JSON control message sent by the phone (e.g. setting the folder)."""
+    try:
+        data = json.loads(raw)
+    except (ValueError, TypeError):
+        return
+    mtype = data.get("type")
+    if mtype == "say" and data.get("text") and operator is not None:
+        await operator.send_text(data["text"])
+    elif mtype == "claude_input" and data.get("text"):
+        # Raw terminal chat from the phone's full-screen view: type straight into the
+        # live Claude session, bypassing the voice operator.
+        await orchestrator.send_direct(data["text"])
+    elif mtype == "claude_scrollback":
+        # Full-screen terminal view wants the whole scrollback (not just the pane).
+        await orchestrator.send_scrollback()
+    elif mtype == "set_terminal" and data.get("app"):
+        orchestrator.set_terminal_app(data["app"])
+    elif mtype == "set_dir" and data.get("path"):
+        result = await orchestrator.handle_tool_call(
+            "set_working_dir", {"path": data["path"]}
+        )
+        if "error" in result:
+            await websocket.send_json(
+                {"type": "status", "status": f"folder error: {result['error']}"}
+            )
+    elif mtype == "stop":
+        # Cancel the running Claude task (works even while the mic stream is paused).
+        await orchestrator.handle_tool_call("stop_claude", {})
+        await websocket.send_json({"type": "status", "status": "stopped"})
+    elif mtype == "list_dirs":
+        # The phone's folder browser asks for the subdirectories of a path. Resolve the
+        # deepest existing ancestor (so a half-typed/nonexistent path still lists
+        # something sensible) and send its subfolders back for navigation.
+        from server.orchestrator import suggest_dirs
+        base, options = suggest_dirs(data.get("path") or "~", limit=500)
+        await websocket.send_json({"type": "dirs", "path": base, "dirs": options})
+    elif mtype == "list_terminals":
+        # The tool pushes a {"type":"terminals",...} message to the phone itself.
+        await orchestrator.handle_tool_call("list_terminals", {})
+    elif mtype == "attach_terminal" and data.get("id"):
+        res = await orchestrator.handle_tool_call("attach_terminal", {"id": data["id"]})
+        if "error" in res:
+            await websocket.send_json({"type": "status", "status": res["error"]})
+
+
+@asynccontextmanager
+async def _as_cm(obj):
+    """Accept either an async context manager or a plain object."""
+    if hasattr(obj, "__aenter__"):
+        async with obj as entered:
+            yield entered
+    else:
+        yield obj