voxa-code 0.1.0__py3-none-any.whl

server/tmux_controller.py

@@ -0,0 +1,580 @@
+"""Attach-mode controller for Loop.
+
+Runs an interactive ``claude`` inside a tmux session that the user can BOTH watch
+and type into on the laptop (a Terminal window attached to the session) AND drive
+by voice from the phone (we inject transcribed text with ``tmux send-keys``).
+
+It implements the same interface as :class:`ClaudeController`
+(``status``, ``working_dir``, ``on_final``, ``start``, ``send``, ``stop``) so the
+orchestrator and server use the two interchangeably.
+
+Speaking results back is best-effort: we capture the tmux pane, strip the TUI
+chrome, and return the new text since the prompt was sent. The laptop terminal is
+always the source of truth.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import os
+import json
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+import tempfile
+from typing import Awaitable, Callable, Optional, Sequence
+
+
+def _claude_launch_cmd() -> str:
+    """`claude` invocation for the Voxa-driven session. By default it uses the
+    user's NORMAL environment (their plugins, MCP, hooks) so it behaves like their
+    own Claude. Set VOXA_ISOLATE_CLAUDE=1 to run in an isolated config dir instead
+    (no global hooks/plugins) if some hook interferes; auth stays in the Keychain."""
+    base = "claude --dangerously-skip-permissions"
+    if os.environ.get("VOXA_ISOLATE_CLAUDE", "").strip().lower() not in ("1", "true", "yes"):
+        return base
+    cfg = os.path.expanduser("~/.voxa/claude-config")
+    try:
+        os.makedirs(cfg, exist_ok=True)
+        sp = os.path.join(cfg, "settings.json")
+        if not os.path.exists(sp):
+            with open(sp, "w") as f:
+                json.dump({
+                    "permissions": {"defaultMode": "bypassPermissions"},
+                    "skipDangerousModePermissionPrompt": True,
+                    "hasCompletedOnboarding": True,
+                    "theme": "dark",
+                }, f)
+    except OSError:
+        return base
+    return f"CLAUDE_CONFIG_DIR={shlex.quote(cfg)} {base}"
+
+logger = logging.getLogger(__name__)
+
+FinalCallback = Callable[[str], Awaitable[None]] | Callable[[str], None]
+# A tmux runner runs ``tmux <args>`` and returns stdout; raises on failure.
+TmuxRunner = Callable[[Sequence[str]], str]
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+_BORDER_CHARS = set("─━│┃╭╮╰╯┌┐└┘├┤┬┴┼ =·•")
+# Spinner / bullet glyphs Claude Code prints at the start of status lines.
+_SPINNER_PREFIX = "✶✻✽✢✣✤✥◐◓◑◒*•◦›❯⏵"
+# Substrings that mark Claude Code's own interface noise (not its actual answer).
+_NOISE = (
+    "mcp", "esc to interrupt", "for shortcuts", "ctrl+", "shift+tab",
+    "bypass permissions", "auto-update", "/doctor", "release-notes",
+    "what's new", "tips for getting started", "welcome back", "welcome to",
+    "claude code v", "to expand", "1m context", "/1m", "tokens", "-- insert",
+    "accept edits", "plan mode", "for agents", "/effort", "/model",
+)
+# Claude Code's status bar / footer carries these glyphs (model, effort level, usage,
+# cost, mode). It's pure UI chrome — never relay it to the operator or show it in the
+# live view (the agent kept reading "⚡ xhigh /effort" and asking the user about it).
+_STATUS_GLYPHS = "⚡🤖💰📅⊙⏵⏷◀▸"
+# Whimsical "working" verbs Claude shows in its spinner (Crunched/Sautéing/...).
+_WORK_TIMER_RE = re.compile(r"\bfor\s+\d+s\b", re.IGNORECASE)
+_COST_RE = re.compile(r"\$\d")
+
+
+def _make_default_runner(socket: Optional[str]) -> TmuxRunner:
+    """Build a tmux runner. A named ``socket`` uses a private server with NO user
+    config (so a broken ~/.tmux.conf can't break Loop) — used for sessions Loop
+    launches. ``socket=None`` targets the user's DEFAULT tmux server, used when
+    attaching to a session the user already started there."""
+    base = ["tmux"] + (["-L", socket, "-f", "/dev/null"] if socket else [])
+
+    def run(args: Sequence[str]) -> str:
+        proc = subprocess.run(base + list(args), capture_output=True, text=True)
+        if proc.returncode != 0:
+            raise RuntimeError(f"tmux {list(args)} failed: {proc.stderr.strip()}")
+        return proc.stdout
+    return run
+
+
+def _resolve_terminal_app(choice: str) -> str:
+    """Pick the macOS terminal app: explicit choice, else auto-detect (prefer iTerm2)."""
+    choice = (choice or "auto").strip()
+    if choice.lower() in ("iterm", "iterm2"):
+        return "iTerm"
+    if choice.lower() == "terminal":
+        return "Terminal"
+    # auto
+    return "iTerm" if os.path.isdir("/Applications/iTerm.app") else "Terminal"
+
+
+def clean_pane(text: str) -> str:
+    """Strip ANSI escapes and Claude-Code TUI chrome (borders, prompt, spinners,
+    MCP/status/cost noise) so only Claude's actual output reaches the user."""
+    text = _ANSI_RE.sub("", text)
+    out: list[str] = []
+    for raw in text.splitlines():
+        stripped = raw.strip()
+        if not stripped:
+            continue
+        if set(stripped) <= _BORDER_CHARS:           # box-drawing borders
+            continue
+        if stripped[0] in "│┃>" or stripped[0] in _SPINNER_PREFIX:  # input box / spinner
+            continue
+        low = stripped.lower()
+        if any(n in low for n in _NOISE):            # MCP/tips/status-bar noise
+            continue
+        if _WORK_TIMER_RE.search(low):               # "Crunched for 5s" spinner lines
+            continue
+        if _COST_RE.search(stripped) and "%" in stripped:  # the cost/token status bar
+            continue
+        if any(g in stripped for g in _STATUS_GLYPHS):      # model/effort/usage footer
+            continue
+        out.append(stripped)
+    return "\n".join(out)
+
+
+def clean_pane_with_color(text: str, max_lines: int = 200, max_bytes: int = 16000) -> str:
+    """Like clean_pane, but KEEP each surviving line's ANSI colour escapes (the phone
+    parses them into coloured text). Every filter DECISION still runs against an
+    ANSI-stripped copy of the line, so colour bytes can't smuggle chrome/noise past the
+    substring checks. Leading indentation is preserved; bounded to the last
+    ``max_lines`` / ``max_bytes`` to protect the socket and the iOS Text view."""
+    out: list[str] = []
+    for raw in text.splitlines():
+        visible = _ANSI_RE.sub("", raw)
+        stripped = visible.strip()
+        if not stripped:
+            continue
+        if set(stripped) <= _BORDER_CHARS:
+            continue
+        if stripped[0] in "│┃>" or stripped[0] in _SPINNER_PREFIX:
+            continue
+        low = stripped.lower()
+        if any(n in low for n in _NOISE):
+            continue
+        if _WORK_TIMER_RE.search(low):
+            continue
+        if _COST_RE.search(stripped) and "%" in stripped:
+            continue
+        if any(g in stripped for g in _STATUS_GLYPHS):      # model/effort/usage footer
+            continue
+        out.append(raw.rstrip())   # keep colour escapes + leading indent; trim trailing pad
+    out = out[-max_lines:]
+    s = "\n".join(out)
+    data = s.encode("utf-8")                       # bound by BYTES, not code points
+    if len(data) > max_bytes:
+        s = data[-max_bytes:].decode("utf-8", errors="ignore")
+    return s
+
+
+def new_text(before: str, after: str) -> str:
+    """Best-effort: lines present in ``after`` but not in ``before`` (else all of after)."""
+    before_lines = set(before.splitlines())
+    fresh = [ln for ln in after.splitlines() if ln not in before_lines]
+    return "\n".join(fresh) if fresh else after
+
+
+def stable_key(text: str) -> str:
+    """Normalize a screen for change-detection: drop the remaining volatile chrome and
+    ignore ticking numbers, so 'idle' is detected even while timers/costs change."""
+    out = []
+    for ln in clean_pane(text).splitlines():
+        low = ln.lower()
+        if any(k in low for k in (
+            "esc to interrupt", "tokens", "context left", "auto-update",
+            "/doctor", "crunch", "✶", "✻", "✽",
+        )):
+            continue
+        out.append(re.sub(r"\d+", "#", ln))  # ignore changing numbers
+    return "\n".join(out)
+
+
+# Claude shows these only while actively generating; their presence means "working".
+_ACTIVE_MARKERS = ("esc to interrupt", "esc to cancel")
+
+_MENU_RE = re.compile(r"^\s*[>❯]?\s*\d+[.)]\s+\S", re.MULTILINE)
+_YESNO_RE = re.compile(r"\(y/n\)|\[y/n\]|\(yes/no\)", re.IGNORECASE)
+_PROMPT_WORDS = ("do you trust", "allow ", "permission", "proceed?", "overwrite",
+                 "continue?")
+
+
+def looks_actionable(text: str) -> bool:
+    """True when the screen is a real prompt waiting on the user: a numbered menu (>=2
+    options), a (y/n), or a trust/permission question. Lets a fresh session announce
+    ONLY for an actual prompt, never for a plain idle prompt (which would call the user
+    the moment they start a session)."""
+    body = text or ""
+    if _YESNO_RE.search(body):
+        return True
+    low = body.lower()
+    if any(w in low for w in _PROMPT_WORDS):
+        return True
+    return len(_MENU_RE.findall(body)) >= 2
+
+
+async def monitor_loop(ctrl) -> None:
+    """Shared live monitor: announce new screen content when the controller's
+    ``_capture()`` stabilises (Claude finished, or is waiting on a prompt).
+
+    ``ctrl`` must expose: ``_capture()``, ``_started``, ``_poll``, ``_idle_polls``,
+    ``status`` and an async ``_emit(text)``. Used by both the tmux and iTerm controllers.
+    """
+    try:
+        baseline = ctrl._capture()
+    except Exception:
+        return
+    last_key = stable_key(baseline)
+    announced = clean_pane(baseline)
+    stable = 0
+    active = False
+    while ctrl._started:
+        await asyncio.sleep(ctrl._poll)
+        try:
+            cur = ctrl._capture()
+        except Exception:
+            break  # session gone
+        key = stable_key(cur)
+        if key != last_key:
+            last_key = key
+            stable = 0
+            active = True
+            emit_output = getattr(ctrl, "_emit_output", None)
+            if emit_output is not None:
+                await emit_output(cur)
+            emit_output_color = getattr(ctrl, "_emit_output_color", None)
+            if emit_output_color is not None:
+                await emit_output_color(cur)
+        else:
+            stable += 1
+            if active and stable >= ctrl._idle_polls:
+                cur_clean = clean_pane(cur)
+                delta = new_text(announced, cur_clean)
+                announced = cur_clean
+                active = False
+                ctrl.status = "idle"
+                await ctrl._emit(delta)
+
+
+class TmuxController:
+    def __init__(
+        self,
+        session_name: str = "voxa",
+        runner: Optional[TmuxRunner] = None,
+        launch_terminal: bool = True,
+        terminal_app: str = "auto",
+        socket: str = "voxa",
+        poll_interval: float = 1.2,
+        idle_polls: int = 3,
+        timeout: float = 180.0,
+    ):
+        self._socket = socket
+        self._run = runner or _make_default_runner(socket)
+        self._session = session_name
+        self._launch_terminal = launch_terminal
+        self._terminal_app = terminal_app
+        self._poll = poll_interval
+        self._idle_polls = idle_polls
+        self._timeout = timeout
+        self.status = "idle"
+        # True once this session has actually worked (or been sent a task) since the
+        # last announce. Gates the "finished" announce so a fresh session that merely
+        # booted to its idle prompt does not ring the phone on startup.
+        self._saw_work = False
+        self.working_dir: Optional[str] = None
+        # Set by start() when the visible terminal window could NOT be opened, so the
+        # caller can tell the user how to attach manually (e.g. Automation denied).
+        self.window_hint = ""
+        self._final_cb: Optional[FinalCallback] = None
+        # Live-output callbacks: stream Claude's current screen to the UI while it
+        # works. _on_output gets plain text (back-compat); _on_output_color gets the
+        # same lines with ANSI colour escapes kept, for the terminal-themed view.
+        self._on_output = None
+        self._on_output_color = None
+        self._started = False
+        self._monitor_task: Optional[asyncio.Task] = None
+
+    def set_terminal_app(self, app: str) -> None:
+        """Override which terminal app to open (e.g. from a phone setting)."""
+        if app:
+            self._terminal_app = app
+
+    def on_final(self, cb: FinalCallback) -> None:
+        self._final_cb = cb
+
+    def on_output(self, cb) -> None:
+        """Register a callback that receives Claude's live screen text (cleaned)."""
+        self._on_output = cb
+
+    def on_output_color(self, cb) -> None:
+        """Register a callback that receives Claude's live screen WITH ANSI colour."""
+        self._on_output_color = cb
+
+    def _capture(self) -> str:
+        # -e preserves SGR colour escapes (the live colour feed parses them on the
+        # phone). clean_pane and _stable_key still strip ANSI, so idle detection and
+        # the spoken finals are unaffected by this.
+        return self._run(["capture-pane", "-p", "-e", "-t", self._session])
+
+    def capture_scrollback(self, lines: int = 1200) -> str:
+        """Capture the pane PLUS scrollback history (coloured, chrome-stripped) for the
+        phone's full-screen terminal view. On-demand only (heavier than the live pane
+        feed) — `-S -N` reaches back into history."""
+        try:
+            raw = self._run(["capture-pane", "-p", "-e", "-S", f"-{lines}", "-t", self._session])
+        except Exception:
+            return ""
+        return clean_pane_with_color(raw, max_lines=lines, max_bytes=128000)
+
+    def _has_session(self) -> bool:
+        try:
+            self._run(["has-session", "-t", self._session])
+            return True
+        except Exception:
+            return False
+
+    def _has_client(self) -> bool:
+        """True if a terminal window is currently attached to the session, so we
+        don't open a duplicate, but DO open one if the window was closed."""
+        try:
+            return bool(self._run(["list-clients", "-t", self._session]).strip())
+        except Exception:
+            return False
+
+    def _session_path(self) -> str:
+        """The folder the existing tmux session is actually in (its pane's cwd), so
+        a stale session from a previous run isn't reused for a different folder."""
+        try:
+            return self._run(
+                ["display-message", "-p", "-t", self._session, "#{pane_current_path}"]
+            ).strip()
+        except Exception:
+            return ""
+
+    async def start(self, working_dir: str) -> None:
+        path = os.path.abspath(os.path.expanduser(working_dir))
+        if not os.path.isdir(path):
+            raise ValueError(f"not a directory: {working_dir}")
+        self.working_dir = path
+        self.status = "idle"
+
+        # An explicit "open/start a session" ALWAYS starts fresh: kill any existing
+        # session (a leftover from a previous run, or a different project) and
+        # relaunch claude clean in the requested folder. (Plain phone reconnects do
+        # NOT call start(), so a running session still persists across reconnects.)
+        if self._has_session():
+            try:
+                self._run(["kill-session", "-t", self._session])
+            except Exception:
+                pass
+        existed = False
+        if not existed:
+            # Run interactive claude inside a detached tmux session in the project dir.
+            # Launch via a login shell so the user's PATH (e.g. ~/.local/bin) is loaded,
+            # and drop back to an interactive shell when claude exits so the window stays.
+            shell = os.environ.get("SHELL", "/bin/bash")
+            self._run([
+                "new-session", "-d", "-s", self._session, "-c", path,
+                "-x", "220", "-y", "50",
+                shell, "-lc", f"{_claude_launch_cmd()}; exec {shell} -il",
+            ])
+        self._started = True
+
+        # Open a terminal window so the user can SEE the session. Open it when we
+        # just made the session, OR when one exists but no window is attached (a
+        # lingering detached session, or the user closed the window). Skip only when
+        # a window is already attached, to avoid duplicates on reconnect.
+        self.window_hint = ""
+        if self._launch_terminal and sys.platform == "darwin" and (not existed or not self._has_client()):
+            if not self._open_terminal():
+                self.window_hint = (
+                    "Couldn't open the terminal window automatically (check macOS "
+                    "Automation permission for your terminal app). To see it, run: "
+                    f"tmux -L {self._socket} attach -t {self._session}")
+
+        # Start (or restart) the live monitor that watches the pane and surfaces
+        # whatever Claude says or asks to the user by voice.
+        if self._monitor_task and not self._monitor_task.done():
+            self._monitor_task.cancel()
+        self._monitor_task = asyncio.ensure_future(self._monitor())
+
+    def _open_terminal(self) -> bool:
+        # Write an attach script so the window never just vanishes: it re-attaches while
+        # the session lives, and falls back to an interactive shell if the session ends
+        # (iTerm/Terminal close a window the moment its command returns, which caused the
+        # "window flashes then disappears" bug).
+        sock, sess = self._socket, self._session
+        # Absolute tmux path: the terminal window runs a non-login shell whose PATH may
+        # not include Homebrew, so a bare "tmux" is not found.
+        tmux_bin = shutil.which("tmux") or "tmux"
+        script_path = os.path.join(tempfile.gettempdir(), f"voxa-attach-{sock}.sh")
+        body = (
+            "#!/bin/bash\n"
+            f'echo "Voxa — attaching to your Claude session ({sess})..."\n'
+            "while true; do\n"
+            f"  {tmux_bin} -L {sock} -f /dev/null attach -t {sess}\n"
+            f"  {tmux_bin} -L {sock} -f /dev/null has-session -t {sess} 2>/dev/null || break\n"
+            "  sleep 0.5\n"
+            "done\n"
+            'echo "Voxa session ended. (window kept open)"\n'
+            'exec "$SHELL" -il\n'
+        )
+        try:
+            with open(script_path, "w") as f:
+                f.write(body)
+            os.chmod(script_path, 0o755)
+        except OSError:
+            logger.exception("could not write attach script")
+            return False
+
+        cmd = f"bash {script_path}"
+        # Try the preferred terminal app, then fall back to the other if its
+        # AppleScript fails (e.g. iTerm isn't authorised for Automation, or isn't
+        # installed). Returns True only if a window was actually opened.
+        preferred = _resolve_terminal_app(self._terminal_app)
+        order = ["iTerm", "Terminal"] if preferred == "iTerm" else ["Terminal", "iTerm"]
+        for app in order:
+            if self._run_open_script(app, cmd):
+                return True
+        logger.warning(
+            "could not open a terminal window (Automation permission?); "
+            "attach manually: tmux -L %s attach -t %s", self._socket, self._session)
+        return False
+
+    @staticmethod
+    def _open_script_for(app: str, cmd: str) -> str:
+        if app == "iTerm":
+            return ('tell application "iTerm"\n'
+                    "  activate\n"
+                    f'  create window with default profile command "{cmd}"\n'
+                    "end tell")
+        return (f'tell application "Terminal" to do script "{cmd}"\n'
+                'tell application "Terminal" to activate')
+
+    def _run_open_script(self, app: str, cmd: str) -> bool:
+        """Run the open-window AppleScript for `app`; True if it actually succeeded
+        (osascript exits non-zero when Automation is denied or the app is missing)."""
+        try:
+            r = subprocess.run(["osascript", "-e", self._open_script_for(app, cmd)],
+                               capture_output=True, text=True, timeout=10)
+            if r.returncode == 0:
+                return True
+            logger.warning("osascript open via %s failed: %s", app, (r.stderr or "").strip())
+        except Exception:
+            logger.exception("osascript open via %s raised", app)
+        return False
+
+    async def send(self, text: str) -> None:
+        """Inject the user's words into the live claude session. Returns immediately;
+        the monitor announces whatever Claude says or asks next."""
+        if not self._started:
+            raise ValueError("call start() before send()")
+        self.status = "working"
+        self._saw_work = True   # a dispatched task should announce when it finishes
+        try:
+            self._run(["send-keys", "-t", self._session, "-l", text])
+            await asyncio.sleep(0.15)
+            self._run(["send-keys", "-t", self._session, "Enter"])
+        except Exception:
+            logger.exception("tmux send failed")
+            self.status = "error"
+
+    def _stable_key(self, text: str) -> str:
+        """Normalize a pane for change-detection: drop volatile chrome (spinners, the
+        status bar, ticking timers/costs) so 'idle' is detected even though those keep
+        changing."""
+        out = []
+        for ln in clean_pane(text).splitlines():
+            low = ln.lower()
+            if any(k in low for k in (
+                "esc to interrupt", "tokens", "context left", "auto-update",
+                "/doctor", "crunch", "✶", "✻", "✽",
+            )):
+                continue
+            out.append(re.sub(r"\d+", "#", ln))  # ignore changing numbers
+        return "\n".join(out)
+
+    async def _emit(self, text: str) -> None:
+        if text.strip() and self._final_cb is not None:
+            result = self._final_cb(text)
+            if inspect.isawaitable(result):
+                await result
+
+    async def _emit_output(self, raw: str) -> None:
+        """Push the current (cleaned) screen to the live-output UI, if anyone's
+        listening. Throttled naturally by the monitor's poll interval."""
+        if self._on_output is None:
+            return
+        text = clean_pane(raw)
+        if not text.strip():
+            return
+        result = self._on_output(text)
+        if inspect.isawaitable(result):
+            await result
+
+    async def _emit_output_color(self, raw: str) -> None:
+        """Push the current screen WITH colour to the terminal-themed UI, if anyone's
+        listening. Mirrors _emit_output; throttled by the monitor's poll interval."""
+        if self._on_output_color is None:
+            return
+        text = clean_pane_with_color(raw)
+        if not text.strip():
+            return
+        result = self._on_output_color(text)
+        if inspect.isawaitable(result):
+            await result
+
+    async def _monitor(self) -> None:
+        """Watch the pane; when Claude stops changing (finished, or waiting on a
+        question/menu/permission prompt), announce the new screen content so the
+        operator can read it to the user and ask what to do."""
+        try:
+            baseline = self._capture()
+        except Exception:
+            return
+        last_key = self._stable_key(baseline)
+        announced = clean_pane(baseline)
+        stable = 0
+        active = False
+        while self._started:
+            await asyncio.sleep(self._poll)
+            try:
+                cur = self._capture()
+            except Exception:
+                break  # session gone
+            if any(m in cur.lower() for m in _ACTIVE_MARKERS):
+                self._saw_work = True
+            key = self._stable_key(cur)
+            if key != last_key:
+                last_key = key
+                stable = 0
+                active = True
+                await self._emit_output(cur)         # plain live stream (back-compat)
+                await self._emit_output_color(cur)   # colour live stream (themed view)
+            else:
+                stable += 1
+                if active and stable >= self._idle_polls:
+                    cur_clean = clean_pane(cur)
+                    delta = new_text(announced, cur_clean)
+                    announced = cur_clean
+                    active = False
+                    self.status = "idle"
+                    # Announce only a real finish (work happened) or a genuine prompt;
+                    # a fresh boot settling to its idle prompt must not fire (it would
+                    # ring the phone the moment a session starts).
+                    if self._saw_work or looks_actionable(cur_clean):
+                        self._saw_work = False
+                        await self._emit(delta)
+
+    async def stop(self, *, detach_only: bool = False) -> None:
+        # Do NOT kill the tmux session: the laptop terminal must stay usable after the
+        # phone hangs up. Stop the monitor and (unless detach_only) send an interrupt
+        # (Escape) to halt any in-progress generation. detach_only is used when swapping
+        # to another terminal, so the session we leave keeps running its task.
+        self._started = False
+        if self._monitor_task and not self._monitor_task.done():
+            self._monitor_task.cancel()
+        if not detach_only:
+            try:
+                self._run(["send-keys", "-t", self._session, "Escape"])
+            except Exception:
+                pass
+        self.status = "idle"