cli-relay 0.1.0__py3-none-any.whl

cli_relay/events.py

@@ -0,0 +1,115 @@
+"""Normalized event stream shared by every provider adapter.
+
+Every adapter run yields zero or more progress events and then exactly one terminal
+event: :class:`Completed` or :class:`Failed`. The relay adds its own routing events
+(:class:`Skipped`, :class:`Waiting`, :class:`Switched`).
+"""
+
+from __future__ import annotations
+
+import enum
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+class FailureKind(enum.StrEnum):
+    RATE_LIMIT = "rate_limit"
+    AUTH = "auth"
+    NOT_INSTALLED = "not_installed"
+    TIMEOUT = "timeout"
+    CANCELLED = "cancelled"
+    ERROR = "error"
+
+
+@dataclass(frozen=True, kw_only=True)
+class Event:
+    provider: str
+    at: float = field(default_factory=time.time)
+
+    @property
+    def type(self) -> str:
+        name = type(self).__name__
+        return "".join("_" + c.lower() if c.isupper() else c for c in name).lstrip("_")
+
+    @property
+    def terminal(self) -> bool:
+        return False
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        for key, value in data.items():
+            if isinstance(value, enum.Enum):
+                data[key] = value.value
+        return {"type": self.type, **data}
+
+
+@dataclass(frozen=True, kw_only=True)
+class Started(Event):
+    session_id: str | None = None
+    model: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class TextDelta(Event):
+    text: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class ToolActivity(Event):
+    tool: str
+    detail: str = ""
+
+
+@dataclass(frozen=True, kw_only=True)
+class QuotaInfo(Event):
+    """A usage window reported by the provider (e.g. Claude's five_hour / seven_day)."""
+
+    window: str
+    status: str
+    utilization: float | None = None
+    resets_at: float | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class Completed(Event):
+    text: str
+    session_id: str | None = None
+    usage: dict[str, Any] = field(default_factory=dict)
+    cost_usd: float | None = None
+    duration_s: float | None = None
+
+    @property
+    def terminal(self) -> bool:
+        return True
+
+
+@dataclass(frozen=True, kw_only=True)
+class Failed(Event):
+    kind: FailureKind
+    message: str = ""
+    resets_at: float | None = None
+    session_id: str | None = None
+
+    @property
+    def terminal(self) -> bool:
+        return True
+
+
+@dataclass(frozen=True, kw_only=True)
+class Skipped(Event):
+    reason: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class Waiting(Event):
+    until: float
+    reason: str = ""
+
+
+@dataclass(frozen=True, kw_only=True)
+class Switched(Event):
+    """Emitted by the relay; ``provider`` is the one being left."""
+
+    to_provider: str
+    reason: str

cli_relay/handoff.py

@@ -0,0 +1,68 @@
+"""Carry a half-finished task over to the next provider."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from cli_relay.events import Event, Failed, TextDelta, ToolActivity
+
+HANDOFF_FILE = "HANDOFF.md"
+
+
+@dataclass
+class HandoffLog:
+    """Collects what each provider did, to brief the next one."""
+
+    original_prompt: str
+    max_tools: int = 40
+    max_text_chars: int = 6000
+    attempts: list[tuple[str, str]] = field(default_factory=list)  # (provider, reason)
+    tools: deque[str] = field(default_factory=deque)
+    text: str = ""
+
+    def observe(self, event: Event) -> None:
+        if isinstance(event, ToolActivity):
+            self.tools.append(f"[{event.provider}] {event.tool} {event.detail}".rstrip())
+            while len(self.tools) > self.max_tools:
+                self.tools.popleft()
+        elif isinstance(event, TextDelta):
+            self.text = (self.text + event.text)[-self.max_text_chars :]
+        elif isinstance(event, Failed):
+            self.attempts.append((event.provider, f"{event.kind.value}: {event.message[:200]}"))
+
+    @property
+    def has_progress(self) -> bool:
+        return bool(self.tools or self.text.strip())
+
+    def render(self) -> str:
+        lines = ["# Handoff", "", "## Original task", "", self.original_prompt.strip(), ""]
+        if self.attempts:
+            lines += ["## Previous attempts", ""]
+            lines += [f"- {p} stopped: {r}" for p, r in self.attempts]
+            lines.append("")
+        if self.tools:
+            lines += ["## Actions already taken (most recent last)", ""]
+            lines += [f"- {t}" for t in self.tools]
+            lines.append("")
+        if self.text.strip():
+            lines += ["## Last output of the previous agent", "", self.text.strip(), ""]
+        return "\n".join(lines)
+
+    def continuation_prompt(self) -> str:
+        if not self.has_progress:
+            return self.original_prompt
+        return (
+            "You are taking over a task from another coding agent that had to stop "
+            "(for example because it hit a usage limit). Its handoff notes are below.\n"
+            "The previous agent may already have changed files: before doing anything else, "
+            "inspect the current state of the working directory (for example `git status` "
+            "and `git diff`). Do not redo work that is already done; finish the task.\n\n"
+            + self.render()
+        )
+
+    def write(self, directory: Path) -> Path:
+        path = directory / HANDOFF_FILE
+        path.write_text(self.render(), encoding="utf-8")
+        return path

cli_relay/mcp_server.py

@@ -0,0 +1,102 @@
+"""Expose the relay as an MCP server (stdio), so any MCP client - Claude Code, Codex,
+Antigravity, a voice assistant - can delegate a task and get fallback for free.
+
+Requires the optional dependency: ``pip install "cli-relay[mcp]"``.
+"""
+
+# No ``from __future__ import annotations`` here: FastMCP inspects the tool signatures at
+# runtime and must see the real ``Context`` class, which is imported lazily below.
+
+import contextlib
+from pathlib import Path
+from typing import Any
+
+from cli_relay.config import Config
+from cli_relay.events import Completed, Failed, Skipped, Started, Switched
+from cli_relay.models import Permission, Task
+from cli_relay.relay import Relay
+
+
+def build_server(config: Config) -> Any:
+    try:
+        from mcp.server.fastmcp import Context, FastMCP
+    except ImportError as exc:  # pragma: no cover - depends on optional extra
+        raise SystemExit(
+            "cli-relay mcp needs the optional dependency: pip install 'cli-relay[mcp]'"
+        ) from exc
+
+    server = FastMCP("cli-relay")
+
+    @server.tool()
+    async def relay_run(
+        prompt: str,
+        cwd: str | None = None,
+        providers: list[str] | None = None,
+        permission: str = "read_only",
+        ctx: Context[Any, Any, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Run a coding task on the first available agent CLI (Claude Code, Antigravity,
+        Codex, API...), switching to the next one if a provider hits its usage limit.
+
+        permission: read_only (default), edit, or full. The server caps it at the
+        configured ``[mcp] max_permission`` (read_only unless the user raised it).
+        Returns which provider finished, its final answer and any switches that happened.
+        """
+        granted = Permission(permission).capped_by(config.mcp_max_permission)
+        relay = Relay(config.adapters(providers), config.quota(), config.policy)
+        task = Task(prompt=prompt, cwd=Path(cwd) if cwd else None, permission=granted)
+        switches: list[str] = []
+        skipped: list[str] = []
+        final: Completed | Failed | None = None
+        async for event in relay.run(task):
+            if isinstance(event, Switched):
+                switches.append(f"{event.provider} -> {event.to_provider} ({event.reason})")
+            elif isinstance(event, Skipped):
+                skipped.append(f"{event.provider}: {event.reason}")
+            elif isinstance(event, Started) and ctx is not None:
+                with contextlib.suppress(Exception):  # no request context when called directly
+                    await ctx.info(f"{event.provider} started")
+            elif isinstance(event, Completed | Failed):
+                final = event
+        if isinstance(final, Completed):
+            return {
+                "ok": True,
+                "provider": final.provider,
+                "text": final.text,
+                "session_id": final.session_id,
+                "permission": granted.value,
+                "switches": switches,
+                "skipped": skipped,
+            }
+        return {
+            "ok": False,
+            "error": final.message if final else "no result",
+            "kind": final.kind.value if isinstance(final, Failed) else None,
+            "switches": switches,
+            "skipped": skipped,
+        }
+
+    @server.tool()
+    def relay_status() -> dict[str, Any]:
+        """Show which agent providers are installed, and which are rate-limited and until when."""
+        quota = config.quota()
+        out = []
+        for adapter in config.adapters():
+            ok, reason = adapter.available()
+            block = quota.blocked(adapter.name)
+            out.append(
+                {
+                    "provider": adapter.name,
+                    "available": ok,
+                    "reason": reason,
+                    "blocked_until": block.until if block else None,
+                    "blocked_reason": block.reason if block else None,
+                }
+            )
+        return {"order": config.order, "providers": out}
+
+    return server
+
+
+def serve(config: Config) -> None:
+    build_server(config).run()

cli_relay/models.py

@@ -0,0 +1,67 @@
+"""Task and provider configuration models."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass, field, replace
+from pathlib import Path
+
+
+class Permission(enum.StrEnum):
+    """What a worker may do, mapped to each CLI's own permission flags.
+
+    * ``read_only`` - read files and answer; anything that would write or run commands
+      is denied without prompting.
+    * ``edit`` - may edit files inside the working directory; no shell commands unless
+      the provider config allows them explicitly.
+    * ``full`` - the provider's own automatic mode (Claude ``auto``, Antigravity ``auto``,
+      Codex ``workspace-write`` + ``--approve-for-me``). Never a "skip all checks" mode.
+    """
+
+    READ_ONLY = "read_only"
+    EDIT = "edit"
+    FULL = "full"
+
+    @property
+    def rank(self) -> int:
+        return ("read_only", "edit", "full").index(self.value)
+
+    def capped_by(self, cap: Permission | None) -> Permission:
+        if cap is None or self.rank <= cap.rank:
+            return self
+        return cap
+
+
+@dataclass(frozen=True)
+class Task:
+    prompt: str
+    cwd: Path | None = None
+    permission: Permission = Permission.READ_ONLY
+    #: Extra instructions appended to the provider's system prompt.
+    system_prompt: str | None = None
+    #: Session id to resume, per provider name.
+    resume: dict[str, str] = field(default_factory=dict)
+    #: Hard wall-clock limit for one provider attempt, in seconds.
+    timeout_s: float | None = None
+
+    def with_prompt(self, prompt: str) -> Task:
+        return replace(self, prompt=prompt)
+
+
+@dataclass(frozen=True)
+class ProviderSettings:
+    """Configuration of one provider entry (``[providers.<name>]`` in the config file)."""
+
+    name: str
+    type: str
+    #: Full launcher command, e.g. ``["claude"]`` or ``["wsl", "-e", "claude"]``.
+    #: ``None`` means the adapter's default binary looked up on ``PATH``.
+    command: list[str] | None = None
+    model: str | None = None
+    #: Upper bound: a task never runs with more than this on this provider.
+    permission: Permission | None = None
+    extra_args: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+    # OpenAI-compatible HTTP providers only:
+    base_url: str | None = None
+    api_key_env: str | None = None

cli_relay/ndjson.py

@@ -0,0 +1,41 @@
+"""Tolerant NDJSON parsing.
+
+CLI event streams are usually one JSON object per line, but in practice a line can be
+corrupted (e.g. an event written into the middle of another one) or contain stray log
+text. We never want one bad line to kill a long agent run, so we recover every object
+we can and drop the rest.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+_decoder = json.JSONDecoder()
+
+
+def parse_line(line: str) -> list[dict[str, Any]]:
+    """Return every JSON object that can be recovered from ``line``."""
+    line = line.strip()
+    if not line:
+        return []
+    try:
+        obj = json.loads(line)
+    except ValueError:
+        return _salvage(line)
+    return [obj] if isinstance(obj, dict) else []
+
+
+def _salvage(line: str) -> list[dict[str, Any]]:
+    found: list[dict[str, Any]] = []
+    pos = line.find("{")
+    while pos != -1:
+        try:
+            obj, end = _decoder.raw_decode(line, pos)
+        except ValueError:
+            pos = line.find("{", pos + 1)
+            continue
+        if isinstance(obj, dict):
+            found.append(obj)
+        pos = line.find("{", end)
+    return found

cli_relay/proc.py

@@ -0,0 +1,184 @@
+"""Subprocess plumbing: launch a CLI, stream stdout lines, stop it cleanly.
+
+Security notes
+--------------
+* Commands are always launched as an argument vector, never through a shell.
+* On Windows, ``.cmd``/``.bat`` launchers (npm shims such as ``claude.cmd``) are run by
+  ``cmd.exe``, which re-parses the arguments. Adapters therefore pass user text through
+  stdin or temp files, and :func:`check_cmd_shim_args` refuses arguments containing
+  ``cmd.exe`` metacharacters for such launchers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+import shutil
+import signal
+import subprocess
+import sys
+from collections.abc import AsyncIterator, Sequence
+from pathlib import Path
+
+_STREAM_LIMIT = 16 * 1024 * 1024
+_STDERR_TAIL = 64 * 1024
+_CMD_META = set('&|<>^%!"\r\n')
+
+
+class UnsafeArgumentError(ValueError):
+    pass
+
+
+def resolve(command: Sequence[str]) -> list[str] | None:
+    """Resolve ``command[0]`` on ``PATH``; ``None`` if it is not installed."""
+    if not command:
+        return None
+    exe = shutil.which(command[0])
+    if exe is None:
+        return None
+    return [exe, *command[1:]]
+
+
+def is_cmd_shim(exe: str) -> bool:
+    return sys.platform == "win32" and exe.lower().endswith((".cmd", ".bat"))
+
+
+def check_cmd_shim_args(argv: Sequence[str]) -> None:
+    if not argv or not is_cmd_shim(argv[0]):
+        return
+    for arg in argv[1:]:
+        bad = _CMD_META.intersection(arg)
+        if bad:
+            raise UnsafeArgumentError(
+                f"refusing to pass {arg!r} to {Path(argv[0]).name}: cmd.exe would interpret "
+                f"{''.join(sorted(bad))!r}. Pass it via stdin/a file, or point the provider "
+                f"'command' at the real executable instead of the .cmd shim."
+            )
+
+
+class ProcessRun:
+    """One running CLI process. Iterate :meth:`lines`; afterwards read ``returncode``."""
+
+    def __init__(
+        self,
+        argv: Sequence[str],
+        *,
+        cwd: Path | None = None,
+        stdin_data: bytes | None = None,
+        env: dict[str, str] | None = None,
+        timeout_s: float | None = None,
+    ) -> None:
+        check_cmd_shim_args(argv)
+        self.argv = list(argv)
+        self.cwd = cwd
+        self.stdin_data = stdin_data
+        self.env = {**os.environ, **env} if env else None
+        self.timeout_s = timeout_s
+        self.returncode: int | None = None
+        self.timed_out = False
+        self._stderr = bytearray()
+        self._proc: asyncio.subprocess.Process | None = None
+
+    @property
+    def stderr_tail(self) -> str:
+        return self._stderr.decode("utf-8", errors="replace")
+
+    async def lines(self) -> AsyncIterator[str]:
+        kwargs: dict[str, object] = {}
+        if sys.platform == "win32":
+            kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+        else:
+            kwargs["start_new_session"] = True
+        proc = await asyncio.create_subprocess_exec(
+            *self.argv,
+            cwd=str(self.cwd) if self.cwd else None,
+            env=self.env,
+            stdin=asyncio.subprocess.PIPE if self.stdin_data is not None else subprocess.DEVNULL,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            limit=_STREAM_LIMIT,
+            **kwargs,  # type: ignore[arg-type]
+        )
+        self._proc = proc
+        stderr_task = asyncio.create_task(self._drain_stderr(proc))
+        # Feed stdin concurrently with reading stdout, so a large prompt can never deadlock
+        # against a child that is already writing output.
+        stdin_task = asyncio.create_task(self._feed_stdin(proc))
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + self.timeout_s if self.timeout_s else None
+        assert proc.stdout is not None
+        try:
+            while True:
+                remaining = None if deadline is None else max(0.0, deadline - loop.time())
+                try:
+                    raw = await asyncio.wait_for(proc.stdout.readline(), remaining)
+                except TimeoutError:
+                    self.timed_out = True
+                    await self.stop()
+                    break
+                except ValueError:
+                    # A single line longer than the stream limit: asyncio drops it from the
+                    # buffer; skip it rather than abort the whole run.
+                    continue
+                if not raw:
+                    break
+                yield raw.decode("utf-8", errors="replace")
+            self.returncode = await proc.wait()
+        except BaseException:
+            await self.stop()
+            raise
+        finally:
+            if not stdin_task.done():
+                stdin_task.cancel()
+            await asyncio.gather(stdin_task, stderr_task, return_exceptions=True)
+
+    async def _feed_stdin(self, proc: asyncio.subprocess.Process) -> None:
+        if self.stdin_data is None or proc.stdin is None:
+            return
+        with contextlib.suppress(BrokenPipeError, ConnectionResetError):
+            proc.stdin.write(self.stdin_data)
+            await proc.stdin.drain()
+            proc.stdin.close()
+
+    async def _drain_stderr(self, proc: asyncio.subprocess.Process) -> None:
+        assert proc.stderr is not None
+        while chunk := await proc.stderr.read(8192):
+            self._stderr.extend(chunk)
+            if len(self._stderr) > _STDERR_TAIL:
+                del self._stderr[: len(self._stderr) - _STDERR_TAIL]
+
+    async def stop(self, grace_s: float = 5.0) -> None:
+        """Interrupt politely (SIGINT / CTRL_BREAK), then kill the whole process tree."""
+        proc = self._proc
+        if proc is None or proc.returncode is not None:
+            return
+        with contextlib.suppress(ProcessLookupError, OSError):
+            if sys.platform == "win32":
+                proc.send_signal(signal.CTRL_BREAK_EVENT)
+            else:
+                os.killpg(proc.pid, signal.SIGINT)
+        try:
+            await asyncio.wait_for(proc.wait(), grace_s)
+        except TimeoutError:
+            await _kill_tree(proc)
+        self.returncode = proc.returncode
+
+
+async def _kill_tree(proc: asyncio.subprocess.Process) -> None:
+    with contextlib.suppress(ProcessLookupError, OSError):
+        if sys.platform == "win32":
+            killer = await asyncio.create_subprocess_exec(
+                "taskkill",
+                "/T",
+                "/F",
+                "/PID",
+                str(proc.pid),
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+            await killer.wait()
+        else:
+            os.killpg(proc.pid, signal.SIGKILL)
+    with contextlib.suppress(Exception):
+        await asyncio.wait_for(proc.wait(), 5)