coderouter-cli 2.15.1__tar.gz → 2.17.0__tar.gz

{coderouter_cli-2.15.1 → coderouter_cli-2.17.0}/CHANGELOG.md

@@ -9,6 +9,127 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.17.0] — 2026-10-24 (time-to-first-token cut-off, retry signals)
+
+### Added
+
+- **`ttft_timeout_s` (provider).** A streaming attempt that has not
+  produced its first real output (text / tool_use / thinking delta) within
+  this many seconds is abandoned before any byte reached the client, and
+  the chain moves on — e.g. a local llama-server still loading a model or
+  prefilling a long prompt while a cloud provider could answer now. Never
+  applied to the last provider of a chain (nothing to fall back to), nor to
+  non-streaming requests (`timeout_s` covers those), nor to the
+  `/v1/chat/completions` route. It is also skipped for the tool-turn
+  downgrade (`kind: openai_compat` with tools, which calls the upstream
+  non-streaming so tool calls can be repaired): there the "first output" is
+  the whole answer, and a deadline would discard slow but healthy replies —
+  use `kind: anthropic` (native `/v1/messages`) to get the cut-off for a
+  local server. It always covers the
+  wait for the first event; covering the gap between the opening events and
+  the first real output needs `empty_response_action: fallback`, which is
+  what withholds those events from the client. Abandoned attempts are
+  ordinary retryable failures: new fallback reason `ttft-timeout` (detail
+  `no-first-token`) and the self-healing guards learn from them. A cut that
+  happens after the opening events is handled like a truncated stream: the
+  withheld, unterminated preamble is never flushed to the client if the
+  rest of the chain also fails, and the abandoned upstream stream is closed
+  immediately. Default
+  `None` (off). Docs: `docs/concepts/commit-point.md` / `.en.md`.
+- **`x-should-retry` on `/v1/messages` errors.** Every Anthropic-shaped
+  error CodeRouter produces now says whether retrying can help — the header
+  Claude Code reads, with `retry-after`, to decide whether to spend its
+  retry budget: `false` for 400 / 413 (including tool-search and
+  `context_budget_action: reject` refusals), `true` for 429, and for 502
+  `true` only when at least one upstream failure was retryable (a chain that
+  failed purely on 401/403 fails the same way on every retry).
+- **Docs: the commit point** (`docs/concepts/commit-point.md` / `.en.md`) —
+  which failures before the body ships CodeRouter can still move to another
+  provider, which it cannot, and the error each chain failure becomes.
+  Recommends `empty_response_action: fallback` for Claude Code profiles.
+
+### Known limits
+
+- No keep-alive `ping` is sent while opening events are withheld; keep
+  `ttft_timeout_s` below the client's idle timeout
+  (`CLAUDE_STREAM_IDLE_TIMEOUT_MS` for Claude Code).
+
+---
+
+## [v2.16.0] — 2026-10-24 (Claude Code 2.1.3xx behind a gateway)
+
+Claude Code 2.1.285–2.1.309 changed several defaults for sessions behind a
+custom `ANTHROPIC_BASE_URL`: tool search is on, Opus 4.7+ / Sonnet 5+ /
+Fable ids are treated as 1M-context models, auto mode asks the gateway for a
+server-side classifier, and recovery from rejected features or an
+overflowing prompt now depends on reading the gateway's error message. This
+release makes CodeRouter answer in the shape those recoveries expect.
+
+### Added
+
+- **Anthropic-shaped errors when the whole chain fails (`/v1/messages`).**
+  A failed chain used to come back as FastAPI's `{"detail": "..."}` with
+  HTTP 502 whatever the upstreams said. It now uses Anthropic's envelope
+  (`{"type": "error", "error": {"type", "message"}}`) and a status chosen
+  from what the upstreams said (`coderouter/ingress/anthropic_errors.py`):
+  - an upstream context-overflow error (llama.cpp
+    `exceed_context_size_error`, vLLM / OpenAI "maximum context length",
+    Ollama "prompt too long", …) → **400 `invalid_request_error`, message
+    starting `prompt is too long`**, which is what triggers Claude Code's
+    reactive compaction. An overflow caused by the *completion* budget
+    ("… 32000 in the completion", `max_tokens`) is not reported this way —
+    compacting the prompt cannot fix it — and goes out as a plain 400;
+  - a non-retryable upstream 400 / 422 → 400 with the upstream's own
+    message (Claude Code drops a rejected beta header / feature only when it
+    can read why);
+  - 413 → `request_too_large`; 429 → `rate_limit_error` with the upstream's
+    `retry-after` passed through;
+  - upstream 401 / 403 and everything else → 502 `api_error` (they concern
+    CodeRouter's own upstream credentials, not the client's).
+  Upstream messages are secret-redacted and length-capped. `AdapterError`
+  now keeps the upstream body (capped at 4096 chars) and `Retry-After`.
+- **Streaming requests get a real HTTP status for pre-content failures.**
+  The route now pulls the engine's first event before committing the
+  response, so a chain that fails before producing anything is answered
+  with the status above instead of `200` plus an in-stream `error` event —
+  as api.anthropic.com does. Once the first event exists, nothing changes.
+  The wait shares the stream's overall M14 ceiling (one deadline, not two),
+  and a client that disconnects during it cancels the upstream attempt.
+- **`deferred_tools_action` (profile; `auto` | `reject` | `expand` |
+  `passthrough`, default `auto`).** Claude Code 2.1.304+ sends a server-side
+  `tool_search_tool_*` and tools marked `defer_loading: true`; only
+  api.anthropic.com runs the search. `auto` passes the request through only
+  when every provider in the chain is `kind: anthropic` on api.anthropic.com
+  and otherwise answers 400, which makes Claude Code (2.1.305+) retry
+  without tool search. `expand` drops the search tool and the flags and
+  sends every tool up front.
+- **`context_budget_action: reject`.** At `context_budget_trim_threshold`
+  the guard answers 400 `prompt is too long: ~N tokens > M maximum` instead
+  of trimming, so Claude Code summarizes the conversation itself rather
+  than losing history silently. Works for streaming and non-streaming.
+- **`coderouter vscode-init` writes Claude Code gateway settings** by
+  default: `ENABLE_TOOL_SEARCH=false`, `CLAUDE_CODE_AUTO_MODE_SERVER=0`,
+  and — with the new `--max-context-tokens N` —
+  `CLAUDE_CODE_MAX_CONTEXT_TOKENS=N`. `--no-claude-code-env` opts out. Same
+  merge / conflict rules as the existing variables; an export of one of
+  them outside the `.envrc` fence conflicts only when this run writes it.
+- **`coderouter doctor --check-claude-code`.** Local-only check of the
+  Claude Code install: warns on versions with known gateway bugs (before
+  2.1.301: compaction can repeat; 2.1.304: every request fails when the
+  gateway rejects tool search) and on missing `ENABLE_TOOL_SEARCH`,
+  `CLAUDE_CODE_MAX_CONTEXT_TOKENS` (2.1.285+) and
+  `CLAUDE_CODE_AUTO_MODE_SERVER`. Exit 0 OK / 2 needs attention.
+
+### Changed
+
+- **Breaking for clients that parse error bodies:** `/v1/messages` errors
+  for a failed chain are no longer `{"detail": "..."}`, and a streaming
+  request whose chain fails before the first event is no longer
+  `200` + `event: error`. Both now match the Anthropic API. The
+  `/v1/chat/completions` (OpenAI) route is unchanged.
+
+---
+
 ## [v2.15.1] — 2026-10-24 (docs and defaults for the October 2026 ecosystem)
 
 ### Added

{coderouter_cli-2.15.1 → coderouter_cli-2.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: coderouter-cli
-Version: 2.15.1
+Version: 2.17.0
 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.15.1 → coderouter_cli-2.17.0}/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_cli-2.15.1 → coderouter_cli-2.17.0}/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."""
@@ -180,6 +200,23 @@ class StreamTruncatedError(AdapterError):
         self.tool_call_in_flight = tool_call_in_flight
 
 
+# v2.17.0: the provider did not produce its first real streamed output within
+# ``ProviderConfig.ttft_timeout_s``. Raised by the engine (not the adapter),
+# before any byte reached the client, so the chain falls back normally and the
+# self-healing guards learn from it like any other retryable failure.
+class TTFTTimeoutError(AdapterError):
+    """No first token within ``ttft_timeout_s``."""
+
+    def __init__(self, *, provider: str, ttft_timeout_s: float) -> None:
+        super().__init__(
+            f"timeout: no first token within {ttft_timeout_s:g}s (ttft_timeout_s)",
+            provider=provider,
+            status_code=None,
+            retryable=True,
+        )
+        self.ttft_timeout_s = ttft_timeout_s
+
+
 # v0.6-B: per-call overrides resolved from the active profile. The engine
 # builds one instance per request (since a profile is invariant across its
 # chain) and threads it through every adapter call on that chain. Adapters

{coderouter_cli-2.15.1 → coderouter_cli-2.17.0}/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-2.15.1 → coderouter_cli-2.17.0}/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_cli-2.15.1 → coderouter_cli-2.17.0}/coderouter/config/schemas.py

@@ -550,6 +550,28 @@ class ProviderConfig(BaseModel):
         description="If true, only used when ALLOW_PAID=true (plan.md §2.3).",
     )
     timeout_s: float = Field(default=30.0, ge=1.0, le=86400.0)
+    # v2.17.0: time-to-first-token cut-off for streaming requests. When the
+    # provider has not produced its first real output (text / tool_use /
+    # thinking delta) within this many seconds of the attempt starting, the
+    # attempt is abandoned and the chain moves on — before any byte reached
+    # the client. Never applied to the last provider of a chain (nothing to
+    # move on to), nor to non-streaming requests (``timeout_s`` covers
+    # those). Before the first *event* it always applies; between the first
+    # event and the first real output it needs
+    # ``empty_response_action: fallback`` on the profile, which is what
+    # withholds those opening events from the client. ``None`` (default)
+    # disables it. Typical use: a local llama-server still loading a model
+    # or chewing through a long prompt while a cloud fallback could answer.
+    ttft_timeout_s: float | None = Field(
+        default=None,
+        gt=0.0,
+        le=3600.0,
+        description=(
+            "v2.17.0: seconds to wait for the first real streamed output "
+            "before falling back to the next provider (not applied to the "
+            "last provider in a chain). None disables."
+        ),
+    )
 
     # v2.6 language-tax track: path to a LOCAL ``tokenizer.json`` for this
     # provider's model, used to measure the CJK over-count vs the char/4
@@ -1089,7 +1111,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 +1125,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 +1253,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_cli-2.17.0/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_cli-2.15.1 → coderouter_cli-2.17.0}/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."""