Model provider — conformance#

Error taxonomy#

A plugin MUST classify every failure into one of the following, and MUST NOT collapse them into a single generic error — the kernel's routing/fallback/retry behavior depends on telling these apart. (An undifferentiated "API error" makes it impossible to tell a context-overflow from a transient overload without reading raw transcripts — this requirement exists to prevent exactly that ambiguity.)

ModelError MUST include: category (above), message (human-readable), retryable (bool), and SHOULD include retry_after_seconds and the raw vendor-provided error code/body for debugging.

On the wire, each category maps to a grpc/codes.Code: context_length_exceeded → ResourceExhausted, rate_limited → ResourceExhausted with structured detail, overloaded → Unavailable, auth_error → Unauthenticated, invalid_request → InvalidArgument, content_filtered → FailedPrecondition, cancellation → Canceled — never an application error, unknown/unmapped → Internal, never Unknown.

Required vs. optional support — summary matrix#

Open questions#

• Whether supports_parallel_tool_calls needs a per-request override (some vendors may allow disabling parallel calls per-call even when generally supported).
• PricingTier assumes one cache rate per model, and real vendors have several. The tier carries a single cache_write_per_mtok/cache_read_per_mtok pair, but a model can bill cached tokens at more than one rate depending on which caching mechanism serviced the request: Anthropic publishes distinct 5-minute and 1-hour cache-write rates (the 1-hour rate is 2× input against 1.25× for 5-minute), and a Gemini model running both caching axes discounts implicit hits ~75% and explicit hits ~90%. Two consequences follow, and both are currently unresolved rather than solved:
• There is no way to select a TTL. CacheBreakpoint carries no TTL field, so an adapter can only ever incur its vendor's default, and internal/anthropic/catalog correspondingly quotes only the 5-minute rate — quoting the 1-hour rate would overstate every cached turn by 60%.
• There is no way to price the non-default path even if one were selectable.

This deliberately did not become a provider_options knob: the kernel computes and persists cost_usd from Pricing, so a TTL that changed the rate while riding in a pass-through field would silently produce wrong ledger rows forever — exactly the failure the repository's replay-determinism rule (.claude/rules/determinism.md) treats as a correctness bug. Fixing it properly means making the cache rate a function of the mechanism used, which is a Pricing redesign, not a field addition. - Whether a model needs to declare that it rejects GenerationParams.temperature. Several vendors' reasoning models reject non-default sampling parameters outright (Anthropic's effort-ladder models return a 400; other vendors' reasoning models ignore the value silently). There is no field for this, so an adapter facing such a model can only drop the operator's temperature on the floor — which is the right behavior, but it happens invisibly, and the kernel cannot tell a dropped parameter from an honored one. Today adapters infer it from the thinking shape, which is a proxy that will be wrong for the first model that has an effort ladder and accepts temperature. The same question applies to top_p and any other sampling parameter added later, so the fix is probably a general "declared sampling parameters" list rather than a per-parameter bool. - Retry/backoff policy specifics (exponential backoff parameters) — likely belongs in the kernel's routing logic rather than this protocol, but needs to be decided somewhere; see configuration/blocks-reference.md's settings{} retry defaults for the current kernel-side values. - Whether content_filtered needs sub-categories (input filtered vs. output filtered) — there isn't enough vendor detail yet to decide. - Pricing.currency is declared as a string but v1 only ever acts on "USD" — no conversion mechanism, no mixed-currency cost aggregation across providers with different currencies. Fine while vendors generally price in USD; would need real design work the moment that stops being true. - Whether a plugin author republishing overlapping Pricing.tiers should be a hard capability-load-time rejection (as currently specified) or a softer warning-plus-last-write-wins — the former was chosen for consistency with this project's general "ambiguity is an error" posture, but hasn't been stress-tested against how often a plugin author might get tier boundaries slightly wrong.