voxa-code 0.1.0__py3-none-any.whl

server/ax_controller.py

@@ -0,0 +1,202 @@
+"""Universal terminal controller: Accessibility keystroke injection.
+
+Covers any terminal app we have no scripting bridge for (Ghostty, Warp,
+VS Code, ...). Input goes in as keyboard events posted straight to the app's
+pid (no focus steal). Reading: apps that expose text through the Accessibility
+tree get real screens; GPU terminals that do not are monitored through the
+session transcript instead (TranscriptMonitor).
+
+All system access is behind injectable seams so tests (and the Linux cloud
+box, which installs the same package) never import pyobjc.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import logging
+import subprocess
+from typing import Callable, Optional
+
+from .tmux_controller import FinalCallback, monitor_loop, clean_pane, clean_pane_with_color
+from .transcript_monitor import TranscriptMonitor
+from .transcripts import PROJECTS_DIR
+
+logger = logging.getLogger(__name__)
+
+AX_PERMISSION_ERROR = "accessibility_permission_needed"
+NO_LIVE_VIEW_NOTE = "Live view isn't available for this terminal."
+_AX_SETTINGS_URL = ("x-apple.systempreferences:"
+                    "com.apple.preference.security?Privacy_Accessibility")
+_RETURN_KEYCODE = 36
+
+
+def _quartz_post_keys(pid: int, text: str) -> None:
+    """Default poster: type `text` + Return into the app via CGEventPostToPid."""
+    import Quartz  # lazy: macOS-only
+
+    for ch in text:
+        for down in (True, False):
+            ev = Quartz.CGEventCreateKeyboardEvent(None, 0, down)
+            Quartz.CGEventKeyboardSetUnicodeString(ev, len(ch), ch)
+            Quartz.CGEventPostToPid(pid, ev)
+    for down in (True, False):
+        ev = Quartz.CGEventCreateKeyboardEvent(None, _RETURN_KEYCODE, down)
+        Quartz.CGEventPostToPid(pid, ev)
+
+
+def _ax_capture(pid: int) -> str:
+    """Default capturer: best-effort text from the app's AX tree ('' if none)."""
+    try:
+        from ApplicationServices import (  # lazy: macOS-only
+            AXUIElementCreateApplication, AXUIElementCopyAttributeValue,
+        )
+        app = AXUIElementCreateApplication(int(pid))
+        err, win = AXUIElementCopyAttributeValue(app, "AXFocusedWindow", None)
+        if err != 0 or win is None:
+            return ""
+        err, val = AXUIElementCopyAttributeValue(win, "AXValue", None)
+        return str(val) if err == 0 and val else ""
+    except Exception:
+        return ""
+
+
+def _ax_trusted() -> bool:
+    try:
+        from ApplicationServices import AXIsProcessTrusted  # lazy: macOS-only
+        return bool(AXIsProcessTrusted())
+    except Exception:
+        return False
+
+
+def _open_url(url: str) -> None:
+    try:
+        subprocess.Popen(["open", url])
+    except Exception:
+        logger.exception("could not open settings URL")
+
+
+class AXController:
+    """Drives ANY terminal app running Claude via Accessibility keystrokes.
+    Same interface as the other controllers. stop() never touches the app."""
+
+    def __init__(
+        self,
+        app_pid: int | str,
+        cwd: str,
+        *,
+        poster: Callable[[int, str], None] = _quartz_post_keys,
+        capturer: Callable[[int], str] = _ax_capture,
+        trusted: Callable[[], bool] = _ax_trusted,
+        opener: Callable[[str], None] = _open_url,
+        poll_interval: float = 1.2,
+        idle_polls: int = 3,
+        quiet_secs: float = 5.0,
+        projects_dir: str = PROJECTS_DIR,
+    ):
+        self._pid = int(app_pid)
+        self._poster = poster
+        self._capturer = capturer
+        self._trusted = trusted
+        self._opener = opener
+        self._poll = poll_interval
+        self._idle_polls = idle_polls
+        self._quiet = quiet_secs
+        self._projects = projects_dir
+        self.status = "idle"
+        self.working_dir: Optional[str] = cwd
+        self._final_cb: Optional[FinalCallback] = None
+        self._on_output = None
+        self._on_output_color = None
+        self.mirrors_screen = True
+        self._started = False
+        self._monitor_task: Optional[asyncio.Task] = None
+        self._transcript_mon: Optional[TranscriptMonitor] = None
+
+    def on_final(self, cb: FinalCallback) -> None:
+        self._final_cb = cb
+        if self._transcript_mon is not None:
+            self._transcript_mon.on_final(cb)
+
+    def on_output(self, cb) -> None:
+        self._on_output = cb
+
+    def on_output_color(self, cb) -> None:
+        self._on_output_color = cb
+
+    async def _emit_output(self, raw: str) -> None:
+        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:
+        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
+
+    def capture_scrollback(self, lines: int = 1200) -> str:
+        if not self.mirrors_screen:
+            return NO_LIVE_VIEW_NOTE
+        raw = self._capture()
+        return clean_pane_with_color(raw, max_lines=lines, max_bytes=128000)
+
+    def set_terminal_app(self, app: str) -> None:
+        pass
+
+    def _capture(self) -> str:
+        return self._capturer(self._pid)
+
+    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 start(self, working_dir: Optional[str] = None) -> None:
+        if not self._trusted():
+            self._opener(_AX_SETTINGS_URL)
+            raise PermissionError(
+                f"{AX_PERMISSION_ERROR}: grant Accessibility permission to the "
+                "Voxa server in System Settings (the pane was just opened), "
+                "then attach again.")
+        if working_dir:
+            self.working_dir = working_dir
+        self._started = True
+        self.status = "idle"
+        if self._monitor_task and not self._monitor_task.done():
+            self._monitor_task.cancel()
+        first = self._capture()
+        self.mirrors_screen = bool(first.strip())
+        if self.mirrors_screen:
+            self._monitor_task = asyncio.ensure_future(monitor_loop(self))
+        else:
+            # GPU terminal with no AX text: transcript is the source of truth.
+            self._transcript_mon = TranscriptMonitor(
+                self.working_dir or "", self._final_cb,
+                poll_interval=self._poll, quiet_secs=self._quiet,
+                projects_dir=self._projects)
+            self._monitor_task = asyncio.ensure_future(self._transcript_mon.run())
+
+    async def send(self, text: str) -> None:
+        if not self._started:
+            raise ValueError("attach to a terminal before sending")
+        self.status = "working"
+        await asyncio.to_thread(self._poster, self._pid, text)
+
+    async def stop(self, *, detach_only: bool = False) -> None:
+        self._started = False
+        if self._transcript_mon is not None:
+            await self._transcript_mon.stop()
+        if self._monitor_task and not self._monitor_task.done():
+            self._monitor_task.cancel()
+        self.status = "idle"

server/billing.py

@@ -0,0 +1,177 @@
+"""Per-account minute balance + usage ledger for Voxa's metered V2V.
+
+JSON-backed (like DeviceRegistry). The metered proxy debits seconds as a session
+streams and refuses/cuts off when the balance hits zero; IAP purchases credit
+minutes. Accounts are keyed by a stable per-customer id (e.g. the Apple
+originalTransactionId, or a device id for the free trial).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import time
+
+# Minutes granted to a brand-new account so people can try it before buying.
+FREE_TRIAL_MINUTES = float(os.environ.get("VOXA_FREE_MINUTES", "5"))
+
+# Minutes granted per StoreKit product id (subscription + consumable top-ups).
+PRODUCT_MINUTES = {
+    "voxa.sub.starter": 200,
+    "voxa.sub.starter.yearly": 2400,   # 200/mo equivalent, billed yearly
+    "voxa.topup.small": 50,
+    "voxa.topup.medium": 120,
+    "voxa.topup.large": 280,
+}
+
+
+class Billing:
+    def __init__(self, path: str = "billing.json", free_minutes: float | None = None):
+        self._path = path
+        self._free = FREE_TRIAL_MINUTES if free_minutes is None else free_minutes
+        self._lock = threading.Lock()
+        self._data: dict = self._load()
+
+    def _load(self) -> dict:
+        try:
+            with open(self._path) as f:
+                return json.load(f)
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self) -> None:
+        tmp = f"{self._path}.tmp"
+        with open(tmp, "w") as f:
+            json.dump(self._data, f)
+        os.replace(tmp, self._path)
+
+    def _acct(self, account: str) -> dict:
+        a = self._data.get(account)
+        if a is None:
+            a = {"balance_sec": self._free * 60.0, "used_sec": 0.0,
+                 "applied": [], "purchased_sec": 0.0}
+            self._data[account] = a
+        return a
+
+    # --- reads ---
+    def exists(self, account: str) -> bool:
+        """True if the account already has a ledger record (does NOT create one).
+        Used to decide whether a request would MINT a new free-trial account, so
+        that creation can be rate-limited."""
+        with self._lock:
+            return account in self._data
+
+    def balance_minutes(self, account: str) -> float:
+        with self._lock:
+            return round(self._acct(account)["balance_sec"] / 60.0, 2)
+
+    def has_minutes(self, account: str) -> bool:
+        with self._lock:
+            return self._acct(account)["balance_sec"] > 0.0
+
+    # --- writes ---
+    def credit_minutes(self, account: str, minutes: float) -> float:
+        with self._lock:
+            a = self._acct(account)
+            a["balance_sec"] += minutes * 60.0
+            a["purchased_sec"] = a.get("purchased_sec", 0.0) + minutes * 60.0
+            self._save()
+            return round(a["balance_sec"] / 60.0, 2)
+
+    def apply_purchase(self, account: str, product_id: str, txn_id: str) -> float:
+        """Credit the minutes for a verified purchase, idempotently (a given
+        transaction id is only ever applied once). Returns the new balance."""
+        with self._lock:
+            a = self._acct(account)
+            if txn_id and txn_id in a["applied"]:
+                return round(a["balance_sec"] / 60.0, 2)
+            minutes = PRODUCT_MINUTES.get(product_id, 0)
+            a["balance_sec"] += minutes * 60.0
+            a["purchased_sec"] = a.get("purchased_sec", 0.0) + minutes * 60.0
+            if txn_id:
+                a["applied"].append(txn_id)
+            self._save()
+            return round(a["balance_sec"] / 60.0, 2)
+
+    def delete_account(self, account: str) -> bool:
+        """Remove an account's balance/ledger entirely (account deletion). Returns
+        True if there was anything to remove."""
+        with self._lock:
+            existed = self._data.pop(account, None) is not None
+            if existed:
+                self._save()
+            return existed
+
+    def debit_seconds(self, account: str, seconds: float) -> float:
+        """Consume usage; returns remaining balance in minutes (floored at 0)."""
+        with self._lock:
+            a = self._acct(account)
+            a["balance_sec"] = max(0.0, a["balance_sec"] - seconds)
+            a["used_sec"] += seconds
+            self._save()
+            return round(a["balance_sec"] / 60.0, 2)
+
+    def merge_account(self, into_account: str, device_account: str) -> float:
+        """Fold an anonymous device account's balance into a signed-in account, once.
+        Verified purchases carry in full; the FREE portion is capped so a user can't
+        stack multiple free trials onto one account. Idempotent: a device account is
+        marked merged and never contributes twice. Returns the target balance (min)."""
+        with self._lock:
+            into = self._acct(into_account)
+            if not device_account or device_account == into_account:
+                return round(into["balance_sec"] / 60.0, 2)
+            if not device_account.startswith("d-"):
+                return round(into["balance_sec"] / 60.0, 2)
+            dev = self._data.get(device_account)
+            if not dev or dev.get("merged"):
+                return round(into["balance_sec"] / 60.0, 2)
+            dev_balance = dev.get("balance_sec", 0.0)
+            dev_purchased = dev.get("purchased_sec", 0.0)
+            purchased_portion = min(dev_balance, dev_purchased)
+            free_portion = max(0.0, dev_balance - purchased_portion)
+            free_cap = max(0.0, self._free * 60.0 - into.get("merged_free_sec", 0.0))
+            free_credit = min(free_portion, free_cap)
+            credit = purchased_portion + free_credit
+            into["balance_sec"] += credit
+            into["purchased_sec"] = into.get("purchased_sec", 0.0) + purchased_portion
+            into["merged_free_sec"] = into.get("merged_free_sec", 0.0) + free_credit
+            dev["balance_sec"] = 0.0
+            dev["merged"] = into_account
+            self._save()
+            return round(into["balance_sec"] / 60.0, 2)
+
+
+class MeteredSession:
+    """Tracks billable seconds for an account while a V2V session streams, and
+    tells the proxy when to cut off. Used by the hosted metered proxy: call tick()
+    periodically while audio is flowing; flush() when the session ends."""
+
+    def __init__(self, billing: Billing, account: str,
+                 flush_every: float = 10.0, clock=time.monotonic):
+        self._b = billing
+        self._acct = account
+        self._flush_every = flush_every
+        self._clock = clock
+        self._last = clock()
+        self._accum = 0.0
+
+    def tick(self) -> float:
+        """Accrue elapsed time; flush to the ledger in `flush_every` chunks.
+        Returns remaining minutes."""
+        now = self._clock()
+        self._accum += max(0.0, now - self._last)
+        self._last = now
+        if self._accum >= self._flush_every:
+            self._b.debit_seconds(self._acct, self._accum)
+            self._accum = 0.0
+        return self._b.balance_minutes(self._acct)
+
+    def flush(self) -> float:
+        if self._accum > 0:
+            self._b.debit_seconds(self._acct, self._accum)
+            self._accum = 0.0
+        return self._b.balance_minutes(self._acct)
+
+    def out_of_minutes(self) -> bool:
+        return not self._b.has_minutes(self._acct)

server/call_manager.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Bound the in-memory queues so a long-running process that never gets a phone
+# connection (or a chatty decline stream) can't grow without limit.
+_MAX_PENDING = 10
+_MAX_DECLINED = 50
+
+
+class CallManager:
+    def __init__(self, pusher, registry, ring_fn=None):
+        self._pusher = pusher
+        self._registry = registry
+        self._pending: list[str] = []
+        self._line_open = False
+        self._seq = 0
+        self._declined: list[str] = []
+        self._last_call_id: dict[str, str] = {}   # account ("" = default) -> last call_id
+
+    @property
+    def line_open(self) -> bool:
+        return self._line_open
+
+    def attach(self) -> list[str]:
+        self._line_open = True
+        drained, self._pending = self._pending, []
+        return drained
+
+    def detach(self) -> None:
+        self._line_open = False
+
+    def queue(self, summary: str) -> None:
+        """Queue an update to speak on the next attach WITHOUT ringing (the app is
+        open but no metered line is up yet)."""
+        self._pending.append(summary)
+        del self._pending[:-_MAX_PENDING]
+
+    async def decline(self, call_id: str) -> None:
+        """The phone declined (or missed) this specific call. Record it (idempotent)
+        and cancel the matching ring on the account's other devices, so a call the
+        user rejected on one phone stops ringing everywhere."""
+        if not call_id or call_id in self._declined:
+            return
+        self._declined.append(call_id)
+        del self._declined[:-_MAX_DECLINED]
+        account = next((a for a, cid in self._last_call_id.items() if cid == call_id), None)
+        if account is not None:
+            await self.cancel(account)
+
+    async def on_update(self, summary: str) -> None:
+        if self._line_open:
+            return
+        self._pending.append(summary)
+        del self._pending[:-_MAX_PENDING]
+        await self.ring(None, summary)
+
+    async def ring(self, account: str | None, summary: str) -> None:
+        """Ring a specific account's registered phones (or all if account is None).
+        Used by the cloud /notify path when a background terminal finishes and the
+        user isn't on the line."""
+        self._seq += 1
+        call_id = f"call-{self._seq}"
+        self._last_call_id[account or ""] = call_id
+        for token in self._registry.tokens(account):
+            try:
+                res = await self._pusher.send_voip(token, call_id, summary)
+            except Exception:
+                logger.exception("voip push raised for token %s", token[:8])
+                continue
+            if res is not True:
+                logger.warning("voip push rejected for token %s (call %s, status %s)",
+                               token[:8], call_id, res)
+                # 410 Gone = the token is permanently dead (app deleted/reinstalled).
+                # Prune it so we stop ringing a phone that will never answer.
+                if res == 410 and hasattr(self._registry, "remove"):
+                    self._registry.remove(token)
+
+    def last_call_id(self, account: str | None = None) -> str | None:
+        return self._last_call_id.get(account or "")
+
+    async def cancel(self, account: str | None = None) -> None:
+        """Stop a ringing/active call on the account's phones (handled elsewhere, or no
+        longer relevant). No-op if nothing was rung for this account."""
+        call_id = self._last_call_id.pop(account or "", None)
+        if not call_id:
+            return
+        for token in self._registry.tokens(account):
+            await self._pusher.send_voip_cancel(token, call_id)

server/certs/AppleRootCA-G3.pem

@@ -0,0 +1,15 @@
+-----BEGIN CERTIFICATE-----
+MIICQzCCAcmgAwIBAgIILcX8iNLFS5UwCgYIKoZIzj0EAwMwZzEbMBkGA1UEAwwS
+QXBwbGUgUm9vdCBDQSAtIEczMSYwJAYDVQQLDB1BcHBsZSBDZXJ0aWZpY2F0aW9u
+IEF1dGhvcml0eTETMBEGA1UECgwKQXBwbGUgSW5jLjELMAkGA1UEBhMCVVMwHhcN
+MTQwNDMwMTgxOTA2WhcNMzkwNDMwMTgxOTA2WjBnMRswGQYDVQQDDBJBcHBsZSBS
+b290IENBIC0gRzMxJjAkBgNVBAsMHUFwcGxlIENlcnRpZmljYXRpb24gQXV0aG9y
+aXR5MRMwEQYDVQQKDApBcHBsZSBJbmMuMQswCQYDVQQGEwJVUzB2MBAGByqGSM49
+AgEGBSuBBAAiA2IABJjpLz1AcqTtkyJygRMc3RCV8cWjTnHcFBbZDuWmBSp3ZHtf
+TjjTuxxEtX/1H7YyYl3J6YRbTzBPEVoA/VhYDKX1DyxNB0cTddqXl5dvMVztK517
+IDvYuVTZXpmkOlEKMaNCMEAwHQYDVR0OBBYEFLuw3qFYM4iapIqZ3r6966/ayySr
+MA8GA1UdEwEB/wQFMAMBAf8wDgYDVR0PAQH/BAQDAgEGMAoGCCqGSM49BAMDA2gA
+MGUCMQCD6cHEFl4aXTQY2e3v9GwOAEZLuN+yRhHFD/3meoyhpmvOwgPUnPWTxnS4
+at+qIxUCMG1mihDK1A3UT82NQz60imOlM27jbdoXt2QfyFMm+YhidDkLF1vLUagM
+6BgD56KyKA==
+-----END CERTIFICATE-----

server/certs/Apple_App_Attestation_Root_CA.pem

@@ -0,0 +1,14 @@
+-----BEGIN CERTIFICATE-----
+MIICITCCAaegAwIBAgIQC/O+DvHN0uD7jG5yH2IXmDAKBggqhkjOPQQDAzBSMSYw
+JAYDVQQDDB1BcHBsZSBBcHAgQXR0ZXN0YXRpb24gUm9vdCBDQTETMBEGA1UECgwK
+QXBwbGUgSW5jLjETMBEGA1UECAwKQ2FsaWZvcm5pYTAeFw0yMDAzMTgxODMyNTNa
+Fw00NTAzMTUwMDAwMDBaMFIxJjAkBgNVBAMMHUFwcGxlIEFwcCBBdHRlc3RhdGlv
+biBSb290IENBMRMwEQYDVQQKDApBcHBsZSBJbmMuMRMwEQYDVQQIDApDYWxpZm9y
+bmlhMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAERTHhmLW07ATaFQIEVwTtT4dyctdh
+NbJhFs/Ii2FdCgAHGbpphY3+d8qjuDngIN3WVhQUBHAoMeQ/cLiP1sOUtgjqK9au
+Yen1mMEvRq9Sk3Jm5X8U62H+xTD3FE9TgS41o0IwQDAPBgNVHRMBAf8EBTADAQH/
+MB0GA1UdDgQWBBSskRBTM72+aEH/pwyp5frq5eWKoTAOBgNVHQ8BAf8EBAMCAQYw
+CgYIKoZIzj0EAwMDaAAwZQIwQgFGnByvsiVbpTKwSga0kP0e8EeDS4+sQmTvb7vn
+53O5+FRXgeLhpJ06ysC5PrOyAjEAp5U4xDgEgllF7En3VcE3iexZZtKeYnpqtijV
+oyFraWVIyd/dganmrduC1bmTBGwD
+-----END CERTIFICATE-----

server/claude_controller.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import contextlib
+import inspect
+import logging
+import os
+import subprocess
+import sys
+from typing import Awaitable, Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def text_from_assistant(message: object) -> Optional[str]:
+    content = getattr(message, "content", None)
+    if content is None:
+        return None
+    parts = [getattr(b, "text", None) for b in content]
+    parts = [p for p in parts if p]
+    return "".join(parts) if parts else None
+
+
+def render_watch(message: object) -> str:
+    """Render a streamed Claude message as human-readable lines for the watch log.
+
+    Emits assistant text verbatim and a marker line for each tool use, so the
+    Terminal `tail -f` shows live progress as Claude works.
+    """
+    content = getattr(message, "content", None)
+    if content is None:
+        return ""
+    out: list[str] = []
+    for block in content:
+        text = getattr(block, "text", None)
+        tool_name = getattr(block, "name", None)  # ToolUseBlock.name
+        if text:
+            out.append(text)
+        elif tool_name:
+            out.append(f"\n  ⚙ {tool_name}")
+    return ("".join(out) + "\n") if out else ""
+
+
+def _default_session_factory(working_dir: str):
+    from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+    opts = ClaudeAgentOptions(cwd=working_dir, permission_mode="bypassPermissions")
+    return ClaudeSDKClient(options=opts)
+
+
+FinalCallback = Callable[[str], Awaitable[None]] | Callable[[str], None]
+
+
+class ClaudeController:
+    def __init__(
+        self,
+        session_factory: Optional[Callable[[str], object]] = None,
+        watch_log_path: Optional[str] = None,
+        launch_terminal: bool = False,
+    ):
+        self._factory = session_factory or _default_session_factory
+        self.status = "idle"
+        self.working_dir: Optional[str] = None
+        self._final_cb: Optional[FinalCallback] = None
+        # One persistent Claude session per call, so multi-turn follow-ups keep
+        # context ("open it", "now add a test", ...).
+        self._client: Optional[object] = None
+        self._stack: Optional[contextlib.AsyncExitStack] = None
+        # Read-only "watch window": stream Claude's live output to a log file and
+        # (optionally, on macOS) open a Terminal tailing it.
+        self._watch_log_path = watch_log_path
+        self._launch_terminal = launch_terminal
+        self._watch_launched = False
+
+    def on_final(self, cb: FinalCallback) -> None:
+        self._final_cb = cb
+
+    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}")
+        # Switching directories closes the previous session (cwd is fixed per client).
+        await self._close_client()
+        self.working_dir = path
+        self.status = "idle"
+        self._open_watch(path)
+        self._stack = contextlib.AsyncExitStack()
+        self._client = await self._stack.enter_async_context(self._factory(path))
+
+    async def _close_client(self) -> None:
+        if self._stack is not None:
+            try:
+                await self._stack.aclose()
+            except Exception:
+                logger.exception("error closing Claude session")
+        self._stack = None
+        self._client = None
+
+    def _open_watch(self, working_dir: str) -> None:
+        if not self._watch_log_path or self._watch_launched:
+            return
+        try:
+            with open(self._watch_log_path, "w") as f:
+                f.write(f"Loop — watching Claude in {working_dir}\n")
+                f.write("(read-only live view; close this window any time)\n")
+        except OSError:
+            logger.exception("could not create watch log %s", self._watch_log_path)
+            return
+        if self._launch_terminal and sys.platform == "darwin":
+            script = f'tell application "Terminal" to do script "tail -f {self._watch_log_path}"'
+            try:
+                subprocess.Popen(
+                    ["osascript", "-e", script, "-e",
+                     'tell application "Terminal" to activate']
+                )
+            except Exception:
+                logger.exception("could not open watch Terminal window")
+        self._watch_launched = True
+
+    def _watch_write(self, text: str) -> None:
+        if not self._watch_log_path or not text:
+            return
+        try:
+            with open(self._watch_log_path, "a") as f:
+                f.write(text)
+                f.flush()
+        except OSError:
+            pass
+
+    async def send(self, text: str) -> None:
+        if self._client is None:
+            raise ValueError("call start() before send()")
+        self.status = "working"
+        final_text: Optional[str] = None
+        try:
+            self._watch_write(f"\n▶ {text}\n")
+            await self._client.query(text)
+            async for msg in self._client.receive_response():
+                t = text_from_assistant(msg)
+                if t:
+                    final_text = t
+                self._watch_write(render_watch(msg))
+            self.status = "finished"
+            self._watch_write("\n✓ done\n")
+        except Exception:
+            self.status = "error"
+            self._watch_write("\n✗ error\n")
+            return
+        if final_text is not None and self._final_cb is not None:
+            result = self._final_cb(final_text)
+            if inspect.isawaitable(result):
+                await result
+
+    async def stop(self, *, detach_only: bool = False) -> None:
+        # detach_only is accepted for a uniform controller interface; the driven SDK
+        # session is closed either way (there is no separate terminal to leave running).
+        await self._close_client()
+        self.status = "idle"