cli-relay 0.1.0__py3-none-any.whl

cli_relay/adapters/openai_compat.py

@@ -0,0 +1,144 @@
+"""Any OpenAI-compatible chat endpoint: OpenRouter, a paid API, vLLM, Ollama, LM Studio...
+
+This is a *text-only* fallback: it has no tools and cannot edit files. It is meant as the
+last links of the chain ("answer from somewhere rather than nowhere"). Standard library
+only - no HTTP client dependency.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections.abc import AsyncIterator
+from typing import Any, ClassVar
+
+from cli_relay.adapters.base import Adapter
+from cli_relay.errors import classify, reset_hint
+from cli_relay.events import Completed, Event, Failed, FailureKind, Started, TextDelta
+from cli_relay.models import Task
+
+_DONE = object()
+
+
+class OpenAICompatAdapter(Adapter):
+    type_name: ClassVar[str] = "openai"
+
+    def available(self) -> tuple[bool, str]:
+        if not self.settings.base_url:
+            return False, "no base_url configured"
+        if not self.settings.model:
+            return False, "no model configured"
+        env = self.settings.api_key_env
+        if env and not os.environ.get(env):
+            return False, f"environment variable {env} is not set"
+        return True, ""
+
+    async def run(self, task: Task) -> AsyncIterator[Event]:
+        ok, reason = self.available()
+        if not ok:
+            yield Failed(provider=self.name, kind=FailureKind.NOT_INSTALLED, message=reason)
+            return
+        messages: list[dict[str, str]] = []
+        if task.system_prompt:
+            messages.append({"role": "system", "content": task.system_prompt})
+        messages.append({"role": "user", "content": task.prompt})
+        body = json.dumps(
+            {"model": self.settings.model, "messages": messages, "stream": True}
+        ).encode()
+        headers = {"Content-Type": "application/json", "Accept": "text/event-stream"}
+        if self.settings.api_key_env:
+            headers["Authorization"] = f"Bearer {os.environ[self.settings.api_key_env]}"
+        url = self.settings.base_url.rstrip("/") + "/chat/completions"  # type: ignore[union-attr]
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")  # noqa: S310
+
+        loop = asyncio.get_running_loop()
+        queue: asyncio.Queue[object] = asyncio.Queue()
+        stop = threading.Event()
+
+        def put(item: object) -> None:
+            loop.call_soon_threadsafe(queue.put_nowait, item)
+
+        def worker() -> None:
+            try:
+                with urllib.request.urlopen(req, timeout=task.timeout_s or 600) as resp:  # noqa: S310
+                    for raw in resp:
+                        if stop.is_set():
+                            return
+                        put(raw)
+            except urllib.error.HTTPError as exc:
+                put(exc)
+            except Exception as exc:
+                put(exc)
+            finally:
+                put(_DONE)
+
+        started = time.monotonic()
+        thread = threading.Thread(target=worker, name=f"cli-relay-{self.name}", daemon=True)
+        thread.start()
+        yield Started(provider=self.name, model=self.settings.model)
+        parts: list[str] = []
+        usage: dict[str, Any] = {}
+        try:
+            while True:
+                item = await queue.get()
+                if item is _DONE:
+                    break
+                if isinstance(item, urllib.error.HTTPError):
+                    yield self._http_failure(item)
+                    return
+                if isinstance(item, Exception):
+                    yield Failed(provider=self.name, kind=classify(item), message=str(item))
+                    return
+                assert isinstance(item, bytes)
+                line = item.decode("utf-8", errors="replace").strip()
+                if not line.startswith("data:"):
+                    continue
+                payload = line[5:].strip()
+                if payload == "[DONE]":
+                    continue
+                with contextlib.suppress(ValueError):
+                    chunk = json.loads(payload)
+                    if chunk.get("usage"):
+                        usage = chunk["usage"]
+                    for choice in chunk.get("choices") or []:
+                        text = (choice.get("delta") or {}).get("content")
+                        if text:
+                            parts.append(text)
+                            yield TextDelta(provider=self.name, text=text)
+            yield Completed(
+                provider=self.name,
+                text="".join(parts),
+                usage=usage,
+                duration_s=time.monotonic() - started,
+            )
+        finally:
+            stop.set()
+
+    def _http_failure(self, exc: urllib.error.HTTPError) -> Failed:
+        try:
+            detail = exc.read().decode("utf-8", errors="replace")[:1000]
+        except Exception:
+            detail = ""
+        message = f"HTTP {exc.code}: {detail or exc.reason}"
+        resets_at = None
+        retry_after = exc.headers.get("Retry-After") if exc.headers else None
+        if retry_after and retry_after.strip().isdigit():
+            resets_at = time.time() + int(retry_after.strip())
+        if exc.code == 429:
+            kind = FailureKind.RATE_LIMIT
+        elif exc.code in (401, 403):
+            kind = FailureKind.AUTH
+        else:
+            kind = classify(message)
+        return Failed(
+            provider=self.name,
+            kind=kind,
+            message=message,
+            resets_at=resets_at or reset_hint(message),
+        )

cli_relay/cli.py

@@ -0,0 +1,238 @@
+"""Command line interface: ``cli-relay run | status | reset | mcp``."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+import time
+from pathlib import Path
+from typing import TextIO
+
+from cli_relay import __version__
+from cli_relay.config import Config, load
+from cli_relay.events import (
+    Completed,
+    Event,
+    Failed,
+    QuotaInfo,
+    Skipped,
+    Started,
+    Switched,
+    TextDelta,
+    ToolActivity,
+    Waiting,
+)
+from cli_relay.models import Permission, Task
+from cli_relay.relay import Relay
+
+EXIT_OK, EXIT_FAILED, EXIT_USAGE = 0, 1, 2
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cli-relay",
+        description="Run a task on Claude Code / Antigravity / Codex / an API, "
+        "falling back to the next one when a provider hits its limit.",
+    )
+    parser.add_argument("--version", action="version", version=f"cli-relay {__version__}")
+    parser.add_argument("--config", help="path to cli-relay.toml")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="run a task")
+    run.add_argument("prompt", help="task text, or '-' to read it from stdin")
+    run.add_argument("--cwd", type=Path, help="working directory for the agent")
+    run.add_argument("--providers", help="comma-separated provider order (overrides config)")
+    run.add_argument(
+        "--permission",
+        choices=[p.value for p in Permission],
+        default=Permission.READ_ONLY.value,
+        help="what the agent may do (default: read_only)",
+    )
+    run.add_argument("--system", help="extra system instructions for the agent")
+    run.add_argument(
+        "--resume",
+        action="append",
+        default=[],
+        metavar="PROVIDER=SESSION",
+        help="resume a provider session (repeatable)",
+    )
+    run.add_argument("--timeout", type=float, help="seconds per provider attempt")
+    run.add_argument(
+        "--format",
+        choices=["text", "ndjson"],
+        default="text",
+        help="text for humans, ndjson for programs (default: text)",
+    )
+
+    status = sub.add_parser("status", help="show providers and known limits")
+    status.add_argument("--format", choices=["text", "json"], default="text")
+
+    reset = sub.add_parser("reset", help="forget recorded limits")
+    reset.add_argument("provider", nargs="?", help="only this provider")
+
+    sub.add_parser(
+        "mcp",
+        help="serve cli-relay as an MCP server over stdio (needs: pip install 'cli-relay[mcp]')",
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            stream.reconfigure(encoding="utf-8", errors="replace")
+    args = _build_parser().parse_args(argv)
+    try:
+        config = load(args.config)
+    except (OSError, ValueError) as exc:
+        print(f"cli-relay: config error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    try:
+        if args.command == "run":
+            return asyncio.run(_run(args, config))
+        if args.command == "status":
+            return _status(args, config)
+        if args.command == "reset":
+            config.quota().clear(args.provider)
+            print("limits cleared" + (f" for {args.provider}" if args.provider else ""))
+            return EXIT_OK
+        if args.command == "mcp":
+            from cli_relay.mcp_server import serve
+
+            serve(config)
+            return EXIT_OK
+    except KeyboardInterrupt:
+        return 130
+    except ValueError as exc:
+        print(f"cli-relay: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    return EXIT_USAGE
+
+
+async def _run(args: argparse.Namespace, config: Config) -> int:
+    # Read stdin as UTF-8 regardless of the console code page (cp1252/cp866 on Windows).
+    prompt = _read_stdin_utf8() if args.prompt == "-" else args.prompt
+    if not prompt.strip():
+        print("cli-relay: empty prompt", file=sys.stderr)
+        return EXIT_USAGE
+    resume: dict[str, str] = {}
+    for item in args.resume:
+        provider, sep, session = item.partition("=")
+        if not sep or not session:
+            raise ValueError(f"--resume expects PROVIDER=SESSION, got {item!r}")
+        resume[provider] = session
+    order = [p.strip() for p in args.providers.split(",")] if args.providers else None
+    relay = Relay(config.adapters(order), config.quota(), config.policy)
+    task = Task(
+        prompt=prompt,
+        cwd=args.cwd,
+        permission=Permission(args.permission),
+        system_prompt=args.system,
+        resume=resume,
+        timeout_s=args.timeout,
+    )
+    last: Event | None = None
+    async for event in relay.run(task):
+        last = event
+        if args.format == "ndjson":
+            print(json.dumps(event.to_dict(), ensure_ascii=False), flush=True)
+        else:
+            _print_human(event, sys.stdout, sys.stderr)
+    return EXIT_OK if isinstance(last, Completed) else EXIT_FAILED
+
+
+def _read_stdin_utf8() -> str:
+    buffer = getattr(sys.stdin, "buffer", None)
+    if buffer is None:  # replaced stdin (tests, embedding)
+        return sys.stdin.read()
+    return buffer.read().decode("utf-8-sig", errors="replace")  # type: ignore[no-any-return]
+
+
+def _print_human(event: Event, out: TextIO, err: TextIO) -> None:
+    def note(text: str) -> None:
+        print(f"\n[cli-relay] {text}", file=err, flush=True)
+
+    if isinstance(event, TextDelta):
+        out.write(event.text)
+        out.flush()
+    elif isinstance(event, Started):
+        note(f"{event.provider} started" + (f" ({event.model})" if event.model else ""))
+    elif isinstance(event, ToolActivity):
+        note(f"{event.provider}: {event.tool} {event.detail}".rstrip())
+    elif isinstance(event, QuotaInfo):
+        if event.utilization is not None and event.utilization >= 0.8:
+            note(f"{event.provider} {event.window} usage at {event.utilization:.0%}")
+    elif isinstance(event, Skipped):
+        note(f"skipping {event.provider}: {event.reason}")
+    elif isinstance(event, Waiting):
+        until = time.strftime("%H:%M", time.localtime(event.until))
+        note(f"waiting for {event.provider} until {until}")
+    elif isinstance(event, Switched):
+        note(f"switching {event.provider} -> {event.to_provider} ({event.reason})")
+    elif isinstance(event, Failed):
+        note(f"{event.provider} failed [{event.kind.value}]: {event.message}")
+    elif isinstance(event, Completed):
+        # On a subscription this is the API-equivalent price reported by the CLI, not a bill.
+        cost = f", api-equivalent ${event.cost_usd:.4f}" if event.cost_usd else ""
+        note(
+            f"done by {event.provider}"
+            + (f" (session {event.session_id}{cost})" if event.session_id else "")
+        )
+
+
+def _status(args: argparse.Namespace, config: Config) -> int:
+    quota = config.quota()
+    rows = []
+    for adapter in config.adapters():
+        ok, reason = adapter.available()
+        block = quota.blocked(adapter.name)
+        rows.append(
+            {
+                "provider": adapter.name,
+                "type": adapter.settings.type,
+                "available": ok,
+                "reason": reason,
+                "blocked_until": block.until if block else None,
+                "blocked_reason": block.reason if block else None,
+                "windows": quota.snapshot().get(adapter.name, {}).get("windows", {}),
+            }
+        )
+    if args.format == "json":
+        print(
+            json.dumps(
+                {
+                    "config": str(config.source) if config.source else None,
+                    "order": config.order,
+                    "providers": rows,
+                },
+                indent=2,
+            )
+        )
+        return EXIT_OK
+    print(f"config: {config.source or '(built-in defaults)'}")
+    for row in rows:
+        state = (
+            "ready"
+            if row["available"] and not row["blocked_until"]
+            else ("limited" if row["blocked_until"] else "unavailable")
+        )
+        line = f"  {row['provider']:<14} {state:<12}"
+        if row["blocked_until"]:
+            until = time.strftime("%Y-%m-%d %H:%M", time.localtime(row["blocked_until"]))
+            reason = " ".join(str(row["blocked_reason"]).split())
+            if len(reason) > 80:
+                reason = reason[:79] + "…"
+            line += f" until {until} ({reason})"
+        elif not row["available"]:
+            line += f" {row['reason']}"
+        for name, window in row["windows"].items():
+            if window.get("utilization") is not None:
+                line += f"  {name}={window['utilization']:.0%}"
+        print(line)
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

cli_relay/config.py

@@ -0,0 +1,131 @@
+"""Load ``cli-relay.toml``.
+
+Lookup order: ``--config PATH``, ``$CLI_RELAY_CONFIG``, ``./cli-relay.toml``, then the user
+config dir (``%APPDATA%/cli-relay/config.toml`` or ``~/.config/cli-relay/config.toml``).
+Without a file, the default chain is Claude Code -> Antigravity -> Codex.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from cli_relay.adapters import Adapter, create
+from cli_relay.events import FailureKind
+from cli_relay.models import Permission, ProviderSettings
+from cli_relay.quota import QuotaTracker, default_state_path
+from cli_relay.relay import RelayPolicy
+
+DEFAULT_ORDER = ["claude", "antigravity", "codex"]
+
+
+def user_config_path() -> Path:
+    if sys.platform == "win32":
+        base = Path(os.environ.get("APPDATA") or Path.home() / "AppData" / "Roaming")
+    else:
+        base = Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config")
+    return base / "cli-relay" / "config.toml"
+
+
+def find_config(explicit: str | Path | None = None) -> Path | None:
+    candidates = [
+        explicit,
+        os.environ.get("CLI_RELAY_CONFIG"),
+        Path("cli-relay.toml"),
+        user_config_path(),
+    ]
+    for candidate in candidates:
+        if candidate and Path(candidate).is_file():
+            return Path(candidate)
+    if explicit:
+        raise FileNotFoundError(f"config file not found: {explicit}")
+    return None
+
+
+@dataclass
+class Config:
+    order: list[str]
+    providers: dict[str, ProviderSettings]
+    policy: RelayPolicy = field(default_factory=RelayPolicy)
+    state_path: Path | None = None
+    default_cooldown_s: float = 1800
+    skip_above_utilization: float | None = 0.98
+    #: Highest permission an MCP client may request through ``relay_run``. Defaults to
+    #: read-only so a sandboxed agent cannot escalate by delegating to another one.
+    mcp_max_permission: Permission = Permission.READ_ONLY
+    source: Path | None = None
+
+    def adapters(self, only: list[str] | None = None) -> list[Adapter]:
+        names = only or self.order
+        unknown = [n for n in names if n not in self.providers]
+        if unknown:
+            raise ValueError(
+                f"unknown provider(s): {', '.join(unknown)}; "
+                f"configured: {', '.join(self.providers)}"
+            )
+        return [create(self.providers[n]) for n in names]
+
+    def quota(self) -> QuotaTracker:
+        return QuotaTracker(
+            self.state_path or default_state_path(),
+            default_cooldown_s=self.default_cooldown_s,
+            skip_above_utilization=self.skip_above_utilization,
+        )
+
+
+def load(path: str | Path | None = None) -> Config:
+    source = find_config(path)
+    data: dict[str, Any] = {}
+    if source:
+        with source.open("rb") as fh:
+            data = tomllib.load(fh)
+    return parse(data, source)
+
+
+def parse(data: dict[str, Any], source: Path | None = None) -> Config:
+    providers: dict[str, ProviderSettings] = {
+        name: ProviderSettings(name=name, type=name) for name in DEFAULT_ORDER
+    }
+    for name, raw in (data.get("providers") or {}).items():
+        if not isinstance(raw, dict):
+            raise ValueError(f"[providers.{name}] must be a table")
+        permission = raw.get("permission")
+        command = raw.get("command")
+        if isinstance(command, str):
+            command = [command]
+        providers[name] = ProviderSettings(
+            name=name,
+            type=str(raw.get("type", name)),
+            command=list(command) if command else None,
+            model=raw.get("model"),
+            permission=Permission(permission) if permission else None,
+            extra_args=[str(a) for a in raw.get("extra_args", [])],
+            env={str(k): str(v) for k, v in (raw.get("env") or {}).items()},
+            base_url=raw.get("base_url"),
+            api_key_env=raw.get("api_key_env"),
+        )
+    relay = data.get("relay") or {}
+    policy = RelayPolicy(
+        wait_if_reset_within_s=float(relay.get("wait_if_reset_within_s", 0)),
+        write_handoff_file=bool(relay.get("write_handoff_file", False)),
+    )
+    if "switch_on" in relay:
+        policy.switch_on = frozenset(FailureKind(k) for k in relay["switch_on"])
+    state = relay.get("state_path")
+    skip = relay.get("skip_above_utilization", 0.98)
+    return Config(
+        order=list(data.get("order") or DEFAULT_ORDER),
+        providers=providers,
+        policy=policy,
+        state_path=Path(state).expanduser() if state else None,
+        default_cooldown_s=float(relay.get("default_cooldown_s", 1800)),
+        skip_above_utilization=None if skip in (None, False) else float(skip),
+        mcp_max_permission=Permission(
+            (data.get("mcp") or {}).get("max_permission", Permission.READ_ONLY.value)
+        ),
+        source=source,
+    )

cli_relay/errors.py

@@ -0,0 +1,85 @@
+"""Heuristics that turn provider error text into a :class:`FailureKind`.
+
+The CLIs do not document their quota errors consistently, so classification is
+pattern based and deliberately conservative: anything not recognised is ``ERROR``.
+"""
+
+from __future__ import annotations
+
+import re
+import time
+
+from cli_relay.events import FailureKind
+
+_RATE_LIMIT = re.compile(
+    r"rate[ _-]?limit|usage[ _-]?limit|limit (?:reached|exceeded)|quota|"
+    r"resource[ _-]?exhausted|too many requests|\b429\b|out of (?:credits|usage)|"
+    r"overloaded_error|\b529\b|hit your limit|limit will reset",
+    re.IGNORECASE,
+)
+_AUTH = re.compile(
+    r"\b401\b|\b403\b|unauthori[sz]ed|not (?:logged|signed) in|please (?:log|sign) ?in|"
+    r"invalid (?:api[ _-]?key|token|credentials)|authentication|oauth token|login required",
+    re.IGNORECASE,
+)
+
+_IN_DURATION = re.compile(
+    r"\b(?:in|after)\s+(?:(\d+)\s*h(?:ours?|rs?)?\b)?\s*(?:(\d+)\s*m(?:in(?:ute)?s?)?\b)?",
+    re.IGNORECASE,
+)
+_EPOCH = re.compile(r"\b(1[6-9]\d{8})\b")
+# "try again at 11:05 AM", "resets 3pm", "resets at 15:30" (local wall-clock time)
+_CLOCK = re.compile(
+    r"\b(?:at|resets?(?:\s+at)?)\s+(\d{1,2})(?::(\d{2}))?\s*([ap]\.?m\.?)?(?![\w:])",
+    re.IGNORECASE,
+)
+
+
+def classify(*texts: object) -> FailureKind:
+    blob = " ".join(str(t) for t in texts if t)
+    if _RATE_LIMIT.search(blob):
+        return FailureKind.RATE_LIMIT
+    if _AUTH.search(blob):
+        return FailureKind.AUTH
+    return FailureKind.ERROR
+
+
+def reset_hint(text: str, now: float | None = None) -> float | None:
+    """Best-effort reset time (epoch seconds) from messages like "try again in 2h 30m"."""
+    now = time.time() if now is None else now
+    for match in _IN_DURATION.finditer(text):
+        hours, minutes = match.group(1), match.group(2)
+        if hours or minutes:
+            return now + int(hours or 0) * 3600 + int(minutes or 0) * 60
+    epoch = _EPOCH.search(text)
+    if epoch:
+        value = float(epoch.group(1))
+        if value > now:
+            return value
+    for match in _CLOCK.finditer(text):
+        clock = _next_clock_time(match, now)
+        if clock is not None:
+            return clock
+    return None
+
+
+def _next_clock_time(match: re.Match[str], now: float) -> float | None:
+    hour, minute, ampm = int(match.group(1)), match.group(2), match.group(3)
+    if minute is None and ampm is None:
+        return None  # a bare number ("at 5") is too ambiguous
+    if ampm:
+        if not 1 <= hour <= 12:
+            return None
+        hour = hour % 12 + (12 if ampm.lower().startswith("p") else 0)
+    elif hour > 23:
+        return None
+    mins = int(minute or 0)
+    if mins > 59:
+        return None
+    local = time.localtime(now)
+    target = time.mktime((local.tm_year, local.tm_mon, local.tm_mday, hour, mins, 0, 0, 0, -1))
+    if target <= now:  # already passed today -> tomorrow
+        target = time.mktime(
+            (local.tm_year, local.tm_mon, local.tm_mday + 1, hour, mins, 0, 0, 0, -1)
+        )
+    return target