voice-copilot 0.0.1__py3-none-any.whl

voice_copilot/__init__.py

@@ -0,0 +1,3 @@
+"""voice-copilot — voice pair-programmer for LLM coding CLIs."""
+
+__version__ = "0.0.1"

voice_copilot/__main__.py

@@ -0,0 +1,4 @@
+from voice_copilot.cli import app
+
+if __name__ == "__main__":
+    app()

voice_copilot/adapters/__init__.py

@@ -0,0 +1,5 @@
+from voice_copilot.adapters.base import CLIAdapter, QuickAsideCapability
+from voice_copilot.adapters.claude_code import ClaudeCodeAdapter
+from voice_copilot.adapters.codex import CodexAdapter
+
+__all__ = ["CLIAdapter", "ClaudeCodeAdapter", "CodexAdapter", "QuickAsideCapability"]

voice_copilot/adapters/base.py

@@ -0,0 +1,91 @@
+"""CLI adapter interface.
+
+An adapter spawns and talks to a target LLM coding CLI. Its job:
+  * normalise vendor events into `EventKind` and push them on the bus
+  * accept user messages (text) from the dialog manager and inject them
+  * support suspend/resume so the user can speak without the agent racing ahead
+
+Adapters declare one of three `QuickAsideCapability` values so the dialog
+manager knows how urgently a user message can be delivered.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from enum import StrEnum
+
+log = logging.getLogger(__name__)
+
+
+class QuickAsideCapability(StrEnum):
+    NATIVE = "native"
+    """CLI has a built-in side-question channel (inject immediately mid-turn)."""
+    QUEUE = "queue"
+    """No side channel, but stdin stays open — message lands on next turn boundary."""
+    MANUAL = "manual"
+    """External process — fall back to clipboard + popup text."""
+
+
+class CLIAdapter(ABC):
+    name: str = "unknown"
+    quick_aside: QuickAsideCapability = QuickAsideCapability.MANUAL
+
+    _proc: asyncio.subprocess.Process | None = None
+    _paused: bool = False
+
+    @abstractmethod
+    async def start(self, initial_prompt: str | None = None) -> None:
+        """Spawn the CLI subprocess and start reading its events into the bus."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def send_user_message(self, text: str, *, urgent: bool = False) -> None:
+        """Deliver a user message into the running session."""
+        raise NotImplementedError
+
+    @abstractmethod
+    async def stop(self) -> None:
+        """Close stdin and terminate the subprocess."""
+        raise NotImplementedError
+
+    async def pause(self) -> bool:
+        """Freeze the child process so the user can talk uninterrupted.
+
+        Returns True if the process was actually paused (False if already
+        paused, not started, or pause unsupported on this platform). Uses
+        psutil.suspend — works on Win/macOS/Linux without sending signals.
+        """
+        if self._proc is None or self._proc.returncode is not None:
+            return False
+        if self._paused:
+            return False
+        try:
+            import psutil
+
+            psutil.Process(self._proc.pid).suspend()
+        except Exception as e:
+            log.warning("pause failed: %s", e)
+            return False
+        self._paused = True
+        return True
+
+    async def resume(self) -> bool:
+        if self._proc is None or self._proc.returncode is not None:
+            return False
+        if not self._paused:
+            return False
+        try:
+            import psutil
+
+            psutil.Process(self._proc.pid).resume()
+        except Exception as e:
+            log.warning("resume failed: %s", e)
+            return False
+        self._paused = False
+        return True
+
+    @property
+    def is_paused(self) -> bool:
+        return self._paused

voice_copilot/adapters/claude_code.py

@@ -0,0 +1,232 @@
+"""Claude Code adapter.
+
+Spawns `claude --output-format stream-json --input-format stream-json --verbose`
+and bridges its NDJSON event stream onto the bus. User messages are written to
+stdin as `{"type":"user","message":{"role":"user","content":"..."}}` — the CLI
+picks them up at the next turn boundary (queue semantics).
+
+Reference: https://code.claude.com/docs/en/agent-sdk/streaming-vs-single-mode
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+from typing import Any
+
+from voice_copilot.adapters.base import CLIAdapter, QuickAsideCapability
+from voice_copilot.core.bus import EventBus
+from voice_copilot.core.events import Event, EventKind
+
+log = logging.getLogger(__name__)
+
+_EDIT_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"}
+
+
+class ClaudeCodeAdapter(CLIAdapter):
+    name = "claude"
+    quick_aside = QuickAsideCapability.QUEUE
+
+    def __init__(
+        self,
+        bus: EventBus,
+        binary: str = "claude",
+        extra_args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        suppress_llm_events: bool = False,
+    ) -> None:
+        self._bus = bus
+        self._binary = binary
+        self._extra_args = extra_args or []
+        self._env = env or {}
+        self._suppress_llm = suppress_llm_events
+        self._proc: asyncio.subprocess.Process | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._stderr_task: asyncio.Task[None] | None = None
+        self._tool_use_to_path: dict[str, str] = {}
+        self._session_id: str | None = None
+        self._stdin_lock = asyncio.Lock()
+
+    # ------------------------------------------------------------------ lifecycle
+
+    async def start(self, initial_prompt: str | None = None) -> None:
+        if shutil.which(self._binary) is None:
+            raise RuntimeError(
+                f"`{self._binary}` not found in PATH. "
+                f"Install Claude Code: https://claude.com/product/claude-code"
+            )
+        argv = [
+            self._binary,
+            "--output-format",
+            "stream-json",
+            "--input-format",
+            "stream-json",
+            "--verbose",
+            *self._extra_args,
+        ]
+        log.info("spawning %s", " ".join(argv))
+        merged_env = {**os.environ, **self._env} if self._env else None
+        self._proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=merged_env,
+        )
+        self._reader_task = asyncio.create_task(self._read_stdout(), name="claude.stdout")
+        self._stderr_task = asyncio.create_task(self._read_stderr(), name="claude.stderr")
+
+        if initial_prompt:
+            await self.send_user_message(initial_prompt)
+
+    async def stop(self) -> None:
+        for t in (self._reader_task, self._stderr_task):
+            if t is not None:
+                t.cancel()
+        if self._proc is not None:
+            try:
+                if self._proc.stdin is not None and not self._proc.stdin.is_closing():
+                    self._proc.stdin.close()
+            except Exception:
+                pass
+            try:
+                await asyncio.wait_for(self._proc.wait(), timeout=5.0)
+            except TimeoutError:
+                self._proc.kill()
+                await self._proc.wait()
+        await self._emit(EventKind.SESSION_ENDED, {"session_id": self._session_id})
+
+    # ------------------------------------------------------------------ input
+
+    async def send_user_message(self, text: str, *, urgent: bool = False) -> None:
+        if self._proc is None or self._proc.stdin is None:
+            raise RuntimeError("Claude adapter not started")
+        frame = {"type": "user", "message": {"role": "user", "content": text}}
+        payload = (json.dumps(frame) + "\n").encode("utf-8")
+        async with self._stdin_lock:
+            self._proc.stdin.write(payload)
+            await self._proc.stdin.drain()
+        await self._emit(
+            EventKind.USER_MESSAGE,
+            {"text": text, "urgent": urgent, "delivery": "queued"},
+        )
+
+    # ------------------------------------------------------------------ readers
+
+    async def _read_stdout(self) -> None:
+        assert self._proc is not None and self._proc.stdout is not None
+        while True:
+            line = await self._proc.stdout.readline()
+            if not line:
+                break
+            try:
+                msg = json.loads(line.decode("utf-8"))
+            except json.JSONDecodeError:
+                log.warning("non-json stdout line: %r", line[:200])
+                continue
+            try:
+                await self._handle_message(msg)
+            except Exception:
+                log.exception("failed to handle claude event")
+
+    async def _read_stderr(self) -> None:
+        assert self._proc is not None and self._proc.stderr is not None
+        while True:
+            line = await self._proc.stderr.readline()
+            if not line:
+                break
+            log.info("claude stderr: %s", line.decode("utf-8", errors="replace").rstrip())
+
+    # ------------------------------------------------------------------ dispatch
+
+    async def _handle_message(self, msg: dict[str, Any]) -> None:
+        mtype = msg.get("type")
+
+        if mtype == "system":
+            if msg.get("subtype") == "init":
+                self._session_id = msg.get("session_id")
+                await self._emit(
+                    EventKind.SESSION_STARTED,
+                    {
+                        "target": "claude",
+                        "session_id": self._session_id,
+                        "model": msg.get("model"),
+                        "cwd": msg.get("cwd"),
+                        "tools": msg.get("tools"),
+                    },
+                )
+            return
+
+        if mtype == "assistant":
+            content = ((msg.get("message") or {}).get("content")) or []
+            if not isinstance(content, list):
+                return
+            for block in content:
+                if not isinstance(block, dict):
+                    continue
+                btype = block.get("type")
+                if btype == "text":
+                    if not self._suppress_llm:
+                        await self._emit(EventKind.AGENT_TEXT, {"text": block.get("text", "")})
+                elif btype == "thinking":
+                    if not self._suppress_llm:
+                        await self._emit(
+                            EventKind.AGENT_THINKING,
+                            {"text": block.get("thinking", "")},
+                        )
+                elif btype == "tool_use":
+                    tid = block.get("id", "")
+                    name = block.get("name", "")
+                    inp = block.get("input") or {}
+                    # Still record file paths locally so TOOL_CALL_FINISHED can
+                    # emit FILE_EDITED — the proxy never sees tool results.
+                    if name in _EDIT_TOOLS and isinstance(inp, dict) and "file_path" in inp:
+                        self._tool_use_to_path[tid] = str(inp["file_path"])
+                    if not self._suppress_llm:
+                        await self._emit(
+                            EventKind.TOOL_CALL_STARTED,
+                            {"tool_use_id": tid, "tool": name, "input": inp},
+                        )
+            return
+
+        if mtype == "user":
+            content = ((msg.get("message") or {}).get("content")) or []
+            if not isinstance(content, list):
+                return
+            for block in content:
+                if not isinstance(block, dict) or block.get("type") != "tool_result":
+                    continue
+                tid = block.get("tool_use_id", "")
+                is_error = bool(block.get("is_error"))
+                body = block.get("content", "")
+                preview = body if isinstance(body, str) else json.dumps(body)
+                await self._emit(
+                    EventKind.TOOL_CALL_FINISHED,
+                    {"tool_use_id": tid, "is_error": is_error, "preview": preview[:400]},
+                )
+                if not is_error and tid in self._tool_use_to_path:
+                    await self._emit(
+                        EventKind.FILE_EDITED,
+                        {"path": self._tool_use_to_path.pop(tid)},
+                    )
+            return
+
+        if mtype == "result":
+            await self._emit(
+                EventKind.TURN_ENDED,
+                {
+                    "subtype": msg.get("subtype"),
+                    "duration_ms": msg.get("duration_ms"),
+                    "total_cost_usd": msg.get("total_cost_usd"),
+                    "usage": msg.get("usage"),
+                    "is_error": bool(msg.get("is_error")),
+                    "result": msg.get("result"),
+                },
+            )
+            return
+
+    async def _emit(self, kind: EventKind, payload: dict[str, Any]) -> None:
+        await self._bus.publish(Event(kind=kind, source="claude.adapter", payload=payload))

voice_copilot/adapters/codex.py

@@ -0,0 +1,288 @@
+"""Codex CLI adapter (`codex exec --json`).
+
+Codex uses a `ThreadEvent` JSON stream:
+
+  * `thread.started`   → SESSION_STARTED
+  * `turn.started`     → TURN_STARTED
+  * `turn.completed`   → TURN_ENDED
+  * `turn.failed`      → TURN_ENDED (is_error)
+  * `item.started`     → TOOL_CALL_STARTED (for command_execution / mcp_tool_call / web_search)
+  * `item.completed`   → AGENT_TEXT / AGENT_THINKING / TOOL_CALL_FINISHED / FILE_EDITED
+  * `error`            → ERROR
+
+Reference: https://developers.openai.com/codex/noninteractive
+
+Caveat — `codex exec` is one-shot: a single turn per process. True multi-turn
+with queued user messages needs `codex proto` (proto stream JSON-RPC). Here
+we wire the single-turn case correctly; the dialog manager (Э10) will
+orchestrate follow-up turns by re-spawning with thread resumption.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import shutil
+from typing import Any
+
+from voice_copilot.adapters.base import CLIAdapter, QuickAsideCapability
+from voice_copilot.core.bus import EventBus
+from voice_copilot.core.events import Event, EventKind
+
+log = logging.getLogger(__name__)
+
+
+class CodexAdapter(CLIAdapter):
+    name = "codex"
+    quick_aside = QuickAsideCapability.QUEUE
+
+    #: Flags that make `codex exec` behave sensibly under a non-interactive wrapper.
+    #: The user can override or extend via `extra_args`.
+    DEFAULT_ARGS: tuple[str, ...] = ("--skip-git-repo-check",)
+
+    def __init__(
+        self,
+        bus: EventBus,
+        binary: str = "codex",
+        extra_args: list[str] | None = None,
+        sandbox: str | None = "workspace-write",
+        env: dict[str, str] | None = None,
+        suppress_llm_events: bool = False,
+    ) -> None:
+        self._bus = bus
+        self._binary = binary
+        extras = list(self.DEFAULT_ARGS)
+        if sandbox:
+            extras += ["--sandbox", sandbox]
+        if extra_args:
+            extras += extra_args
+        self._extra_args = extras
+        self._env = env or {}
+        self._suppress_llm = suppress_llm_events
+        self._proc: asyncio.subprocess.Process | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._stderr_task: asyncio.Task[None] | None = None
+        self._thread_id: str | None = None
+        self._pending: list[str] = []
+
+    async def start(self, initial_prompt: str | None = None) -> None:
+        if shutil.which(self._binary) is None:
+            raise RuntimeError(
+                f"`{self._binary}` not found in PATH. "
+                f"Install Codex CLI: https://github.com/openai/codex"
+            )
+        if not initial_prompt:
+            raise RuntimeError("codex exec needs an initial prompt; pass `-p '…'`.")
+
+        argv = [self._binary, "exec", "--json", *self._extra_args, initial_prompt]
+        log.info("spawning %s", " ".join(argv))
+        merged_env = {**os.environ, **self._env} if self._env else None
+        self._proc = await asyncio.create_subprocess_exec(
+            *argv,
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            env=merged_env,
+        )
+        self._reader_task = asyncio.create_task(self._read_stdout(), name="codex.stdout")
+        self._stderr_task = asyncio.create_task(self._read_stderr(), name="codex.stderr")
+
+    async def send_user_message(self, text: str, *, urgent: bool = False) -> None:
+        # `codex exec` doesn't accept follow-up messages. Queue for Э10 to pick up
+        # and spawn a new turn with thread resumption.
+        self._pending.append(text)
+        await self._emit(
+            EventKind.USER_MESSAGE,
+            {"text": text, "urgent": urgent, "delivery": "pending-next-turn"},
+        )
+        log.info("codex user message queued (%d pending)", len(self._pending))
+
+    async def stop(self) -> None:
+        for t in (self._reader_task, self._stderr_task):
+            if t is not None:
+                t.cancel()
+        if self._proc is not None:
+            try:
+                if self._proc.stdin is not None and not self._proc.stdin.is_closing():
+                    self._proc.stdin.close()
+            except Exception:
+                pass
+            try:
+                await asyncio.wait_for(self._proc.wait(), timeout=5.0)
+            except TimeoutError:
+                self._proc.kill()
+                await self._proc.wait()
+        await self._emit(EventKind.SESSION_ENDED, {"thread_id": self._thread_id})
+
+    # ------------------------------------------------------------------ readers
+
+    async def _read_stdout(self) -> None:
+        assert self._proc is not None and self._proc.stdout is not None
+        while True:
+            line = await self._proc.stdout.readline()
+            if not line:
+                break
+            try:
+                msg = json.loads(line.decode("utf-8"))
+            except json.JSONDecodeError:
+                log.warning("non-json codex stdout: %r", line[:200])
+                continue
+            try:
+                await self._handle_event(msg)
+            except Exception:
+                log.exception("failed to handle codex event")
+
+    async def _read_stderr(self) -> None:
+        assert self._proc is not None and self._proc.stderr is not None
+        while True:
+            line = await self._proc.stderr.readline()
+            if not line:
+                break
+            log.info("codex stderr: %s", line.decode("utf-8", errors="replace").rstrip())
+
+    # ------------------------------------------------------------------ dispatch
+
+    async def _handle_event(self, msg: dict[str, Any]) -> None:
+        etype = msg.get("type")
+
+        if etype == "thread.started":
+            self._thread_id = msg.get("thread_id")
+            await self._emit(
+                EventKind.SESSION_STARTED,
+                {"target": "codex", "thread_id": self._thread_id},
+            )
+            return
+
+        if etype == "turn.started":
+            await self._emit(EventKind.TURN_STARTED, {"thread_id": self._thread_id})
+            return
+
+        if etype in ("turn.completed", "turn.failed"):
+            usage = msg.get("usage") or {}
+            await self._emit(
+                EventKind.TURN_ENDED,
+                {
+                    "is_error": etype == "turn.failed",
+                    "input_tokens": usage.get("input_tokens"),
+                    "output_tokens": usage.get("output_tokens"),
+                    "cached_input_tokens": usage.get("cached_input_tokens"),
+                },
+            )
+            return
+
+        if etype == "item.started":
+            await self._on_item(msg, phase="started")
+            return
+        if etype == "item.updated":
+            # Most items only get a single completion event; skip updates to avoid
+            # spamming the commentator. Dialog manager can opt-in later if needed.
+            return
+        if etype == "item.completed":
+            await self._on_item(msg, phase="completed")
+            return
+
+        if etype == "error":
+            await self._emit(EventKind.ERROR, {"message": msg.get("message"), "raw": msg})
+            return
+
+    async def _on_item(self, msg: dict[str, Any], *, phase: str) -> None:
+        item = msg.get("item") or {}
+        itype = item.get("item_type") or item.get("type")
+        item_id = item.get("id") or item.get("item_id")
+
+        if itype == "agent_message" and phase == "completed":
+            if not self._suppress_llm:
+                await self._emit(EventKind.AGENT_TEXT, {"text": item.get("text", "")})
+            return
+
+        if itype == "reasoning" and phase == "completed":
+            if not self._suppress_llm:
+                await self._emit(
+                    EventKind.AGENT_THINKING,
+                    {"text": item.get("summary") or item.get("text", "")},
+                )
+            return
+
+        if itype == "command_execution":
+            if phase == "started":
+                if not self._suppress_llm:
+                    await self._emit(
+                        EventKind.TOOL_CALL_STARTED,
+                        {
+                            "tool_use_id": item_id,
+                            "tool": "Bash",
+                            "input": {"cmd": item.get("command")},
+                        },
+                    )
+            else:
+                await self._emit(
+                    EventKind.TOOL_CALL_FINISHED,
+                    {
+                        "tool_use_id": item_id,
+                        "tool": "Bash",
+                        "is_error": (item.get("exit_code") or 0) != 0,
+                        "exit_code": item.get("exit_code"),
+                        "preview": (item.get("aggregated_output") or "")[:400],
+                    },
+                )
+            return
+
+        if itype == "file_change" and phase == "completed":
+            for change in item.get("changes") or []:
+                path = change.get("path") or change.get("file_path")
+                if path:
+                    await self._emit(EventKind.FILE_EDITED, {"path": path})
+            return
+
+        if itype in ("mcp_tool_call", "collab_tool_call"):
+            if phase == "started":
+                if not self._suppress_llm:
+                    await self._emit(
+                        EventKind.TOOL_CALL_STARTED,
+                        {
+                            "tool_use_id": item_id,
+                            "tool": item.get("tool") or itype,
+                            "server": item.get("server"),
+                            "input": item.get("arguments"),
+                        },
+                    )
+            else:
+                await self._emit(
+                    EventKind.TOOL_CALL_FINISHED,
+                    {
+                        "tool_use_id": item_id,
+                        "tool": item.get("tool") or itype,
+                        "is_error": bool(item.get("error")),
+                        "preview": (str(item.get("result") or "")[:400]),
+                    },
+                )
+            return
+
+        if itype == "web_search":
+            if phase == "started":
+                if not self._suppress_llm:
+                    await self._emit(
+                        EventKind.TOOL_CALL_STARTED,
+                        {
+                            "tool_use_id": item_id,
+                            "tool": "WebSearch",
+                            "input": {"query": item.get("query")},
+                        },
+                    )
+            else:
+                await self._emit(
+                    EventKind.TOOL_CALL_FINISHED,
+                    {"tool_use_id": item_id, "tool": "WebSearch"},
+                )
+            return
+
+        if itype == "error":
+            await self._emit(EventKind.ERROR, {"message": item.get("message"), "raw": item})
+            return
+
+        # todo_list and unknown items — fall through silently.
+
+    async def _emit(self, kind: EventKind, payload: dict[str, Any]) -> None:
+        await self._bus.publish(Event(kind=kind, source="codex.adapter", payload=payload))

voice_copilot/audio/__init__.py

@@ -0,0 +1,5 @@
+from voice_copilot.audio.hub import AudioHub
+from voice_copilot.audio.mic import MicSession, transcribe_and_publish
+from voice_copilot.audio.tts_driver import TTSDriver
+
+__all__ = ["AudioHub", "MicSession", "TTSDriver", "transcribe_and_publish"]