cli-relay 0.1.0__py3-none-any.whl

cli_relay/__init__.py

@@ -0,0 +1,39 @@
+"""cli-relay: one worker interface over several coding-agent CLIs, with fallback on limits."""
+
+from cli_relay.events import (
+    Completed,
+    Event,
+    Failed,
+    FailureKind,
+    QuotaInfo,
+    Skipped,
+    Started,
+    Switched,
+    TextDelta,
+    ToolActivity,
+    Waiting,
+)
+from cli_relay.models import Permission, ProviderSettings, Task
+from cli_relay.relay import Relay, RelayPolicy
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Completed",
+    "Event",
+    "Failed",
+    "FailureKind",
+    "Permission",
+    "ProviderSettings",
+    "QuotaInfo",
+    "Relay",
+    "RelayPolicy",
+    "Skipped",
+    "Started",
+    "Switched",
+    "Task",
+    "TextDelta",
+    "ToolActivity",
+    "Waiting",
+    "__version__",
+]

cli_relay/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from cli_relay.cli import main
+
+sys.exit(main())

cli_relay/adapters/__init__.py

@@ -0,0 +1,38 @@
+"""Provider adapters and the type registry used by the config loader."""
+
+from __future__ import annotations
+
+from cli_relay.adapters.antigravity import AntigravityAdapter
+from cli_relay.adapters.base import Adapter, CliAdapter
+from cli_relay.adapters.claude import ClaudeAdapter
+from cli_relay.adapters.codex import CodexAdapter
+from cli_relay.adapters.openai_compat import OpenAICompatAdapter
+from cli_relay.models import ProviderSettings
+
+REGISTRY: dict[str, type[Adapter]] = {
+    cls.type_name: cls
+    for cls in (ClaudeAdapter, AntigravityAdapter, CodexAdapter, OpenAICompatAdapter)
+}
+
+
+def create(settings: ProviderSettings) -> Adapter:
+    try:
+        cls = REGISTRY[settings.type]
+    except KeyError:
+        known = ", ".join(sorted(REGISTRY))
+        raise ValueError(
+            f"provider {settings.name!r}: unknown type {settings.type!r} (known: {known})"
+        ) from None
+    return cls(settings)
+
+
+__all__ = [
+    "REGISTRY",
+    "Adapter",
+    "AntigravityAdapter",
+    "ClaudeAdapter",
+    "CliAdapter",
+    "CodexAdapter",
+    "OpenAICompatAdapter",
+    "create",
+]

cli_relay/adapters/antigravity.py

@@ -0,0 +1,109 @@
+"""Google Antigravity CLI (``agy -p --output-format stream-json``).
+
+``agy`` is a native executable, so the prompt can go on the command line. Very long
+prompts are written to a temp file that the agent is asked to read (Windows limits a
+command line to ~32k characters).
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, ClassVar
+
+from cli_relay.adapters.base import CliAdapter, Invocation, ParseState, short
+from cli_relay.errors import classify, reset_hint
+from cli_relay.events import Completed, Event, Failed, Started, TextDelta, ToolActivity
+from cli_relay.models import Permission, Task
+
+_MODE = {
+    Permission.READ_ONLY: "plan",
+    Permission.EDIT: "accept-edits",
+    Permission.FULL: "auto",
+}
+_MAX_ARG_PROMPT = 20_000
+
+
+class AntigravityAdapter(CliAdapter):
+    type_name: ClassVar[str] = "antigravity"
+    default_command: ClassVar[list[str]] = ["agy"]
+
+    def build(self, task: Task, exe: list[str]) -> Invocation:
+        inv = Invocation(argv=[*exe])
+        prompt = task.prompt
+        if task.system_prompt:
+            prompt = f"{task.system_prompt.strip()}\n\n---\n\n{prompt}"
+        if len(prompt) > _MAX_ARG_PROMPT:
+            path = self.temp_text_file(inv, prompt)
+            inv.argv += ["--add-dir", os.path.dirname(path)]
+            prompt = (
+                f"Your full task is in the file {path}. Read that file completely and "
+                f"do exactly what it says."
+            )
+        inv.argv += [
+            "-p",
+            prompt,
+            "--output-format",
+            "stream-json",
+            "--mode",
+            _MODE[self.permission_for(task)],
+        ]
+        if self.settings.model:
+            inv.argv += ["--model", self.settings.model]
+        if session := task.resume.get(self.name):
+            inv.argv += ["--conversation", session]
+        inv.argv += self.settings.extra_args
+        return inv
+
+    def parse(self, obj: dict[str, Any], state: ParseState) -> list[Event]:
+        p = self.name
+        event = obj.get("event")
+        if event == "init":
+            init = obj.get("init") or {}
+            state.session_id = obj.get("conversation_id") or init.get("conversation_id")
+            state.model = init.get("model")
+            return [Started(provider=p, session_id=state.session_id, model=state.model)]
+        if event == "step_update":
+            step = obj.get("step_update") or {}
+            kind = step.get("step_type")
+            if kind == "agent_response" and step.get("text_delta"):
+                return [TextDelta(provider=p, text=step["text_delta"])]
+            if kind == "tool" and step.get("state") == "ACTIVE":
+                info = step.get("tool_info") or {}
+                params = info.get("parameters") or {}
+                detail = next((short(v) for v in params.values() if isinstance(v, str)), "")
+                return [
+                    ToolActivity(provider=p, tool=str(step.get("tool_name", "?")), detail=detail)
+                ]
+            if step.get("error"):
+                state.error_text.append(short(step["error"], 500))
+            return []
+        if event == "error" or "error" in obj:
+            err = obj.get("error")
+            state.error_text.append(short(err if err is not None else obj, 500))
+            return []
+        if event == "result":
+            return [self._result(obj.get("result") or {}, state)]
+        return []
+
+    def _result(self, res: dict[str, Any], state: ParseState) -> Event:
+        session = res.get("conversation_id") or state.session_id
+        status = str(res.get("status", ""))
+        response = res.get("response") if isinstance(res.get("response"), str) else ""
+        if status.upper() == "SUCCESS":
+            return Completed(
+                provider=self.name,
+                text=(response or "").strip(),
+                session_id=session,
+                usage=res.get("usage") or {},
+                duration_s=res.get("duration_seconds"),
+            )
+        message = "\n".join(
+            x for x in (status, str(res.get("error") or ""), response or "", *state.error_text) if x
+        )
+        return Failed(
+            provider=self.name,
+            kind=classify(message),
+            message=short(message, 2000),
+            resets_at=reset_hint(message),
+            session_id=session,
+        )

cli_relay/adapters/base.py

@@ -0,0 +1,153 @@
+"""Adapter interface and the shared implementation for NDJSON-streaming CLIs."""
+
+from __future__ import annotations
+
+import abc
+import contextlib
+import os
+import tempfile
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from cli_relay.errors import classify
+from cli_relay.events import Event, Failed, FailureKind
+from cli_relay.models import Permission, ProviderSettings, Task
+from cli_relay.ndjson import parse_line
+from cli_relay.proc import ProcessRun, UnsafeArgumentError, resolve
+
+
+class Adapter(abc.ABC):
+    """A provider the relay can hand a task to."""
+
+    #: Adapter type name used in config files (``type = "claude"``).
+    type_name: ClassVar[str]
+
+    def __init__(self, settings: ProviderSettings) -> None:
+        self.settings = settings
+
+    @property
+    def name(self) -> str:
+        return self.settings.name
+
+    @abc.abstractmethod
+    def available(self) -> tuple[bool, str]:
+        """``(True, "")`` if the provider can be used right now, else ``(False, reason)``."""
+
+    @abc.abstractmethod
+    def run(self, task: Task) -> AsyncIterator[Event]:
+        """Yield progress events, then exactly one terminal event."""
+
+    def permission_for(self, task: Task) -> Permission:
+        return task.permission.capped_by(self.settings.permission)
+
+
+@dataclass
+class Invocation:
+    argv: list[str]
+    stdin: bytes | None = None
+    temp_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class ParseState:
+    """Mutable per-run state an adapter's parser can use."""
+
+    session_id: str | None = None
+    model: str | None = None
+    text: list[str] = field(default_factory=list)
+    error_text: list[str] = field(default_factory=list)
+    resets_at: float | None = None
+    terminal: bool = False
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+class CliAdapter(Adapter):
+    """Base for adapters that launch a CLI emitting one JSON event per line."""
+
+    default_command: ClassVar[list[str]]
+
+    def command(self) -> list[str] | None:
+        return resolve(self.settings.command or self.default_command)
+
+    def available(self) -> tuple[bool, str]:
+        if self.command() is None:
+            wanted = (self.settings.command or self.default_command)[0]
+            return False, f"'{wanted}' not found on PATH"
+        return True, ""
+
+    # -- to implement -------------------------------------------------------------------
+    @abc.abstractmethod
+    def build(self, task: Task, exe: list[str]) -> Invocation: ...
+
+    @abc.abstractmethod
+    def parse(self, obj: dict[str, Any], state: ParseState) -> list[Event]: ...
+
+    # -- shared ------------------------------------------------------------------------
+    def finish(self, state: ParseState, returncode: int | None, stderr: str) -> Event:
+        """Terminal event when the stream ended without one."""
+        message = "\n".join(state.error_text) or stderr.strip()[-2000:]
+        if not message:
+            message = f"{self.name} exited with code {returncode} without a result"
+        return Failed(
+            provider=self.name,
+            kind=classify(message),
+            message=message,
+            resets_at=state.resets_at,
+            session_id=state.session_id,
+        )
+
+    def temp_text_file(self, inv: Invocation, text: str, suffix: str = ".md") -> str:
+        fd, path = tempfile.mkstemp(prefix="cli-relay-", suffix=suffix)
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        inv.temp_files.append(path)
+        return path
+
+    async def run(self, task: Task) -> AsyncIterator[Event]:
+        exe = self.command()
+        if exe is None:
+            yield Failed(
+                provider=self.name, kind=FailureKind.NOT_INSTALLED, message=self.available()[1]
+            )
+            return
+        inv = self.build(task, exe)
+        state = ParseState()
+        try:
+            try:
+                proc = ProcessRun(
+                    inv.argv,
+                    cwd=task.cwd,
+                    stdin_data=inv.stdin,
+                    env=self.settings.env or None,
+                    timeout_s=task.timeout_s,
+                )
+            except UnsafeArgumentError as exc:
+                yield Failed(provider=self.name, kind=FailureKind.ERROR, message=str(exc))
+                return
+            async for line in proc.lines():
+                for obj in parse_line(line):
+                    for event in self.parse(obj, state):
+                        if state.terminal and event.terminal:
+                            continue  # keep the first terminal event only
+                        if event.terminal:
+                            state.terminal = True
+                        yield event
+            if proc.timed_out and not state.terminal:
+                yield Failed(
+                    provider=self.name,
+                    kind=FailureKind.TIMEOUT,
+                    message=f"no result within {task.timeout_s}s",
+                    session_id=state.session_id,
+                )
+            elif not state.terminal:
+                yield self.finish(state, proc.returncode, proc.stderr_tail)
+        finally:
+            for path in inv.temp_files:
+                with contextlib.suppress(OSError):
+                    os.unlink(path)
+
+
+def short(value: object, limit: int = 120) -> str:
+    text = " ".join(str(value).split())
+    return text if len(text) <= limit else text[: limit - 1] + "…"

cli_relay/adapters/claude.py

@@ -0,0 +1,169 @@
+"""Claude Code (``claude -p --output-format stream-json``).
+
+Runs the official, unmodified ``claude`` binary under the user's own login. The prompt is
+sent on stdin and the system prompt through a temp file, so no user text ever goes on
+the command line (``claude`` is an npm ``.cmd`` shim on Windows).
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+
+from cli_relay.adapters.base import CliAdapter, Invocation, ParseState, short
+from cli_relay.errors import classify, reset_hint
+from cli_relay.events import (
+    Completed,
+    Event,
+    Failed,
+    FailureKind,
+    QuotaInfo,
+    Started,
+    TextDelta,
+    ToolActivity,
+)
+from cli_relay.models import Permission, Task
+
+_PERMISSION_MODE = {
+    Permission.READ_ONLY: "dontAsk",  # pre-approved reads only, everything else denied
+    Permission.EDIT: "acceptEdits",
+    Permission.FULL: "auto",
+}
+
+
+class ClaudeAdapter(CliAdapter):
+    type_name: ClassVar[str] = "claude"
+    default_command: ClassVar[list[str]] = ["claude"]
+
+    def build(self, task: Task, exe: list[str]) -> Invocation:
+        argv = [
+            *exe,
+            "-p",
+            "--output-format",
+            "stream-json",
+            "--verbose",
+            "--include-partial-messages",
+            "--permission-mode",
+            _PERMISSION_MODE[self.permission_for(task)],
+            "--permission-prompts",
+            "none",
+        ]
+        inv = Invocation(argv=argv, stdin=task.prompt.encode("utf-8"))
+        if self.settings.model:
+            argv += ["--model", self.settings.model]
+        if session := task.resume.get(self.name):
+            argv += ["--resume", session]
+        if task.system_prompt:
+            argv += ["--append-system-prompt-file", self.temp_text_file(inv, task.system_prompt)]
+        argv += self.settings.extra_args
+        return inv
+
+    def parse(self, obj: dict[str, Any], state: ParseState) -> list[Event]:
+        kind = obj.get("type")
+        p = self.name
+        if kind == "system":
+            sub = obj.get("subtype")
+            if sub == "init":
+                state.session_id = obj.get("session_id")
+                state.model = obj.get("model")
+                return [Started(provider=p, session_id=state.session_id, model=state.model)]
+            if sub == "api_retry":
+                err = obj.get("error")
+                if err:
+                    state.error_text.append(short(err, 500))
+            return []
+        if kind == "stream_event":
+            ev = obj.get("event") or {}
+            delta = ev.get("delta") or {}
+            if ev.get("type") == "content_block_delta" and delta.get("type") == "text_delta":
+                state.extra["partial"] = True
+                return [TextDelta(provider=p, text=delta.get("text", ""))]
+            return []
+        if kind == "assistant":
+            out: list[Event] = []
+            for block in (obj.get("message") or {}).get("content") or []:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "tool_use":
+                    out.append(
+                        ToolActivity(
+                            provider=p,
+                            tool=str(block.get("name", "?")),
+                            detail=_tool_detail(block.get("input")),
+                        )
+                    )
+                elif block.get("type") == "text" and not state.extra.get("partial"):
+                    out.append(TextDelta(provider=p, text=block.get("text", "")))
+            return out
+        if kind == "rate_limit_event":
+            return self._quota(obj.get("rate_limit_info") or {}, state)
+        if kind == "result":
+            return [self._result(obj, state)]
+        return []
+
+    def _quota(self, info: dict[str, Any], state: ParseState) -> list[Event]:
+        events: list[Event] = []
+        windows = info.get("unifiedWindows") or {}
+        if not windows and info.get("rateLimitType"):
+            windows = {info["rateLimitType"]: info}
+        for window, data in windows.items():
+            if not isinstance(data, dict):
+                continue
+            status = str(data.get("status", "unknown"))
+            resets = _num(data.get("resetsAt"))
+            if status not in ("allowed", "allowed_warning") and resets:
+                state.resets_at = max(state.resets_at or 0, resets)
+            events.append(
+                QuotaInfo(
+                    provider=self.name,
+                    window=str(window),
+                    status=status,
+                    utilization=_num(data.get("utilization")),
+                    resets_at=resets,
+                )
+            )
+        return events
+
+    def _result(self, obj: dict[str, Any], state: ParseState) -> Event:
+        session = obj.get("session_id") or state.session_id
+        text = obj.get("result")
+        if obj.get("subtype") == "success" and not obj.get("is_error"):
+            duration = _num(obj.get("duration_ms"))
+            return Completed(
+                provider=self.name,
+                text=text if isinstance(text, str) else "",
+                session_id=session,
+                usage=obj.get("usage") or {},
+                cost_usd=_num(obj.get("total_cost_usd")),
+                duration_s=duration / 1000 if duration is not None else None,
+            )
+        message = (
+            "\n".join(str(x) for x in (text, *obj.get("errors", []), *state.error_text) if x)
+            or f"claude result: {obj.get('subtype')}"
+        )
+        status = obj.get("api_error_status")
+        failure = FailureKind.RATE_LIMIT if status in (429, "429") else classify(message, status)
+        if failure is FailureKind.ERROR and state.resets_at:
+            failure = FailureKind.RATE_LIMIT  # a window was reported as exhausted
+        return Failed(
+            provider=self.name,
+            kind=failure,
+            message=short(message, 2000),
+            resets_at=state.resets_at or reset_hint(message),
+            session_id=session,
+        )
+
+
+def _tool_detail(data: object) -> str:
+    if isinstance(data, dict):
+        for key in ("command", "file_path", "path", "pattern", "url", "query", "description"):
+            if data.get(key):
+                return short(data[key])
+    return ""
+
+
+def _num(value: object) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int | float):
+        return float(value)
+    return None

cli_relay/adapters/codex.py

@@ -0,0 +1,120 @@
+"""OpenAI Codex CLI (``codex exec --json``).
+
+Command layout and the failure / rate-limit path are verified against codex-cli 0.167;
+the success path follows the published JSONL event documentation. The prompt always goes
+on stdin (``codex`` is an npm shim on Windows).
+
+If ``codex`` is not on ``PATH``, the copy bundled with the Codex desktop app on Windows
+(``%LOCALAPPDATA%\\OpenAI\\Codex\\bin\\<build>\\codex.exe``) is used.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, ClassVar
+
+from cli_relay.adapters.base import CliAdapter, Invocation, ParseState, short
+from cli_relay.errors import classify, reset_hint
+from cli_relay.events import Completed, Event, Failed, Started, TextDelta, ToolActivity
+from cli_relay.models import Permission, Task
+
+_SANDBOX = {
+    Permission.READ_ONLY: ["--sandbox", "read-only"],
+    Permission.EDIT: ["--sandbox", "workspace-write"],
+    Permission.FULL: ["--sandbox", "workspace-write", "--approve-for-me"],
+}
+_TOOL_ITEMS = {
+    "command_execution": "command",
+    "file_change": "path",
+    "mcp_tool_call": "tool",
+    "web_search": "query",
+}
+
+
+def desktop_bundled_codex() -> Path | None:
+    """Newest ``codex.exe`` shipped with the Codex desktop app (Windows only)."""
+    if sys.platform != "win32":
+        return None
+    base = os.environ.get("LOCALAPPDATA")
+    if not base:
+        return None
+    candidates = list((Path(base) / "OpenAI" / "Codex" / "bin").glob("*/codex.exe"))
+    if not candidates:
+        return None
+    return max(candidates, key=lambda p: p.stat().st_mtime)
+
+
+class CodexAdapter(CliAdapter):
+    type_name: ClassVar[str] = "codex"
+    default_command: ClassVar[list[str]] = ["codex"]
+
+    def command(self) -> list[str] | None:
+        found = super().command()
+        if found is None and self.settings.command is None:
+            bundled = desktop_bundled_codex()
+            if bundled is not None:
+                return [str(bundled)]
+        return found
+
+    def build(self, task: Task, exe: list[str]) -> Invocation:
+        # `exec` options (sandbox, model, extra args) must come before the `resume`
+        # subcommand: `codex exec resume` itself rejects --sandbox.
+        argv = [*exe, "exec", *_SANDBOX[self.permission_for(task)]]
+        if self.settings.model:
+            argv += ["--model", self.settings.model]
+        argv += self.settings.extra_args
+        if session := task.resume.get(self.name):
+            argv += ["resume", session]
+        argv += ["--json", "--skip-git-repo-check", "-"]  # "-": prompt from stdin
+        prompt = task.prompt
+        if task.system_prompt:
+            prompt = f"{task.system_prompt.strip()}\n\n---\n\n{prompt}"
+        return Invocation(argv=argv, stdin=prompt.encode("utf-8"))
+
+    def parse(self, obj: dict[str, Any], state: ParseState) -> list[Event]:
+        p = self.name
+        kind = obj.get("type")
+        if kind == "thread.started":
+            state.session_id = obj.get("thread_id")
+            return [Started(provider=p, session_id=state.session_id)]
+        if kind in ("item.started", "item.completed"):
+            item = obj.get("item") or {}
+            itype = item.get("type")
+            if itype == "agent_message" and kind == "item.completed":
+                text = str(item.get("text", ""))
+                state.text.append(text)
+                return [TextDelta(provider=p, text=text)]
+            if itype in _TOOL_ITEMS and kind == "item.started":
+                detail = item.get(_TOOL_ITEMS[itype]) or item.get("changes") or ""
+                return [ToolActivity(provider=p, tool=str(itype), detail=short(detail))]
+            return []
+        if kind == "error":
+            state.error_text.append(short(obj.get("message") or obj, 500))
+            return []
+        if kind == "turn.failed":
+            err = obj.get("error") or {}
+            main = str(err.get("message", err)) if isinstance(err, dict) else str(err)
+            # codex repeats the same text in the preceding `error` event: keep it once
+            parts = [main, *(t for t in state.error_text if t != short(main, 500))]
+            message = "\n".join(dict.fromkeys(p for p in parts if p))
+            return [
+                Failed(
+                    provider=p,
+                    kind=classify(message),
+                    message=short(message, 2000),
+                    resets_at=reset_hint(message),
+                    session_id=state.session_id,
+                )
+            ]
+        if kind == "turn.completed":
+            return [
+                Completed(
+                    provider=p,
+                    text=state.text[-1] if state.text else "",
+                    session_id=state.session_id,
+                    usage=obj.get("usage") or {},
+                )
+            ]
+        return []