Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// POST /api/brain/chat — Multi-LLM provider proxy for the /brain page.
//
// Body: { provider, messages, system?, maxTokens? }
// Response: SSE stream:
// event: meta → { provider, label, network, model, tier }
// event: first → { firstTokenMs }
// (data-only) → JSON-encoded text chunk
// event: done → { elapsedMs, firstTokenMs, usage }
// event: error → { message, elapsedMs }
//
// GET /api/brain/chat → returns available providers list
import { streamText } from 'ai';
import { createAnthropic } from '@ai-sdk/anthropic';
import { createOpenAI } from '@ai-sdk/openai';
import { createQwen } from 'qwen-ai-provider';
import { env } from '../_lib/env.js';
import { cors, method, readJson, error, wrap, rateLimited } from '../_lib/http.js';
import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.js';
import { limits, clientIp } from '../_lib/rate-limit.js';
import { watsonxConfig, watsonxChatRequest } from '../_lib/watsonx.js';
import { OPENROUTER_ATTRIBUTION_HEADERS } from '../_lib/openrouter-attribution.js';
import {
DEFAULT_FREE_MODEL,
modelThinksByDefault,
XAI_API_BASE,
GROK_MODELS,
GROK_MENU_MODELS,
GROK_RETIRED_ALIASES,
grokMenuModelId,
} from '../_lib/chat-models.js';
import { ROSTER, rosterModel } from '../_lib/model-roster.js';
import { rosterTransports, transportHeaders } from '../_lib/model-routes.js';
import { createReasoningStripper } from '../_lib/strip-reasoning.js';
import {
vertexClaudeEnabled,
vertexClaudeConfigured,
vertexAnthropicMessages,
} from '../_lib/vertex-claude.js';
import {
vertexGeminiAvailable,
vertexGeminiModel,
vertexGeminiOpenAIBase,
vertexGeminiAccessToken,
vertexGeminiBudget,
} from '../_lib/vertex-gemini.js';
import { recordEvent } from '../_lib/usage.js';
import { costMicroUsd } from '../_lib/llm-pricing.js';
import { meterFreeModel, FreeTierExhaustedError, freeTierErrorBody, retryAfterSeconds } from '../_lib/free-tier.js';
import { assertInferenceAllowed, chargeInference } from '../_lib/inference-billing.js';
import { randomUUID } from 'node:crypto';
import { openrouterUsageFetch } from '../_lib/openrouter-usage.js';
const WATSONX_HEADERS_TIMEOUT_MS = 45_000;
// Providers an anonymous (signed-out) caller may use: only the genuinely free
// tiers — the OpenRouter-routed open-weight default and the free NVIDIA NIM
// models. Every paid first-party model (Claude, GPT-5.x, o3, DashScope, DeepSeek)
// requires sign-in so an unauthenticated script can't drain the server's billed
// API keys. Mirrors the anon-provider gate in api/chat.js.
// The free open-model roster rows (model-roster.js `free: true`) are open to a
// signed-out caller too; their messages draw on the daily free-tier allowance
// (api/_lib/free-tier.js) instead of on a paid key.
export const ANON_BRAIN_PROVIDERS = new Set([
'gpt-oss-120b',
'nvidia-nemotron-120b',
'nvidia-nemotron-super-49b',
'nvidia-nemotron-nano',
...ROSTER.filter((m) => m.free).map((m) => m.id),
]);
// Menu tier for a roster row: chat-only reasoners, premium flagships, and the
// rest. Drives the same tier chip the hand-written specs carry.
function rosterTier(m) {
if (m.reasoning && !m.tools) return 'reasoning';
if (m.price[0] >= 1) return 'flagship';
return m.free ? 'fast' : 'balanced';
}
export const maxDuration = 120;
// Each spec declares its *native* provider model (built from a first-party key,
// or null when that key is absent) and the OpenRouter model id that mirrors it.
// buildPrimary() prefers the native model and falls back to routing through
// OpenRouter; buildFallback() reuses the OpenRouter id to route *around* a native
// provider outage (quota/billing/rate-limit) at request time.
// A /brain row for a Grok model. Ids, labels, context and mirrors all come from
// GROK_MODELS, so a new or retired xAI model is a one-line change there.
// Native on GROK_API_KEY; mirrored on OpenRouter when the catalog names a
// mirror, which is also the route around an xAI outage.
function grokSpec(m) {
return {
label: m.label,
network: 'xAI',
tier: m.tier,
maxOutput: m.tier === 'fast' ? 8192 : 16384,
context: m.contextWindow,
description: m.description,
native: () =>
env.GROK_API_KEY ? createOpenAI({ apiKey: env.GROK_API_KEY, baseURL: XAI_API_BASE }).chat(m.id) : null,
...(m.openrouterModel ? { openrouterModel: m.openrouterModel } : {}),
};
}
const PROVIDERS = {
// The key is historical (agents store it); the model behind it is whatever
// DEFAULT_FREE_MODEL names today. The label says what actually answers: it
// used to read "GPT-OSS 120B" long after that free endpoint was retired.
'gpt-oss-120b': {
label: 'Gemma 4 31B',
network: 'Google · OpenRouter',
tier: 'balanced',
maxOutput: 8192,
context: 262_144,
description: 'Platform default. Google open-weights, free, no sign-in needed.',
openrouterModel: DEFAULT_FREE_MODEL,
},
'claude-fable-5': {
label: 'Claude Fable 5',
network: 'Anthropic',
tier: 'flagship',
maxOutput: 16384,
description: 'Most capable model. State-of-the-art reasoning, long-horizon agentic work, knowledge work, and vision.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-fable-5') : null),
// Mirrored on OpenRouter (verified 2026-07-29, same $10/$50 per MTok as
// first-party). Without this the roster showed the platform's most capable
// model as permanently unavailable, since no ANTHROPIC_API_KEY is set.
openrouterModel: 'anthropic/claude-fable-5',
},
// claude-mythos-5 is deliberately NOT in this menu: it is restricted-access
// (Project Glasswing orgs only), so with any normal host key the entry would
// render as selectable and then 404 at call time — a dead menu item. BYOK
// callers with access can still name it through api/chat.js (it stays in
// _lib/chat-models.js as an explicit-only gated model).
'claude-opus-5': {
label: 'Claude Opus 5',
network: 'Anthropic',
tier: 'flagship',
maxOutput: 16384,
description: 'Current Opus. Deep reasoning, agentic and long-horizon work; thinks by default.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-opus-5') : null),
openrouterModel: 'anthropic/claude-opus-5',
},
'claude-sonnet-5': {
label: 'Claude Sonnet 5',
network: 'Anthropic',
tier: 'balanced',
maxOutput: 16384,
description: 'Near-Opus quality on coding and agentic work at Sonnet cost. Best for most tasks.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-sonnet-5') : null),
openrouterModel: 'anthropic/claude-sonnet-5',
},
'claude-opus-4-7': {
label: 'Claude Opus 4.7',
network: 'Anthropic',
tier: 'flagship',
maxOutput: 16384,
description: 'Most capable. Extended thinking, complex reasoning.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-opus-4-7') : null),
openrouterModel: 'anthropic/claude-opus-4',
},
'claude-sonnet-4-6': {
label: 'Claude Sonnet 4.6',
network: 'Anthropic',
tier: 'balanced',
maxOutput: 16384,
description: 'Balanced speed and intelligence. Best for most tasks.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-sonnet-4-6') : null),
openrouterModel: 'anthropic/claude-sonnet-4',
},
'claude-haiku-4-5': {
label: 'Claude Haiku 4.5',
network: 'Anthropic',
tier: 'fast',
maxOutput: 8192,
description: 'Fastest Claude. Low latency, high throughput.',
native: () => (env.ANTHROPIC_API_KEY ? createAnthropic({ apiKey: env.ANTHROPIC_API_KEY })('claude-haiku-4-5-20251001') : null),
openrouterModel: 'anthropic/claude-haiku-4.5',
},
'gpt-5.6-sol': {
label: 'GPT-5.6 Sol',
network: 'OpenAI',
tier: 'flagship',
maxOutput: 16384,
description: 'OpenAI flagship. Frontier reasoning, coding, and agentic work.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.6-sol') : null),
openrouterModel: 'openai/gpt-5.6-sol',
},
'gpt-5.6-terra': {
label: 'GPT-5.6 Terra',
network: 'OpenAI',
tier: 'balanced',
maxOutput: 16384,
description: 'Balanced intelligence and cost. Best for most tasks.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.6-terra') : null),
openrouterModel: 'openai/gpt-5.6-terra',
},
'gpt-5.6-luna': {
label: 'GPT-5.6 Luna',
network: 'OpenAI',
tier: 'fast',
maxOutput: 16384,
description: 'Fast, cost-efficient GPT. Great for simple tasks.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.6-luna') : null),
openrouterModel: 'openai/gpt-5.6-luna',
},
'gpt-5.5': {
label: 'GPT-5.5',
network: 'OpenAI',
tier: 'flagship',
maxOutput: 16384,
description: 'A new class of intelligence for coding and professional work.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.5') : null),
openrouterModel: 'openai/gpt-5.5',
},
'gpt-5.5-pro': {
label: 'GPT-5.5 Pro',
network: 'OpenAI',
tier: 'pro',
maxOutput: 16384,
description: 'Maximum-compute GPT-5.5. Smarter, more precise responses.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.5-pro') : null),
openrouterModel: 'openai/gpt-5.5-pro',
},
'gpt-5.4': {
label: 'GPT-5.4',
network: 'OpenAI',
tier: 'balanced',
maxOutput: 16384,
description: 'Affordable model for coding and professional work.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.4') : null),
openrouterModel: 'openai/gpt-5.4',
},
'gpt-5.4-pro': {
label: 'GPT-5.4 Pro',
network: 'OpenAI',
tier: 'pro',
maxOutput: 16384,
description: 'Maximum-compute GPT-5.4. Smarter, more precise responses.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.4-pro') : null),
openrouterModel: 'openai/gpt-5.4-pro',
},
'gpt-5.4-mini': {
label: 'GPT-5.4 mini',
network: 'OpenAI',
tier: 'fast',
maxOutput: 16384,
description: 'Strong mini model for coding, computer use, and subagents.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.4-mini') : null),
openrouterModel: 'openai/gpt-5.4-mini',
},
'gpt-5.4-nano': {
label: 'GPT-5.4 nano',
network: 'OpenAI',
tier: 'fast',
maxOutput: 16384,
description: 'Cheapest current GPT. Simple, high-volume tasks.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.4-nano') : null),
openrouterModel: 'openai/gpt-5.4-nano',
},
'gpt-5.3-codex': {
label: 'GPT-5.3 Codex',
network: 'OpenAI',
tier: 'coding',
maxOutput: 16384,
description: 'Agentic coding specialist behind Codex.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('gpt-5.3-codex') : null),
openrouterModel: 'openai/gpt-5.3-codex',
},
'o3': {
label: 'o3',
network: 'OpenAI',
tier: 'reasoning',
maxOutput: 16384,
description: 'Reasoning model for complex tasks.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('o3') : null),
openrouterModel: 'openai/o3',
},
'o3-pro': {
label: 'o3-pro',
network: 'OpenAI',
tier: 'reasoning',
maxOutput: 16384,
description: 'o3 with more compute for better responses.',
native: () => (env.OPENAI_API_KEY ? createOpenAI({ apiKey: env.OPENAI_API_KEY }).chat('o3-pro') : null),
openrouterModel: 'openai/o3-pro',
},
// xAI Grok: one row per menu model in GROK_MODELS (chat-models.js).
...Object.fromEntries(GROK_MENU_MODELS.map((m) => [m.id, grokSpec(m)])),
'qwen-plus': {
label: 'Qwen Plus',
network: 'DashScope',
tier: 'balanced',
maxOutput: 8192,
description: 'Qwen Plus on DashScope. Strong multilingual.',
native: () => (env.DASHSCOPE_API_KEY ? createQwen({ apiKey: env.DASHSCOPE_API_KEY })('qwen-plus') : null),
openrouterModel: 'qwen/qwen-2.5-72b-instruct',
},
'modelscope-qwen': {
label: 'Qwen3-Coder 480B',
network: 'ModelScope',
tier: 'flagship',
maxOutput: 16384,
description: 'Largest Qwen coder. Exceptional code generation.',
native: () =>
env.MODELSCOPE_API_KEY
? createOpenAI({ apiKey: env.MODELSCOPE_API_KEY, baseURL: 'https://api-inference.modelscope.cn/v1' }).chat('Qwen/Qwen3-Coder-480B-A35B-Instruct')
: null,
openrouterModel: 'qwen/qwen3-coder',
},
'deepseek-r1': {
label: 'DeepSeek R1',
network: 'DeepSeek',
tier: 'reasoning',
maxOutput: 8192,
description: 'Open reasoning model. Strong at math and code.',
native: () =>
env.DEEPSEEK_API_KEY
? createOpenAI({ apiKey: env.DEEPSEEK_API_KEY, baseURL: 'https://api.deepseek.com/v1' }).chat('deepseek-reasoner')
: null,
openrouterModel: 'deepseek/deepseek-r1',
},
// IBM watsonx.ai Granite. watsonx is not OpenAI-compatible at the API layer
// (IAM bearer token, project scoping, version param), so it can't be a
// Vercel AI SDK model object. The `watsonx` flag routes it to a dedicated
// streaming path; buildPrimary() only reports availability.
'ibm-granite': {
label: 'IBM Granite 3.8B',
network: 'IBM watsonx.ai',
tier: 'balanced',
maxOutput: 4096,
description: 'IBM’s open, enterprise-governed foundation model on watsonx.ai.',
watsonx: true,
// Same Granite family hosted on OpenRouter — the same-model backstop when
// watsonx drops a request, and the primary lane when watsonx creds are
// absent entirely (so Granite stays selectable without an IBM account).
openrouterModel: 'ibm-granite/granite-4.1-8b',
},
// ── Google Vertex AI — first-party Claude billed to GCP credits ──────────────
// Only present when VERTEX_CLAUDE_ENABLED (merged below), so the /brain roster
// is byte-identical when the flag is off. The `vertex` flag names the Vertex
// publisher model id; buildPrimary() routes it through the shared vertex-claude
// transport (like the `watsonx` flag), so /brain can compare Vertex-served
// Claude head-to-head with first-party Claude and every other provider.
...(vertexClaudeEnabled()
? {
'vertex-claude-sonnet': {
label: 'Claude Sonnet 4.6 · Vertex',
network: 'Anthropic · Google Vertex',
tier: 'balanced',
maxOutput: 16384,
description: 'Claude Sonnet 4.6 served from Google Vertex AI (billed to GCP credits).',
vertex: 'claude-sonnet-4-6',
},
'vertex-claude-opus': {
label: 'Claude Opus 4.7 · Vertex',
network: 'Anthropic · Google Vertex',
tier: 'flagship',
maxOutput: 16384,
description: 'Claude Opus 4.7 served from Google Vertex AI (billed to GCP credits).',
vertex: 'claude-opus-4-7',
},
'vertex-claude-haiku': {
label: 'Claude Haiku 4.5 · Vertex',
network: 'Anthropic · Google Vertex',
tier: 'fast',
maxOutput: 8192,
description: 'Claude Haiku 4.5 served from Google Vertex AI (billed to GCP credits).',
vertex: 'claude-haiku-4-5-20251001',
},
}
: {}),
// ── NVIDIA NIM (build.nvidia.com) — free hosted inference ────────────────────
// One free `nvapi-...` key (NVIDIA_API_KEY) unlocks all of these. NVIDIA-hosted,
// so there is no first-party-vs-OpenRouter split: `native` is the only route and
// the provider simply shows unavailable until the key is set. Rate-limited free
// tier — great for experimentation, not a guaranteed-uptime production path.
'nvidia-nemotron-120b': {
label: 'Nemotron 3 Super 120B',
network: 'NVIDIA NIM',
tier: 'flagship',
maxOutput: 16384,
description: 'NVIDIA’s flagship Nemotron MoE. Strong agentic reasoning, free on NIM.',
reasoningTrace: true,
native: () => (env.NVIDIA_API_KEY ? nvidia('nvidia/nemotron-3.5-lightning-30b-a3b') : null),
},
'nvidia-nemotron-super-49b': {
label: 'Llama-Nemotron Super 49B',
network: 'NVIDIA NIM',
tier: 'reasoning',
maxOutput: 16384,
description: 'Nemotron reasoning model tuned on Llama 3.3. Math, code, planning.',
reasoningTrace: true,
native: () => (env.NVIDIA_API_KEY ? nvidia('nvidia/nemotron-3-ultra-550b-a55b') : null),
},
'nvidia-nemotron-nano': {
label: 'Nemotron Nano 9B',
network: 'NVIDIA NIM',
tier: 'balanced',
maxOutput: 8192,
description: 'Compact Nemotron with built-in reasoning. Strong quality per token.',
reasoningTrace: true,
native: () => (env.NVIDIA_API_KEY ? nvidia('nvidia/nemotron-3.5-lightning-30b-a3b') : null),
},
};
// ── The open-model roster (api/_lib/model-roster.js) ─────────────────────────
// Llama, DeepSeek, Kimi, Mistral, Qwen and Gemini. Each row streams through its
// own ordered routes (free lanes, then Vertex AI Model Garden) before the free
// safety net below it, so a pick is honored on every lane that serves it.
for (const m of ROSTER) {
PROVIDERS[m.id] = {
label: m.label,
network: m.family,
tier: rosterTier(m),
maxOutput: m.maxOutput,
context: m.context,
description: m.description,
reasoningTrace: Boolean(m.reasoning),
roster: m.id,
};
}
// Every configured OpenRouter key, primary first. Fallback keys are typically
// unfunded free-tier accounts (see env.OPENROUTER_FALLBACK_KEYS) — they can't
// serve paid mirrors, but they keep every :free route alive when the primary
// account is out of credits or rate-limited.
function openrouterKeys() {
return [...new Set([env.OPENROUTER_API_KEY, ...env.OPENROUTER_FALLBACK_KEYS].filter(Boolean))];
}
// Resolve the primary route for a spec: native first-party model when its key is
// present, otherwise the OpenRouter-routed equivalent, otherwise nothing. `via`
// records which path won so buildFallback() knows whether OpenRouter is a
// distinct escape hatch.
function buildPrimary(spec) {
// watsonx leads when its creds are present; otherwise fall through so a
// Granite spec with an openrouterModel still resolves (OpenRouter-hosted
// Granite becomes the primary lane instead of showing unavailable).
if (spec.watsonx && watsonxConfig().configured) return { kind: 'watsonx' };
// Vertex-served Claude — routed through the shared vertex-claude transport
// (not an AI SDK model object), so it reports availability here and streams
// via streamVertex() in streamBrain(). Requires the GCP project to be set.
if (spec.vertex) return vertexClaudeConfigured() ? { kind: 'vertex', model: spec.vertex } : null;
if (spec.roster) {
const transports = rosterTransports(spec.roster);
return transports.length ? { kind: 'roster', transports } : null;
}
const native = spec.native?.();
if (native) return { kind: 'model', model: native, via: 'native' };
if (spec.openrouterModel && openrouterKeys().length) {
return { kind: 'model', model: openrouter()(spec.openrouterModel), via: 'openrouter' };
}
return null;
}
// The spend-ledger lane for a resolved primary route. A native route meters
// under its own network's provider (the model id comes off the AI SDK model
// object); an OpenRouter-routed one meters as openrouter on the mirror id, which
// is the lane that quietly drew real money before any of this was recorded.
function meterForPrimary(spec, primary) {
if (primary?.via === 'openrouter') return { provider: 'openrouter', model: spec.openrouterModel };
const provider = meterProviderForNetwork(spec.network);
const model = primary?.model?.modelId || null;
return provider && model ? { provider, model } : null;
}
// A distinct fallback exists only when the primary ran on a native provider key
// AND an OpenRouter key is configured — then OpenRouter routes around a native
// outage (quota exhausted, out of credits, rate-limited). When the primary was
// already OpenRouter the free-tier safety net (freeFallbackChain) is the next stop.
function buildFallback(spec, primary) {
if (!spec.openrouterModel || !openrouterKeys().length) return null;
// The mirror routes around a native/watsonx/vertex outage on the SAME model
// via OpenRouter. Skip it only when the primary ALREADY ran on OpenRouter —
// the mirror would be the identical key+model and the free-tier chain is the
// meaningful next stop.
if (primary?.via === 'openrouter') return null;
return openrouter()(spec.openrouterModel);
}
// The last line of defense: free providers the platform can always fall back to
// when the requested model's primary AND mirror routes both fail before any
// token streamed. Free-first platform policy (api/_lib/llm.js): the user gets
// an answer from an open-weight model rather than an error event. Skips routes
// that already failed as the primary (same key + model would fail identically).
// Exported for the anchor regression tests (tests/api/llm-vertex-anchor-surfaces).
export function freeFallbackChain(providerKey, spec, primary) {
const chain = [];
// Groq retired every Llama model (2026-09-22); Qwen 3.8 27B is the live,
// tool-capable model on the same free account.
if (env.GROQ_API_KEY) {
chain.push({
label: 'groq/qwen/qwen3.8-27b',
model: createOpenAI({ apiKey: env.GROQ_API_KEY, baseURL: 'https://api.groq.com/openai/v1' }).chat('qwen/qwen3.8-27b'),
meter: { provider: 'groq', model: 'qwen/qwen3.8-27b' },
});
}
openrouterKeys().forEach((key, i) => {
// The primary already burned this exact key+model pair — don't repeat it.
if (i === 0 && primary?.via === 'openrouter' && spec.openrouterModel === DEFAULT_FREE_MODEL) return;
chain.push({
label: `openrouter${i > 0 ? `#${i + 1}` : ''}/${DEFAULT_FREE_MODEL}`,
model: openrouter(key)(DEFAULT_FREE_MODEL),
meter: { provider: i > 0 ? `openrouter#${i + 1}` : 'openrouter', model: DEFAULT_FREE_MODEL },
});
});
if (env.NVIDIA_API_KEY && !providerKey.startsWith('nvidia-')) {
chain.push({
label: 'nvidia/nemotron-3.5-lightning-30b-a3b',
model: nvidia('nvidia/nemotron-3.5-lightning-30b-a3b'),
meter: { provider: 'nvidia', model: 'nvidia/nemotron-3.5-lightning-30b-a3b' },
});
}
// Three more free lanes on independent quota pools (see api/_lib/llm.js for
// each tier's limits): SambaNova (Llama 3.3 70B), Mistral (Experiment tier),
// and Z.AI's free GLM Flash. All OpenAI-compatible Chat Completions.
if (env.SAMBANOVA_API_KEY) {
chain.push({
label: 'sambanova/Meta-Llama-3.3-70B-Instruct',
model: createOpenAI({ apiKey: env.SAMBANOVA_API_KEY, baseURL: 'https://api.sambanova.ai/v1' }).chat('Meta-Llama-3.3-70B-Instruct'),
meter: { provider: 'sambanova', model: 'Meta-Llama-3.3-70B-Instruct' },
});
}
if (env.MISTRAL_API_KEY) {
chain.push({
label: 'mistral/mistral-small-latest',
model: createOpenAI({ apiKey: env.MISTRAL_API_KEY, baseURL: 'https://api.mistral.ai/v1' }).chat('mistral-small-latest'),
meter: { provider: 'mistral', model: 'mistral-small-latest' },
});
}
if (env.ZAI_API_KEY) {
chain.push({
label: 'zai/glm-4.7-flash',
model: createOpenAI({ apiKey: env.ZAI_API_KEY, baseURL: 'https://api.z.ai/api/paas/v4' }).chat('glm-4.7-flash'),
meter: { provider: 'zai', model: 'glm-4.7-flash' },
});
}
// Credits-funded Vertex Gemini anchor, ALWAYS at the tail when the GCP
// project is set (api/chat.js semantics, see api/_lib/vertex-gemini.js). No
// key gates it and nothing may evict it: it is the rung that keeps /brain
// streaming when groq/openrouter/nvidia all throttle at once and the paid
// backstops are dead. The AI SDK model is built lazily in streamBrain's
// attempt loop (vertexGemini flag) because its bearer token is minted per
// request; a token failure falls through like any other provider error.
if (vertexGeminiAvailable()) {
chain.push({
label: `vertex-gemini/${vertexGeminiModel()}`,
vertexGemini: true,
// Credits-billed, not free: it draws down the GCP grant, so it meters
// at Vertex list price like every other spending lane.
meter: { provider: 'vertex-gemini', model: vertexGeminiModel() },
});
}
return chain;
}
// Splice Vertex's `extra_body` into an outgoing AI SDK request payload. The SDK
// serializes the body before its fetch hook runs, so the only place to add a
// field it does not model is here. Anything unparseable passes through untouched
// rather than breaking the request.
function withVertexExtraBody(body, extraBody) {
if (typeof body !== 'string' || !extraBody) return body;
try {
const parsed = JSON.parse(body);
if (!parsed || typeof parsed !== 'object') return body;
return JSON.stringify({ ...parsed, extra_body: extraBody });
} catch {
return body;
}
}
// An AI SDK chat model for one roster transport. The transport owns its URL
// and auth (a per-call GCP token for Vertex, nothing for the keyless OVH lane),
// so the SDK's own URL and bearer are replaced in a fetch hook. Gemini on a
// Vertex route gets the same reasoning cap as the anchor, or its hidden
// reasoning tokens eat the visible budget.
function rosterSdkModelFor(transport, maxTokens) {
const gemini = transport.name === 'vertex' && String(transport.model).startsWith('google/');
const budget = gemini ? vertexGeminiBudget(maxTokens) : { max_tokens: maxTokens, extra_body: null };
const model = createOpenAI({
apiKey: 'route-auth',
baseURL: 'https://route.invalid/v1',
fetch: async (_url, init = {}) => {
const headers = new Headers(init.headers || {});
headers.delete('authorization');
for (const [k, v] of Object.entries(await transportHeaders(transport))) headers.set(k, v);
return fetch(transport.url, { ...init, headers, body: withVertexExtraBody(init.body, budget.extra_body) });
},
}).chat(transport.model);
return { model, budget: budget.max_tokens };
}
// NVIDIA NIM (build.nvidia.com) is OpenAI-*compatible* (Chat Completions, not the
// Responses API), so — like Groq, ModelScope and OpenRouter — we force the
// `.chat()` surface. One free `nvapi-...` key unlocks every hosted model.
function nvidia(modelId) {
return createOpenAI({
apiKey: env.NVIDIA_API_KEY,
baseURL: 'https://integrate.api.nvidia.com/v1',
}).chat(modelId);
}
// Reported OpenRouter cost per model instance, in USD. A model object is built
// per request (resolveBrain runs per call), so the WeakMap entry is per-request
// too and disappears with the model. See recordBrainSpend.
const openrouterCostByModel = new WeakMap();
/** The USD OpenRouter reported for the last call on this model, or null. */
function reportedCostFor(model) {
const cell = model ? openrouterCostByModel.get(model) : null;
return cell && Number.isFinite(cell.usd) ? cell.usd : null;
}
function openrouter(key = openrouterKeys()[0]) {
// OpenRouter (like every OpenAI-*compatible* backend) implements the Chat
// Completions API, NOT OpenAI's newer Responses API. The AI SDK's callable
// default `provider(id)` builds a Responses-API model, which OpenRouter
// rejects ("Invalid Responses API request" / "unsupported content types").
// Force the chat-completions surface so every routed model actually answers.
return (modelId) => {
// One cost cell per model instance: the metering fetch fills it in when
// OpenRouter reports what the call was charged (openrouter-usage.js). Paid
// vendor mirrors run through here, so without this the spend is invisible.
const cell = { usd: null };
const model = createOpenAI({
apiKey: key,
baseURL: 'https://openrouter.ai/api/v1',
headers: OPENROUTER_ATTRIBUTION_HEADERS,
fetch: openrouterUsageFetch((usd) => {
cell.usd = usd;
}),
}).chat(modelId);
openrouterCostByModel.set(model, cell);
return model;
};
}
// Display network → the provider name the spend ledger meters under. Every
// PROVIDERS spec's `network` must resolve here (tests/api/brain-spend.test.js
// asserts it), because an unmapped lane would silently record no provider and
// drop out of the metering audit.
const NETWORK_METER_PROVIDER = {
// Roster families meter per route: every roster attempt carries its own
// { provider, model } from model-routes.js, so the family maps to 'roster'
// only to mark the network as accounted for.
...Object.fromEntries(ROSTER.map((m) => [m.family, 'roster'])),
'Google · OpenRouter': 'openrouter',
Anthropic: 'anthropic',
'Anthropic · Google Vertex': 'vertex-anthropic',
OpenAI: 'openai',
'OpenAI · OpenRouter': 'openrouter',
xAI: 'grok',
'NVIDIA NIM': 'nvidia',
Groq: 'groq',
ModelScope: 'modelscope',
DeepSeek: 'deepseek',
DashScope: 'dashscope',
'IBM watsonx.ai': 'watsonx',
};
/** The ledger provider name for a spec's native lane. */
export function meterProviderForNetwork(network) {
return NETWORK_METER_PROVIDER[network] || null;
}
// Write one /brain turn to the spend ledger. Until this existed, /brain was the
// platform's largest unmetered LLM surface: it routes paid vendor mirrors
// (anthropic/claude-opus-5 at $5/$25 per MTok) on the platform OpenRouter key
// and recorded nothing at all, so the balance drained with no trace. Cost comes
// from OpenRouter's own reported charge when it gives one, else the list-price
// table; an unpriced spending lane records unknown (null) and warns rather than
// booking a fake $0. Fire-and-forget, after the response has already ended.
function recordBrainSpend({ provider, model, usage, latencyMs, userId, providerKey, laneLabel, reportedCostUsd = null }) {
if (!provider || !model) return;
const input = usage?.inputTokens ?? 0;
const output = usage?.outputTokens ?? 0;
const cost = costMicroUsd({ provider, model, input, output, reportedCostUsd });
if (cost === null && (input || output)) {
console.warn(`[brain:${providerKey}] unpriced spending lane ${provider}/${model}, recording cost as unknown; add it to llm-pricing.js`);
}
recordEvent({
kind: 'llm',
provider,
model,
tool: `brain:${providerKey}`,
userId: userId ?? null,
inputTokens: input,
outputTokens: output,
costMicroUsd: cost,
latencyMs,
meta: { surface: 'brain', provider_key: providerKey, lane: laneLabel, cost_reported: reportedCostUsd !== null },
});
}
// Stream IBM Granite (watsonx.ai) to the page using the same SSE protocol as
// the AI SDK path. watsonx returns OpenAI-shaped chat completion chunks
// (choices[].delta.content) plus a usage block on the final chunk.
async function streamWatsonx(res, { messages, system, maxTokens, t0 }) {
const cfg = watsonxConfig();
const wxMessages = system ? [{ role: 'system', content: system }, ...messages] : messages;
const { url, headers, body } = await watsonxChatRequest(cfg, {
messages: wxMessages,
maxTokens,
});
// Bound the wait for response HEADERS only: a streamed completion may run
// longer than any sensible deadline, so the timer is cleared once watsonx
// answers, and only a hung connection is cut.
const headersCtrl = new AbortController();
const headersTimer = setTimeout(() => headersCtrl.abort(), WATSONX_HEADERS_TIMEOUT_MS);
let upstream;
try {
upstream = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify(body),
signal: headersCtrl.signal,
});
} catch (err) {
throw new Error(`watsonx unreachable: ${err?.name === 'AbortError' ? `no response headers within ${WATSONX_HEADERS_TIMEOUT_MS}ms` : err?.message || 'network error'}`);
} finally {
clearTimeout(headersTimer);
}
if (!upstream.ok || !upstream.body) {
const detail = await upstream.text().catch(() => '');
throw new Error(`watsonx ${upstream.status}: ${detail.slice(0, 200)}`);
}
const reader = upstream.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let firstTokenMs = null;
let usage = null;
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop();
for (const line of lines) {
if (!line.startsWith('data:')) continue;
const raw = line.slice(5).trim();
if (!raw || raw === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(raw);
} catch {
continue;
}
const delta = evt.choices?.[0]?.delta?.content;
if (delta) {
if (firstTokenMs === null) {
firstTokenMs = Date.now() - t0;
res.write(`event: first\ndata: ${JSON.stringify({ firstTokenMs })}\n\n`);
}
res.write(`data: ${JSON.stringify(delta)}\n\n`);
}
if (evt.usage) {
usage = {
inputTokens: evt.usage.prompt_tokens,
outputTokens: evt.usage.completion_tokens,
totalTokens: evt.usage.total_tokens,
};
}
}
}
const elapsedMs = Date.now() - t0;
res.write(`event: done\ndata: ${JSON.stringify({ elapsedMs, firstTokenMs, usage })}\n\n`);
res.write('data: [DONE]\n\n');
res.end();
return { usage, elapsedMs };
}
// Stream Vertex-served Claude to the /brain page using the same SSE protocol as
// the AI SDK path. Vertex returns first-party Anthropic Messages SSE, so we parse
// content_block_delta text_delta events and re-emit them as brain first/chunk/done
// events. Like streamWatsonx it only throws before writing tokens (a non-ok
// upstream or connection failure), so streamBrain can fall back to the free chain.
async function streamVertex(res, { messages, system, maxTokens, t0, model }) {
const upstream = await vertexAnthropicMessages(
{ model, max_tokens: maxTokens, ...(system ? { system } : {}), messages },
{ stream: true },
);
if (!upstream.ok || !upstream.body) {
const detail = await upstream.text().catch(() => '');
throw new Error(`vertex ${upstream.status}: ${detail.slice(0, 200)}`);
}
const reader = upstream.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let firstTokenMs = null;
let inputTokens = 0;
let outputTokens = 0;
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop();
for (const line of lines) {
if (!line.startsWith('data:')) continue;
const raw = line.slice(5).trim();
if (!raw || raw === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(raw);
} catch {
continue;
}
if (evt.type === 'message_start') {
inputTokens = evt.message?.usage?.input_tokens ?? inputTokens;
} else if (evt.type === 'content_block_delta' && evt.delta?.type === 'text_delta') {
const text = evt.delta.text || '';
if (text) {
if (firstTokenMs === null) {
firstTokenMs = Date.now() - t0;
res.write(`event: first\ndata: ${JSON.stringify({ firstTokenMs })}\n\n`);
}
res.write(`data: ${JSON.stringify(text)}\n\n`);
}
} else if (evt.type === 'message_delta') {
outputTokens = evt.usage?.output_tokens ?? outputTokens;
}
}
}
const elapsedMs = Date.now() - t0;
const usage = { inputTokens, outputTokens, totalTokens: inputTokens + outputTokens };
res.write(`event: done\ndata: ${JSON.stringify({ elapsedMs, firstTokenMs, usage })}\n\n`);
res.write('data: [DONE]\n\n');
res.end();
return { usage, elapsedMs };
}
export function validateMessages(input) {
if (!Array.isArray(input)) {
throw Object.assign(new Error('messages must be an array'), { status: 400 });
}
if (input.length === 0 || input.length > 100) {
throw Object.assign(new Error('messages length out of range'), { status: 400 });
}
const out = [];
for (const m of input) {
if (!m || typeof m !== 'object') throw Object.assign(new Error('bad message'), { status: 400 });
const role = m.role;
const content = typeof m.content === 'string' ? m.content.slice(0, 16000) : '';
if (!['user', 'assistant'].includes(role)) {
throw Object.assign(new Error('role must be user|assistant'), { status: 400 });
}
if (!content.trim()) throw Object.assign(new Error('empty content'), { status: 400 });
out.push({ role, content });
}
return out;
}
export function getAvailableProviders() {
return Object.entries(PROVIDERS).map(([key, spec]) => {
const available = Boolean(buildPrimary(spec));
return {
key,
label: spec.label,
network: spec.network,
tier: spec.tier,
maxOutput: spec.maxOutput,
context: spec.context || null,
description: spec.description,
roster: Boolean(spec.roster),
// The model the key routes to when it has no native lane (or as its
// mirror): what three://models prices against, since keys like
// ibm-granite name no priced model themselves.
openrouterModel: spec.openrouterModel || null,
available,
// `available` means the deployment holds a route for the model;
// `requiresAuth` means the caller still needs a session to use it
// (the anon gate below). A client that cannot tell them apart offers
// a signed-out visitor a model that can only answer 401, which is
// exactly what the brain page used to do with its default line-up.
requiresAuth: !ANON_BRAIN_PROVIDERS.has(key),
};
});
}
// Resolve a provider key into a streamable plan: the spec, its primary route
// (native key or OpenRouter mirror), and a distinct OpenRouter fallback when one
// exists. Returns { ok: false, status, code, message, available? } when the key
// is unknown or no route is configured, so every caller (the brain page handler
// and the live Q&A concierge) reports the same errors identically.
// Retired provider keys still stored in user prefs resolve to their successor
// model instead of a 400 (gpt-4o family deprecated upstream July 2026).
// Retired menu entries whose upstream model is gone (Groq dropped Llama; NIM
// answers 410/404 for DeepSeek V4 Pro, MiniMax M2.7 and Kimi K2.6, and the
// "Llama 4 Maverick" entry was never Llama) map to the roster row that serves
// the same family today, so an agent that stored one keeps answering.
const PROVIDER_ALIASES = {
'gpt-4o': 'gpt-5.6-sol',
'gpt-4o-mini': 'gpt-5.6-luna',
'o3-mini': 'o3',
'groq-llama': 'llama-3.3-70b',
'nvidia-llama4-maverick': 'llama-4-maverick',
'nvidia-deepseek-v4': 'deepseek-v4-flash',
'nvidia-kimi-k2': 'kimi-k2',
'nvidia-minimax-m2': 'gpt-oss-120b',
// Retired Grok slugs, and live Grok models a menu no longer lists, resolve to
// the menu model that replaces them (GROK_RETIRED_ALIASES, then each
// model's `supersededBy`), so a saved pick keeps answering on a current model.
...Object.fromEntries(
[...Object.keys(GROK_RETIRED_ALIASES), ...GROK_MODELS.filter((m) => !m.menu).map((m) => m.id)]
.map((id) => [id, grokMenuModelId(id)])
.filter(([, to]) => to),
),
};
/**
* The live provider key a request should be served on: a retired key maps to its
* successor, everything else passes through unchanged. EVERY key-keyed decision
* (the anon-tier gate, the thinking-model token floor, the spec lookup) has to run
* on this value, or the alias table is dead: the handler used to reject `gpt-4o`
* with a 400 before resolveBrain() ever saw it, which is exactly the key
* packages/brain-mcp advertises to MCP clients in its chat tool schema.
* Exported for tests.
*/
export function canonicalProviderKey(providerKey) {
return PROVIDER_ALIASES[providerKey] || providerKey;
}
export function resolveBrain(providerKey) {
const spec = PROVIDERS[canonicalProviderKey(providerKey)];
if (!spec) {
return {
ok: false,
status: 400,
code: 'unknown_provider',
message: `unknown provider: ${providerKey}`,
available: Object.keys(PROVIDERS),
};
}
const primary = buildPrimary(spec);
if (!primary && spec.roster) {
return {
ok: false,
status: 503,
code: 'model_unavailable',
message: `${spec.label} has no reachable route on this deployment right now. Pick another model or try again shortly.`,
};
}
if (!primary) {
return {
ok: false,
status: 503,
code: 'provider_not_configured',
message: `No API key for ${spec.label}. Add your own key in Account → AI Provider Keys to unlock this model.`,
};
}
return { ok: true, spec, primary, fallbackModel: buildFallback(spec, primary) };
}
// Stream a brain completion to an SSE `res`: sets the event-stream headers, emits
// the `meta` event, then runs the requested route → OpenRouter mirror → free-tier
// safety-net chain, emitting `first` / chunk / `done` / `error` / `fallback`
// events. Shared by POST /api/brain/chat and POST /api/agent-ask so both inherit
// the same tuned timeout budget and never-error-while-a-free-route-can-answer
// behaviour. The caller owns auth, rate limiting, and message validation; this
// owns the transport. Resolve `plan` via resolveBrain() first.
export async function streamBrain(res, { plan, providerKey, messages, system, maxTokens, userId = null, onMetered = null }) {
const { spec, primary, fallbackModel } = plan;
res.statusCode = 200;
res.setHeader('content-type', 'text/event-stream; charset=utf-8');
res.setHeader('cache-control', 'no-cache, no-transform');
res.setHeader('connection', 'keep-alive');
res.setHeader('x-accel-buffering', 'no');
const t0 = Date.now();
res.write(`event: meta\ndata: ${JSON.stringify({
provider: providerKey,
label: spec.label,
network: spec.network,
tier: spec.tier,
})}\n\n`);
// Per-attempt abort budget. A hung native provider must not silently consume
// the whole maxDuration; cap each streamText attempt at the smaller of
// PER_ATTEMPT_MS or the remaining wall-clock so it aborts fast and hands off
// to the OpenRouter fallback while time remains. Mirrors the timeout-budget
// pattern in api/chat.js. TOTAL_BUDGET_MS leaves headroom under maxDuration=120
// so a primary-then-fallback pair both fit; PER_ATTEMPT_MS stays under the
// ~30s hang that previously near-timed-out the function.
const TOTAL_BUDGET_MS = 110_000;
const PER_ATTEMPT_MS = 25_000;
const deadline = t0 + TOTAL_BUDGET_MS;
const attemptBudgetMs = () => Math.max(1_000, Math.min(PER_ATTEMPT_MS, deadline - Date.now()));
let firstTokenMs = null;
// Drains one streamText attempt to the SSE response. firstTokenMs is set on
// the first delta; once tokens have been written we are committed and can no
// longer transparently retry (the client already has partial output).
const streamOnce = async (budget, model) => {
// The SDK's default onError console.errors the entire provider error object
// (the giant 402/429 dumps in the logs). We own error handling via the
// retry/fallback chain below, so capture it here instead. Some providers
// report a pre-stream failure through onError rather than by throwing from
// textStream — surfacing the captured error keeps the chain working either way.
let streamErr = null;
const result = streamText({
model,
system,
messages,
maxOutputTokens: budget,
// maxRetries: 0 — the outer retry/fallback chain owns retries. The SDK
// default of 2 means a quota-exhausted or credits-depleted key burns
// ~10–20s retrying before surfacing the error we already know to route around.
maxRetries: 0,
// Bound this attempt by the remaining wall-clock so a hung provider
// aborts fast and the outer chain can fall back while time remains. The
// abort surfaces as a thrown error (or via onError) handled below.
abortSignal: AbortSignal.timeout(attemptBudgetMs()),
onError: ({ error }) => {
streamErr = error;
},
});
// Reasoning-tuned models (Nemotron, DeepSeek) emit their chain-of-thought
// inline in <think>…</think> before the answer. Strip it from the visible
// stream so the chat never shows scratch work. Enabled only for specs that
// actually emit traces (spec.reasoningTrace) — a no-op for every other model
// — and the filter is streaming-safe, so a tag split across deltas is still
// caught. Fallback routes are non-reasoning, so the same stripper is a no-op
// there too.
const stripper = spec.reasoningTrace ? createReasoningStripper() : null;
// Emit one visible text fragment, marking first-token timing on the first
// fragment the client actually sees (not on suppressed reasoning) — so the
// retry/fallback chain stays free to switch routes until real output streams.
const emit = (text) => {
if (!text) return;
if (firstTokenMs === null) {
firstTokenMs = Date.now() - t0;
res.write(`event: first\ndata: ${JSON.stringify({ firstTokenMs })}\n\n`);
}
res.write(`data: ${JSON.stringify(text)}\n\n`);
};
for await (const delta of result.textStream) {
emit(stripper ? stripper.push(delta) : delta);
}
// Flush any text the filter held at the boundary (a trailing partial tag that
// turned out to be real); an unterminated trace is dropped.
if (stripper) emit(stripper.flush());
// Failure before any token streamed → hand to the retry/fallback logic.
// A failure *after* partial output isn't retryable, so we finish cleanly
// with whatever was produced.
//
// A route can also end a stream having emitted NOTHING and reported no
// error: the per-attempt abort fires before the first token on a slow free
// route, or the upstream returns an empty completion. Silently writing
// `done` there ends the response 200-with-no-text and skips the entire
// fallback chain, so the caller gets a blank answer while healthy routes
// sit unused. Zero visible output is a failed attempt: throw so the next
// route runs, and if every route comes up empty the outer catch surfaces a
// real `error` event instead of a fake success.
if (firstTokenMs === null) throw streamErr || new Error('provider streamed no output');
const usage = await result.usage.catch(() => null);
const elapsedMs = Date.now() - t0;
res.write(`event: done\ndata: ${JSON.stringify({
elapsedMs,
firstTokenMs,
usage: usage ? {
inputTokens: usage.inputTokens,
outputTokens: usage.outputTokens,
totalTokens: usage.totalTokens,
} : null,
})}\n\n`);
res.write('data: [DONE]\n\n');
res.end();
return { usage, elapsedMs };
};
// Ordered attempt list: the requested route first, its OpenRouter mirror
// second, then the free-tier safety net (Groq → OpenRouter :free across every
// key → NVIDIA NIM). Any attempt that fails BEFORE the first token — auth
// failure on a dead server key, quota exhaustion, rate limit, hang, 5xx —
// hands off to the next route, so a single bad provider never surfaces as an
// error event while any free provider can still answer. Once partial output
// has streamed we are committed to that attempt.
try {
// `meter` names the lane in the spend ledger: { provider, model } as
// llm-pricing.js understands them. Every attempt that can draw money
// carries one, so no /brain turn lands in the ledger unattributed. The
// watsonx lane is the one exception: IBM bills its trial entitlement
// outside per-token pricing, so there is no honest number to record.
const attempts =
primary.kind === 'watsonx'
? [{ label: 'watsonx', watsonx: true }]
: primary.kind === 'vertex'
? [{ label: 'vertex', vertex: true, model: primary.model, meter: { provider: 'vertex-anthropic', model: primary.model } }]
: primary.kind === 'roster'
? primary.transports.map((t) => ({
label: `${t.name}/${t.model}`,
rosterTransport: t,
meter: { provider: t.name.split('#')[0], model: t.model },
}))
: [{ label: 'primary', model: primary.model, meter: meterForPrimary(spec, primary) }];
if (fallbackModel) {
attempts.push({
label: 'openrouter-mirror',
model: fallbackModel,
meter: { provider: 'openrouter', model: spec.openrouterModel },
});
}
// A safety-net rung that repeats a roster route (same lane and model) would
// fail the same way twice, so it is skipped.
const tried = new Set(attempts.filter((a) => a.meter).map((a) => `${a.meter.provider}|${a.meter.model}`));
for (const f of freeFallbackChain(providerKey, spec, primary)) {
if (f.meter && tried.has(`${f.meter.provider.split('#')[0]}|${f.meter.model}`)) continue;
attempts.push(f);
}
let lastErr = null;
for (const [i, attempt] of attempts.entries()) {
if (firstTokenMs !== null || res.writableEnded) return;
// Leave the attempt at least a second of wall-clock to connect.
if (i > 0 && Date.now() >= deadline - 1_000) break;
if (i > 0) {
console.warn(`[brain:${providerKey}] ${attempts[i - 1].label} failed (${conciseReason(lastErr)}); falling back to ${attempt.label}`);
// Advisory for the client (current page ignores unknown events).
res.write(`event: fallback\ndata: ${JSON.stringify({ route: attempt.label })}\n\n`);
}
// Record one completed attempt in the spend ledger. Runs after the
// response has already ended, so it never adds latency to the turn.
const meterAttempt = (outcome) => {
if (!attempt.meter) return;
onMetered?.({ provider: attempt.meter.provider, model: attempt.meter.model, usage: outcome?.usage });
recordBrainSpend({
provider: attempt.meter.provider,
model: attempt.meter.model,
usage: outcome?.usage,
latencyMs: outcome?.elapsedMs ?? Date.now() - t0,
userId,
providerKey,
laneLabel: attempt.label,
reportedCostUsd: reportedCostFor(attempt.model),
});
};
try {
// watsonx.ai isn't an AI SDK model — stream it through the shared
// client, emitting the same first/chunk/done event protocol. It only
// throws before writing tokens, so falling through is safe.
if (attempt.watsonx) await streamWatsonx(res, { messages, system, maxTokens, t0 });
else if (attempt.vertex)
meterAttempt(await streamVertex(res, { messages, system, maxTokens, t0, model: attempt.model }));
else if (attempt.rosterTransport) {
const { model: rosterSdkModel, budget } = rosterSdkModelFor(attempt.rosterTransport, maxTokens);
meterAttempt(await streamOnce(budget, rosterSdkModel));
} else if (attempt.vertexGemini) {
// Credits anchor: OpenAI-compatible Vertex endpoint, bearer token
// minted per attempt (a token-exchange failure throws here and is
// handled like any other lane failure). Reuses streamOnce so the
// budget/abort/onError machinery is identical to every other lane.
// Gemini reasons by default and its reasoning tokens are billed
// against max_tokens without being returned, so an uncompensated
// budget streams a truncated answer. vertexGeminiBudget caps the
// reasoning and funds it on top of the caller's budget; the SDK has
// no field for Vertex's `extra_body`, so it rides in on a fetch that
// splices it into the outgoing payload.
const budget = vertexGeminiBudget(maxTokens);
const anchorModel = createOpenAI({
apiKey: await vertexGeminiAccessToken(),
baseURL: vertexGeminiOpenAIBase(),
fetch: (url, init) =>
fetch(url, { ...init, body: withVertexExtraBody(init?.body, budget.extra_body) }),
}).chat(vertexGeminiModel());
meterAttempt(await streamOnce(budget.max_tokens, anchorModel));
} else meterAttempt(await streamOnce(maxTokens, attempt.model));
return;
} catch (err) {
lastErr = err;
// OpenRouter free tier: "requires more credits, or fewer max_tokens.
// You requested up to 1024 tokens, but can only afford 788." Retry this
// route once at the affordable ceiling before moving on.
const affordable = attempt.model ? affordableBudget(err) : null;
if (affordable && firstTokenMs === null && !res.writableEnded) {
try {
meterAttempt(await streamOnce(affordable, attempt.model));
return;
} catch (err2) {
lastErr = err2;
}
}
}
}
throw lastErr || new Error('no provider route available');
} catch (err) {
const elapsedMs = Date.now() - t0;
// The SDK no longer logs for us (onError is captured), so emit one concise
// server line for observability — not the multi-screen error object.
console.warn(`[brain:${providerKey}] stream failed: ${conciseReason(err)}`);
if (!res.writableEnded) {
try {
res.write(`event: error\ndata: ${JSON.stringify({
message: userFacingStreamError(err),
reason: conciseReason(err),
elapsedMs,
})}\n\n`);
res.end();
} catch {
// connection already closed — swallow to prevent unhandled rejection
}
}
}
}
export default wrap(async function handler(req, res) {
if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
if (req.method === 'GET') {
const providers = getAvailableProviders();
res.setHeader('content-type', 'application/json');
res.setHeader('cache-control', 'public, s-maxage=60, stale-while-revalidate=120');
res.end(JSON.stringify({ providers }));
return;
}
if (!method(req, res, ['POST'])) return;
// Auth + rate limiting. The paid flagship models run on the server's billed
// API keys, so an unmetered, unauthenticated proxy is a direct financial-drain
// vector. Authenticated callers get a generous per-user budget; anonymous
// callers a tight per-IP one and access only to the free-tier providers.
const session = await getSessionUser(req);
const bearer = session ? null : await authenticateBearer(extractBearer(req));
const userId = session?.id ?? bearer?.userId ?? null;
if (userId) {
const rl = await limits.brainChatUser(userId);
if (!rl.success) return rateLimited(res, rl, 'too many chat requests, slow down');
} else {
const rl = await limits.brainChatIp(clientIp(req));
if (!rl.success) return rateLimited(res, rl, 'too many anonymous chat requests, try again shortly');
}
let body;
try {
body = await readJson(req, 200_000);
} catch (e) {
return error(res, e.status || 400, 'bad_request', e.message);
}
// Retired keys resolve to their successor before anything else reads them, so
// the anon-tier gate, the plan, and the output-token floor all judge the model
// that will actually serve the turn rather than the name the caller sent.
const providerKey = canonicalProviderKey(String(body.provider || 'gpt-oss-120b'));
const spec = PROVIDERS[providerKey];
if (!spec) {
return error(res, 400, 'unknown_provider', `unknown provider: ${providerKey}`, {
available: Object.keys(PROVIDERS),
});
}
// Paid first-party models are sign-in only — anonymous callers are clamped to
// the free tiers so they can't burn the server's billed Anthropic/OpenAI keys.
if (!userId && !ANON_BRAIN_PROVIDERS.has(providerKey)) {
return error(res, 401, 'unauthorized', 'sign in to use this model');
}
// Validate the caller's own input before resolving routes: a malformed message
// list is the caller's 400 to fix, and reporting it as the provider's 503
// ("add your own key") sends them after the wrong problem entirely.
let messages;
try {
messages = validateMessages(body.messages);
} catch (e) {
return error(res, e.status || 400, 'bad_request', e.message);
}
const plan = resolveBrain(providerKey);
if (!plan.ok) {
return error(res, plan.status, plan.code, plan.message,
plan.available ? { available: plan.available } : undefined);
}
const system = typeof body.system === 'string' ? body.system.slice(0, 8000) : undefined;
const maxTokens = resolveMaxTokens(body.maxTokens, providerKey, plan.spec.maxOutput);
// A free open model costs the caller nothing per message but draws one unit
// from the daily free-tier allowance (api/_lib/free-tier.js); a spent
// allowance is the same 429 body every message surface answers with.
// `paid_fallback: true` is the caller's one-step approval of the paid route
// (the choice the 429 body offers): skip the free tier, gate on credits,
// and bill every metered attempt of this turn to the account.
const paidFallback = body.paid_fallback === true && !!userId;
let onMetered = null;
if (paidFallback) {
try {
await assertInferenceAllowed({ userId });
} catch (err) {
if (!(err.status >= 400 && err.status < 500)) throw err;
return error(res, err.status, err.code, err.message);
}
onMetered = ({ provider, model, usage }) => {
if (!usage) return;
void chargeInference({
userId,
callId: randomUUID(),
inputTokens: usage.inputTokens ?? 0,
outputTokens: usage.outputTokens ?? 0,
provider,
model,
}).catch((err) => console.warn(`[brain:${providerKey}] paid fallback charge failed: ${err?.message}`));
};
} else {
const freeTier = await meterFreeTurn(res, providerKey, { userId, ip: userId ? null : clientIp(req) }, {
signedIn: !!userId,
paidFallback: { method: 'POST', path: '/api/brain/chat' },
});
if (freeTier === false) return;
if (freeTier) res.setHeader('x-free-tier-remaining', String(freeTier.remaining));
}
await streamBrain(res, { plan, providerKey, messages, system, maxTokens, userId, onMetered });
});
/**
* Draw one free-tier unit when the provider key is a free open model. Returns
* the allowance after the draw, null for a model the free tier does not cover,
* or false after answering 429 on a spent allowance. Exported for tests.
*/
export async function meterFreeTurn(res, providerKey, who, ctx = {}) {
try {
return await meterFreeModel(providerKey, who);
} catch (err) {
if (!(err instanceof FreeTierExhaustedError)) throw err;
res.setHeader('Retry-After', String(retryAfterSeconds(err.resetAt)));
error(res, 429, 'free_tier_exhausted', err.message, freeTierErrorBody(err, ctx));
return false;
}
}
/**
* Output-token budget for one /brain turn, clamped to what the model can serve.
*
* The historical 64-token floor assumes the whole budget becomes visible text.
* That is false for a thinking-by-default model, where `max_tokens` covers
* reasoning AND the reply — a caller asking for 100 tokens there gets a turn
* spent entirely on reasoning that streams back nothing, with no error to
* explain it. Those models get a floor with room for both. The model's own
* `maxOutput` still caps the result, and a generous request is never lowered.
*
* (For the Claude entries the provider key IS the model id — see PROVIDERS.)
* Exported for tests.
*/
export function resolveMaxTokens(requestedMaxTokens, providerKey, specMaxOutput) {
const requested = Math.max(Number(requestedMaxTokens) || 4096, 64);
const floor = modelThinksByDefault(providerKey) ? 4096 : 64;
return Math.min(Math.max(requested, floor), specMaxOutput);
}
// OpenRouter (and some OpenAI-compatible backends) reject a request whose
// max_tokens exceeds the caller's remaining credit, naming the affordable
// ceiling: "...but can only afford 788." Returns that ceiling (with a safety
// margin) so we can retry within budget, or null when the error isn't this.
function affordableBudget(err) {
const m = /can only afford (\d+)/i.exec(err?.message || '');
return m ? Math.max(64, Math.floor(Number(m[1]) * 0.9)) : null;
}
// One-line, length-capped error summary for server logs.
function conciseReason(err) {
const msg = (err?.message || String(err)).replace(/\s+/g, ' ').trim();
return msg.length > 160 ? `${msg.slice(0, 157)}…` : msg;
}
/**
* The message a visitor reads inside the model's column once every rung of the
* fallback chain has failed. The raw error belongs to the last route tried, so
* it surfaces words like "Forbidden" or "fetch failed" that describe a provider
* the visitor never chose and cannot act on. Say what happened and what to do
* instead; the precise reason still ships alongside as `reason` and is logged.
* Exported for tests.
*/
export function userFacingStreamError(err) {
const status = Number(err?.statusCode ?? err?.status) || 0;
const msg = (err?.message || '').toLowerCase();
if (status === 429 || /rate.?limit|too many requests|quota|resource[ _-]?exhausted/.test(msg)) {
return 'Every route for this model is rate limited right now. Try again in a moment, or pick another model.';
}
if (status === 401 || status === 403 || /forbidden|unauthorized|permission denied|api key/.test(msg)) {
return 'This model has no working route on this deployment right now. Pick another model while the route is restored.';
}
if (status === 404 || /not found|no such model|model.*(deprecated|retired)/.test(msg)) {
return 'This model is no longer served upstream. Pick another model.';
}
if (/timeout|timed out|aborted|deadline/.test(msg)) {
return 'This model took too long to answer. Try again, or pick a faster model.';
}
return 'This model could not answer. Try again, or pick another model.';
}