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

coderouter/adapters/agent_cli.py

@@ -18,24 +18,36 @@ CodeRouter merely performs the one conversion. Following the
 ``openai_compat`` precedent, a *single* adapter class fronts *multiple*
 target agents, dispatched on the ``agent`` field.
 
-Phase 1a scope
-==============
-
-Only the ``claude`` (Claude Code CLI) target is implemented here — it is
-the most stable CLI, has the most fine-grained safety controls, and is the
-only one that emits ``total_cost_usd`` directly (making it the reference
-implementation for the parser / cost path). The other agents
-(codex / gemini / grok) 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 lands.
+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 fed on stdin, so it is never subject to shell
-  interpretation.
+  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
@@ -104,6 +116,17 @@ _CLAUDE_PERMISSION_MODE = {
     "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."""
@@ -112,7 +135,7 @@ def _chunk_text(text: str, size: int = _STREAM_CHUNK_CHARS) -> Iterator[str]:
 
 
 class AgentCliAdapter(BaseAdapter):
-    """Invoke an external coding-agent CLI one-shot (Phase 1a: claude only).
+    """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
@@ -122,9 +145,10 @@ class AgentCliAdapter(BaseAdapter):
     def __init__(self, config: ProviderConfig) -> None:
         """Bind to a ``ProviderConfig`` and reject unsupported agents.
 
-        Constructing an adapter for an agent other than ``claude`` raises a
-        non-retryable :class:`AdapterError` — the other targets are declared
-        in the schema but not implemented until their phase (design §9).
+        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
@@ -134,21 +158,30 @@ class AgentCliAdapter(BaseAdapter):
                 retryable=False,
             )
         self.acfg: AgentCliConfig = config.agent_cli
-        if self.acfg.agent != "claude":
+        if self.acfg.agent not in ("claude", "grok"):
             raise AdapterError(
-                f"agent {self.acfg.agent!r} is not implemented in Phase 1a "
-                f"(claude only). Configure agent='claude' or wait for the "
-                f"agent's phase.",
+                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. Phase 1a
-        # registers only claude; later phases add codex / gemini / grok.
-        self._builders = {"claude": self._build_claude_argv}
-        self._parsers = {"claude": self._parse_claude}
-        # claude reads its print-mode prompt from stdin (10MB cap), which
-        # keeps argv free of the (potentially huge) prompt text.
-        self._uses_stdin = True
+        # 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
@@ -177,8 +210,7 @@ class AgentCliAdapter(BaseAdapter):
         depth = self._current_depth()
         if depth >= self.acfg.agent_depth_limit:
             raise AdapterError(
-                f"agent recursion depth {depth} >= limit "
-                f"{self.acfg.agent_depth_limit}",
+                f"agent recursion depth {depth} >= limit {self.acfg.agent_depth_limit}",
                 provider=self.name,
                 retryable=False,
             )
@@ -195,68 +227,82 @@ class AgentCliAdapter(BaseAdapter):
 
         prompt = self._render_prompt(request, overrides)
         workdir = self._resolve_workdir()
-        argv = self._builders[self.acfg.agent](workdir)
-        # 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,
-            },
-        )
 
+        # 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:
-            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,
+            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,
+                },
             )
-        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
+            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
 
-        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),
-            )
+            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
 
-        final_text, usage, meta = self._parsers[self.acfg.agent](stdout, stderr)
+            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(
@@ -281,9 +327,7 @@ class AgentCliAdapter(BaseAdapter):
                 id=resp.id,
                 created=resp.created,
                 model=resp.model,
-                choices=[
-                    {"index": 0, "delta": {"content": piece}, "finish_reason": None}
-                ],
+                choices=[{"index": 0, "delta": {"content": piece}, "finish_reason": None}],
             )
         yield StreamChunk(
             id=resp.id,
@@ -297,7 +341,7 @@ class AgentCliAdapter(BaseAdapter):
     # claude argv builder + output parser
     # ------------------------------------------------------------------
 
-    def _build_claude_argv(self, workdir: str) -> list[str]:
+    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::
@@ -305,10 +349,13 @@ class AgentCliAdapter(BaseAdapter):
             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.
-        ``--bare`` is deliberately NOT added — it would skip OAuth/keychain
-        reads and break subscription auth (design §5.3.4).
+        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:
@@ -418,10 +465,154 @@ class AgentCliAdapter(BaseAdapter):
             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:
@@ -442,9 +633,7 @@ class AgentCliAdapter(BaseAdapter):
             **meta,
         )
 
-    def _render_prompt(
-        self, request: ChatRequest, overrides: ProviderCallOverrides | None
-    ) -> str:
+    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

coderouter/config/schemas.py

@@ -170,10 +170,17 @@ class AgentCliConfig(BaseModel):
     ``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. Phase 1a implements the
-    ``claude`` (Claude Code CLI) target only; the other agents are declared
-    at the schema level so configs are forward-compatible, but the adapter
-    rejects them until their phase lands.
+    ``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.
@@ -183,7 +190,10 @@ class AgentCliConfig(BaseModel):
 
     agent: Literal["codex", "gemini", "grok", "claude"] = Field(
         ...,
-        description="External coding-agent CLI to invoke. Phase 1a: 'claude' only.",
+        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,
@@ -248,7 +258,9 @@ class AgentCliConfig(BaseModel):
             "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."
+            "``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(
@@ -627,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 "
@@ -642,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.7.dist-info → coderouter_cli-2.7.8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: coderouter-cli
-Version: 2.7.7
+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.7.dist-info → coderouter_cli-2.7.8.dist-info}/RECORD

@@ -11,12 +11,12 @@ 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=jy8u5aNacQmKMH698P_4aZYNIhjGA6xFgynGquNOzOM,24335
+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
@@ -25,12 +25,12 @@ coderouter/config/__init__.py,sha256=FODEn74fN-qZnt4INPSHswqhOlEgpL6-_onxsitSx8g
 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=-HrlEN1BkfO_Euo0m-mszQIaLupg3en6vHkqpPKTvAw,84538
+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
@@ -58,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
@@ -69,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.7.dist-info/METADATA,sha256=BfuchYkkpXZtvCOcok0FISgazhd7eSFKD9f8qID58dI,15546
-coderouter_cli-2.7.7.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-coderouter_cli-2.7.7.dist-info/entry_points.txt,sha256=-dnLfD1YZ2WjH2zSdNCvlO65wYltM9bsHt9Fhg3yGss,51
-coderouter_cli-2.7.7.dist-info/licenses/LICENSE,sha256=wkEzoR86jFw33jvfOHjULqmkGEfxTFMgMaJnpR8mPRw,1065
-coderouter_cli-2.7.7.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,,