coderouter-cli 1.8.5__py3-none-any.whl → 1.10.0__py3-none-any.whl

coderouter/config/capability_registry.py

@@ -115,6 +115,24 @@ class RegistryCapabilities(BaseModel):
             "startup check)."
         ),
     )
+    cache_control: bool | None = Field(
+        default=None,
+        description=(
+            "v1.9-B: does the upstream preserve Anthropic ``cache_control`` "
+            "markers end-to-end on the wire? When True, the v0.5-B "
+            "translation-lossy gate stays quiet and the doctor cache probe "
+            "treats the upstream as eligible for hit-rate verification. "
+            "Independent from ``providers.yaml capabilities.prompt_cache`` "
+            "(provider-level explicit opt-in); the registry value carries "
+            "model-family defaults that match real-world wire support — "
+            "for Anthropic native (``claude-sonnet-*`` / ``claude-opus-*``) "
+            "and LM Studio's ``/v1/messages`` for ``qwen3.5-*`` / "
+            "``qwen3.6-*`` (verified live in v1.8.4, "
+            "``cache_read_input_tokens: 280`` observed). "
+            "``None`` (default) = no opinion → the v0.5-B gate falls back "
+            "to ``provider.kind == 'anthropic'`` for the answer."
+        ),
+    )
 
 
 class CapabilityRule(BaseModel):
@@ -182,6 +200,7 @@ class ResolvedCapabilities:
     tools: bool | None = None
     max_context_tokens: int | None = None
     claude_code_suitability: Literal["ok", "degraded"] | None = None
+    cache_control: bool | None = None
 
 
 # ---------------------------------------------------------------------------
@@ -233,12 +252,14 @@ class CapabilityRegistry:
         resolved_tools: bool | None = None
         resolved_max_ctx: int | None = None
         resolved_suitability: Literal["ok", "degraded"] | None = None
+        resolved_cache_control: bool | None = None
 
         thinking_locked = False
         reasoning_locked = False
         tools_locked = False
         max_ctx_locked = False
         suitability_locked = False
+        cache_control_locked = False
 
         for rule in self._rules:
             if not rule.kind_matches(kind):
@@ -261,12 +282,16 @@ class CapabilityRegistry:
             if not suitability_locked and caps.claude_code_suitability is not None:
                 resolved_suitability = caps.claude_code_suitability
                 suitability_locked = True
+            if not cache_control_locked and caps.cache_control is not None:
+                resolved_cache_control = caps.cache_control
+                cache_control_locked = True
             if (
                 thinking_locked
                 and reasoning_locked
                 and tools_locked
                 and max_ctx_locked
                 and suitability_locked
+                and cache_control_locked
             ):
                 break
 
@@ -276,6 +301,7 @@ class CapabilityRegistry:
             tools=resolved_tools,
             max_context_tokens=resolved_max_ctx,
             claude_code_suitability=resolved_suitability,
+            cache_control=resolved_cache_control,
         )
 
     # ------------------------------------------------------------------

coderouter/config/schemas.py

@@ -49,6 +49,108 @@ class Capabilities(BaseModel):
     openai_compatible: bool = True
 
 
+class CostConfig(BaseModel):
+    """v1.9-D: per-provider unit pricing for cost aggregation.
+
+    All fields are optional. When :attr:`ProviderConfig.cost` is unset,
+    the provider contributes zero to the cost dashboard but still
+    appears in token-count totals — same shape as a free local model.
+
+    Pricing model
+    -------------
+
+    Anthropic's prompt-cache pricing (verified 2026-04 docs.anthropic.com):
+
+      * Normal input  : 1.0x ``input_tokens_per_million``
+      * Normal output : 1.0x ``output_tokens_per_million``
+      * Cache read    : ``cache_read_discount`` x normal input
+      * Cache creation: ``cache_creation_premium`` x normal input
+
+    The 4-class breakdown (cache_hit / cache_creation / no_cache /
+    unknown) recorded by v1.9-A's ``cache-observed`` log lets the
+    cost aggregator apply the right multiplier per token, and the
+    "savings" figure in the dashboard is computed as
+    ``cache_read_input_tokens x normal x (1 - cache_read_discount)``
+    — i.e. what the operator *would have* paid without prompt
+    caching.
+
+    LiteLLM's cost tracker (verified 2026-04) does not implement
+    cache-aware breakdown; it bills ``cache_read_input_tokens`` at
+    full input rate, overstating spend on cache-heavy workloads. The
+    CodeRouter dashboard's selling point is correctness here.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    input_tokens_per_million: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "USD per million input tokens at normal (uncached) rate. "
+            "Anthropic Sonnet 4.x is around 3.00, Opus 4.x around 15.00 "
+            "(check the upstream's pricing page — values change)."
+        ),
+    )
+    output_tokens_per_million: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "USD per million output tokens. Output is invariably the "
+            "expensive side of the meter — for coding workloads with "
+            "large completions this dominates the bill."
+        ),
+    )
+    cache_read_discount: float = Field(
+        default=0.10,
+        ge=0.0,
+        le=1.0,
+        description=(
+            "Multiplier applied to ``input_tokens_per_million`` for "
+            "tokens served from prompt cache. Anthropic's 2026-04 "
+            "pricing is 0.10 (i.e. cache reads are billed at 10% of "
+            "normal input rate). LM Studio /v1/messages locally "
+            "honors the cache_read field but local backends usually "
+            "have ``input_tokens_per_million`` of 0.0, so this field "
+            "is moot there."
+        ),
+    )
+    cache_creation_premium: float = Field(
+        default=1.25,
+        ge=0.0,
+        description=(
+            "Multiplier applied to ``input_tokens_per_million`` for "
+            "tokens *written* to the prompt cache on the first hit. "
+            "Anthropic's 2026-04 pricing is 1.25 (cache writes cost "
+            "25% more than normal input on the writeback call; "
+            "subsequent reads then cost ``cache_read_discount`` x, "
+            "amortizing the writeback). Above 1.0 means premium, "
+            "1.0 = no premium, below 1.0 = discount on creation "
+            "(unusual but theoretically supported by the schema)."
+        ),
+    )
+    monthly_budget_usd: float | None = Field(
+        default=None,
+        ge=0.0,
+        description=(
+            "v1.10 (LiteLLM 由来 / v1.9-D の累積版): per-provider "
+            "monthly USD spend cap. When set, the engine's chain "
+            "resolver skips this provider and emits "
+            "``skip-budget-exceeded`` once the running per-provider "
+            "total for the current calendar month (UTC) reaches or "
+            "exceeds this value. Unset (None) = no cap (default). "
+            "\n\n"
+            "Reset semantics: in-memory only — running totals zero "
+            "out on process restart and on UTC calendar-month "
+            "rollover. Operators who need durable budget state "
+            "across restarts should pair this with external "
+            "monitoring on the cost dashboard's ``cost_total_usd`` "
+            "panel; persistent budget state is out of scope for "
+            "v1.10 (no on-disk store, no Redis, etc., per the "
+            "5-deps invariant in plan.md §5.4)."
+        ),
+    )
+
+
 class ProviderConfig(BaseModel):
     """A single provider entry from providers.yaml.
 
@@ -116,6 +218,19 @@ class ProviderConfig(BaseModel):
 
     capabilities: Capabilities = Field(default_factory=Capabilities)
 
+    cost: CostConfig | None = Field(
+        default=None,
+        description=(
+            "v1.9-D: per-provider unit pricing for cost aggregation. "
+            "Unset = provider contributes zero to the cost dashboard "
+            "(typical for local models). Set on paid endpoints to "
+            "feed the ``/dashboard`` cost panel and the "
+            "``coderouter stats --cost`` TUI summary. Cache-aware "
+            "calculation differentiates cache_read (90% discount on "
+            "Anthropic) from normal input — see :class:`CostConfig`."
+        ),
+    )
+
     @model_validator(mode="after")
     def _check_output_filters_known(self) -> ProviderConfig:
         """v1.0-A: fail at config-load on a typo'd filter name.
@@ -173,6 +288,162 @@ class FallbackChain(BaseModel):
             "for this profile."
         ),
     )
+    # v1.9-E (L3): tool-loop detection guard.
+    #
+    # Long-running agent loops can fall into "tool stuck" states where
+    # the assistant repeatedly calls the same tool with identical args
+    # because it can't make progress. The guard inspects the assistant
+    # tool_use history in the inbound request and, when the same call
+    # repeats above the threshold, takes the configured action.
+    #
+    # Three actions trade off intervention against UX disruption:
+    #   * ``warn``   — emit a structured ``tool-loop-detected`` log only.
+    #                  Diagnostic; default for v1.9-E.
+    #   * ``inject`` — append a system message reminder ("you appear to
+    #                  be looping, try a different approach") so the
+    #                  next assistant turn has a chance to course-correct.
+    #   * ``break``  — short-circuit the request with an error response.
+    #                  Use when downstream cost / context exhaustion is
+    #                  worse than telling the agent to stop.
+    tool_loop_window: int = Field(
+        default=5,
+        ge=2,
+        le=50,
+        description=(
+            "v1.9-E (L3): how many of the most recent assistant tool_use "
+            "blocks to inspect for a loop. Default 5 covers the typical "
+            "Claude Code agent step depth without false-positiving on "
+            "legitimate same-tool repetition (e.g. iterating Read on "
+            "different files)."
+        ),
+    )
+    tool_loop_threshold: int = Field(
+        default=3,
+        ge=2,
+        le=50,
+        description=(
+            "v1.9-E (L3): how many *consecutive identical* tool calls "
+            "(same name + same args) trigger a loop verdict. Default 3 "
+            "catches the most common stuck patterns (Read same file 3x, "
+            "Bash same command 3x) while leaving headroom for "
+            "intentional repetition with intermediate observations."
+        ),
+    )
+    tool_loop_action: Literal["warn", "inject", "break"] = Field(
+        default="warn",
+        description=(
+            "v1.9-E (L3): action when a loop is detected. ``warn`` (default) "
+            "emits a log line only; ``inject`` adds a ``you-are-looping`` "
+            "system message reminder to the request; ``break`` returns an "
+            "error response. See FallbackChain comment for trade-offs."
+        ),
+    )
+    # v1.9-E phase 2 (L2): memory-pressure detection + cooldown.
+    #
+    # Local backends (Ollama / LM Studio / llama.cpp) report VRAM
+    # exhaustion via 5xx responses with bodies like "out of memory" /
+    # "CUDA out of memory" / "insufficient memory". When the chain
+    # encounters one of these, marking the provider as "pressured"
+    # for a cooldown window prevents the engine from re-hammering the
+    # same exhausted backend on the very next request — the chain
+    # falls through to the next provider, which is typically a
+    # lighter-weight model or a remote fallback that has the headroom.
+    #
+    # Three actions trade off intervention against operator preference:
+    #   * ``off``   — no detection / no logging / no skip. Backward-compat default.
+    #   * ``warn``  — emit ``memory-pressure-detected`` log when an OOM
+    #                 error is observed; do not skip on subsequent calls.
+    #   * ``skip``  — ``warn`` + put the provider in a cooldown window;
+    #                 subsequent chain resolves filter it out and emit
+    #                 ``skip-memory-pressure`` until the cooldown expires.
+    memory_pressure_action: Literal["off", "warn", "skip"] = Field(
+        default="warn",
+        description=(
+            "v1.9-E (L2 phase 2): action on observed backend OOM "
+            "(provider failure with an out-of-memory error body). "
+            "``warn`` (default) logs only — diagnostic, no chain "
+            "behavior change. ``skip`` enters a cooldown window so "
+            "the next request's chain resolver filters the pressured "
+            "provider out and falls through to the next entry. "
+            "``off`` disables the detector entirely (zero "
+            "observation overhead, identical to v1.9.x behavior)."
+        ),
+    )
+    memory_pressure_cooldown_s: int = Field(
+        default=120,
+        ge=10,
+        le=3600,
+        description=(
+            "v1.9-E (L2 phase 2): cooldown window in seconds applied "
+            "after an OOM detection when ``memory_pressure_action`` "
+            "is ``skip``. Default 120 s gives the local backend "
+            "enough time to release model state from VRAM before the "
+            "engine re-attempts. Capped at 3600 s (1 hour) — anything "
+            "longer is better expressed as marking the provider "
+            "``paid: true`` and bouncing the process."
+        ),
+    )
+    # v1.9-E phase 2 (L5): backend health monitoring (passive).
+    #
+    # A consecutive-failure state machine per provider:
+    #   * HEALTHY   — no recent failures (initial state).
+    #   * DEGRADED  — ``backend_health_threshold`` consecutive failures
+    #                 observed; the provider has lost its "fresh" status
+    #                 but is still attempted in chain order.
+    #   * UNHEALTHY — ``2 x backend_health_threshold`` consecutive
+    #                 failures; depending on the action, the provider
+    #                 is either demoted to chain end or skipped entirely.
+    # A single success on ``provider-ok`` resets the counter and the
+    # state to HEALTHY immediately — no rolling window, no debounce.
+    # 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"] = Field(
+        default="warn",
+        description=(
+            "v1.9-E (L5 phase 2): action when a provider transitions "
+            "to UNHEALTHY (consecutive failures crossed the threshold). "
+            "``warn`` (default) emits a state-change log line only — "
+            "diagnostic, no chain reorder. ``demote`` additionally "
+            "moves the UNHEALTHY provider to the back of the chain "
+            "for the next ``_resolve_chain`` (similar to v1.9-C "
+            "adaptive demotion but state-machine-based, not "
+            "rolling-window-based). ``off`` disables the monitor "
+            "entirely (zero observation overhead, identical to "
+            "v1.9.x behavior)."
+        ),
+    )
+    backend_health_threshold: int = Field(
+        default=3,
+        ge=2,
+        le=20,
+        description=(
+            "v1.9-E (L5 phase 2): consecutive-failure count that "
+            "triggers the HEALTHY → DEGRADED transition. The "
+            "DEGRADED → UNHEALTHY transition fires at ``2x`` this "
+            "value. Default 3 catches "
+            "Ollama / LM Studio crashes (which produce a deterministic "
+            "5xx pattern on every retry) without flapping on transient "
+            "blips that the v1.9-C adaptive adjuster already handles."
+        ),
+    )
+    adaptive: bool = Field(
+        default=False,
+        description=(
+            "v1.9-C: enable health-based dynamic chain reordering for "
+            "this profile. When True, the engine consults its "
+            "AdaptiveAdjuster and may demote providers whose rolling-"
+            "window median latency or error rate exceeds the configured "
+            "thresholds (1.5x global median / 10% errors). Demotions are "
+            "debounced (30 s minimum between rank changes per provider) "
+            "so a transient blip cannot oscillate the chain. When False "
+            "(default), the static ``providers`` order is honored "
+            "verbatim — no observation overhead. Orthogonal to L5 "
+            "(binary HEALTHY/UNHEALTHY backend swap, planned for "
+            "v1.9-E phase 3): C handles the gradient case during normal "
+            "operation, L5 handles hard crashes."
+        ),
+    )
 
 
 # ---------------------------------------------------------------------------
@@ -197,6 +468,36 @@ class RuleMatcher(BaseModel):
     - ``content_contains: "foo"`` — substring match (case-sensitive).
     - ``content_regex: r"..."`` — Python ``re.search``; compiled at
       model-construction time so typos fail startup.
+
+    Variants ([Unreleased] / per-model auto-routing, free-claude-code 由来):
+
+    - ``model_pattern: r"claude-3-5-haiku.*"`` — Python ``re.fullmatch``
+      against the request body's ``model`` field. Lets clients route on
+      the model identifier the agent (Claude Code / Cursor) sent
+      (Opus / Sonnet / Haiku → different profiles) without needing an
+      explicit ``profile`` field on the wire. Compiled at load like
+      ``content_regex``. ``fullmatch`` semantics (vs ``search`` for
+      ``content_regex``) because model identifiers are structured tokens
+      — users typically describe the whole identifier with a wildcard
+      tail, not an arbitrary substring.
+
+    Variants ([Unreleased] / longContext auto-switch, claude-code-router
+    由来):
+
+    - ``content_token_count_min: 32000`` — char-count ÷ 4 heuristic
+      across **all** messages in the request body (not just the
+      latest user message — this matcher describes the request's
+      overall size). When the estimated token count is ``>=`` the
+      threshold, route to a long-context profile (typically pointing
+      at Gemini Flash 1M ctx, Haiku 200K, etc.). Distinct from the
+      other content matchers which operate on the latest user
+      message only — context-window pressure is a request-shape
+      property, not a per-turn property. The estimator deliberately
+      avoids tiktoken / SentencePiece (forbidden by the 5-deps
+      invariant in plan.md §5.4); operators with non-English-heavy
+      workloads can compensate by tuning the threshold, since the
+      char/4 heuristic is conservative for CJK and looser for
+      English code.
     """
 
     model_config = ConfigDict(extra="forbid")
@@ -205,12 +506,16 @@ class RuleMatcher(BaseModel):
     code_fence_ratio_min: float | None = Field(default=None, ge=0.0, le=1.0)
     content_contains: str | None = None
     content_regex: str | None = None
+    model_pattern: str | None = None
+    content_token_count_min: int | None = Field(default=None, ge=1)
 
     _MATCHER_FIELDS: tuple[str, ...] = (
         "has_image",
         "code_fence_ratio_min",
         "content_contains",
         "content_regex",
+        "model_pattern",
+        "content_token_count_min",
     )
 
     @model_validator(mode="after")
@@ -227,7 +532,9 @@ class RuleMatcher(BaseModel):
 
     @model_validator(mode="after")
     def _compile_regex_eagerly(self) -> Self:
-        """Compile ``content_regex`` at load so bad patterns fail startup."""
+        """Compile ``content_regex`` / ``model_pattern`` at load so bad
+        patterns fail startup rather than at first request.
+        """
         if self.content_regex is not None:
             try:
                 re.compile(self.content_regex)
@@ -235,6 +542,13 @@ class RuleMatcher(BaseModel):
                 raise ValueError(
                     f"Invalid regex for content_regex {self.content_regex!r}: {exc}"
                 ) from exc
+        if self.model_pattern is not None:
+            try:
+                re.compile(self.model_pattern)
+            except re.error as exc:
+                raise ValueError(
+                    f"Invalid regex for model_pattern {self.model_pattern!r}: {exc}"
+                ) from exc
         return self
 
 

coderouter/cost.py

@@ -0,0 +1,154 @@
+"""Cost calculation utilities (v1.9-D Cost-aware Dashboard).
+
+Pure functions for translating per-request token counts into USD
+spend, accounting for Anthropic's prompt-cache pricing model
+(``cache_read`` at 10% of normal input, ``cache_creation`` at 125%).
+
+Where this fits
+===============
+
+The engine's ``_emit_cache_observed`` site (v1.9-A) calls
+:func:`compute_cost_for_attempt` to enrich the ``cache-observed``
+log line with ``cost_usd`` + ``cost_savings_usd`` fields. The
+MetricsCollector then aggregates per-provider totals over the
+process lifetime, and the dashboard / ``coderouter stats --cost``
+TUI render those aggregates.
+
+Why a separate module
+=====================
+
+Pricing math is small, pure, and shared by:
+
+  * the engine's per-request cost calc
+  * the collector's snapshot rendering (recomputes a "what-if no
+    cache" total for the savings panel)
+  * the future ``coderouter stats --cost`` CLI
+
+Keeping it as a leaf module with no engine / collector imports
+prevents circular dependencies and makes the pricing semantics
+trivially testable in isolation.
+
+Anthropic pricing reference (verified 2026-04)
+==============================================
+
+For Sonnet / Opus / Haiku 4.x:
+
+  * Normal input  : ``input_tokens_per_million``         x 1.0
+  * Cache read    : ``input_tokens_per_million``         x 0.10
+  * Cache creation: ``input_tokens_per_million``         x 1.25
+  * Normal output : ``output_tokens_per_million``        x 1.0
+
+Tokens reported by the upstream:
+
+  * ``input_tokens`` — "fresh" input (cache reads / writes are
+    excluded from this count and reported via the cache fields).
+  * ``cache_read_input_tokens`` — served from prompt cache.
+  * ``cache_creation_input_tokens`` — written to prompt cache.
+  * ``output_tokens`` — completion.
+
+So a single response's billable cost is the sum of the four buckets
+billed at their respective rates. The "savings" figure is the
+counterfactual: what the operator *would have* paid without prompt
+caching, so it focuses on the cache_read tokens (those are the
+ones that got the 90% discount). cache_creation is a premium, not
+a savings, so it doesn't enter the savings figure even though it's
+in the cost calc.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from coderouter.config.schemas import CostConfig
+
+
+@dataclass(frozen=True)
+class CostBreakdown:
+    """Per-attempt cost components, all in USD.
+
+    All fields default to 0.0 so a free / unconfigured provider
+    yields a zero breakdown without callers having to special-case
+    None.
+
+    Fields
+        total_usd: full cost charged for this attempt (sum of the
+            four token buckets at their respective rates).
+        savings_usd: hypothetical "no-cache" delta — what the
+            operator *would have* paid for ``cache_read_input_tokens``
+            at full input rate, minus what they actually paid at
+            ``cache_read_discount`` rate. Always >= 0.
+        input_usd / output_usd / cache_read_usd / cache_creation_usd:
+            per-bucket breakdown for the dashboard's stacked bar
+            chart. ``input_usd`` is "fresh input only" (does not
+            include cache buckets); cache_read_usd / cache_creation_usd
+            are the post-discount / post-premium values.
+    """
+
+    total_usd: float = 0.0
+    savings_usd: float = 0.0
+    input_usd: float = 0.0
+    output_usd: float = 0.0
+    cache_read_usd: float = 0.0
+    cache_creation_usd: float = 0.0
+
+
+_PER_MILLION: float = 1_000_000.0
+
+
+def compute_cost_for_attempt(
+    cost_config: CostConfig | None,
+    *,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read_input_tokens: int,
+    cache_creation_input_tokens: int,
+) -> CostBreakdown:
+    """Translate per-attempt token counts into a USD :class:`CostBreakdown`.
+
+    Returns a zero-filled breakdown when:
+      * ``cost_config`` is ``None`` (provider has no pricing
+        declared — typical for local models)
+      * Both ``input_tokens_per_million`` and ``output_tokens_per_million``
+        are unset (a partial declaration is permitted but the
+        resulting cost is whatever the set fields can compute)
+
+    Negative or zero token counts are accepted and contribute zero
+    cost — the engine never emits negatives, but this defensive
+    handling keeps a malformed log line from corrupting the
+    aggregate counters in the collector.
+    """
+    if cost_config is None:
+        return CostBreakdown()
+
+    input_rate = (cost_config.input_tokens_per_million or 0.0) / _PER_MILLION
+    output_rate = (cost_config.output_tokens_per_million or 0.0) / _PER_MILLION
+
+    safe_input = max(input_tokens, 0)
+    safe_output = max(output_tokens, 0)
+    safe_read = max(cache_read_input_tokens, 0)
+    safe_create = max(cache_creation_input_tokens, 0)
+
+    input_usd = safe_input * input_rate
+    output_usd = safe_output * output_rate
+    cache_read_usd = safe_read * input_rate * cost_config.cache_read_discount
+    cache_creation_usd = safe_create * input_rate * cost_config.cache_creation_premium
+
+    total_usd = input_usd + output_usd + cache_read_usd + cache_creation_usd
+
+    # Savings = what the operator would have paid at full input rate
+    # for the cache_read tokens, minus what they actually paid at
+    # the discounted rate. cache_creation is a *premium* (not a
+    # savings) so it doesn't enter the savings figure — including
+    # it would let a cache miss show up as "negative savings" which
+    # is semantically wrong and would confuse the dashboard.
+    full_rate_for_cache_read = safe_read * input_rate
+    savings_usd = full_rate_for_cache_read - cache_read_usd
+
+    return CostBreakdown(
+        total_usd=total_usd,
+        savings_usd=max(savings_usd, 0.0),
+        input_usd=input_usd,
+        output_usd=output_usd,
+        cache_read_usd=cache_read_usd,
+        cache_creation_usd=cache_creation_usd,
+    )

coderouter/data/model-capabilities.yaml

@@ -90,6 +90,61 @@ rules:
     capabilities:
       thinking: true
 
+  # ------------------------------------------------------------------
+  # Anthropic prompt caching — `cache_control` body field support (v1.9-B).
+  #
+  # Declares which (kind, model) pairs preserve the ``cache_control``
+  # marker end-to-end on the wire. The capability gate
+  # (``provider_supports_cache_control`` in coderouter/routing/capability.py)
+  # consults these declarations to decide whether to emit a
+  # ``capability-degraded reason=translation-lossy`` log when handing
+  # a cache_control-bearing request to the provider.
+  #
+  # Verification basis:
+  #   * api.anthropic.com (kind=anthropic, claude-* models):
+  #     verified live 2026-04-20 — 1321 tokens written on call 1,
+  #     1321 read on call 2. Native Anthropic shape passes through
+  #     verbatim, no translation hop loses the marker.
+  #   * LM Studio /v1/messages (kind=anthropic, qwen3.5-* / qwen3.6-*):
+  #     verified live 2026-04-27 in v1.8.4 — `cache_read_input_tokens: 280`
+  #     observed end-to-end through CodeRouter. LM Studio 0.4.12+ honors
+  #     the marker on its Anthropic-compatible endpoint.
+  #
+  # All entries are kind=anthropic. openai_compat upstreams have no wire
+  # equivalent for cache_control (the OpenAI Chat Completions schema does
+  # not carry it), so they intentionally stay undeclared — the gate's
+  # fallback maps undeclared + kind=openai_compat to False.
+  # ------------------------------------------------------------------
+
+  - match: "claude-opus-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "claude-sonnet-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "claude-haiku-4-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  # LM Studio /v1/messages exposes Qwen3.5 / Qwen3.6 with Anthropic-shaped
+  # responses including ``cache_read_input_tokens``. The provider declares
+  # ``kind: anthropic`` even though the underlying model is open-weights;
+  # the registry rule keys off the model name pattern.
+  - match: "qwen3.5-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
+  - match: "qwen3.6-*"
+    kind: anthropic
+    capabilities:
+      cache_control: true
+
   # ------------------------------------------------------------------
   # Claude Code suitability — agentic harness compatibility hint (v1.7-B).
   #