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.exampleindex 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.tsnew file mode 100644index 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.tsindex 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-compatiblediff --git a/server/src/llm.ts b/server/src/llm.tsindex 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): votestLlmOverride = 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.tsindex 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.tsnew file mode 100644index 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,+ )+}