coderouter-cli 2.6.1__py3-none-any.whl → 2.7.1__py3-none-any.whl

coderouter/adapters/anthropic_native.py

@@ -35,6 +35,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -68,6 +69,26 @@ _RETRYABLE_STATUSES = {404, 408, 425, 429, 500, 502, 503, 504}
 _DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
 
+def anthropic_messages_url(base_url: str) -> str:
+    """Resolve the ``/v1/messages`` endpoint URL from a ``base_url``.
+
+    ``base_url`` may be given with or without a trailing ``/v1`` — users
+    may point it at either ``https://api.anthropic.com`` or
+    ``https://api.anthropic.com/v1`` (LM Studio and similar servers
+    commonly advertise the latter). We normalize by stripping a trailing
+    ``/v1`` so appending ``/v1/messages`` always yields a valid,
+    non-duplicated URL.
+
+    Shared by :class:`AnthropicAdapter` and the continuous-probe guard so
+    both hit the exact same endpoint (see bug H4: a mismatch made the
+    probe target ``/v1/v1/messages`` and 404 on healthy backends).
+    """
+    base = base_url.rstrip("/")
+    if base.endswith("/v1"):
+        base = base[: -len("/v1")]
+    return f"{base}/v1/messages"
+
+
 class AnthropicAdapter(BaseAdapter):
     """Native Anthropic Messages API adapter (passthrough).
 
@@ -87,15 +108,10 @@ class AnthropicAdapter(BaseAdapter):
 
         ``base_url`` may be given with or without a trailing ``/v1`` —
         we normalize by stripping it so appending ``/v1/messages``
-        always yields a valid URL.
+        always yields a valid URL. Delegates to the shared
+        :func:`anthropic_messages_url` helper.
         """
-        base = str(self.config.base_url).rstrip("/")
-        # Users may point base_url at either `https://api.anthropic.com`
-        # or `https://api.anthropic.com/v1`. We normalize to the former so
-        # we can always append /v1/messages.
-        if base.endswith("/v1"):
-            base = base[: -len("/v1")]
-        return f"{base}/v1/messages"
+        return anthropic_messages_url(str(self.config.base_url))
 
     def _headers(self, request: AnthropicRequest | None = None) -> dict[str, str]:
         """Build Anthropic-native HTTP headers, including beta-header forwarding.
@@ -161,21 +177,21 @@ class AnthropicAdapter(BaseAdapter):
         that auth works and the endpoint is reachable.
         """
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.post(
-                    self._url(),
-                    headers=self._headers(),
-                    json={
-                        "model": self.config.model,
-                        "max_tokens": 1,
-                        "messages": [{"role": "user", "content": "ping"}],
-                    },
-                )
-                # 200 is clearly healthy. 4xx auth errors indicate the
-                # endpoint is reachable even if the key is bad — still a
-                # "the server answered" signal for healthcheck purposes.
-                # 5xx is upstream trouble.
-                return resp.status_code < 500
+            resp = await self.client().post(
+                self._url(),
+                headers=self._headers(),
+                json={
+                    "model": self.config.model,
+                    "max_tokens": 1,
+                    "messages": [{"role": "user", "content": "ping"}],
+                },
+                timeout=5.0,
+            )
+            # 200 is clearly healthy. 4xx auth errors indicate the
+            # endpoint is reachable even if the key is bad — still a
+            # "the server answered" signal for healthcheck purposes.
+            # 5xx is upstream trouble.
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -331,8 +347,9 @@ class AnthropicAdapter(BaseAdapter):
         timeout = self.effective_timeout(overrides)
 
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers(request))
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(request), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -394,7 +411,22 @@ class AnthropicAdapter(BaseAdapter):
         # (future additions like thinking blocks) pass through via
         # extra="allow" on AnthropicResponse.
         data["coderouter_provider"] = self.name
-        return AnthropicResponse.model_validate(data)
+        # M6: guard the model validation. A 200 body that isn't a valid
+        # Anthropic Messages response (missing ``content``/``id``, an
+        # error envelope returned with a 200, etc.) would otherwise raise
+        # a bare pydantic ValidationError that escapes the engine's
+        # AdapterError-based retry/fallback path. Convert to a retryable
+        # AdapterError so the chain can fall through (mirrors the
+        # invalid-JSON branch above, but retryable — a malformed shape is
+        # usually transient upstream noise rather than a config fault).
+        try:
+            return AnthropicResponse.model_validate(data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream_anthropic(
         self,
@@ -424,10 +456,14 @@ class AnthropicAdapter(BaseAdapter):
         logged_flag: list[bool] = [False]
 
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers(request)) as resp,
-            ):
+            # H3: stream over the shared client (pool / keep-alive / TLS
+            # reuse). Only the ``stream(...)`` context is scoped here; the
+            # client persists and is closed via ``aclose`` on shutdown. The
+            # ``async with`` releases the response's borrowed connection even
+            # if the caller abandons this generator mid-stream — no GC leak.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(request), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(

coderouter/adapters/base.py

@@ -11,6 +11,7 @@ from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator
 from typing import Any, Literal
 
+import httpx
 from pydantic import BaseModel, ConfigDict, Field
 
 from coderouter.config.schemas import ProviderConfig
@@ -164,17 +165,59 @@ class BaseAdapter(ABC):
     def __init__(self, config: ProviderConfig) -> None:
         """Bind the adapter to a :class:`ProviderConfig`.
 
-        Subclasses do not need to override this; HTTP clients are
-        constructed lazily inside :meth:`generate` / :meth:`stream` so
-        each call can honor a per-call timeout override.
+        Subclasses do not need to override this. A single shared
+        :class:`httpx.AsyncClient` is created lazily on first use (see
+        :meth:`client`) and reused across every call on this adapter so
+        the connection pool, HTTP keep-alive, and TLS session are all
+        reused. Per-call timeouts are still honored by passing
+        ``timeout=`` to ``client.post`` / ``client.stream`` — they do
+        NOT require a fresh client.
         """
         self.config = config
+        # Shared client, created lazily inside the running event loop the
+        # first time an adapter method needs it (see ``client``). Kept as
+        # ``None`` until then so constructing an adapter has no I/O cost and
+        # is safe outside an event loop (e.g. at import / config time).
+        self._client: httpx.AsyncClient | None = None
 
     @property
     def name(self) -> str:
         """Shortcut for ``self.config.name`` — used in log trails and errors."""
         return self.config.name
 
+    # ---- H3: shared HTTP client (connection-pool / keep-alive reuse) ----
+    def client(self) -> httpx.AsyncClient:
+        """Return the shared :class:`httpx.AsyncClient`, creating it lazily.
+
+        The client is created on first use so construction happens inside
+        the running event loop and carries no I/O cost at adapter-build
+        time. Subsequent calls return the same instance, which is what
+        lets httpx reuse pooled connections, keep-alive, and the TLS
+        session across requests.
+
+        No default timeout is baked in here: every call site passes an
+        explicit per-call ``timeout=`` (resolved from the active profile
+        via :meth:`effective_timeout`), so leaving the client timeout
+        unset avoids a surprising default clamping long-running calls.
+        """
+        if self._client is None:
+            self._client = httpx.AsyncClient(timeout=None)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the shared HTTP client and drop the reference.
+
+        Idempotent: safe to call when no client was ever created, and
+        safe to call more than once. Invoked from the app lifespan
+        shutdown path so pooled connections are released cleanly rather
+        than left to garbage collection. After ``aclose`` a later call
+        re-creates the client on demand via :meth:`client`.
+        """
+        client = self._client
+        self._client = None
+        if client is not None:
+            await client.aclose()
+
     # ---- v0.6-B override resolution helpers -----------------------------
     def effective_timeout(self, overrides: ProviderCallOverrides | None) -> float:
         """Profile override wins when set; else provider default."""

coderouter/adapters/openai_compat.py

@@ -19,6 +19,7 @@ from collections.abc import AsyncIterator
 from typing import Any
 
 import httpx
+from pydantic import ValidationError
 
 from coderouter.adapters.base import (
     AdapterError,
@@ -197,9 +198,8 @@ class OpenAICompatAdapter(BaseAdapter):
         base = str(self.config.base_url).rstrip("/")
         url = f"{base}/models"
         try:
-            async with httpx.AsyncClient(timeout=5.0) as client:
-                resp = await client.get(url, headers=self._headers())
-                return resp.status_code < 500
+            resp = await self.client().get(url, headers=self._headers(), timeout=5.0)
+            return resp.status_code < 500
         except httpx.HTTPError:
             return False
 
@@ -221,8 +221,9 @@ class OpenAICompatAdapter(BaseAdapter):
         payload = self._payload(request, stream=False, overrides=overrides)
         timeout = self.effective_timeout(overrides)
         try:
-            async with httpx.AsyncClient(timeout=timeout) as client:
-                resp = await client.post(url, json=payload, headers=self._headers())
+            resp = await self.client().post(
+                url, json=payload, headers=self._headers(), timeout=timeout
+            )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout contacting {url}", provider=self.name, retryable=True
@@ -287,7 +288,22 @@ class OpenAICompatAdapter(BaseAdapter):
 
         # Tag the response with which provider answered
         data.setdefault("object", "chat.completion")
-        return ChatResponse(coderouter_provider=self.name, **data)
+        # M6: a syntactically valid JSON body may still not be a valid
+        # Chat Completions response (e.g. an OpenAI-compat server that
+        # returns ``{"error": ...}`` with a 200, or omits ``choices``).
+        # pydantic raises ValidationError here; if left uncaught it would
+        # propagate past the engine's AdapterError-based retry/fallback
+        # logic. Convert to a retryable AdapterError so the chain can fall
+        # through to the next provider (mirrors the invalid-JSON branch,
+        # but retryable since a malformed shape is often transient).
+        try:
+            return ChatResponse(coderouter_provider=self.name, **data)
+        except ValidationError as exc:
+            raise AdapterError(
+                f"malformed response shape from upstream: {exc}",
+                provider=self.name,
+                retryable=True,
+            ) from exc
 
     async def stream(
         self,
@@ -312,6 +328,10 @@ class OpenAICompatAdapter(BaseAdapter):
         # produce dozens of duplicate log lines.
         strip_reasoning = not self.config.capabilities.reasoning_passthrough
         reasoning_logged = False
+        # M6: one-shot dedupe flag for the malformed-chunk warning. A single
+        # broken stream can emit many non-conforming chunks; we skip each one
+        # but log only on the first to avoid a log flood.
+        malformed_chunk_logged = False
 
         # v1.0-A: stateful output_filters chain for the duration of this
         # stream. Handles `<think>...</think>` / stop markers that split
@@ -325,10 +345,16 @@ class OpenAICompatAdapter(BaseAdapter):
         # seen chunk's id/model so the flush emission looks native.
         last_chunk_template: dict[str, Any] | None = None
         try:
-            async with (
-                httpx.AsyncClient(timeout=timeout) as client,
-                client.stream("POST", url, json=payload, headers=self._headers()) as resp,
-            ):
+            # H3: stream over the shared client so the connection pool /
+            # keep-alive / TLS session are reused. Only the ``stream(...)``
+            # context is entered here — the client itself outlives the
+            # stream and is closed via ``aclose`` on app shutdown. The
+            # ``async with`` guarantees the response (and its borrowed
+            # connection) is released even if the consumer abandons this
+            # generator mid-stream, so no connection leaks on GC.
+            async with self.client().stream(
+                "POST", url, json=payload, headers=self._headers(), timeout=timeout
+            ) as resp:
                 if resp.status_code >= 400:
                     body = await resp.aread()
                     raise AdapterError(
@@ -375,7 +401,23 @@ class OpenAICompatAdapter(BaseAdapter):
                             if isinstance(content, str) and content:
                                 delta["content"] = filter_chain.feed(content)
                         last_chunk_template = payload_obj
-                    yield StreamChunk(**payload_obj)
+                    # M6: a chunk may be valid JSON yet not a valid
+                    # StreamChunk (e.g. a mid-stream ``{"error": ...}``
+                    # frame, or a chunk missing required fields). Rather
+                    # than let the ValidationError abort the whole stream
+                    # (bypassing the engine's AdapterError handling), skip
+                    # the bad chunk and keep consuming. Warn once per stream.
+                    try:
+                        chunk = StreamChunk(**payload_obj)
+                    except ValidationError as exc:
+                        if not malformed_chunk_logged:
+                            logger.warning(
+                                "malformed-stream-chunk",
+                                extra={"provider": self.name, "error": str(exc)},
+                            )
+                            malformed_chunk_logged = True
+                        continue
+                    yield chunk
 
             # v1.0-A: flush the chain at end-of-stream. If filters held
             # back a partial-tag suffix that turned out NOT to be a tag,

coderouter/config/capability_registry.py

@@ -115,6 +115,20 @@ class RegistryCapabilities(BaseModel):
             "startup check)."
         ),
     )
+    tool_choice: bool | None = Field(
+        default=None,
+        description=(
+            "S2 (shim): does the upstream honor a forced Anthropic "
+            "``tool_choice`` (``{type: any}`` / ``{type: tool}``) on the "
+            "wire? When True, the fallback engine's ``tool_choice_action`` "
+            "leaves the request untouched. ``None`` (default) = no opinion "
+            "→ the gate falls back to ``provider.kind == 'anthropic'``. "
+            "``False`` hard-disables even on an anthropic-kind provider "
+            "(useful when a specific model regresses). Independent from "
+            "``providers.yaml capabilities.tool_choice`` (explicit "
+            "per-provider opt-in, highest precedence)."
+        ),
+    )
     cache_control: bool | None = Field(
         default=None,
         description=(
@@ -201,6 +215,7 @@ class ResolvedCapabilities:
     max_context_tokens: int | None = None
     claude_code_suitability: Literal["ok", "degraded"] | None = None
     cache_control: bool | None = None
+    tool_choice: bool | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -253,6 +268,7 @@ class CapabilityRegistry:
         resolved_max_ctx: int | None = None
         resolved_suitability: Literal["ok", "degraded"] | None = None
         resolved_cache_control: bool | None = None
+        resolved_tool_choice: bool | None = None
 
         thinking_locked = False
         reasoning_locked = False
@@ -260,6 +276,7 @@ class CapabilityRegistry:
         max_ctx_locked = False
         suitability_locked = False
         cache_control_locked = False
+        tool_choice_locked = False
 
         for rule in self._rules:
             if not rule.kind_matches(kind):
@@ -285,6 +302,9 @@ class CapabilityRegistry:
             if not cache_control_locked and caps.cache_control is not None:
                 resolved_cache_control = caps.cache_control
                 cache_control_locked = True
+            if not tool_choice_locked and caps.tool_choice is not None:
+                resolved_tool_choice = caps.tool_choice
+                tool_choice_locked = True
             if (
                 thinking_locked
                 and reasoning_locked
@@ -292,6 +312,7 @@ class CapabilityRegistry:
                 and max_ctx_locked
                 and suitability_locked
                 and cache_control_locked
+                and tool_choice_locked
             ):
                 break
 
@@ -302,6 +323,7 @@ class CapabilityRegistry:
             max_context_tokens=resolved_max_ctx,
             claude_code_suitability=resolved_suitability,
             cache_control=resolved_cache_control,
+            tool_choice=resolved_tool_choice,
         )
 
     # ------------------------------------------------------------------

coderouter/config/schemas.py

@@ -43,6 +43,18 @@ class Capabilities(BaseModel):
     # you explicitly want the raw reasoning text to flow to the client
     # (e.g. CodeRouter is fronting a reasoning-aware downstream).
     reasoning_passthrough: bool = False
+    # S2 (shim): Anthropic's ``tool_choice`` forcing modes (``{type: any}``
+    # / ``{type: tool, name: ...}``). Only a subset of backends honor a
+    # forced tool_choice on the wire; openai_compat translation drops it.
+    # This narrow per-model flag mirrors ``thinking`` / ``prompt_cache``:
+    # when unset (None), the capability gate falls back to the registry and
+    # then to a ``kind == "anthropic"`` heuristic (see
+    # ``coderouter/routing/capability.py``). Motivation: let the fallback
+    # engine's ``tool_choice_action`` emulate forced tool calls via a
+    # system-prompt directive on backends that would otherwise silently
+    # ignore the field. Backward compatible — None leaves v2.x behavior
+    # untouched (no gate, no emulation).
+    tool_choice: bool | None = None
     # v1.0+ fields, declared early so providers.yaml can future-proof
     reasoning_control: Literal["none", "openai", "anthropic", "provider_specific"] = "none"
     mcp: Literal["none", "anthropic", "provider_specific"] = "none"
@@ -706,6 +718,129 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    # --- S2 (shim): tool_choice capability gate + emulation -----------------
+    #
+    # Anthropic clients (Claude Code, SDKs) can pin the model to a specific
+    # tool with ``tool_choice: {type: "tool", name: "X"}`` or force *some*
+    # tool with ``{type: "any"}``. Native Anthropic honors this; most
+    # openai_compat backends silently ignore it after translation, so the
+    # model may answer with plain text where the client expected a tool
+    # call. This knob decides what the fallback engine does when a forced
+    # tool_choice request is routed to a provider that does not support it
+    # (per ``provider_supports_tool_choice``):
+    #
+    #   * ``off``     — no detection / no mutation / no log. Backward-compat
+    #                   default (identical to pre-shim behavior).
+    #   * ``warn``    — emit a ``capability-degraded`` log line only; the
+    #                   request is sent unchanged.
+    #   * ``emulate`` — strip the ``tool_choice`` field and inject an English
+    #                   directive into the system prompt instructing the
+    #                   model to call the requested tool. Best-effort
+    #                   forcing for backends without native support. The
+    #                   original request object is left untouched so a later
+    #                   capable provider in the chain still receives the real
+    #                   ``tool_choice``.
+    tool_choice_action: Literal["off", "warn", "emulate"] = Field(
+        default="off",
+        description=(
+            "S2 (shim): action when a request carries a forced "
+            "``tool_choice`` (``{type: any}`` or ``{type: tool}``) and the "
+            "target provider does not support it. ``off`` (default) leaves "
+            "the request unchanged. ``warn`` emits a ``capability-degraded`` "
+            "log only. ``emulate`` strips ``tool_choice`` and injects a "
+            "system-prompt directive to coax the model into calling the "
+            "tool. Per-provider — capable providers are never mutated."
+        ),
+    )
+
+    # --- S3 (shim): cache_control strip -------------------------------------
+    #
+    # By default cache_control markers are simply lost during Anthropic →
+    # OpenAI translation and the ``capability-degraded`` gate logs it
+    # (v0.5-B, observability only). Some strict openai_compat backends,
+    # however, 400 when an unexpected ``cache_control`` key rides along on a
+    # content block (rather than silently ignoring it). ``strip`` proactively
+    # removes those keys from a deep copy of the request before dispatch to
+    # a non-supporting provider, so the marker never reaches the wire.
+    #
+    #   * ``off``   — legacy behavior: leave the request as-is and rely on
+    #                 the existing ``capability-degraded`` observability log.
+    #   * ``strip`` — deep-copy the request and remove every ``cache_control``
+    #                 key from system / tools / message blocks before sending
+    #                 to a non-supporting provider; emit a
+    #                 ``cache-control-stripped`` log with the marker count.
+    #                 Does NOT emit a tokens-saved event (this is not token
+    #                 savings, just a wire-compatibility strip).
+    cache_control_action: Literal["off", "strip"] = Field(
+        default="off",
+        description=(
+            "S3 (shim): action when a request carries ``cache_control`` "
+            "markers and the target provider does not support them. ``off`` "
+            "(default) keeps legacy behavior (marker dropped in translation, "
+            "``capability-degraded`` log only). ``strip`` removes the "
+            "``cache_control`` keys from a deep copy before dispatch and "
+            "emits a ``cache-control-stripped`` log. Per-provider — capable "
+            "providers are never mutated."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def _check_context_budget_thresholds_ordered(self) -> FallbackChain:
+        """v2.0-F (mE): cross-field sanity of the context-budget ratios.
+
+        The three ratios describe a strict staircase: a warning fires
+        first, then trimming kicks in at a higher usage, and trimming
+        reclaims space down to a target below the trim point. If they are
+        mis-ordered the guard is either a dead knob (warn above trim never
+        fires) or an infinite trim loop (target >= trim never converges).
+        Same fast-fail philosophy as ``_check_default_profile_exists`` —
+        surface the mistake at load with a concrete pointer to the fix
+        rather than at the first request that trips the guard.
+
+        Required invariants:
+          * ``context_budget_warn_threshold`` <= ``context_budget_trim_threshold``
+          * ``context_budget_trim_target``    <  ``context_budget_trim_threshold``
+        """
+        if self.context_budget_warn_threshold > self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_warn_threshold "
+                f"({self.context_budget_warn_threshold}) must be <= "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — the warning has to "
+                f"fire at or before trimming, otherwise it can never fire. "
+                f"Lower warn_threshold or raise trim_threshold."
+            )
+        if self.context_budget_trim_target >= self.context_budget_trim_threshold:
+            raise ValueError(
+                f"profile {self.name!r}: context_budget_trim_target "
+                f"({self.context_budget_trim_target}) must be < "
+                f"context_budget_trim_threshold "
+                f"({self.context_budget_trim_threshold}) — trimming must "
+                f"reclaim space *below* the trigger point, otherwise trim "
+                f"never converges. Lower trim_target below trim_threshold."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_recovery_probe_interval_ordered(self) -> FallbackChain:
+        """v2.0-J (mE): the recovery-probe backoff floor must not exceed its cap.
+
+        ``recovery_probe_initial_s`` is the first probe interval and each
+        failed probe doubles it up to ``recovery_probe_max_s``. When the
+        initial interval already exceeds the max, the exponential-backoff
+        ceiling is below its own floor — a nonsensical configuration that
+        the backoff loop would silently clamp. Surface it at load instead.
+        """
+        if self.recovery_probe_initial_s > self.recovery_probe_max_s:
+            raise ValueError(
+                f"profile {self.name!r}: recovery_probe_initial_s "
+                f"({self.recovery_probe_initial_s}) must be <= "
+                f"recovery_probe_max_s ({self.recovery_probe_max_s}) — the "
+                f"initial probe interval cannot exceed the backoff ceiling. "
+                f"Lower recovery_probe_initial_s or raise recovery_probe_max_s."
+            )
+        return self
+
 
 # ---------------------------------------------------------------------------
 # v1.6-A: auto_router — declarative request-body classifier
@@ -720,6 +855,14 @@ class RuleMatcher(BaseModel):
     adding a new optional field — the single-field invariant enforces
     discriminated-union semantics without pydantic's tagged-union syntax.
 
+    Boolean matchers (``has_image`` / ``has_tools``) only carry meaning at
+    ``True``: the runtime evaluator matches with ``is True`` (see
+    ``coderouter.routing.auto_router._match_rule``), so a ``False`` value
+    would construct without error yet never match anything — a dead rule
+    that silently shadows nothing and confuses operators. ``_exactly_one``
+    therefore rejects ``False`` for these fields at load (``None`` remains
+    the "unset" sentinel).
+
     Variants (v1.6-A):
 
     - ``has_image: True`` — any ``image_url`` / ``image`` /
@@ -822,8 +965,29 @@ class RuleMatcher(BaseModel):
         "cjk_ratio_min",
     )
 
+    # Boolean matcher fields carry meaning only at ``True`` — the runtime
+    # evaluator uses ``is True`` — so a ``False`` value is a dead rule that
+    # never matches. ``_exactly_one`` rejects it explicitly (see below).
+    _BOOL_MATCHER_FIELDS: tuple[str, ...] = ("has_image", "has_tools")
+
     @model_validator(mode="after")
     def _exactly_one(self) -> Self:
+        # Reject the dead-rule shape first so the error names the specific
+        # field the operator got wrong, rather than the generic
+        # "exactly one" message (``False`` counts as "set" below).
+        false_bools = [
+            name
+            for name in self._BOOL_MATCHER_FIELDS
+            if getattr(self, name) is False
+        ]
+        if false_bools:
+            raise ValueError(
+                f"RuleMatcher boolean matcher(s) set to False: {false_bools}. "
+                f"These matchers are evaluated with ``is True``, so a False "
+                f"value is a dead rule that never matches (it would silently "
+                f"shadow nothing). Use True to match, or omit the field "
+                f"(leave it None) to not use this matcher."
+            )
         set_fields = [
             name for name in self._MATCHER_FIELDS if getattr(self, name) is not None
         ]
@@ -1391,6 +1555,74 @@ class CodeRouterConfig(BaseModel):
             )
         return self
 
+    @model_validator(mode="after")
+    def _check_names_unique(self) -> CodeRouterConfig:
+        """mE: provider and profile names must each be unique.
+
+        ``provider_by_name`` / ``profile_by_name`` return the *first*
+        match, so a duplicate name silently shadows every later entry with
+        the same key — the operator's second ``local:`` block is loaded,
+        validated, and then never reachable. Reject duplicates at load with
+        the offending names, matching the fast-fail philosophy of the other
+        ``_check_*`` validators.
+        """
+        seen_p: set[str] = set()
+        dup_p: list[str] = []
+        for p in self.providers:
+            if p.name in seen_p and p.name not in dup_p:
+                dup_p.append(p.name)
+            seen_p.add(p.name)
+        if dup_p:
+            raise ValueError(
+                f"duplicate provider name(s): {sorted(dup_p)}. Provider names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (provider_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+
+        seen_f: set[str] = set()
+        dup_f: list[str] = []
+        for prof in self.profiles:
+            if prof.name in seen_f and prof.name not in dup_f:
+                dup_f.append(prof.name)
+            seen_f.add(prof.name)
+        if dup_f:
+            raise ValueError(
+                f"duplicate profile name(s): {sorted(dup_f)}. Profile names "
+                f"must be unique — a duplicate silently shadows the later "
+                f"entry (profile_by_name returns the first match). Rename or "
+                f"remove the duplicate(s)."
+            )
+        return self
+
+    @model_validator(mode="after")
+    def _check_profile_providers_exist(self) -> CodeRouterConfig:
+        """mE: every provider named in a profile chain must be declared.
+
+        Previously a typo in ``profiles[].providers`` was tolerated at load
+        and only surfaced at runtime as a ``skip-unknown-provider`` warning;
+        if *every* entry in a chain was typo'd the profile silently had no
+        usable providers and only failed once fully drained. Rejecting at
+        load — same philosophy as ``_check_default_profile_exists`` and
+        ``_check_mode_alias_targets_exist`` — turns a silent-until-drained
+        misconfig into a startup error naming the profile and the bad
+        provider(s).
+        """
+        names = {p.name for p in self.providers}
+        errors: list[str] = []
+        for prof in self.profiles:
+            missing = [name for name in prof.providers if name not in names]
+            if missing:
+                errors.append(f"{prof.name!r} -> {missing}")
+        if errors:
+            raise ValueError(
+                f"profile(s) reference undeclared provider(s): "
+                f"{'; '.join(errors)}. known providers={sorted(names)}. "
+                f"Fix the typo in profiles[].providers or add the missing "
+                f"provider(s)."
+            )
+        return self
+
     def provider_by_name(self, name: str) -> ProviderConfig:
         """Look up a provider config by name. Raises KeyError if not found."""
         for p in self.providers: