feat(provider): add OrcaRouter as a named OpenAI-compatible provider

[Marc-oss-hub]

PR Type

• ✨ Feature — New capability or behavior change (requires Feature Doc)

Related Issue

No issue number — this is a purely additive provider registration. Happy to open an issue / feature doc for an F-number if the maintainers prefer tracked features for provider additions.

Feature Doc (Feature PRs only)

Not requested. This change is a thin, purely additive provider registration that mirrors the already-shipped OpenRouter wiring in the same files (env-map.ts, invoke-single-cat.ts, account-resolver.ts, HubCatEditor.tsx, hub-cat-editor.sections.tsx). No new capability or behavior change, and no roadmap impact — so no F-number is required. If the maintainers would rather track it, I'm glad to open an issue and implement against the resulting Feature Doc.

What

Adds OrcaRouter as a named provider across the API and web surfaces, exactly parallel to the existing OpenRouter entry. OrcaRouter is an OpenAI-compatible model routing gateway (base URL https://api.orcarouter.ai, API rooted at /v1) exposing a broad model catalog under namespaced IDs (e.g. openai/gpt-5.5, anthropic/claude-sonnet-4.6, z-ai/glm-5.2). It also ships gateway-level security controls for AI agents.

• packages/api/src/domains/cats/services/agents/providers/env-map.ts — orcarouter added to BUILTIN_ENV_MAPS, so an opencode cat bound to an OrcaRouter API-key profile gets ORCAROUTER_API_KEY injected into its environment.
• packages/api/src/domains/cats/services/agents/invocation/invoke-single-cat.ts — orcarouter: 'openai' added to protocolForProvider (same protocol mapping as OpenRouter).
• packages/api/src/config/account-resolver.ts — orcarouter added to KNOWN_CANONICAL_PROVIDERS so account resolution treats it as a first-party provider name.
• packages/web/src/components/hub-cat-editor.sections.tsx + packages/web/src/components/HubCatEditor.tsx — orcarouter added to the known OpenAI-compatible provider lists in the Hub account editor.
• Tests — env-map.test.js (provider-name resolution), invoke-single-cat.test.js (env-var injection for opencode members bound to orcarouter API-key profiles), opencode-config-template.test.js (protocol mapping), hub-cat-editor-oc-providers.test.ts (known-provider list).
• Docs — README.md / README.ja-JP.md / README.zh-CN.md and SETUP.md / SETUP.zh-CN.md list OrcaRouter in the third-party provider guides alongside OpenRouter.

Why

The Hub account editor already treats OpenAI-compatible aggregators as named first-class providers (OpenRouter is wired this way). OrcaRouter is the same shape, and routing it through the generic OpenAI-compatible path would silently skip the dedicated ORCAROUTER_API_KEY env surface, the named-provider UI, and the protocol mapping every other named gateway gets. Keeping it named gives users the same one-key setup they already have for OpenRouter:

export ORCAROUTER_API_KEY=sk-orca-...

then pick a model such as openai/gpt-5.5 or anthropic/claude-opus-4.8 from the catalog at https://www.orcarouter.ai/models.

Tradeoff

• Alternatives considered: (1) relying solely on the existing OpenAI-compatible "Custom endpoint" escape hatch — rejected, because that drops the named ORCAROUTER_API_KEY env injection, the provider picker entry, and protocol mapping consistency; (2) a shared generic gateway abstraction — rejected as a larger architectural change than warranted; mirroring the OpenRouter entry is the smallest change that keeps the model picker, docs, and config reference consistent.
• Behavioral risk: none — the change is purely additive. Providers already registered are untouched, and ORCAROUTER_API_KEY resolution only activates when a user explicitly selects OrcaRouter. Existing user flows are unchanged.

Test Evidence

# API package — the three touched test files (full file runs):
#   env-map.test.js · opencode-config-template.test.js · invoke-single-cat.test.js
tests 218 | pass 216 | fail 2
#   the 2 failures are pre-existing Windows path-separator assertions
#   (invoke-single-cat.test.js:7166 mcp split-entrypoint check,
#    opencode-config-template.test.js:773 oc-config path regex);
#   verified identical on clean main — unrelated to this change.

# Web package — known OpenAI-compatible providers list:
pnpm exec vitest run src/components/__tests__/hub-cat-editor-oc-providers.test.ts
#   Test Files  1 passed (1)
#   Tests       11 passed (11)

pnpm lint
#   packages/finance lint: Done
#   packages/shared lint: Done
#   packages/mcp-server lint: Done
#   packages/web lint: Done     (pre-existing hardcoded-color warnings only)
#   packages/api lint: Done     (exit 0)

pnpm check
#   Biome: 0 errors on changed files.
#   One test in the check chain (scripts/biome-review-worktrees-ignore.test.mjs)
#   fails on this Windows host; verified identical on clean main (spawn of the
#   Biome binary inside a temp fixture), unrelated to this change.

# L3 live test (real OrcaRouter key, through the built env-map + OpenAI SDK):
resolveEnvMap('opencode', 'orcarouter') => { ORCAROUTER_API_KEY: 'sk-orca-live' }
POST https://api.orcarouter.ai/v1/chat/completions (model openai/gpt-5.4-mini)
  => HTTP 200, content 'ORCA-OK'

---

I'm an engineer on the OrcaRouter team.

[zts212653]

Thanks for the contribution, and for disclosing your affiliation with the OrcaRouter team. The integration may be useful, but I’m pausing code review at the direction gate for now.

This is a feature change and there is no accepted issue linked to the PR. It is also broader than a purely additive/no-behavior-change registration: it changes provider canonicalization, credential environment injection, protocol selection, Hub suggestions, and the public provider/support documentation.

Please open a focused issue first (or link an already accepted one) that covers:

• the user problem that is not already served by a custom OpenAI-compatible account with apiKey + baseUrl;
• why OrcaRouter should be a named built-in provider, including the intended ongoing support boundary and stable endpoint/model semantics;
• whether the provider metadata should live in one canonical registry instead of adding the same name to several hard-coded lists;
• primary references for the public product/security claims, with the OrcaRouter affiliation kept explicit;
• verification of the actual named-provider path: provider: "orcarouter", ORCAROUTER_API_KEY injection, protocol mapping, and no stale OPENROUTER_API_KEY expectation. The current test summary is not green, so any claimed pre-existing failures also need reproducible links/evidence.

Once that issue is triaged and accepted, we can review the exact PR HEAD on its merits. Until then the maintainer verdict is NEEDS-DISCUSSION: the design conversation is welcome, while implementation/merge is on hold. We are not taking over your branch.

— 小太阳·砚砚 / GPT-5.6 Sol 🐾

[zts212653]

Thanks again for the contribution and for being transparent about your affiliation with the OrcaRouter team.

We have now completed the maintainer direction review. We are going to decline and close this PR without merging it.

The reason is primarily product and support scope, rather than the amount of implementation work. Clowder AI already supports arbitrary OpenAI-compatible services through a custom API-key account with apiKey + baseUrl, together with user-configurable environment templates. Making an individual commercial gateway a named built-in provider would additionally create an ongoing public support and documentation commitment. We do not want to grow that surface one gateway at a time without a distinct user capability that the generic path cannot provide.

The current proposal also repeats provider identity across several hard-coded registries. If we expand built-in provider metadata in the future, we would first want a canonical, data-driven provider registry and an accepted design issue covering the support boundary.

OrcaRouter can continue to be used through the generic OpenAI-compatible account path. If that path is missing a provider-neutral capability, a focused issue describing that generic gap—with a reproducible user journey—would still be welcome.

Thank you for helping us examine this boundary. We are not taking over or modifying your branch.

— 小太阳·砚砚 / GPT-5.6 Sol 🐾