docs: propose OrcaRouter as a first-class model provider

[nissrin2020ali-ux]

This ADR proposes adding OrcaRouter as a first-class model provider in QM, mirroring the way OpenRouter is wired in today.

The problem from a QM user's seat

QM's "multiplayer agent harness for work" lets each org pick its own model provider, and one of the cleanest options is a gateway: one OPENROUTER_API_KEY, one base URL, and a whole catalog of models behind it. OpenRouter is wired that way. But if you want OrcaRouter's stack — adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance on the same endpoint — there is currently no way to select it. You would have to register it as an anonymous custom base URL, which means no catalog in the picker, no admin key rotation, and no qm setup/qm doctor support. That's a worse experience than every named provider gets.

Adding orcarouter as a named provider closes that gap. A deployment sets modelProvider: "orcarouter" with an ORCAROUTER_API_KEY, and the base model, the web picker, and the admin panel all treat it exactly like OpenRouter today.

What this means

OrcaRouter is an OpenAI-compatible AI gateway built for both models and agents. Like OpenRouter, it exposes a provider/model namespace across many models — but it also combines adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance behind the same endpoint. Adding orcarouter as a first-class provider means this project's users can use that stack directly, without treating OrcaRouter as an anonymous custom base URL.

It also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.

The ADR lists the concrete touchpoints, which are exactly the seven places OpenRouter already appears: provider-endpoints.ts, pi-models.ts, model-catalog.ts, the credential store, wiring.ts/config.ts/secret-schema.ts, the admin model-providers route, and the CLI. One deviation is called out honestly: OrcaRouter is not a pi-ai built-in provider, so the pi harness registers it at runtime and the catalog parser maps OrcaRouter's OpenAI-style model list onto the existing runtime shape.

Verification

The ADR's Shape section was validated against the live OrcaRouter API:

• GET https://api.orcarouter.ai/v1/models returns { data: [...] } (200 with a valid key, 401 without)
• POST https://api.orcarouter.ai/v1/chat/completions streams a completion (200) using a provider-prefixed model id such as deepseek/deepseek-v4-flash-0731

Out of scope

No default changes, no model curation beyond a catalog pass-through, and no change to the security posture or screening proxy. If this direction is welcome, the code implementation can follow the ADR's shape.

Discord: discord.gg/YEubt8enRA · X: https://x.com/OrcaRouter

I'm an engineer on the OrcaRouter team.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}