coderouter-cli 2.15.0__py3-none-any.whl → 2.16.0__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -458,6 +458,8 @@ class AnthropicAdapter(BaseAdapter):
                 provider=self.name,
                 status_code=resp.status_code,
                 retryable=resp.status_code in _RETRYABLE_STATUSES,
+                upstream_body=resp.text,
+                retry_after=resp.headers.get("retry-after"),
             )
 
         try:
@@ -570,6 +572,8 @@ class AnthropicAdapter(BaseAdapter):
                         provider=self.name,
                         status_code=resp.status_code,
                         retryable=resp.status_code in _RETRYABLE_STATUSES,
+                        upstream_body=body.decode("utf-8", errors="replace"),
+                        retry_after=resp.headers.get("retry-after"),
                     )
 
                 # Anthropic SSE block shape:

coderouter/adapters/base.py

@@ -101,6 +101,12 @@ class StreamChunk(BaseModel):
     usage: dict[str, Any] | None = None
 
 
+#: v2.16.0: max chars of an upstream error body an :class:`AdapterError`
+#: keeps. Error bodies are small; the cap only bounds a misbehaving upstream
+#: that answers an error status with a large HTML page.
+UPSTREAM_BODY_CAP = 4096
+
+
 class AdapterError(CodeRouterError):
     """Raised when a provider call fails in a way the fallback engine should retry on."""
 
@@ -111,6 +117,8 @@ class AdapterError(CodeRouterError):
         provider: str,
         status_code: int | None = None,
         retryable: bool = True,
+        upstream_body: str | None = None,
+        retry_after: str | None = None,
     ) -> None:
         """Construct an AdapterError.
 
@@ -125,11 +133,23 @@ class AdapterError(CodeRouterError):
             retryable: When True, the fallback engine may try the next
                 provider in the chain. When False, the engine stops
                 and surfaces the error as a terminal failure.
+            upstream_body: v2.16.0 — the upstream's error body (capped at
+                :data:`UPSTREAM_BODY_CAP` chars), kept so the ingress can
+                hand the upstream's own wording back to the client.
+                Claude Code recovers from several 400s (rejected beta
+                headers, tool search, context overflow) only when it can
+                read the upstream message. Never logged by this class.
+            retry_after: v2.16.0 — the upstream's ``Retry-After`` header
+                value, verbatim, when it sent one.
         """
         super().__init__(message)
         self.provider = provider
         self.status_code = status_code
         self.retryable = retryable
+        self.upstream_body = (
+            upstream_body[:UPSTREAM_BODY_CAP] if upstream_body is not None else None
+        )
+        self.retry_after = retry_after
 
     def __str__(self) -> str:
         """Render as ``[provider status=NNN] message`` for log trails."""

coderouter/adapters/openai_compat.py

@@ -244,6 +244,8 @@ class OpenAICompatAdapter(BaseAdapter):
                 provider=self.name,
                 status_code=resp.status_code,
                 retryable=resp.status_code in _RETRYABLE_STATUSES,
+                upstream_body=resp.text,
+                retry_after=resp.headers.get("retry-after"),
             )
 
         try:
@@ -381,6 +383,8 @@ class OpenAICompatAdapter(BaseAdapter):
                         provider=self.name,
                         status_code=resp.status_code,
                         retryable=resp.status_code in _RETRYABLE_STATUSES,
+                        upstream_body=body.decode("utf-8", errors="replace"),
+                        retry_after=resp.headers.get("retry-after"),
                     )
                 async for line in resp.aiter_lines():
                     if not line:

coderouter/cli.py

@@ -165,6 +165,17 @@ def _build_parser() -> argparse.ArgumentParser:
             "for live key values. Exit 0 clean / 2 needs attention / 1 leak."
         ),
     )
+    doctor.add_argument(
+        "--check-claude-code",
+        action="store_true",
+        help=(
+            "v2.16.0: check the local Claude Code install for gateway use — "
+            "known-bad versions (<2.1.301, 2.1.304) and the env vars that "
+            "matter behind a non-Anthropic gateway (ENABLE_TOOL_SEARCH, "
+            "CLAUDE_CODE_MAX_CONTEXT_TOKENS, CLAUDE_CODE_AUTO_MODE_SERVER). "
+            "No network. Exit 0 OK / 2 needs attention."
+        ),
+    )
     doctor.add_argument(
         "--config",
         default=None,
@@ -454,6 +465,28 @@ def _build_parser() -> argparse.ArgumentParser:
             "generation. Tip: keep secrets in a separate .envrc.local."
         ),
     )
+    vscode_init.add_argument(
+        "--max-context-tokens",
+        type=int,
+        default=None,
+        metavar="N",
+        help=(
+            "v2.16.0: also write CLAUDE_CODE_MAX_CONTEXT_TOKENS=N so Claude "
+            "Code compacts before your local model's context fills up "
+            "(since 2.1.285 it assumes 1M behind a gateway). Use the "
+            "smallest context window in the profile's chain."
+        ),
+    )
+    vscode_init.add_argument(
+        "--no-claude-code-env",
+        action="store_true",
+        help=(
+            "v2.16.0: do not write the Claude Code gateway settings "
+            "(ENABLE_TOOL_SEARCH=false, CLAUDE_CODE_AUTO_MODE_SERVER=0, "
+            "and --max-context-tokens). Use when the chain is "
+            "api.anthropic.com only."
+        ),
+    )
     vscode_init.add_argument(
         "--dry-run",
         action="store_true",
@@ -595,10 +628,16 @@ def _run_doctor(args: argparse.Namespace) -> int:
     risks AND broken providers can use a single command.
     """
     check_secrets = bool(getattr(args, "check_secrets", False))
-    if args.check_model is None and args.check_env is None and not check_secrets:
+    check_claude_code = bool(getattr(args, "check_claude_code", False))
+    if (
+        args.check_model is None
+        and args.check_env is None
+        and not check_secrets
+        and not check_claude_code
+    ):
         print(
             "doctor: provide --check-model PROVIDER, --check-env [PATH], "
-            "and/or --check-secrets",
+            "--check-secrets and/or --check-claude-code",
             file=sys.stderr,
         )
         return 1
@@ -614,6 +653,14 @@ def _run_doctor(args: argparse.Namespace) -> int:
     if check_secrets:
         worst_exit = max(worst_exit, _run_check_secrets(args.config))
 
+    if check_claude_code:
+        from coderouter.doctor_claude_code import format_report as _cc_format
+        from coderouter.doctor_claude_code import run_check as _cc_run
+
+        cc_report = _cc_run()
+        print(_cc_format(cc_report))
+        worst_exit = max(worst_exit, cc_report.exit_code)
+
     if args.check_model is not None:
         worst_exit = max(worst_exit, _run_check_model(args))
 
@@ -976,6 +1023,7 @@ def _run_vscode_init(args: argparse.Namespace) -> int:
     """
     from coderouter.vscode_init import (
         DEFAULT_PORT,
+        claude_code_env,
         exit_code_for,
         format_result,
         run_vscode_init,
@@ -991,6 +1039,22 @@ def _run_vscode_init(args: argparse.Namespace) -> int:
 
     port = args.port if args.port is not None else DEFAULT_PORT
 
+    extra_env: dict[str, str] | None = None
+    max_ctx = getattr(args, "max_context_tokens", None)
+    if getattr(args, "no_claude_code_env", False):
+        if max_ctx is not None:
+            print(
+                "vscode-init: --max-context-tokens has no effect with --no-claude-code-env",
+                file=sys.stderr,
+            )
+            return 2
+    else:
+        try:
+            extra_env = claude_code_env(max_context_tokens=max_ctx)
+        except ValueError as exc:
+            print(f"vscode-init: {exc}", file=sys.stderr)
+            return 2
+
     try:
         result = run_vscode_init(
             target,
@@ -999,6 +1063,7 @@ def _run_vscode_init(args: argparse.Namespace) -> int:
             with_envrc=args.with_envrc,
             dry_run=args.dry_run,
             force=args.force,
+            extra_env=extra_env,
         )
     except FileNotFoundError as exc:
         # Raised only when target vanishes between the pre-check above

coderouter/config/schemas.py

@@ -1089,7 +1089,13 @@ class FallbackChain(BaseModel):
     #                (``context_budget_preserve_last_n``) are always
     #                kept, and tool_use / tool_result pairs are preserved
     #                atomically to avoid breaking agent loops.
-    context_budget_action: Literal["off", "warn", "trim"] = Field(
+    #   * ``reject`` — v2.16.0: ``warn`` + at ``context_budget_trim_threshold``
+    #                refuse the request with Anthropic's own overflow error
+    #                (HTTP 400, ``prompt is too long: ...``). Claude Code
+    #                answers that by compacting the conversation itself
+    #                (a summary, not a silent cut), so this is the
+    #                recommended action for Claude Code sessions.
+    context_budget_action: Literal["off", "warn", "trim", "reject"] = Field(
         default="off",
         description=(
             "v2.0-F (L1): action when estimated request tokens approach "
@@ -1097,7 +1103,10 @@ class FallbackChain(BaseModel):
             "disables the guard entirely. ``warn`` emits a log and "
             "response header at ``context_budget_warn_threshold``. "
             "``trim`` additionally removes old messages at "
-            "``context_budget_trim_threshold`` to reclaim context space."
+            "``context_budget_trim_threshold`` to reclaim context space. "
+            "``reject`` (v2.16.0) instead answers HTTP 400 "
+            "``prompt is too long`` at that threshold so the client "
+            "compacts the conversation itself (Claude Code does)."
         ),
     )
     context_budget_warn_threshold: float = Field(
@@ -1222,6 +1231,31 @@ class FallbackChain(BaseModel):
     # --- v2.0-H (L6): Mid-stream partial stitching --------------------------
     #   * ``off``      — discard partial content on mid-stream failure (legacy).
     #   * ``surface``  — return partial content as a truncated-but-valid response.
+    # v2.16.0 (tool search): Claude Code 2.1.304+ turns tool search on behind
+    # a custom ANTHROPIC_BASE_URL. The request then carries a server-side
+    # tool-search tool (``type: tool_search_tool_*``) and tools marked
+    # ``defer_loading: true``, which only api.anthropic.com executes. A
+    # local model sees the search tool as an ordinary function (and may
+    # "call" it), while every deferred MCP tool lands in its context anyway.
+    # Claude Code retries without tool search when the gateway answers 400.
+    #   * ``auto``        — ``passthrough`` when every provider in the chain
+    #                       is ``kind: anthropic`` on api.anthropic.com,
+    #                       otherwise ``reject`` (default).
+    #   * ``reject``      — answer 400 so the client turns tool search off.
+    #   * ``expand``      — drop the search tool and the ``defer_loading``
+    #                       flags; every tool is sent up front.
+    #   * ``passthrough`` — forward unchanged (pre-v2.16.0 behaviour).
+    deferred_tools_action: Literal["auto", "reject", "expand", "passthrough"] = Field(
+        default="auto",
+        description=(
+            "v2.16.0: what to do with Claude Code tool search "
+            "(``defer_loading`` tools / ``tool_search_tool_*``). ``auto`` "
+            "passes it through only for chains made entirely of "
+            "api.anthropic.com providers and rejects it (HTTP 400, which "
+            "makes Claude Code retry without tool search) otherwise."
+        ),
+    )
+
     partial_stitch_action: Literal["off", "surface"] = Field(
         default="off",
         description=(

coderouter/doctor.py

@@ -635,6 +635,49 @@ _PROBE_TOOL_SPEC_ANTHROPIC = {
 }
 
 
+# v2.15.1: llama.cpp changed ``llama-server``'s default listen port from
+# 8080 to 9931 (ggml-org/llama.cpp#30159, build b11521, 2026-10-09). A server
+# started without ``--port`` on a new build is invisible to a provider that
+# still points at :8080, and the reverse holds for configs written against
+# the new default. When the basic probe cannot connect to one of those two
+# ports on a loopback host, check the other one so the transport error can
+# name the likely cause instead of looking like "server not running".
+_LLAMACPP_PORT_PAIR: dict[int, int] = {8080: 9931, 9931: 8080}
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+
+
+async def _llamacpp_port_hint(base_url: object) -> str | None:
+    """Return a hint when the other llama.cpp default port answers.
+
+    Only fires for loopback hosts on port 8080 or 9931. The alternate
+    port is probed at ``GET /health`` (llama-server's readiness route)
+    with a short timeout on the IPv4 literal — ``localhost`` can resolve
+    to ``::1`` first on macOS, where llama-server is not listening. The
+    config is never rewritten; the operator decides.
+    """
+    try:
+        parsed = httpx.URL(str(base_url))
+    except (httpx.InvalidURL, TypeError):
+        return None
+    if parsed.host not in _LOOPBACK_HOSTS or parsed.port not in _LLAMACPP_PORT_PAIR:
+        return None
+    other = _LLAMACPP_PORT_PAIR[parsed.port]
+    try:
+        async with httpx.AsyncClient(timeout=1.5) as client:
+            resp = await client.get(f"http://127.0.0.1:{other}/health")
+    except httpx.HTTPError:
+        return None
+    if resp.status_code >= 500:
+        return None
+    return (
+        f"Something is answering on port {other} instead. llama.cpp "
+        f"builds b11521+ listen on 9931 when started without --port "
+        f"(older builds: 8080). Either start llama-server with "
+        f"--port {parsed.port}, or change this provider's base_url to "
+        f"port {other}"
+    )
+
+
 async def _probe_auth_and_basic_chat(
     provider: ProviderConfig,
 ) -> ProbeResult:
@@ -670,10 +713,14 @@ async def _probe_auth_and_basic_chat(
     )
 
     if status is None:
+        detail = f"could not reach {url}: {raw}"
+        hint = await _llamacpp_port_hint(provider.base_url)
+        if hint:
+            detail = f"{detail}. {hint}"
         return ProbeResult(
             name="auth+basic-chat",
             verdict=ProbeVerdict.TRANSPORT_ERROR,
-            detail=f"could not reach {url}: {raw}",
+            detail=detail,
         )
 
     if status in (401, 403):

coderouter/doctor_claude_code.py

@@ -0,0 +1,181 @@
+"""``coderouter doctor --check-claude-code`` (v2.16.0).
+
+Local-only checks for a Claude Code install that talks to CodeRouter:
+
+1. **Version.** Known gateway-relevant regressions:
+
+   - before 2.1.301: compaction could repeat when the response's ``model``
+     name differs from the requested one (every translating gateway);
+   - exactly 2.1.304: every request failed behind a gateway that rejects
+     tool search (fixed in 2.1.305).
+
+2. **Environment.** Variables that matter behind a non-Anthropic gateway
+   (see ``coderouter vscode-init``):
+
+   - ``ENABLE_TOOL_SEARCH`` unset → tool search is on by default since
+     2.1.304; CodeRouter refuses it (``deferred_tools_action``) and Claude
+     Code retries without it — works, but costs a round trip per session;
+   - ``CLAUDE_CODE_MAX_CONTEXT_TOKENS`` unset on 2.1.285+ → Claude Code may
+     assume a 1M window and compact far too late for a local model;
+   - ``CLAUDE_CODE_AUTO_MODE_SERVER`` unset → auto mode asks the gateway
+     for a server-side classifier a local backend does not have.
+
+No network, no config file. Exit codes follow the other doctor checks:
+0 = OK, 2 = needs attention, 1 = could not run.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+
+_VERSION_RE = re.compile(r"(\d+)\.(\d+)\.(\d+)")
+
+Version = tuple[int, int, int]
+
+
+@dataclass
+class ClaudeCodeFinding:
+    level: str  # "ok" | "warn" | "info"
+    message: str
+
+
+@dataclass
+class ClaudeCodeReport:
+    version: Version | None
+    findings: list[ClaudeCodeFinding] = field(default_factory=list)
+    error: str | None = None
+
+    @property
+    def exit_code(self) -> int:
+        if self.error is not None:
+            return 1
+        return 2 if any(f.level == "warn" for f in self.findings) else 0
+
+
+def parse_version(text: str) -> Version | None:
+    m = _VERSION_RE.search(text)
+    if m is None:
+        return None
+    return (int(m.group(1)), int(m.group(2)), int(m.group(3)))
+
+
+def _fmt(v: Version) -> str:
+    return ".".join(str(p) for p in v)
+
+
+def check(version: Version | None, env: Mapping[str, str]) -> list[ClaudeCodeFinding]:
+    """Pure check: findings for a Claude Code version and an environment."""
+    out: list[ClaudeCodeFinding] = []
+    if version is not None:
+        if version < (2, 1, 301):
+            out.append(
+                ClaudeCodeFinding(
+                    "warn",
+                    f"Claude Code {_fmt(version)} is older than 2.1.301: compaction can "
+                    "repeat behind a gateway that reports a different model name. "
+                    "Update Claude Code.",
+                )
+            )
+        elif version == (2, 1, 304):
+            out.append(
+                ClaudeCodeFinding(
+                    "warn",
+                    "Claude Code 2.1.304 fails every request behind a gateway that "
+                    "rejects tool search (fixed in 2.1.305). Update Claude Code, or "
+                    "set ENABLE_TOOL_SEARCH=false.",
+                )
+            )
+        else:
+            out.append(ClaudeCodeFinding("ok", f"Claude Code {_fmt(version)}"))
+
+    if env.get("ENABLE_TOOL_SEARCH", "").lower() in ("false", "0"):
+        out.append(ClaudeCodeFinding("ok", "ENABLE_TOOL_SEARCH=false"))
+    else:
+        out.append(
+            ClaudeCodeFinding(
+                "warn",
+                "ENABLE_TOOL_SEARCH is not false: Claude Code 2.1.304+ starts each "
+                "session with tool search, which only api.anthropic.com runs. "
+                "CodeRouter refuses it and Claude Code retries without it. Set "
+                "ENABLE_TOOL_SEARCH=false (coderouter vscode-init does) to skip "
+                "that round trip.",
+            )
+        )
+
+    if "CLAUDE_CODE_MAX_CONTEXT_TOKENS" in env:
+        out.append(
+            ClaudeCodeFinding(
+                "ok", f"CLAUDE_CODE_MAX_CONTEXT_TOKENS={env['CLAUDE_CODE_MAX_CONTEXT_TOKENS']}"
+            )
+        )
+    elif version is None or version >= (2, 1, 285):
+        out.append(
+            ClaudeCodeFinding(
+                "warn",
+                "CLAUDE_CODE_MAX_CONTEXT_TOKENS is not set: since 2.1.285 Claude Code "
+                "may assume a 1M window behind a gateway and compact long after a "
+                "local model has overflowed. Set it to your smallest local context "
+                "window (coderouter vscode-init --max-context-tokens N), and/or use "
+                "context_budget_action: reject in the profile.",
+            )
+        )
+
+    if env.get("CLAUDE_CODE_AUTO_MODE_SERVER") == "0":
+        out.append(ClaudeCodeFinding("ok", "CLAUDE_CODE_AUTO_MODE_SERVER=0"))
+    else:
+        out.append(
+            ClaudeCodeFinding(
+                "warn",
+                "CLAUDE_CODE_AUTO_MODE_SERVER is not 0: on a gateway, auto mode "
+                "defaults to a server-side classifier that a local backend does not "
+                "provide. Set CLAUDE_CODE_AUTO_MODE_SERVER=0.",
+            )
+        )
+    return out
+
+
+def _claude_version(run: Callable[[list[str]], str] | None = None) -> tuple[Version | None, str | None]:
+    if run is None:
+        exe = shutil.which("claude")
+        if exe is None:
+            return None, "`claude` not found on PATH (version checks skipped)"
+
+        def run(cmd: list[str]) -> str:
+            proc = subprocess.run(cmd, capture_output=True, text=True, timeout=15, check=False)
+            return proc.stdout + proc.stderr
+
+        cmd = [exe, "--version"]
+    else:
+        cmd = ["claude", "--version"]
+    try:
+        text = run(cmd)
+    except (OSError, subprocess.SubprocessError) as exc:
+        return None, f"could not run `claude --version`: {exc}"
+    version = parse_version(text)
+    if version is None:
+        return None, f"could not parse `claude --version` output: {text.strip()[:80]!r}"
+    return version, None
+
+
+def run_check(
+    env: Mapping[str, str] | None = None,
+    run: Callable[[list[str]], str] | None = None,
+) -> ClaudeCodeReport:
+    version, note = _claude_version(run)
+    findings = check(version, os.environ if env is None else env)
+    if note:
+        findings.insert(0, ClaudeCodeFinding("info", note))
+    return ClaudeCodeReport(version=version, findings=findings)
+
+
+def format_report(report: ClaudeCodeReport) -> str:
+    lines = ["Claude Code (behind CodeRouter)"]
+    for f in report.findings:
+        mark = {"ok": "OK  ", "warn": "WARN", "info": "INFO"}.get(f.level, f.level.upper())
+        lines.append(f"  [{mark}] {f.message}")
+    return "\n".join(lines)

coderouter/guards/context_budget.py

@@ -87,6 +87,25 @@ if TYPE_CHECKING:
 # ---------------------------------------------------------------------------
 
 
+class ContextBudgetRejectError(Exception):
+    """v2.16.0: ``context_budget_action: reject`` refused an oversized request.
+
+    The ingress answers with Anthropic's overflow error (HTTP 400,
+    ``prompt is too long: ...``) so the client compacts the conversation
+    itself. Carries the numbers for the message and the log line.
+    """
+
+    def __init__(self, *, estimated_tokens: int, max_context_tokens: int, profile: str) -> None:
+        self.estimated_tokens = estimated_tokens
+        self.max_context_tokens = max_context_tokens
+        self.profile = profile
+        super().__init__(
+            f"prompt is too long: ~{estimated_tokens} tokens > "
+            f"{max_context_tokens} maximum (CodeRouter profile {profile!r}, "
+            "estimated)"
+        )
+
+
 @dataclass(frozen=True, slots=True)
 class ContextBudgetEstimate:
     """Result of a context-budget estimation check."""