(MOT-4414) fix(llm-router): make failures actionable

[ytallo]

What

• Add a stable RouterFailure envelope with router/* codes, retryability, provider/model context, and attempt count.
• Add opt-in failure_mode: "structured" semantics so pre-stream failures produce one terminal error frame and the same unsuccessful direct response.
• Sanitize provider failures before they reach responses, durable diagnostics, or downstream consumers.
• Add token-gated provider diagnostics for credential, catalog, freshness, and recovery state.
• Surface loading, missing worker, missing credential, discovery error, empty catalog, and historical states in the router configuration UI.
• Validate timeout, retry, routing, URL, provider-reference, and token-limit errors inline before save.
• Preserve structured failures in Harness and context-manager, including bounded transient recovery.

Why

Router failures were split across thrown errors, compatibility strings, and terminal frames. Callers had to infer whether a failure was retryable, operators could not distinguish setup states, and raw provider response bodies could leak into public error paths. This change gives each layer one explicit contract while preserving the legacy throw mode for callers that have not opted in.

New error contract

With failure_mode: "structured", a model that cannot be routed returns one terminal error frame and the same failure in the direct response:

{
  "ok": false,
  "provider": "",
  "model": "gpt-5",
  "stop_reason": "error",
  "error": {
    "code": "router/no_provider_for_model",
    "message": "no provider registered for model gpt-5"
  },
  "failure": {
    "code": "router/no_provider_for_model",
    "kind": "permanent",
    "message": "no provider registered for model gpt-5",
    "retryable": false,
    "model": "gpt-5",
    "attempts": 0
  }
}

Provider-facing messages are bounded and actionable while raw response bodies and credential material remain in provider-local logs:

Failure	Public message	Retryable
Expired credentials	openai authentication failed (HTTP 401); refresh credentials	No
Rate limit	openai rate limit reached (HTTP 429); retry later	Yes
Temporary outage	openai is temporarily unavailable (HTTP 503)	Yes
Transport failure	openai request failed before a response; inspect provider logs	Yes
Invalid provider response	openai returned an invalid response; inspect provider logs	No
Model discovery	openai model discovery failed; inspect provider logs	Depends on classification

Existing callers retain the legacy { code, message } throw behavior until they opt into structured failures.

Verification

• cargo clippy --all-targets --all-features -- -D warnings in llm-router and harness
• cargo test --all-features in llm-router and harness
• cargo test --all-features across all 11 provider workers
• Schema goldens for the router, Harness, and all provider functions
• npm --prefix llm-router/ui test
• npm --prefix llm-router/ui run build
• cargo check --manifest-path context-manager/Cargo.toml
• npm --prefix console/web run typecheck
• cargo fmt --all -- --check for every touched Rust worker
• git diff --check

Fixes MOT-4414

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
workers	Ready	Preview	Aug 13, 2026 11:29am
workers-tech-spec	Ready	Preview	Aug 13, 2026 11:29am

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 933e40ff-499e-4e99-bfb0-45661e41b6f8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

skill-check — worker

0 verified, 58 skipped (no docs/).

Layer	Result
structure	✓
vale	✓
ai	✓
render	✓

Four for four. Nicely done.