coderouter-cli 2.7.6__py3-none-any.whl → 2.7.8__py3-none-any.whl

coderouter/adapters/agent_cli.py

@@ -0,0 +1,780 @@
+"""External coding-agent CLI adapter (``kind="agent_cli"``).
+
+This adapter invokes an external coding-agent CLI (Claude Code / Codex /
+Gemini / Grok) as a single one-shot ``exec`` and returns the agent's final
+answer as one ``prompt in → text out`` transformation. It is the in-core
+implementation of the external-agents-adapter design
+(``docs/designs/external-agents-adapter.md``).
+
+Design in one paragraph
+=======================
+
+A coding-agent CLI is normally a stateful, multi-turn, filesystem-editing
+control loop — at odds with CodeRouter's "one request = one stateless
+transformation" ethos. Restricting it to a single non-interactive
+one-shot ``exec`` collapses it back into a single transformation, which
+keeps the ethos intact: orchestration stays on the *client* side, and
+CodeRouter merely performs the one conversion. Following the
+``openai_compat`` precedent, a *single* adapter class fronts *multiple*
+target agents, dispatched on the ``agent`` field.
+
+Implemented agents (Phase 1a + 1d)
+==================================
+
+Two targets are implemented here:
+
+* ``claude`` (Claude Code CLI, Phase 1a) — the most stable CLI, the most
+  fine-grained safety controls, and the only one that emits
+  ``total_cost_usd`` directly (making it the reference implementation for
+  the parser / cost path).
+* ``grok`` (grok CLI, Phase 1d) — headless one-shot via ``--prompt-file`` +
+  ``--output-format json``. The CLI emits no token/cost figures, so usage
+  is reported as zeros (cost stays 0 unless the operator sets
+  ``ProviderConfig.cost``, design §5.1.6). ``--no-memory`` is always passed
+  so a user-level cross-session memory setting cannot leak state between
+  requests.
+
+The remaining agents (codex / gemini) are declared in the config schema so
+providers.yaml is forward-compatible, but constructing an adapter for them
+raises a clear ``AdapterError`` until their phase (1b / 1c) lands.
+
+Security (design §6, non-negotiable)
+====================================
+
+* **allowlist argv only** — the child is launched with
+  :func:`asyncio.create_subprocess_exec` and a list argv. ``shell=True`` is
+  never used; the prompt is never subject to shell interpretation (claude
+  reads it from stdin; grok reads it from a private ``0600`` prompt file
+  inside the resolved workdir — its ``-p`` requires the prompt as an argv
+  value, and argv would both hit Linux's ~128KiB ``MAX_ARG_STRLEN`` on huge
+  prompts and leak the text into ``ps`` output).
+* **default read-only** — ``allow_file_writes=False`` /
+  ``sandbox_mode="read_only"`` are the defaults, mapped to claude's
+  ``--permission-mode plan``. Writes require explicit opt-in and the sandbox
+  mapping is clamped to read-only whenever ``allow_file_writes`` is False.
+* **workdir boundary** — the working directory is expanded, resolved to an
+  absolute path and created; a literal ``..`` escape is rejected.
+* **timeout with process-group kill** — ``exec_timeout_s`` is enforced with
+  :func:`asyncio.wait_for`; on expiry the whole process *group* is
+  ``SIGKILL``ed (the CLI hangs a real LLM call off a child, so killing only
+  the parent would orphan it).
+* **env allowlist** — the child does NOT inherit the parent environment. A
+  minimal env is built explicitly; ``ANTHROPIC_API_KEY`` is never forwarded
+  unless the operator lists it in ``passthrough_env`` (this prevents a
+  stray key from silently overriding subscription OAuth).
+* **recursion cap** — ``CODEROUTER_AGENT_DEPTH`` is propagated (incremented)
+  into the child and refused at or above ``agent_depth_limit``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import shutil
+import signal
+import time
+import uuid
+from collections.abc import AsyncIterator, Iterator
+from pathlib import Path
+from typing import Any
+
+from coderouter.adapters.base import (
+    AdapterError,
+    BaseAdapter,
+    ChatRequest,
+    ChatResponse,
+    ProviderCallOverrides,
+    StreamChunk,
+)
+from coderouter.config.schemas import AgentCliConfig, ProviderConfig
+from coderouter.logging import get_logger
+
+logger = get_logger(__name__)
+
+# Fixed, minimal PATH injected into the child (design §5.3.1). The adapter
+# resolves the CLI executable to an absolute path itself (see ``generate``),
+# so this PATH only governs any helper binaries the CLI spawns.
+_SAFE_PATH = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+
+# Environment variable that carries the recursion depth across nested agent
+# invocations (design §5.5).
+_DEPTH_ENV = "CODEROUTER_AGENT_DEPTH"
+
+# How many trailing stderr bytes to attach to a non-zero-exit error message.
+_MAX_STDERR_TAIL = 2000
+
+# Coarse chunk size (characters) for the pseudo-stream splitter (design §5.1.4).
+_STREAM_CHUNK_CHARS = 512
+
+# sandbox_mode → claude ``--permission-mode`` value (design §5.4). ``edit``
+# and ``full_auto`` both map to ``acceptEdits`` in Phase 1a.
+_CLAUDE_PERMISSION_MODE = {
+    "read_only": "plan",
+    "edit": "acceptEdits",
+    "full_auto": "acceptEdits",
+}
+
+# sandbox_mode → grok sandbox/approval flags (design §5.4, grok CLI v0.2.93).
+# grok's ``--sandbox`` takes a built-in profile VALUE (off|workspace|
+# read-only|strict) and its ``--permission-mode`` shares Claude Code's value
+# set; ``full_auto`` swaps the permission mode for ``--always-approve``
+# (auto-approve all tool executions).
+_GROK_SANDBOX_ARGS = {
+    "read_only": ["--sandbox", "read-only", "--permission-mode", "plan"],
+    "edit": ["--sandbox", "workspace", "--permission-mode", "acceptEdits"],
+    "full_auto": ["--sandbox", "workspace", "--always-approve"],
+}
+
+
+def _chunk_text(text: str, size: int = _STREAM_CHUNK_CHARS) -> Iterator[str]:
+    """Split ``text`` into ``size``-char pieces for the pseudo-stream."""
+    for start in range(0, len(text), size):
+        yield text[start : start + size]
+
+
+class AgentCliAdapter(BaseAdapter):
+    """Invoke an external coding-agent CLI one-shot (claude + grok).
+
+    The ``agent`` field selects the argv builder / output parser via the
+    dispatch tables built in :meth:`__init__`, mirroring how
+    ``openai_compat`` fronts many HTTP backends from one class.
+    """
+
+    def __init__(self, config: ProviderConfig) -> None:
+        """Bind to a ``ProviderConfig`` and reject unsupported agents.
+
+        Constructing an adapter for an agent other than ``claude`` / ``grok``
+        raises a non-retryable :class:`AdapterError` — the other targets are
+        declared in the schema but not implemented until their phase
+        (design §9).
+        """
+        super().__init__(config)
+        if config.agent_cli is None:  # pragma: no cover - schema enforces this
+            raise AdapterError(
+                "agent_cli provider is missing its agent_cli sub-config",
+                provider=config.name,
+                retryable=False,
+            )
+        self.acfg: AgentCliConfig = config.agent_cli
+        if self.acfg.agent not in ("claude", "grok"):
+            raise AdapterError(
+                f"agent {self.acfg.agent!r} is not implemented yet "
+                f"(implemented: claude, grok). Wait for Phase 1b/1c.",
+                provider=config.name,
+                retryable=False,
+            )
+        # agent → argv builder / output parser dispatch tables. claude landed
+        # in Phase 1a, grok in Phase 1d; Phase 1b/1c add codex / gemini.
+        self._builders = {
+            "claude": self._build_claude_argv,
+            "grok": self._build_grok_argv,
+        }
+        self._parsers = {
+            "claude": self._parse_claude,
+            "grok": self._parse_grok,
+        }
+        # Prompt delivery is per-agent: claude reads its print-mode prompt
+        # from stdin (10MB cap), which keeps argv free of the (potentially
+        # huge) prompt text. grok's ``-p`` REQUIRES the prompt as its argv
+        # value (piped stdin is only appended as extra context, verified on
+        # v0.2.93), so grok gets the prompt via ``--prompt-file`` instead —
+        # see ``_write_prompt_file`` for the rationale.
+        self._uses_stdin = self.acfg.agent == "claude"
+
+    # ------------------------------------------------------------------
+    # BaseAdapter contract
+    # ------------------------------------------------------------------
+
+    async def healthcheck(self) -> bool:
+        """Lightweight check: the CLI binary exists on PATH (design §5.1.2)."""
+        return shutil.which(self.acfg.command) is not None
+
+    async def generate(
+        self,
+        request: ChatRequest,
+        *,
+        overrides: ProviderCallOverrides | None = None,
+    ) -> ChatResponse:
+        """Run the CLI once and shape the final answer into a ChatResponse.
+
+        Raises :class:`AdapterError` on every failure path, with
+        ``retryable`` set so the fallback engine can decide whether to try
+        the next provider (transient failures) or stop (config / recursion
+        errors).
+        """
+        # Recursion guard (design §5.5): refuse when we are already nested at
+        # or beyond the configured depth. Non-retryable — retrying the same
+        # chain would recurse again.
+        depth = self._current_depth()
+        if depth >= self.acfg.agent_depth_limit:
+            raise AdapterError(
+                f"agent recursion depth {depth} >= limit {self.acfg.agent_depth_limit}",
+                provider=self.name,
+                retryable=False,
+            )
+
+        # exec_timeout_s is the base; a profile-level override wins when set.
+        # NOTE: the inherited ``effective_timeout`` falls back to
+        # ``ProviderConfig.timeout_s``, which is the wrong knob here, so we
+        # resolve against ``exec_timeout_s`` explicitly (design §5.1.3).
+        timeout = (
+            overrides.timeout_s
+            if overrides is not None and overrides.timeout_s is not None
+            else self.acfg.exec_timeout_s
+        )
+
+        prompt = self._render_prompt(request, overrides)
+        workdir = self._resolve_workdir()
+
+        # Agents that cannot take the prompt on stdin (grok) get it through a
+        # private temp file inside the workdir; it is ALWAYS removed in the
+        # ``finally`` below, including on timeout / exception paths.
+        prompt_file = None if self._uses_stdin else self._write_prompt_file(prompt, workdir)
+        try:
+            argv = self._builders[self.acfg.agent](workdir, prompt_file)
+            # Resolve the executable to an absolute path so argv[0] is a
+            # concrete binary independent of the child's minimal PATH
+            # (design §6 allowlist).
+            resolved = shutil.which(argv[0])
+            if resolved is not None:
+                argv = [resolved, *argv[1:]]
+            env = self._build_child_env()
+
+            logger.info(
+                "agent-cli-exec",
+                extra={
+                    "provider": self.name,
+                    "agent": self.acfg.agent,
+                    "argv0": argv[0],
+                    "timeout_s": timeout,
+                },
+            )
+
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    *argv,
+                    stdin=asyncio.subprocess.PIPE,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    cwd=workdir,
+                    env=env,
+                    # New session/process group so a timeout can SIGKILL the
+                    # whole group (the CLI hangs its real LLM call off a
+                    # child).
+                    start_new_session=True,
+                )
+            except (FileNotFoundError, OSError) as exc:
+                raise AdapterError(
+                    f"failed to launch {self.acfg.command!r}: {exc}",
+                    provider=self.name,
+                    retryable=False,
+                ) from exc
+
+            stdin_bytes = prompt.encode("utf-8") if self._uses_stdin else None
+            try:
+                stdout, stderr = await asyncio.wait_for(
+                    proc.communicate(input=stdin_bytes), timeout=timeout
+                )
+            except TimeoutError as exc:
+                self._kill_process_group(proc)
+                with contextlib.suppress(Exception):
+                    await proc.wait()
+                raise AdapterError(
+                    f"{self.acfg.agent} exec timed out after {timeout}s",
+                    provider=self.name,
+                    retryable=True,
+                ) from exc
+
+            if proc.returncode != 0:
+                detail = self._error_detail(stdout, stderr)
+                raise AdapterError(
+                    f"{self.acfg.agent} exited {proc.returncode}: {detail}",
+                    provider=self.name,
+                    status_code=None,
+                    retryable=self._is_retryable_exit(proc.returncode),
+                )
+
+            final_text, usage, meta = self._parsers[self.acfg.agent](stdout, stderr)
+        finally:
+            if prompt_file is not None:
+                # Best-effort cleanup — the child may already have exited and
+                # a vanished file is not an error worth surfacing.
+                with contextlib.suppress(OSError):
+                    os.unlink(prompt_file)
+        return self._to_chat_response(final_text, usage, meta)
+
+    async def stream(
+        self,
+        request: ChatRequest,
+        *,
+        overrides: ProviderCallOverrides | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Pseudo-stream (design §5.1.4): run once, then chunk the answer.
+
+        No CLI in Phase 1a exposes a stable token stream, so the final text
+        from :meth:`generate` is split into content chunks followed by a
+        terminal ``finish_reason="stop"`` chunk carrying usage.
+        """
+        resp = await self.generate(request, overrides=overrides)
+        try:
+            content = resp.choices[0]["message"]["content"] or ""
+        except (IndexError, KeyError, TypeError):  # pragma: no cover - defensive
+            content = ""
+        for piece in _chunk_text(content):
+            yield StreamChunk(
+                id=resp.id,
+                created=resp.created,
+                model=resp.model,
+                choices=[{"index": 0, "delta": {"content": piece}, "finish_reason": None}],
+            )
+        yield StreamChunk(
+            id=resp.id,
+            created=resp.created,
+            model=resp.model,
+            choices=[{"index": 0, "delta": {}, "finish_reason": "stop"}],
+            usage=resp.usage,
+        )
+
+    # ------------------------------------------------------------------
+    # claude argv builder + output parser
+    # ------------------------------------------------------------------
+
+    def _build_claude_argv(self, workdir: str, prompt_file: str | None = None) -> list[str]:
+        """Assemble the ``claude -p`` argv (design §5.1.5 / §5.4).
+
+        Shape::
+
+            claude -p --output-format json --model <m> --max-turns <n>
+                   --permission-mode <plan|acceptEdits> --add-dir <workdir>
+
+        The prompt is fed on stdin (not argv), so it never appears here and
+        ``prompt_file`` is ignored (it exists only to keep the builder
+        signature uniform across agents). ``--bare`` is deliberately NOT
+        added — it would skip OAuth/keychain reads and break subscription
+        auth (design §5.3.4).
+        """
+        del prompt_file  # claude takes the prompt on stdin, not from a file.
+        model = self.acfg.model or self.config.model
+        argv = [self.acfg.command, "-p", "--output-format", "json", "--model", model]
+        if self.acfg.max_turns is not None:
+            argv += ["--max-turns", str(self.acfg.max_turns)]
+        argv += ["--permission-mode", self._claude_permission_mode()]
+        argv += ["--add-dir", workdir]
+        return argv
+
+    def _claude_permission_mode(self) -> str:
+        """Map ``sandbox_mode`` → claude ``--permission-mode``, clamped.
+
+        When ``allow_file_writes`` is False the effective mode is clamped to
+        ``read_only`` regardless of ``sandbox_mode`` — defense in depth so an
+        ``edit`` / ``full_auto`` request cannot grant writes without the
+        explicit ``allow_file_writes`` opt-in (design §5.4).
+        """
+        mode = self.acfg.sandbox_mode if self.acfg.allow_file_writes else "read_only"
+        return _CLAUDE_PERMISSION_MODE[mode]
+
+    def _parse_claude(
+        self, stdout: bytes, stderr: bytes
+    ) -> tuple[str, dict[str, Any], dict[str, Any]]:
+        """Parse claude ``--output-format json`` output (design §5.1.6).
+
+        Returns ``(final_text, usage, meta)``. Parsing is deliberately
+        defensive: any missing/blank field or a reported ``is_error`` raises a
+        retryable :class:`AdapterError` so the chain can fall through.
+        """
+        text = stdout.decode("utf-8", "replace").strip()
+        if not text:
+            raise AdapterError(
+                "claude produced no stdout to parse",
+                provider=self.name,
+                retryable=True,
+            )
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise AdapterError(
+                f"claude emitted non-JSON output: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
+        if not isinstance(data, dict):
+            raise AdapterError(
+                "claude JSON output was not an object",
+                provider=self.name,
+                retryable=True,
+            )
+        if data.get("is_error"):
+            raise AdapterError(
+                f"claude reported is_error=true: {str(data.get('result'))[:500]!r}",
+                provider=self.name,
+                retryable=True,
+            )
+        result = data.get("result")
+        if not isinstance(result, str):
+            raise AdapterError(
+                "claude JSON output missing string 'result' field",
+                provider=self.name,
+                retryable=True,
+            )
+
+        usage = self._claude_usage(data)
+        meta: dict[str, Any] = {}
+        cost = data.get("total_cost_usd")
+        if isinstance(cost, (int, float)):
+            # claude is the only CLI that emits a dollar figure directly;
+            # surface it as response metadata for the cost dashboard.
+            meta["coderouter_cost_usd"] = float(cost)
+        session_id = data.get("session_id")
+        if isinstance(session_id, str):
+            meta["coderouter_session_id"] = session_id
+        return result, usage, meta
+
+    def _claude_usage(self, data: dict[str, Any]) -> dict[str, Any]:
+        """Normalize claude token usage into the OpenAI usage shape.
+
+        ``input_tokens`` plus the two cache buckets fold into
+        ``prompt_tokens``; ``cache_read_input_tokens`` is preserved under
+        ``prompt_tokens_details.cached_tokens``. ``num_turns`` / ``duration_ms``
+        ride along as extra keys (design §5.1.6).
+        """
+        raw = data.get("usage")
+        raw = raw if isinstance(raw, dict) else {}
+
+        def _int(key: str) -> int:
+            value = raw.get(key)
+            return int(value) if isinstance(value, (int, float)) else 0
+
+        input_tokens = _int("input_tokens")
+        output_tokens = _int("output_tokens")
+        cache_read = _int("cache_read_input_tokens")
+        cache_creation = _int("cache_creation_input_tokens")
+        prompt_tokens = input_tokens + cache_read + cache_creation
+
+        usage: dict[str, Any] = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": output_tokens,
+            "total_tokens": prompt_tokens + output_tokens,
+        }
+        if cache_read:
+            usage["prompt_tokens_details"] = {"cached_tokens": cache_read}
+        if isinstance(data.get("num_turns"), int):
+            usage["num_turns"] = data["num_turns"]
+        if isinstance(data.get("duration_ms"), (int, float)):
+            usage["duration_ms"] = data["duration_ms"]
+        return usage
+
+    # ------------------------------------------------------------------
+    # grok argv builder + output parser (Phase 1d)
+    # ------------------------------------------------------------------
+
+    def _build_grok_argv(self, workdir: str, prompt_file: str | None = None) -> list[str]:
+        """Assemble the grok headless argv (design §5, grok CLI v0.2.93).
+
+        Shape::
+
+            grok --prompt-file <f> --output-format json -m <m> --cwd <w>
+                 --max-turns <n> --no-memory --sandbox <profile>
+                 [--permission-mode <mode> | --always-approve]
+
+        The prompt travels via ``--prompt-file`` (never argv / stdin): grok's
+        ``-p`` requires the prompt as its argv value, and putting it there
+        would hit Linux's ~128KiB ``MAX_ARG_STRLEN`` on large prompts and
+        leak the text into ``ps`` output. ``--no-memory`` is deliberate: it
+        enforces the one-request-one-transformation statelessness even if
+        the user's grok config enables cross-session memory.
+        """
+        if prompt_file is None:  # pragma: no cover - generate() always supplies it
+            raise AdapterError(
+                "grok argv requires a prompt file",
+                provider=self.name,
+                retryable=False,
+            )
+        model = self.acfg.model or self.config.model
+        argv = [
+            self.acfg.command,
+            "--prompt-file",
+            prompt_file,
+            "--output-format",
+            "json",
+            "-m",
+            model,
+            "--cwd",
+            workdir,
+        ]
+        if self.acfg.max_turns is not None:
+            argv += ["--max-turns", str(self.acfg.max_turns)]
+        argv += ["--no-memory"]
+        argv += self._grok_sandbox_args()
+        return argv
+
+    def _grok_sandbox_args(self) -> list[str]:
+        """Map ``sandbox_mode`` → grok sandbox/approval flags, clamped.
+
+        Same clamp as claude (design §5.4): when ``allow_file_writes`` is
+        False the effective mode is forced to ``read_only`` regardless of
+        ``sandbox_mode``, so writes always require the explicit opt-in.
+        """
+        mode = self.acfg.sandbox_mode if self.acfg.allow_file_writes else "read_only"
+        return list(_GROK_SANDBOX_ARGS[mode])
+
+    def _parse_grok(
+        self, stdout: bytes, stderr: bytes
+    ) -> tuple[str, dict[str, Any], dict[str, Any]]:
+        """Parse grok ``--output-format json`` output (verified v0.2.93).
+
+        Real-run shape::
+
+            {"text": "...", "stopReason": "EndTurn", "sessionId": "<uuid>",
+             "requestId": "<uuid>", "thought": "..."}
+
+        The CLI is early beta, so parsing is deliberately defensive: empty /
+        non-JSON / non-object stdout and a missing ``text`` field all raise
+        a retryable :class:`AdapterError` so the chain can fall through.
+        ``thought`` is ignored — only the final ``text`` is the answer.
+        """
+        text = stdout.decode("utf-8", "replace").strip()
+        if not text:
+            raise AdapterError(
+                "grok produced no stdout to parse",
+                provider=self.name,
+                retryable=True,
+            )
+        try:
+            data = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise AdapterError(
+                f"grok emitted non-JSON output: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
+        if not isinstance(data, dict):
+            raise AdapterError(
+                "grok JSON output was not an object",
+                provider=self.name,
+                retryable=True,
+            )
+        result = data.get("text")
+        if not isinstance(result, str):
+            raise AdapterError(
+                "grok JSON output missing string 'text' field",
+                provider=self.name,
+                retryable=True,
+            )
+
+        # grok emits NO token usage / cost fields (verified), so usage is
+        # all-zeros; the cost dashboard shows 0 for this provider unless the
+        # operator sets ``ProviderConfig.cost`` rates (design §5.1.6).
+        usage: dict[str, Any] = {
+            "prompt_tokens": 0,
+            "completion_tokens": 0,
+            "total_tokens": 0,
+        }
+        meta: dict[str, Any] = {}
+        session_id = data.get("sessionId")
+        if isinstance(session_id, str):
+            meta["coderouter_session_id"] = session_id
+        return result, usage, meta
+
+    # ------------------------------------------------------------------
+    # helpers: prompt rendering, response shaping, env, workdir, kill
+    # ------------------------------------------------------------------
+
+    def _write_prompt_file(self, prompt: str, workdir: str) -> str:
+        """Write the prompt to a private ``0600`` temp file in ``workdir``.
+
+        Rationale: grok's ``-p`` requires the prompt as an argv value, but a
+        huge prompt would hit Linux's ~128KiB ``MAX_ARG_STRLEN`` and argv
+        leaks into ``ps`` output; file delivery keeps argv small and private,
+        and ``0600`` + the isolated workdir bounds exposure. ``O_EXCL`` with
+        a uuid4 name makes creation race-free; the caller (``generate``)
+        deletes the file in a ``finally`` block on every path.
+        """
+        path = os.path.join(workdir, f".coderouter-prompt-{uuid.uuid4().hex}.txt")
+        try:
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except OSError as exc:
+            raise AdapterError(
+                f"failed to create prompt file in {workdir}: {exc}",
+                provider=self.name,
+                retryable=False,
+            ) from exc
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as handle:
+                handle.write(prompt)
+        except OSError as exc:
+            with contextlib.suppress(OSError):
+                os.unlink(path)
+            raise AdapterError(
+                f"failed to write prompt file {path}: {exc}",
+                provider=self.name,
+                retryable=False,
+            ) from exc
+        return path
+
+    def _to_chat_response(
+        self, final_text: str, usage: dict[str, Any], meta: dict[str, Any]
+    ) -> ChatResponse:
+        """Wrap the agent's final text in an OpenAI ChatResponse."""
+        return ChatResponse(
+            id=f"chatcmpl-{uuid.uuid4().hex}",
+            created=int(time.time()),
+            model=self.config.model,
+            choices=[
+                {
+                    "index": 0,
+                    "message": {"role": "assistant", "content": final_text},
+                    "finish_reason": "stop",
+                }
+            ],
+            usage=usage,
+            coderouter_provider=self.name,
+            **meta,
+        )
+
+    def _render_prompt(self, request: ChatRequest, overrides: ProviderCallOverrides | None) -> str:
+        """Flatten the chat messages into a single role-tagged prompt string.
+
+        The profile-level ``append_system_prompt`` (if any) is prepended as a
+        leading system block, matching the openai_compat directive semantics.
+        """
+        parts: list[str] = []
+        directive = self.effective_append_system_prompt(overrides)
+        if directive:
+            parts.append(f"[system]\n{directive}")
+        for message in request.messages:
+            text = self._message_text(message.content)
+            if text:
+                parts.append(f"[{message.role}]\n{text}")
+        return "\n\n".join(parts).strip()
+
+    @staticmethod
+    def _message_text(content: str | list[dict[str, Any]] | None) -> str:
+        """Extract plain text from a message's ``content`` (str or blocks)."""
+        if content is None:
+            return ""
+        if isinstance(content, str):
+            return content
+        chunks: list[str] = []
+        for part in content:
+            if isinstance(part, dict) and part.get("type") == "text":
+                text = part.get("text")
+                if isinstance(text, str):
+                    chunks.append(text)
+        return "\n".join(chunks)
+
+    def _current_depth(self) -> int:
+        """Read the current recursion depth from the environment (0 default)."""
+        raw = os.environ.get(_DEPTH_ENV, "0")
+        try:
+            return int(raw)
+        except ValueError:
+            return 0
+
+    def _build_child_env(self) -> dict[str, str]:
+        """Build the minimal child environment (design §5.3).
+
+        The child does NOT inherit the parent environment. Only a fixed base
+        (PATH / NO_COLOR / TERM), the inherited HOME / USER / LOGNAME (for
+        credential discovery — on macOS the Claude Code CLI resolves its
+        Keychain entry via ``USER``; without it headless runs fail with
+        "Not logged in"), the incremented recursion depth, and the operator's
+        ``passthrough_env`` allowlist are injected. ``ANTHROPIC_API_KEY`` is
+        therefore excluded unless explicitly allowlisted.
+        """
+        parent = os.environ
+        env: dict[str, str] = {
+            "PATH": _SAFE_PATH,
+            "NO_COLOR": "1",
+            "TERM": "dumb",
+            _DEPTH_ENV: str(self._current_depth() + 1),
+        }
+        for name in ("HOME", "USER", "LOGNAME"):
+            value = parent.get(name)
+            if value:
+                env[name] = value
+        for name in self.acfg.passthrough_env:
+            value = parent.get(name)
+            if value is not None:
+                env[name] = value
+        return env
+
+    @staticmethod
+    def _error_detail(stdout: bytes, stderr: bytes) -> str:
+        """Extract the most useful error text from a failed CLI run.
+
+        The Claude Code CLI reports auth / API failures as an ``is_error:
+        true`` result JSON on **stdout** with exit code 1 (stderr stays
+        empty), so a stderr-only tail hides the actual cause (e.g. ``Not
+        logged in · Please run /login``). Preference order: the ``result``
+        field of an ``is_error`` stdout JSON → stderr tail → stdout tail.
+        """
+        if stdout:
+            with contextlib.suppress(ValueError, TypeError):
+                doc = json.loads(stdout)
+                if isinstance(doc, dict) and doc.get("is_error"):
+                    result = doc.get("result")
+                    if isinstance(result, str) and result.strip():
+                        return result.strip()[:_MAX_STDERR_TAIL]
+        if stderr:
+            return repr(stderr[-_MAX_STDERR_TAIL:].decode("utf-8", "replace"))
+        if stdout:
+            return repr(stdout[-_MAX_STDERR_TAIL:].decode("utf-8", "replace"))
+        return "''"
+
+    def _resolve_workdir(self) -> str:
+        """Resolve + create the working directory, rejecting ``..`` escapes.
+
+        A configured ``workdir`` is ``~`` / env-var expanded and resolved to
+        an absolute path; a literal ``..`` component is rejected as an escape
+        attempt. When unset, a dedicated isolated directory
+        (``~/.coderouter/agents/<name>``) is used (design §6).
+        """
+        raw = self.acfg.workdir
+        if raw:
+            if ".." in Path(raw).parts:
+                raise AdapterError(
+                    f"workdir {raw!r} must not contain '..' (escape attempt)",
+                    provider=self.name,
+                    retryable=False,
+                )
+            expanded = os.path.expanduser(os.path.expandvars(raw))
+            path = Path(expanded).resolve()
+        else:
+            path = (Path.home() / ".coderouter" / "agents" / self.name).resolve()
+        try:
+            path.mkdir(parents=True, exist_ok=True)
+        except OSError as exc:
+            raise AdapterError(
+                f"failed to prepare workdir {path}: {exc}",
+                provider=self.name,
+                retryable=False,
+            ) from exc
+        return str(path)
+
+    def _kill_process_group(self, proc: asyncio.subprocess.Process) -> None:
+        """SIGKILL the child's whole process group (best effort)."""
+        pid = proc.pid
+        try:
+            os.killpg(os.getpgid(pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError, OSError):
+            # Group already gone / no permission — fall back to a direct kill.
+            with contextlib.suppress(ProcessLookupError, OSError):
+                proc.kill()
+
+    def _is_retryable_exit(self, returncode: int | None) -> bool:
+        """Whether a non-zero exit should let the chain fall through.
+
+        Phase 1a treats any non-zero exit as transient (rate-limit / OAuth
+        expiry / network), so the fallback engine advances to the next
+        provider rather than surfacing a terminal failure.
+        """
+        return True
+
+    # ``BaseAdapter`` (HTTP-oriented) lazily builds an httpx client; the agent
+    # adapter never touches it, but ``aclose`` on the inherited base is a safe
+    # no-op, so nothing extra is needed here.
+
+
+__all__ = ["AgentCliAdapter"]

coderouter/adapters/registry.py

@@ -14,4 +14,10 @@ def build_adapter(provider: ProviderConfig) -> BaseAdapter:
         return OpenAICompatAdapter(provider)
     if provider.kind == "anthropic":
         return AnthropicAdapter(provider)
+    if provider.kind == "agent_cli":
+        # Imported lazily so the external-agent adapter (and its subprocess /
+        # os plumbing) is only pulled in when a config actually uses it.
+        from coderouter.adapters.agent_cli import AgentCliAdapter
+
+        return AgentCliAdapter(provider)
     raise ValueError(f"Unknown adapter kind: {provider.kind!r}")

coderouter/config/schemas.py

@@ -163,6 +163,137 @@ class CostConfig(BaseModel):
     )
 
 
+class AgentCliConfig(BaseModel):
+    """External coding-agent CLI settings for ``kind="agent_cli"`` providers.
+
+    Introduced by the external-agents-adapter design (Phase 1). One
+    ``agent_cli`` sub-config drives the :class:`AgentCliAdapter`, which
+    invokes an external coding-agent CLI (codex / gemini / grok / claude)
+    in a single one-shot ``exec`` and returns the final answer as one
+    ``prompt in → text out`` transformation. ``claude`` (Claude Code CLI,
+    Phase 1a) and ``grok`` (grok CLI, Phase 1d) are implemented;
+    codex / gemini are declared at the schema level so configs are
+    forward-compatible, but the adapter rejects them until their phase
+    lands.
+
+    Auth note (grok): the grok CLI uses OAuth credentials stored under
+    ``~/.grok`` (``grok login``), which the adapter's HOME inheritance
+    already covers — no extra config needed. For CI / API-key setups, list
+    ``GROK_CODE_XAI_API_KEY`` in ``passthrough_env`` (this is grok's key
+    env var — NOT ``XAI_API_KEY``).
+
+    Follows the ``extra="forbid"`` convention used across this module so a
+    typo'd key fails at config-load rather than being silently ignored.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    agent: Literal["codex", "gemini", "grok", "claude"] = Field(
+        ...,
+        description=(
+            "External coding-agent CLI to invoke. 'claude' (Phase 1a) and "
+            "'grok' (Phase 1d) are implemented; 'codex' / 'gemini' pending."
+        ),
+    )
+    command: str | None = Field(
+        default=None,
+        description=(
+            "CLI executable name or absolute path (resolved via PATH). "
+            "When unset, defaults to the ``agent`` name."
+        ),
+    )
+    workdir: str | None = Field(
+        default=None,
+        description=(
+            "Working directory for the one-shot exec. ``~`` / env-var "
+            "expansion is applied. When unset, a dedicated isolated "
+            "directory (``~/.coderouter/agents/<name>``) is used."
+        ),
+    )
+    exec_timeout_s: float = Field(
+        default=600.0,
+        ge=1.0,
+        le=1800.0,
+        description=(
+            "Forced timeout (seconds) for the one-shot exec. Independent "
+            "of ``ProviderConfig.timeout_s`` — the CLI has no built-in "
+            "wall clock so this is enforced with an asyncio watchdog + "
+            "process-group SIGKILL."
+        ),
+    )
+    allow_file_writes: bool = Field(
+        default=False,
+        description=(
+            "Allow the agent to write to the filesystem. Default False "
+            "(read-only). When False the sandbox mapping is clamped to "
+            "read-only regardless of ``sandbox_mode`` (defense in depth)."
+        ),
+    )
+    sandbox_mode: Literal["read_only", "edit", "full_auto"] = Field(
+        default="read_only",
+        description=(
+            "Source mode mapped onto each CLI's sandbox / approval flags. "
+            "Default read_only maps to claude ``--permission-mode plan``."
+        ),
+    )
+    model: str | None = Field(
+        default=None,
+        description=(
+            "Model name passed to the CLI's ``--model``. When unset, "
+            "``ProviderConfig.model`` is used."
+        ),
+    )
+    max_turns: int | None = Field(
+        default=8,
+        ge=1,
+        le=50,
+        description=(
+            "Turn cap. Passed to the CLI's ``--max-turns`` where supported "
+            "(codex ignores it — the CLI has no such flag)."
+        ),
+    )
+    passthrough_env: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Allowlist of environment variable NAMES forwarded from the "
+            "parent process into the child. The child otherwise inherits "
+            "no parent environment (subscription-first auth policy). "
+            "``ANTHROPIC_API_KEY`` is NOT forwarded unless listed here. "
+            "For grok in CI, list ``GROK_CODE_XAI_API_KEY`` here; OAuth "
+            "logins under ``~/.grok`` work without it (HOME is inherited)."
+        ),
+    )
+    agent_depth_limit: int = Field(
+        default=2,
+        ge=1,
+        le=4,
+        description=(
+            "Recursion nesting cap. ``CODEROUTER_AGENT_DEPTH`` is "
+            "propagated (incremented) into the child; ``generate()`` "
+            "refuses when the current depth is at or above this limit."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _resolve_and_check(self) -> AgentCliConfig:
+        """Default ``command`` to ``agent`` and reject contradictory sandbox.
+
+        Rule (design §5.2.1 #2): ``allow_file_writes=True`` together with
+        ``sandbox_mode="read_only"`` is contradictory — the operator asked
+        for writes while pinning a read-only sandbox. Fail fast at load,
+        matching the module's other cross-field validators.
+        """
+        if self.command is None:
+            self.command = self.agent
+        if self.allow_file_writes and self.sandbox_mode == "read_only":
+            raise ValueError(
+                "agent_cli: allow_file_writes=True conflicts with "
+                "sandbox_mode='read_only'. Set sandbox_mode to 'edit' or "
+                "'full_auto' to permit writes, or keep allow_file_writes=False."
+            )
+        return self
+
+
 class ProviderConfig(BaseModel):
     """A single provider entry from providers.yaml.
 
@@ -170,20 +301,26 @@ class ProviderConfig(BaseModel):
         - Local llama.cpp server: kind=openai_compat, base_url=http://localhost:8080/v1
         - OpenRouter free: kind=openai_compat, base_url=https://openrouter.ai/api/v1
         - (future) Anthropic: kind=anthropic, base_url=https://api.anthropic.com
+        - External agent CLI: kind=agent_cli, agent_cli={agent: claude, ...}
     """
 
     model_config = ConfigDict(extra="forbid")
 
     name: str = Field(..., description="Unique identifier used in profiles.yaml")
-    kind: Literal["openai_compat", "anthropic"] = Field(
+    kind: Literal["openai_compat", "anthropic", "agent_cli"] = Field(
         default="openai_compat",
         description=(
             "Adapter type. 'openai_compat' covers llama.cpp / Ollama / "
             "OpenRouter / LM Studio / Together / Groq. 'anthropic' is the "
-            "native Anthropic Messages API passthrough (v0.3.x)."
+            "native Anthropic Messages API passthrough (v0.3.x). 'agent_cli' "
+            "invokes an external coding-agent CLI one-shot (see AgentCliConfig)."
         ),
     )
-    base_url: HttpUrl
+    # base_url is required for HTTP-backed adapters (openai_compat / anthropic)
+    # but meaningless for agent_cli (which shells out to a local CLI rather
+    # than calling a URL). It is optional at the field level and enforced per
+    # kind by ``_check_kind_requirements`` below.
+    base_url: HttpUrl | None = None
     model: str = Field(..., description="Upstream model id sent in the request body")
     api_key_env: str | None = Field(
         default=None,
@@ -243,6 +380,14 @@ class ProviderConfig(BaseModel):
 
     capabilities: Capabilities = Field(default_factory=Capabilities)
 
+    # kind="agent_cli": required external coding-agent CLI settings. Opt-in
+    # (default None) exactly like ``restart_command`` — only meaningful when
+    # ``kind == "agent_cli"``, and enforced by ``_check_kind_requirements``.
+    agent_cli: AgentCliConfig | None = Field(
+        default=None,
+        description="Required when kind='agent_cli': external agent CLI settings.",
+    )
+
     cost: CostConfig | None = Field(
         default=None,
         description=(
@@ -298,6 +443,32 @@ class ProviderConfig(BaseModel):
         validate_output_filters(self.output_filters)
         return self
 
+    @model_validator(mode="after")
+    def _check_kind_requirements(self) -> ProviderConfig:
+        """Enforce per-``kind`` field requirements (external-agents design §5.2.2).
+
+        - HTTP-backed adapters (``openai_compat`` / ``anthropic``) require a
+          ``base_url`` — they have nowhere to send the request otherwise.
+          ``base_url`` was relaxed to Optional so ``agent_cli`` providers can
+          omit it; this validator restores the required-ness for the HTTP kinds.
+        - ``agent_cli`` requires the ``agent_cli`` sub-config (the adapter has
+          no CLI to invoke without it).
+
+        Same fast-fail philosophy as ``_check_output_filters_known`` — a
+        misconfigured provider surfaces at config-load, not at first request.
+        """
+        if self.kind in ("openai_compat", "anthropic") and self.base_url is None:
+            raise ValueError(
+                f"provider {self.name!r}: base_url is required for "
+                f"kind={self.kind!r}."
+            )
+        if self.kind == "agent_cli" and self.agent_cli is None:
+            raise ValueError(
+                f"provider {self.name!r}: agent_cli sub-config is required "
+                f"for kind='agent_cli'."
+            )
+        return self
+
 
 class FallbackChain(BaseModel):
     """An ordered list of provider names to try in sequence.
@@ -468,7 +639,7 @@ class FallbackChain(BaseModel):
     # Distinct from the v1.9-C ``adaptive`` gradient (continuous
     # latency / error-rate buffer with debounce) which handles the
     # "slow but alive" case; L5 handles the "hard crash" case.
-    backend_health_action: Literal["off", "warn", "demote", "exclude"] = Field(
+    backend_health_action: Literal["off", "warn", "demote", "exclude", "skip"] = Field(
         default="warn",
         description=(
             "v1.9-E (L5 phase 2): action when a provider transitions "
@@ -483,11 +654,35 @@ class FallbackChain(BaseModel):
             "self-healing (restart helper if configured, recovery "
             "probe with exponential backoff). On recovery, the "
             "provider is automatically restored to its original "
-            "chain position. ``off`` disables the monitor "
+            "chain position. ``skip`` (v2.x) filters UNHEALTHY providers "
+            "out of the chain like ``exclude`` but with a self-contained "
+            "half-open circuit breaker — no self-healing orchestrator "
+            "required: every ``backend_health_half_open_s`` window one "
+            "trial request is let through, and a single success snaps the "
+            "provider back into rotation. If skipping would empty the "
+            "chain, the unfiltered chain is used as a last resort so a "
+            "uniformly-UNHEALTHY chain still attempts every provider "
+            "rather than 502-ing outright. ``off`` disables the monitor "
             "entirely (zero observation overhead, identical to "
             "v1.9.x behavior)."
         ),
     )
+    backend_health_half_open_s: float = Field(
+        default=30.0,
+        ge=5.0,
+        le=600.0,
+        description=(
+            "v2.x: half-open interval (seconds) for the ``skip`` "
+            "backend-health action. While a provider is UNHEALTHY, at most "
+            "one trial request is let through per interval — the built-in "
+            "circuit breaker's half-open probe. A successful trial resets "
+            "the provider to HEALTHY immediately; a failed trial keeps it "
+            "skipped until the next interval elapses. Ignored for every "
+            "other ``backend_health_action``. Default 30 s balances quick "
+            "recovery against hammering a still-down backend; capped at "
+            "600 s (10 min)."
+        ),
+    )
     backend_health_threshold: int = Field(
         default=3,
         ge=2,

coderouter/guards/backend_health.py

@@ -46,6 +46,7 @@ record can't observe a torn state.
 from __future__ import annotations
 
 import threading
+import time
 from dataclasses import dataclass
 from typing import Literal
 
@@ -84,6 +85,15 @@ class HealthTransition:
 class _ProviderHealth:
     state: HealthState = "HEALTHY"
     consecutive_failures: int = 0
+    # v2.x (``skip`` action): monotonic timestamps driving the built-in
+    # half-open trial. ``unhealthy_since`` is stamped when the provider
+    # crosses into UNHEALTHY (diagnostic — "how long has it been down");
+    # ``last_half_open_at`` records the last time :meth:`should_skip` let a
+    # single trial request through. Both are cleared on any success. These
+    # are ``time.monotonic`` values, so they are intentionally NOT persisted
+    # across restarts (see :meth:`save_state`).
+    unhealthy_since: float | None = None
+    last_half_open_at: float | None = None
 
 
 class BackendHealthMonitor:
@@ -140,6 +150,10 @@ class BackendHealthMonitor:
 
             if success:
                 entry.consecutive_failures = 0
+                # v2.x: a single success snaps back to HEALTHY and clears the
+                # half-open bookkeeping so a future crash starts a fresh cycle.
+                entry.unhealthy_since = None
+                entry.last_half_open_at = None
                 if old_state != "HEALTHY":
                     entry.state = "HEALTHY"
                     return HealthTransition(
@@ -168,6 +182,12 @@ class BackendHealthMonitor:
                 return None
 
             entry.state = new_state
+            if new_state == "UNHEALTHY":
+                # v2.x: record the moment we went down (diagnostic). The
+                # half-open trial itself is keyed off ``last_half_open_at``,
+                # which starts unset so the first resolve after this
+                # transition is allowed straight through as a trial.
+                entry.unhealthy_since = time.monotonic()
             return HealthTransition(
                 provider=provider,
                 old_state=old_state,
@@ -200,12 +220,54 @@ class BackendHealthMonitor:
         """True iff ``provider``'s current state is ``UNHEALTHY``."""
         return self.state_for(provider) == "UNHEALTHY"
 
+    def should_skip(self, provider: str, *, half_open_interval_s: float) -> bool:
+        """v2.x: decide whether to skip ``provider`` at chain-resolve time.
+
+        Drives the ``skip`` backend-health action's built-in half-open
+        circuit breaker. Semantics:
+
+        * Not UNHEALTHY → ``False`` (never skip a HEALTHY/DEGRADED provider).
+        * UNHEALTHY, but either never trialed (``last_half_open_at is None``)
+          or the half-open interval has elapsed since the last trial → stamp
+          ``last_half_open_at = now`` and return ``False`` — exactly one
+          request is let through as a probe. If it succeeds,
+          :meth:`record_attempt` snaps the provider back to HEALTHY; if it
+          fails, the counter stays UNHEALTHY and the freshly-stamped trial
+          time keeps the provider skipped until the interval elapses again.
+        * UNHEALTHY and inside the current interval → ``True`` (skip).
+
+        This is a mutating read: the ``last_half_open_at`` stamp is the
+        side effect that makes the half-open trial fire at most once per
+        ``half_open_interval_s`` window. Held under the lock so concurrent
+        resolves can't both slip a trial through the same window.
+        """
+        with self._lock:
+            entry = self._state.get(provider)
+            if entry is None or entry.state != "UNHEALTHY":
+                return False
+            now = time.monotonic()
+            last = entry.last_half_open_at
+            if last is None or (now - last) >= half_open_interval_s:
+                entry.last_half_open_at = now
+                return False
+            return True
+
     # ------------------------------------------------------------------
     # v2.0-K: Persistence
     # ------------------------------------------------------------------
 
     def save_state(self) -> dict[str, object]:
-        """Export the current per-provider health state for persistence."""
+        """Export the current per-provider health state for persistence.
+
+        v2.x: only ``state`` and ``consecutive_failures`` are persisted.
+        ``unhealthy_since`` / ``last_half_open_at`` are ``time.monotonic``
+        values whose zero point is per-process — persisting them across a
+        restart would be meaningless (and could compare against a future
+        process's clock). They are dropped here and default to ``None`` on
+        :meth:`load_state`, which simply means the first resolve after a
+        restart is treated as a fresh half-open trial — safe, since a
+        successful trial resets the provider anyway.
+        """
         with self._lock:
             return {
                 name: {

coderouter/logging.py

@@ -621,6 +621,66 @@ def log_demote_unhealthy_provider(
     logger.info("demote-unhealthy-provider", extra=payload)
 
 
+# ---------------------------------------------------------------------------
+# v2.x: ``skip`` backend-health action log shapes
+# ---------------------------------------------------------------------------
+
+
+class SkipUnhealthyProviderPayload(TypedDict):
+    """Structured shape of the ``skip-unhealthy-provider`` log record."""
+
+    provider: str
+    profile: str
+
+
+class ChainAllUnhealthyLastResortPayload(TypedDict):
+    """Structured shape of the ``chain-all-unhealthy-last-resort`` log record."""
+
+    profile: str
+    providers: list[str]
+
+
+def log_skip_unhealthy_provider(
+    logger: logging.Logger,
+    *,
+    provider: str,
+    profile: str,
+) -> None:
+    """Emit a ``skip-unhealthy-provider`` info line.
+
+    Fires per chain-resolve when the ``skip`` action filters an UNHEALTHY
+    provider out of the chain (and the half-open trial is not currently
+    allowed through). Quiet when a half-open trial lets the provider through
+    — that resolve looks identical to a healthy one.
+    """
+    payload: SkipUnhealthyProviderPayload = {
+        "provider": provider,
+        "profile": profile,
+    }
+    logger.info("skip-unhealthy-provider", extra=payload)
+
+
+def log_chain_all_unhealthy_last_resort(
+    logger: logging.Logger,
+    *,
+    profile: str,
+    providers: list[str],
+) -> None:
+    """Emit a ``chain-all-unhealthy-last-resort`` info line.
+
+    Fires once per chain-resolve when the ``skip`` action would have filtered
+    out every provider — rather than fail the request outright, the engine
+    falls back to the unfiltered chain and attempts everyone. ``providers`` is
+    the last-resort chain (original order) so the operator can see exactly what
+    is being tried despite all members being UNHEALTHY.
+    """
+    payload: ChainAllUnhealthyLastResortPayload = {
+        "profile": profile,
+        "providers": providers,
+    }
+    logger.info("chain-all-unhealthy-last-resort", extra=payload)
+
+
 # ---------------------------------------------------------------------------
 # v2.0-J: self-healing log shapes
 # ---------------------------------------------------------------------------

coderouter/routing/fallback.py

@@ -72,6 +72,7 @@ from coderouter.logging import (
     get_logger,
     log_backend_health_changed,
     log_cache_observed,
+    log_chain_all_unhealthy_last_resort,
     log_chain_budget_exceeded,
     log_chain_memory_pressure_blocked,
     log_chain_paid_gate_blocked,
@@ -80,6 +81,7 @@ from coderouter.logging import (
     log_memory_pressure_detected,
     log_skip_budget_exceeded,
     log_skip_memory_pressure,
+    log_skip_unhealthy_provider,
     log_tool_loop_detected,
 )
 from coderouter.plugins.registry import PluginRegistry
@@ -2063,6 +2065,41 @@ class FallbackEngine:
             if excluded:
                 adapters = [a for a in adapters if a.name not in excluded]
 
+        # Pass 4c: v2.x ``skip`` action — self-contained half-open circuit
+        # breaker. Unlike ``exclude`` (which relies on the self-healing
+        # orchestrator's excluded set + background recovery probes), ``skip``
+        # asks the backend-health monitor directly: an UNHEALTHY provider is
+        # filtered out unless its half-open interval has elapsed, in which
+        # case ``should_skip`` lets exactly one trial request through (a
+        # success snaps it back to HEALTHY). If skipping would empty the
+        # chain, fall back to the unfiltered list as a last resort — a
+        # uniformly-UNHEALTHY chain still attempts everyone rather than
+        # failing with NoProvidersAvailableError before trying anything.
+        if chain.backend_health_action == "skip":
+            kept: list[BaseAdapter] = []
+            for adapter in adapters:
+                if self._backend_health.should_skip(
+                    adapter.name,
+                    half_open_interval_s=chain.backend_health_half_open_s,
+                ):
+                    log_skip_unhealthy_provider(
+                        logger,
+                        provider=adapter.name,
+                        profile=chosen,
+                    )
+                else:
+                    kept.append(adapter)
+            if kept:
+                adapters = kept
+            elif adapters:
+                # Everyone was skipped — last-resort: try the unfiltered
+                # chain rather than 502 without attempting a single provider.
+                log_chain_all_unhealthy_last_resort(
+                    logger,
+                    profile=chosen,
+                    providers=[a.name for a in adapters],
+                )
+
         return adapters
 
     def _resolve_anthropic_chain(self, request: AnthropicRequest) -> list[tuple[BaseAdapter, bool]]:

{coderouter_cli-2.7.6.dist-info → coderouter_cli-2.7.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.6
+Version: 2.7.8
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter

{coderouter_cli-2.7.6.dist-info → coderouter_cli-2.7.8.dist-info}/RECORD

@@ -11,25 +11,26 @@ coderouter/gguf_introspect.py,sha256=KeE00CfbYRa4gSTrzuwC6zVuHi20IzLC4nUQa98BEXI
 coderouter/hardware.py,sha256=gn3_9qbVcGRR81yKMn1lJE_8-YDRau0LxIH_M-f7pxE,8356
 coderouter/language_tax.py,sha256=LTbE3tIfoJuV2O3T0NixRKhzq_dEOTUuPEerJv2q9uk,9360
 coderouter/launcher_speculative.py,sha256=kWaHNmhzBsbWuM_lRGDlbWkgJ1suuxBWQNTKhJOC-yg,12644
-coderouter/logging.py,sha256=91cveN8SCJEMNz9DGi6TrFSlc8cx0wdUkOdSLWLA-z8,56144
+coderouter/logging.py,sha256=5rfi4_R4aoeeUYDc642dgs61wA0aBX7wvubyB-k3Uyo,58074
 coderouter/output_filters.py,sha256=0ry_rPiS_kC-FnHgaNVP6v7e6Al2djxzu9vBzZ8kEkE,25314
 coderouter/token_estimation.py,sha256=iz22vZEEW2P7uKLB2pYvPNpIbZGbgXRO5MtfkS_-9Sk,7531
 coderouter/token_estimation_accurate.py,sha256=GTfzrBVnvAGjeVzmzAeUdOYZvWZKLAxcxPpFiJGlzjk,4609
 coderouter/adapters/__init__.py,sha256=7dIDSZ-FE_0iSqLSDc_lK1idRdLTKcM2hP9tCJipgPI,463
+coderouter/adapters/agent_cli.py,sha256=_-9DsSO-zQJI-bEldBhFgIBbAQd6kqMCqX7xNy8WqtQ,32992
 coderouter/adapters/anthropic_native.py,sha256=CT9Hitun-c3z83YHT2zZXgwZpY3_t6eRnOfAmNud2aw,23610
 coderouter/adapters/base.py,sha256=ykKMaiIVVGr23oFFXilK2iP_YhI8-CtsEiJyFXaC9bE,10396
 coderouter/adapters/openai_compat.py,sha256=wcrd_UpV7N6ISpUyKvdFPGU-YjCrX5oMqGpjAFEeWfg,20356
-coderouter/adapters/registry.py,sha256=Syt3eDljWZAK5mfiJGvUMKaZYAfCRScp7PvV6pYt7mc,683
+coderouter/adapters/registry.py,sha256=A2LNhp70LOSNodM_iKO6EL-MBadB3kli-YPWRe1U7pQ,979
 coderouter/config/__init__.py,sha256=FODEn74fN-qZnt4INPSHswqhOlEgpL6-_onxsitSx8g,274
 coderouter/config/capability_registry.py,sha256=RZgzHF54dXy0CCDocRCz2ee21qXGbbgTSKTkRI9iLL4,16936
 coderouter/config/env_file.py,sha256=CoMK27fuAXm-NtoLzXb8yN2E-wDFjHQuFwiIlmgTBQw,10356
 coderouter/config/loader.py,sha256=FUEe8m4Tnmj_aul0vSctD8vKvNW-oLRoMRbTpSKqSmc,4077
-coderouter/config/schemas.py,sha256=f46bpmSzZ_zJRhHbo9-inp-mAW86WZAg6hfSxgPaEcc,77741
+coderouter/config/schemas.py,sha256=c5VJkcsuPHIKgTtcRQnXL-q52ollsWOISnDC8RuOX70,86528
 coderouter/data/__init__.py,sha256=uNyfD9jaCvTWsBAWtaw1Fr25OSxzv3psGMfBjT1z0Cc,328
 coderouter/data/model-capabilities.yaml,sha256=S9jt6SC6-3s2-icZ_n-a14iEMnc2yB1C2R6q-N_tZWQ,19309
 coderouter/guards/__init__.py,sha256=5qliYBqygvVPneej7nx0uSjxDKsz7t8VzvrDgVBJlvU,1170
 coderouter/guards/_fingerprint.py,sha256=qsgNzIq9jv3FHrKL39nGJARp0cMenpN_QmWoJu87vU4,4835
-coderouter/guards/backend_health.py,sha256=Xx5OpX1x7atxghmBNDVxtwGg62zQIOsk6FmrQV4ILa4,9113
+coderouter/guards/backend_health.py,sha256=GLUVQ5BhU6i8Cxz_FrgIMs5AZ-YSKAW8veFWgvn9GFI,12565
 coderouter/guards/context_budget.py,sha256=6u08JqBdRQkDz9NIQ-aISXo3w3L804oYFg027s04IwY,17202
 coderouter/guards/continuous_probe.py,sha256=WIfS-apVMWXGv7bPBxxkJssePa95I4fT0mi4PNqK5iE,12181
 coderouter/guards/drift_actions.py,sha256=A6pY5CR480Ct5rCVyjlBvjPFVc93eu_r5qcUpK9mWKc,3602
@@ -57,7 +58,7 @@ coderouter/routing/adaptive.py,sha256=G2o377twGSjbUh65wiIFx6klnpFGjsD_nI3oDvcBwh
 coderouter/routing/auto_router.py,sha256=y4v0c8u5F9f98Vmhx1vRcKPiOgAvpzbFqr6TIh058h0,13341
 coderouter/routing/budget.py,sha256=PblmVKJGs_BwNa9uDHAA8hmZ4XIVKv38mHAeU0V3OMs,8451
 coderouter/routing/capability.py,sha256=rRQhzTgQYFTFDNYcSLKvq3xjdw6B1w7T-3jS7PTMI14,27864
-coderouter/routing/fallback.py,sha256=L5hwe76DRlmHTR39dXafi27T5zRrgLlgX9uINddcSGk,142983
+coderouter/routing/fallback.py,sha256=WNfDT9XDfKk584rQYHwSesq8-n3Axvp4j_e7qQ5ghuQ,144789
 coderouter/state/__init__.py,sha256=XoGcPmmBQSiZWML2S0juSveQ78xfhtdeCliNnVyzu7E,1088
 coderouter/state/audit_log.py,sha256=n7vuDsTfd5iuNUJhlRQPakJ2tMSsT9EfgPCzs1GEaac,10941
 coderouter/state/replay.py,sha256=Z_YHKroTKZdrL8qObFxcoLOAQWWXZvXFdLfxzvBhEJg,11230
@@ -68,8 +69,8 @@ coderouter/translation/__init__.py,sha256=PYXN7XVEwpG1uC8RLy6fvnGbzEZhhrEuUapH8I
 coderouter/translation/anthropic.py,sha256=aZkcYH4x82b0x7efJgJb9RWn9Hbyc9pEOthXe4vjUdU,11113
 coderouter/translation/convert.py,sha256=VV4kpu4dvLmGBmJfQnCLY5ryy_AnQcV2NuwjqRtaR8Q,52633
 coderouter/translation/tool_repair.py,sha256=DGOKArM53yfVbIfiAveoul1vGq9NEKmjagf43Qh4IkM,57630
-coderouter_cli-2.7.6.dist-info/METADATA,sha256=VNl2YqpfRQDN5Ww8ukg21mjL5JVvgAOtPj6HKTZKP6Y,15546
-coderouter_cli-2.7.6.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-coderouter_cli-2.7.6.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
-coderouter_cli-2.7.6.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
-coderouter_cli-2.7.6.dist-info/RECORD,,
+coderouter_cli-2.7.8.dist-info/METADATA,sha256=S3XO80V0pWn7ifsjuoMOEYcU0Cnru5WIADYIq9-PQb4,15546
+coderouter_cli-2.7.8.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+coderouter_cli-2.7.8.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
+coderouter_cli-2.7.8.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
+coderouter_cli-2.7.8.dist-info/RECORD,,