Skip to content

Where agent teams gather. Cross-platform team chat where AI agents are first-class teammates — with cloud or bring-your-own (Claude Code / Codex) brains.

TypeScript

feat: add OrcaRouter as a named model-prefix provider (#111)

putraperdana1207-pixel9905bb35f7bf
diff --git a/.env.example b/.env.example
index 30c794c..635e071 100644
--- a/.env.example
+++ b/.env.example
@@ -39,6 +39,15 @@ OPENAI_API_KEY=sk-...
# OPENAI_COMPACTION_MODEL=gpt-5.4-mini
# OPENAI_IMAGE_MODEL=gpt-image-2
+# ─── OrcaRouter (optional) ─────────────────────────────────────────────────
+# OpenAI-compatible AI gateway (https://www.orcarouter.ai). An agent opts in
+# by prefixing its model id with `orcarouter/`, e.g. `orcarouter/openai/gpt-4o-mini`.
+# OrcaRouter speaks the Responses API natively, so unlike Novita this is a pure
+# base-URL swap — no translation layer. When the key is unset, agents using an
+# `orcarouter/*` model fall back to the legacy/sub2api client.
+# ORCAROUTER_API_KEY=sk-orca-...
+# ORCAROUTER_BASE_URL=https://api.orcarouter.ai/v1
+
# ─── Tavily (optional) ────────────────────────────────────────────────────
# Used by the agent `web.search` tool. Without this key, web search is a no-op.
# TAVILY_API_KEY=
diff --git a/server/src/__tests__/orcarouter.test.ts b/server/src/__tests__/orcarouter.test.ts
new file mode 100644
index 0000000..4e7d505
--- /dev/null
+++ b/server/src/__tests__/orcarouter.test.ts
@@ -0,0 +1,63 @@
+/**
+ * Unit tests for the OrcaRouter model-prefix routing (server/src/orcarouter.ts).
+ * No network access: the underlying client is stubbed via
+ * `__setOrcaRouterClientOverrideForTesting` so these tests assert the prefix
+ * stripping and forwarding logic, not live OrcaRouter behavior (that's the
+ * live-smoke step with a real ORCAROUTER_API_KEY).
+ *
+ * Run: node --import tsx --test server/src/__tests__/orcarouter.test.ts
+ */
+
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import type OpenAI from 'openai'
+import {
+ __setOrcaRouterClientOverrideForTesting,
+ isOrcaRouterModel,
+ orcarouterClient,
+ orcarouterResponsesCreate,
+ stripOrcaRouterPrefix,
+} from '../orcarouter.js'
+
+function fakeResponsesClient(create: (...args: unknown[]) => unknown): OpenAI {
+ return { responses: { create } } as unknown as OpenAI
+}
+
+test('isOrcaRouterModel / stripOrcaRouterPrefix', () => {
+ assert.equal(isOrcaRouterModel('orcarouter/openai/gpt-4o-mini'), true)
+ assert.equal(isOrcaRouterModel('gpt-5.5'), false)
+ assert.equal(isOrcaRouterModel(null), false)
+ assert.equal(isOrcaRouterModel(undefined), false)
+ assert.equal(stripOrcaRouterPrefix('orcarouter/openai/gpt-4o-mini'), 'openai/gpt-4o-mini')
+})
+
+test('orcarouterResponsesCreate forwards the call with the prefix stripped', async () => {
+ let captured: { model?: string; input?: string; max_output_tokens?: number } = {}
+ __setOrcaRouterClientOverrideForTesting(fakeResponsesClient(async (args: unknown) => {
+ captured = args as typeof captured
+ return { id: 'resp_1', output_text: 'hi' }
+ }))
+ try {
+ const r = await orcarouterResponsesCreate(
+ { model: 'orcarouter/openai/gpt-4o-mini', input: 'hello', max_output_tokens: 10 } as never,
+ undefined,
+ ) as { id: string; output_text: string }
+ assert.equal(r.output_text, 'hi')
+ // The model prefix is stripped before the id is forwarded to OrcaRouter.
+ assert.equal(captured.model, 'openai/gpt-4o-mini')
+ assert.equal(captured.input, 'hello')
+ assert.equal(captured.max_output_tokens, 10)
+ } finally {
+ __setOrcaRouterClientOverrideForTesting(null)
+ }
+})
+
+test('orcarouterClient uses the test override when set', () => {
+ const fake = fakeResponsesClient(() => ({}))
+ __setOrcaRouterClientOverrideForTesting(fake)
+ try {
+ assert.equal(orcarouterClient(), fake)
+ } finally {
+ __setOrcaRouterClientOverrideForTesting(null)
+ }
+})
diff --git a/server/src/env.ts b/server/src/env.ts
index d1332e2..18d355d 100644
--- a/server/src/env.ts
+++ b/server/src/env.ts
@@ -68,6 +68,17 @@ export const env = {
/** Novita's OpenAI-compatible Chat Completions base. Override for a
* self-hosted proxy or a pinned API version. */
NOVITA_BASE_URL: (process.env.NOVITA_BASE_URL ?? 'https://api.novita.ai/openai').replace(/\/+$/, ''),
+ /**
+ * OrcaRouter LLM API key. Optional — when unset, agents configured with a
+ * `orcarouter/<model>` model id (see server/src/orcarouter.ts) fall back to
+ * the legacy/sub2api client instead, so an unconfigured deployment doesn't
+ * break the run; the model just won't resolve to OrcaRouter as intended.
+ */
+ ORCAROUTER_API_KEY: process.env.ORCAROUTER_API_KEY ?? '',
+ /** OrcaRouter's OpenAI-compatible Responses base. OrcaRouter speaks the
+ * Responses API natively, so the `orcarouter/<model>` route is a pure
+ * base-URL swap (no Chat-Completions translation, unlike Novita). */
+ ORCAROUTER_BASE_URL: (process.env.ORCAROUTER_BASE_URL ?? 'https://api.orcarouter.ai/v1').replace(/\/+$/, ''),
/**
* Webhook URL for process-level alerts (unhandledRejection /
* uncaughtException). Currently expects a Discord-compatible
diff --git a/server/src/llm.ts b/server/src/llm.ts
index b6052a5..a09d9d2 100644
--- a/server/src/llm.ts
+++ b/server/src/llm.ts
@@ -24,19 +24,27 @@
* take down agent turns.
*
* Provider routing (model-based, on top of the above): whichever client is
- * chosen by the tenant rules is wrapped by `withNovitaRouting` before it's
+ * chosen by the tenant rules is wrapped by `withProviderRouting` before it's
* returned. That wrapper inspects the `model` on each individual
* `responses.create()` call — not the tenant — and reroutes calls whose
- * model carries the `novita/` prefix to Novita's real Chat Completions API
- * via server/src/novita.ts's translation shim, since Novita has no Responses
- * API to swap a base URL onto. Everything else about the returned client
- * (chat.completions, images, embeddings, non-Novita responses.create calls)
- * is the same object callers already know.
+ * model carries a recognized provider prefix:
+ * - `novita/<model>` → Novita's real Chat Completions API via
+ * server/src/novita.ts's translation shim, since
+ * Novita has no Responses API to swap a base URL
+ * onto.
+ * - `orcarouter/<model>` → OrcaRouter (https://www.orcarouter.ai) via a
+ * pure base-URL swap (server/src/orcarouter.ts),
+ * since OrcaRouter speaks the Responses API
+ * natively — no translation needed.
+ * Everything else about the returned client (chat.completions, images,
+ * embeddings, non-prefixed responses.create calls) is the same object
+ * callers already know.
*/
import OpenAI from 'openai'
import { pool } from './db/pool.js'
import { env } from './env.js'
import { isNovitaModel, novitaResponsesShim } from './novita.js'
+import { isOrcaRouterModel, orcarouterResponsesCreate } from './orcarouter.js'
import { sub2apiConfigured, sub2apiOpenAIBaseURL } from './sub2api.js'
interface CachedClient {
@@ -75,11 +83,15 @@ export function __setLlmClientOverrideForTesting(fn: typeof testLlmOverride): vo
testLlmOverride = fn
}
-/** Wrap a client so any call whose `model` carries the `novita/` prefix
- * (see server/src/novita.ts) is routed to Novita's real Chat Completions
- * API instead of this client's own `responses.create` — translated
- * through `novitaResponsesShim` so the caller sees an ordinary
- * Responses-API stream/return either way.
+/** Wrap a client so any call whose `model` carries a recognized provider
+ * prefix is routed to that provider instead of this client's own
+ * `responses.create`:
+ * - `novita/<model>` → Novita (server/src/novita.ts), translated
+ * through `novitaResponsesShim` so the caller sees
+ * an ordinary Responses-API stream/return.
+ * - `orcarouter/<model>` → OrcaRouter (server/src/orcarouter.ts), a pure
+ * base-URL swap — OrcaRouter speaks the Responses
+ * API natively.
*
* Model, not tenant, decides the provider: `getLlmClient` is resolved
* once per tenant/hop before the model for that specific call is even
@@ -89,15 +101,22 @@ export function __setLlmClientOverrideForTesting(fn: typeof testLlmOverride): vo
* complete, minimal interception — everything else (chat.completions,
* images, embeddings) passes through to the real client untouched. */
let novitaUnconfiguredWarned = false
-/** One log line, not one per call — this fires on every hop of every turn of
- * an agent whose model names an unconfigured provider. */
-function warnNovitaUnconfiguredOnce(model: string | undefined): void {
- if (novitaUnconfiguredWarned) return
- novitaUnconfiguredWarned = true
- console.warn(`[llm] model "${model}" requests Novita but NOVITA_API_KEY is unset — using the tenant's normal client instead`)
+let orcarouterUnconfiguredWarned = false
+/** One log line per provider, not one per call — this fires on every hop of
+ * every turn of an agent whose model names an unconfigured provider. */
+function warnProviderUnconfiguredOnce(provider: 'Novita' | 'OrcaRouter', model: string | undefined): void {
+ if (provider === 'Novita') {
+ if (novitaUnconfiguredWarned) return
+ novitaUnconfiguredWarned = true
+ console.warn(`[llm] model "${model}" requests Novita but NOVITA_API_KEY is unset — using the tenant's normal client instead`)
+ return
+ }
+ if (orcarouterUnconfiguredWarned) return
+ orcarouterUnconfiguredWarned = true
+ console.warn(`[llm] model "${model}" requests OrcaRouter but ORCAROUTER_API_KEY is unset — using the tenant's normal client instead`)
}
-function withNovitaRouting(client: OpenAI): OpenAI {
+function withProviderRouting(client: OpenAI): OpenAI {
return new Proxy(client, {
get(target, prop, receiver): unknown {
if (prop !== 'responses') return Reflect.get(target, prop, receiver)
@@ -115,7 +134,15 @@ function withNovitaRouting(client: OpenAI): OpenAI {
if (env.NOVITA_API_KEY) {
return novitaResponsesShim.create(args as never, opts as never)
}
- warnNovitaUnconfiguredOnce(args.model)
+ warnProviderUnconfiguredOnce('Novita', args.model)
+ } else if (isOrcaRouterModel(args.model)) {
+ // Same degrade-not-die guard for OrcaRouter: an unset key must
+ // fall through to the tenant's normal client, not send a bare
+ // bearer to api.orcarouter.ai.
+ if (env.ORCAROUTER_API_KEY) {
+ return orcarouterResponsesCreate(args, opts)
+ }
+ warnProviderUnconfiguredOnce('OrcaRouter', args.model)
}
return (real.create as (a: unknown, o?: unknown) => unknown)(args, opts)
}
@@ -131,11 +158,11 @@ function withNovitaRouting(client: OpenAI): OpenAI {
export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
if (testLlmOverride) return testLlmOverride(tenant)
// No tenant context → legacy.
- if (!tenant || !sub2apiConfigured()) return withNovitaRouting(legacyClient())
+ if (!tenant || !sub2apiConfigured()) return withProviderRouting(legacyClient())
const cached = cache.get(tenant)
if (cached && Date.now() - cached.mintedAt < CACHE_TTL_MS) {
- return withNovitaRouting(cached.client)
+ return withProviderRouting(cached.client)
}
try {
@@ -153,7 +180,7 @@ export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
// hop, but with a short TTL so the next backfill picks up quickly.
const c = legacyClient()
cache.set(tenant, { client: c, key: 'legacy', mintedAt: Date.now() })
- return withNovitaRouting(c)
+ return withProviderRouting(c)
}
const c = new OpenAI({
apiKey,
@@ -162,10 +189,10 @@ export async function getLlmClient(tenant: string | null): Promise<OpenAI> {
timeout: SDK_TIMEOUT_MS,
})
cache.set(tenant, { client: c, key: apiKey, mintedAt: Date.now() })
- return withNovitaRouting(c)
+ return withProviderRouting(c)
} catch (e) {
console.warn(`[llm] tenant ${tenant} client lookup failed; legacy fallback`, e instanceof Error ? e.message : e)
- return withNovitaRouting(legacyClient())
+ return withProviderRouting(legacyClient())
}
}
diff --git a/server/src/novita.ts b/server/src/novita.ts
index 9388118..4d78bd2 100644
--- a/server/src/novita.ts
+++ b/server/src/novita.ts
@@ -17,7 +17,7 @@
* params, translates them into Chat Completions params, calls Novita's real
* `chat.completions.create`, and translates the result (streaming or not)
* back into the exact Responses-API shapes every existing call site already
- * expects. Nothing outside `llm.ts` needs to change — see `withNovitaRouting`
+ * expects. Nothing outside `llm.ts` needs to change — see `withProviderRouting`
* there for how a per-call `model` id opts into this path.
*
* Model selection convention: an agent (or an env default) opts into Novita
@@ -437,7 +437,7 @@ function wrapAsyncIterable(gen: AsyncGenerator<ResponseStreamEvent>): AsyncItera
/** The Responses-API-shaped surface every call site actually uses off a
* client: `client.responses.create(...)`. Assigning this object as
- * `client.responses` (see `withNovitaRouting` in llm.ts) is sufficient —
+ * `client.responses` (see `withProviderRouting` in llm.ts) is sufficient —
* nothing in this codebase touches any other `client.responses.*` method. */
export const novitaResponsesShim = {
create(args: ResponsesCreateArgs, opts?: RequestOpts): unknown {
diff --git a/server/src/orcarouter.ts b/server/src/orcarouter.ts
new file mode 100644
index 0000000..997cef8
--- /dev/null
+++ b/server/src/orcarouter.ts
@@ -0,0 +1,62 @@
+/**
+ * OrcaRouter LLM provider — model-prefix routing, like Novita but simpler.
+ *
+ * OrcaRouter (https://www.orcarouter.ai) is an OpenAI-compatible AI gateway
+ * that also natively implements the Responses API (POST /v1/responses,
+ * streaming included — verified live). That means opting a model in is a pure
+ * base-URL swap, not a translation: an agent prefixes its `model` id with
+ * `orcarouter/`, e.g. `orcarouter/openai/gpt-4o-mini`, and the prefix is
+ * stripped before the id is sent to OrcaRouter. Nothing needs translating
+ * between the Responses API and Chat Completions the way Novita does
+ * (server/src/novita.ts) — OrcaRouter speaks Responses natively, so the call
+ * is forwarded straight to the OrcaRouter client.
+ *
+ * Mirrors the Novita convention: `isOrcaRouterModel` gates the route in
+ * llm.ts's `withProviderRouting`, and an unset key degrades to the tenant's
+ * normal client instead of failing the run.
+ */
+import OpenAI from 'openai'
+import { env } from './env.js'
+
+export const ORCAROUTER_MODEL_PREFIX = 'orcarouter/'
+
+export function isOrcaRouterModel(model: string | null | undefined): boolean {
+ return typeof model === 'string' && model.startsWith(ORCAROUTER_MODEL_PREFIX)
+}
+
+export function stripOrcaRouterPrefix(model: string): string {
+ return model.slice(ORCAROUTER_MODEL_PREFIX.length)
+}
+
+let _orcarouterClient: OpenAI | null = null
+/** Test-only override for the underlying OrcaRouter client — lets unit tests
+ * assert the prefix-strip + forward logic without a real ORCAROUTER_API_KEY or
+ * network access. Production code never sets this. */
+let testOrcaRouterClientOverride: OpenAI | null = null
+export function __setOrcaRouterClientOverrideForTesting(client: OpenAI | null): void {
+ testOrcaRouterClientOverride = client
+}
+export function orcarouterClient(): OpenAI {
+ if (testOrcaRouterClientOverride) return testOrcaRouterClientOverride
+ if (!_orcarouterClient) {
+ _orcarouterClient = new OpenAI({
+ apiKey: env.ORCAROUTER_API_KEY,
+ baseURL: env.ORCAROUTER_BASE_URL,
+ })
+ }
+ return _orcarouterClient
+}
+
+/** Route a single `responses.create` call to OrcaRouter. The model prefix is
+ * stripped before the id is forwarded; everything else passes through
+ * untouched because OrcaRouter speaks the Responses API natively. */
+export function orcarouterResponsesCreate(
+ args: { model?: string } & Record<string, unknown>,
+ opts?: unknown,
+): unknown {
+ const { model, ...rest } = args
+ return orcarouterClient().responses.create(
+ { ...rest, model: stripOrcaRouterPrefix(model ?? '') } as never,
+ opts as never,
+ )
+}