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
feat(inference): free-tier model roster with health-aware routing, per-run billing and brain chat on the new model routes
nirholasc33d2e63b80a
diff --git a/api/_lib/agents-v1/billing.js b/api/_lib/agents-v1/billing.jsnew file mode 100644index 000000000..23b082f7d--- /dev/null+++ b/api/_lib/agents-v1/billing.js@@ -0,0 +1,105 @@+// How v1 chat messages and runs pay for their model calls.+//+// Every account gets FREE_DAILY_CALLS free agent calls per UTC day. A chat+// message counts as one call, and so does each model call a run makes. The+// count comes from the rows the calls themselves write (agent_messages with+// free_tier = true, run model_call steps marked freeTier), so there is no+// separate counter to drift.+//+// Past the free allowance a call is billed from credits, one of two ways:+// • the platform's free-first chain (no model named) at the published+// three-ws/agent rate, through chargeInference (api/_lib/inference-billing.js),+// which also enforces the per-agent inference budget;+// • a paid model the caller named explicitly, at that model's list price+// (api/_lib/llm-pricing.js), because the flat agent rate would not cover it.+// assertInferenceAllowed gates every billed call up front, so an empty balance+// or an exhausted agent budget is refused before any tokens are spent.++import { sql } from '../db.js';+import { debitCredits } from '../credits.js';+import { MODEL_CATALOG } from '../chat-models.js';+import { isFreeLane } from '../llm-pricing.js';+import { assertInferenceAllowed, chargeInference } from '../inference-billing.js';++export const FREE_DAILY_CALLS = 50;++function utcDayStart(now = new Date()) {+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate()));+}++/** Whether a catalog model id draws on credits at its own price. */+export function isPaidModel(model) {+ return Boolean(model && MODEL_CATALOG[model] && !isFreeLane(MODEL_CATALOG[model].provider, model));+}++/**+ * The caller's free allowance for today.+ * @returns {Promise<{ limit: number, used: number, remaining: number, period: 'utc_day', resetsAt: string }>}+ */+export async function freeTierStatus(userId, now = new Date()) {+ const since = utcDayStart(now);+ const [row] = await sql`+ SELECT+ (SELECT count(*)::int FROM agent_messages+ WHERE user_id = ${userId} AND role = 'user' AND free_tier = true AND created_at >= ${since.toISOString()})+ ++ (SELECT count(*)::int FROM agent_run_steps s JOIN agent_runs r ON r.id = s.run_id+ WHERE r.user_id = ${userId} AND s.kind = 'model_call' AND s.created_at >= ${since.toISOString()}+ AND (s.output->>'freeTier')::boolean IS TRUE)+ AS used+ `;+ const used = Number(row?.used || 0);+ const resetsAt = new Date(since.getTime() + 86_400_000).toISOString();+ return { limit: FREE_DAILY_CALLS, used, remaining: Math.max(0, FREE_DAILY_CALLS - used), period: 'utc_day', resetsAt };+}++/**+ * Decide how the next call is paid for, and refuse it now if it cannot be.+ * @returns {Promise<{ free: boolean }>}+ */+export async function admitCall({ userId, agent, model }) {+ if (!isPaidModel(model)) {+ const tier = await freeTierStatus(userId);+ if (tier.remaining > 0) return { free: true };+ }+ await assertInferenceAllowed({ userId, agent });+ return { free: false };+}++/**+ * Bill one completed model call. `event` is the loop's model_call event.+ * @returns {Promise<{ chargedUsd: number, shortfallUsd: number }>}+ */+export async function chargeCall({ userId, agentId, callId, event, model, free }) {+ if (free) return { chargedUsd: 0, shortfallUsd: 0 };+ // The named paid model answered: bill its own metered cost.+ if (isPaidModel(model) && !event.free && event.costMicroUsd > 0) {+ const amountUsd = Math.ceil(event.costMicroUsd) / 1e6;+ try {+ const r = await debitCredits({+ userId,+ amountUsd,+ action: 'agent.model',+ refType: 'agent',+ refId: agentId,+ idempotencyKey: `agent_model:${callId}`,+ meta: { model: event.model, provider: event.provider, input_tokens: event.usage.input, output_tokens: event.usage.output },+ });+ return { chargedUsd: r.chargedUsd ?? amountUsd, shortfallUsd: 0 };+ } catch (err) {+ if (err?.code === 'insufficient_credits') return { chargedUsd: 0, shortfallUsd: amountUsd };+ throw err;+ }+ }+ const r = await chargeInference({+ userId,+ agentId,+ callId,+ inputTokens: event.usage.input,+ outputTokens: event.usage.output,+ estimated: event.usage.estimated,+ provider: event.provider,+ model: event.model,+ });+ return { chargedUsd: r.chargedUsd, shortfallUsd: r.shortfallUsd };+}diff --git a/api/_lib/chat-models.js b/api/_lib/chat-models.jsindex 8ab6f31f3..c2a752b62 100644--- a/api/_lib/chat-models.js+++ b/api/_lib/chat-models.js@@ -24,11 +24,18 @@// - mistralai/mistral-7b-instruct:free → OpenRouter 404 "No endpoints found"// - meta-llama/llama-3.2-3b-instruct:free → no tool-capable endpoint//+// Open-model roster (Llama, DeepSeek, Kimi, Mistral, Qwen, Gemini) lives in+// model-roster.js and is merged into MODEL_CATALOG below under provider+// 'roster': those ids route through their own ordered transports+// (model-routes.js), not through a single provider lane.+//// Operational note (ops must act): the OpenAI account is over quota and the// prod Anthropic key 401s. Both are intentionally ranked at the very END of// the ladder — dead final tiers that only burn an attempt after every free// lane is exhausted. Fix the keys or remove them to drop them entirely.+import { ROSTER } from './model-roster.js';+/*** Capability metadata per chat model id — the routing brain. Only models* listed here are auto-selectable; the router uses these flags to avoid@@ -57,10 +64,12 @@ export const MODEL_CATALOG = {'claude-haiku-4-5-20251001': { provider: 'anthropic', tools: true },// ── Groq free tier — fast (sub-second) and first-attempt-reliable ─────────+ // Groq retired every Llama model (GET /openai/v1/models on 2026-09-22 lists+ // only GPT-OSS and Qwen); the two Llama ids that sat here 404 and are mapped+ // forward by RETIRED_MODEL_ALIASES below.'qwen/qwen3.8-27b': { provider: 'groq', tools: true },'openai/gpt-oss-20b': { provider: 'groq', tools: true },- 'llama-3.3-70b-versatile': { provider: 'groq', tools: true },- 'llama-3.1-8b-instant': { provider: 'groq', tools: true },+ 'openai/gpt-oss-120b': { provider: 'groq', tools: true },// ── OpenRouter free tier — rate-limited per model; tool support varies ────//@@ -142,8 +151,35 @@ export const MODEL_CATALOG = {'gpt-5.3-codex': { provider: 'openai', tools: true },'o3': { provider: 'openai', tools: true },'o3-pro': { provider: 'openai', tools: true },++ // ── Open-model roster (model-roster.js). Free rows ride free lanes first and+ // draw on the daily free-tier allowance (free-tier.js); every other row is a+ // paid lane gated to signed-in callers and metered at its Vertex price.+ ...Object.fromEntries(+ ROSTER.map((m) => [m.id, { provider: 'roster', tools: m.tools, ...(m.free ? { free: true } : { paid: true }) }]),+ ),};+/**+ * Model ids an upstream retired, mapped to the live model that replaces them.+ * Agents and embeds store a model id in their config, so a retirement must not+ * turn every stored reference into a 404: resolveModelId() maps them forward.+ */+export const RETIRED_MODEL_ALIASES = {+ 'llama-3.3-70b-versatile': 'llama-3.3-70b',+ 'llama-3.1-8b-instant': 'qwen3.8-27b',+};++/** The live id for a model: a retired id maps to its successor. */+export function resolveModelId(modelId) {+ return RETIRED_MODEL_ALIASES[modelId] || modelId;+}++/** Whether a model is covered by the daily free-tier allowance. */+export function isFreeTierModel(modelId) {+ return MODEL_CATALOG[resolveModelId(modelId)]?.free === true;+}+/*** Anthropic model ids that the Vertex Claude transport (api/_lib/vertex-claude.js)* can serve when VERTEX_CLAUDE_ENABLED is set. The SAME ids serve both first-party@@ -258,7 +294,7 @@ export function promptCacheMinChars(modelId) {/** Whether a model exposes a tool/function-calling endpoint. Unknown → false. */export function modelSupportsTools(modelId) {- return MODEL_CATALOG[modelId]?.tools === true;+ return MODEL_CATALOG[resolveModelId(modelId)]?.tools === true;}/** Whether a model's upstream is moderation-gated (excluded from auto chains). */@@ -272,7 +308,7 @@ export function isModelModerationGated(modelId) {* traffic) and are metered in llm-pricing.js rather than priced to zero.*/export function isPaidModel(modelId) {- return MODEL_CATALOG[modelId]?.paid === true;+ return MODEL_CATALOG[resolveModelId(modelId)]?.paid === true;}/**diff --git a/api/_lib/free-tier.js b/api/_lib/free-tier.jsnew file mode 100644index 000000000..ca1ac43e3--- /dev/null+++ b/api/_lib/free-tier.js@@ -0,0 +1,193 @@+// Daily free-tier allowance for the free open models.+//+// A model the roster marks `free` (api/_lib/model-roster.js) costs the caller+// nothing per message, but every message on it draws one unit from a daily+// allowance. The allowance lives in app_settings['free_tier'] so it can be+// changed without a deploy:+//+// { "daily_messages": 100, "anon_daily_messages": 20 }+//+// A signed-in account is metered by user id, an anonymous caller by a hash of+// its IP. Every day resets at 00:00 UTC. When the allowance is spent, consume+// throws FreeTierExhaustedError carrying the reset time; every surface turns+// that into the same 429 `free_tier_exhausted` body (freeTierErrorBody) so a+// client parses one shape wherever it sends a message.+//+// Paid models never touch this module: they are gated to signed-in callers and+// metered in llm-pricing.js.++import { createHash } from 'node:crypto';+import { sql } from './db.js';+import { isFreeTierModel } from './chat-models.js';++export const FREE_TIER_SETTINGS_KEY = 'free_tier';++// Used only when the settings row is missing (a database the migration has+// not reached). The migration seeds the same numbers.+export const DEFAULT_FREE_TIER = Object.freeze({ daily_messages: 100, anon_daily_messages: 20 });++const SETTINGS_TTL_MS = 60_000;+const RETENTION_DAYS = 90;+let settingsCache = { value: null, at: 0 };+let lastPruneDay = null;++/** A free-tier allowance that is spent for today. */+export class FreeTierExhaustedError extends Error {+ /** @param {{ limit: number, used: number, resetAt: string, model: string|null }} info */+ constructor(info) {+ super(+ `You have used all ${info.limit} free messages for today. The allowance resets at ${info.resetAt}. ` ++ 'Sign in for a larger allowance, or pick a paid model to keep going.',+ );+ this.name = 'FreeTierExhaustedError';+ this.status = 429;+ this.code = 'free_tier_exhausted';+ this.limit = info.limit;+ this.used = info.used;+ this.resetAt = info.resetAt;+ this.model = info.model;+ }+}++function cleanCount(v, fallback) {+ const n = Number(v);+ return Number.isFinite(n) && n >= 0 ? Math.floor(n) : fallback;+}++/** Normalize a stored settings value into { daily_messages, anon_daily_messages }. */+export function normalizeFreeTierSettings(value) {+ const v = value && typeof value === 'object' ? value : {};+ return {+ daily_messages: cleanCount(v.daily_messages, DEFAULT_FREE_TIER.daily_messages),+ anon_daily_messages: cleanCount(v.anon_daily_messages, DEFAULT_FREE_TIER.anon_daily_messages),+ };+}++/** The live allowance, read from app_settings and cached for a minute. */+export async function getFreeTierSettings() {+ if (settingsCache.value && Date.now() - settingsCache.at < SETTINGS_TTL_MS) return settingsCache.value;+ const [row] = await sql`SELECT value FROM app_settings WHERE key = ${FREE_TIER_SETTINGS_KEY}`;+ const value = normalizeFreeTierSettings(row?.value);+ settingsCache = { value, at: Date.now() };+ return value;+}++/** Test seam: forget the cached settings. */+export function resetFreeTierSettingsCache() {+ settingsCache = { value: null, at: 0 };+}++/** The UTC calendar day `now` falls in, as YYYY-MM-DD. */+export function utcDay(now = new Date()) {+ return now.toISOString().slice(0, 10);+}++/** The instant the current UTC day ends, as an ISO string. */+export function nextResetAt(now = new Date()) {+ const d = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1));+ return d.toISOString();+}++/**+ * The metering subject for a caller: the account when signed in, otherwise a+ * truncated SHA-256 of the IP (the raw address is never stored).+ * @param {{ userId?: string|null, ip?: string|null }} who+ */+export function freeTierSubject({ userId = null, ip = null } = {}) {+ if (userId) return { subject: `user:${userId}`, anonymous: false };+ const hash = createHash('sha256').update(String(ip || 'unknown')).digest('hex').slice(0, 32);+ return { subject: `ip:${hash}`, anonymous: true };+}++function limitFor(settings, anonymous) {+ return anonymous ? settings.anon_daily_messages : settings.daily_messages;+}++/**+ * Today's allowance for a caller without consuming anything.+ * @param {{ userId?: string|null, ip?: string|null }} who+ */+export async function getFreeTierStatus(who) {+ const settings = await getFreeTierSettings();+ const { subject, anonymous } = freeTierSubject(who);+ const day = utcDay();+ const [row] = await sql`SELECT used FROM free_tier_usage WHERE subject = ${subject} AND day = ${day}`;+ const limit = limitFor(settings, anonymous);+ const used = Math.min(Number(row?.used || 0), limit);+ return {+ limit,+ used,+ remaining: Math.max(0, limit - used),+ resetAt: nextResetAt(),+ anonymous,+ signedInLimit: settings.daily_messages,+ };+}++/**+ * Draw one message from the caller's allowance. Atomic: the increment only+ * lands while `used` is under the limit, so concurrent requests can never+ * overshoot it. Throws FreeTierExhaustedError when nothing is left.+ * @param {{ userId?: string|null, ip?: string|null, model?: string|null }} who+ * @returns {Promise<{ limit: number, used: number, remaining: number, resetAt: string }>}+ */+export async function consumeFreeMessage({ userId = null, ip = null, model = null } = {}) {+ const settings = await getFreeTierSettings();+ const { subject, anonymous } = freeTierSubject({ userId, ip });+ const limit = limitFor(settings, anonymous);+ const day = utcDay();+ const resetAt = nextResetAt();+ if (limit <= 0) throw new FreeTierExhaustedError({ limit, used: 0, resetAt, model });++ const rows = await sql`+ INSERT INTO free_tier_usage (subject, day, used)+ VALUES (${subject}, ${day}, 1)+ ON CONFLICT (subject, day) DO UPDATE+ SET used = free_tier_usage.used + 1, updated_at = now()+ WHERE free_tier_usage.used < ${limit}+ RETURNING used+ `;+ if (!rows.length) throw new FreeTierExhaustedError({ limit, used: limit, resetAt, model });+ pruneOldUsage(day);+ const used = Number(rows[0].used);+ return { limit, used, remaining: Math.max(0, limit - used), resetAt };+}++// Retention runs at most once per instance per day and never blocks the+// request that triggered it.+function pruneOldUsage(day) {+ if (lastPruneDay === day) return;+ lastPruneDay = day;+ sql`DELETE FROM free_tier_usage WHERE day < (now() AT TIME ZONE 'utc')::date - ${RETENTION_DAYS}::int`.catch((err) =>+ console.warn(`[free-tier] prune failed: ${err?.message || err}`),+ );+}++/**+ * Consume an allowance unit only when the model is a free-tier model. Paid and+ * unknown models pass through untouched (null).+ * @param {string|null|undefined} model+ * @param {{ userId?: string|null, ip?: string|null }} who+ */+export async function meterFreeModel(model, who) {+ if (!model || !isFreeTierModel(model)) return null;+ return consumeFreeMessage({ ...who, model });+}++/** The one JSON body every surface answers an exhausted allowance with. */+export function freeTierErrorBody(err) {+ return {+ error: 'free_tier_exhausted',+ error_description: err.message,+ message: err.message,+ limit: err.limit,+ used: err.used,+ reset_at: err.resetAt,+ model: err.model || null,+ };+}++/** Seconds until the allowance resets, for a Retry-After header. */+export function retryAfterSeconds(resetAt) {+ return Math.max(1, Math.ceil((Date.parse(resetAt) - Date.now()) / 1000));+}diff --git a/api/_lib/llm-health.js b/api/_lib/llm-health.jsindex 8613e7312..37c60cd32 100644--- a/api/_lib/llm-health.js+++ b/api/_lib/llm-health.js@@ -196,3 +196,123 @@ export async function probeLlmHealth() {report.overall = overall;return report;}++// ── Open-model roster health ─────────────────────────────────────────────────+// Per-model health for the model picker: every reachable route of every roster+// model (api/_lib/model-roster.js) gets the same max_tokens:1 ping, and the+// model is judged by its routes in order:+// ok the first reachable route answered+// degraded the first route failed but a later route of the SAME model+// answered (the model works, on a failover lane)+// down no route answered: messages on it fall through to the+// platform chain and are answered by another model+// unavailable this deployment has no credential for any of its routes+// `latencyMs` is the round-trip of the route that would serve the next call.+// Results are cached (Redis when configured, memory otherwise) for five+// minutes and a probe already in flight is shared, so a busy picker costs one+// sweep per window, not one per page view.++const ROSTER_HEALTH_KEY = 'llm:roster-health:v1';+const ROSTER_HEALTH_TTL_S = 300;+const ROSTER_PROBE_TIMEOUT_MS = 10_000;+let rosterSweep = null;++async function probeRosterTransport(transport) {+ const { transportHeaders } = await import('./model-routes.js');+ // The rawPredict surface answers a non-streaming ping; the streaming URL+ // would hold the socket open for an SSE body the probe never reads.+ const url = transport.name === 'vertex-mistral' ? transport.url.replace(':streamRawPredict', ':rawPredict') : transport.url;+ let headers;+ try {+ headers = await transportHeaders(transport);+ } catch (err) {+ return { status: 'error', error: `auth failed: ${err?.message || 'unknown'}`, latencyMs: 0 };+ }+ const started = Date.now();+ try {+ const res = await fetch(url, {+ method: 'POST',+ headers,+ body: JSON.stringify({ model: transport.model, max_tokens: 1, messages: [{ role: 'user', content: 'ping' }] }),+ signal: AbortSignal.timeout(ROSTER_PROBE_TIMEOUT_MS),+ });+ const latencyMs = Date.now() - started;+ if (res.ok) return { status: 'ok', latencyMs };+ const detail = (await res.text().catch(() => '')).slice(0, 160).replace(/\s+/g, ' ');+ return { status: 'error', error: `${res.status}${detail ? ` ${detail}` : ''}`, latencyMs };+ } catch (err) {+ const latencyMs = Date.now() - started;+ return { status: 'error', error: err?.name === 'TimeoutError' ? `timed out after ${ROSTER_PROBE_TIMEOUT_MS}ms` : 'unreachable', latencyMs };+ }+}++/**+ * Fold one model's per-route verdicts (in route order) into its health.+ * Exported for tests.+ * @param {Array<{ lane: string, status: string, latencyMs: number, error?: string }>} routes+ */+export function judgeRosterModel(routes) {+ if (!routes.length) return { status: 'unavailable', latencyMs: null, lane: null, routes };+ const firstOk = routes.findIndex((r) => r.status === 'ok');+ if (firstOk === -1) return { status: 'down', latencyMs: null, lane: null, routes };+ return {+ status: firstOk === 0 ? 'ok' : 'degraded',+ latencyMs: routes[firstOk].latencyMs,+ lane: routes[firstOk].lane,+ routes,+ };+}++async function sweepRoster() {+ const [{ ROSTER }, { rosterTransports }] = await Promise.all([import('./model-roster.js'), import('./model-routes.js')]);+ const models = {};+ await Promise.all(+ ROSTER.map(async (m) => {+ // One probe per distinct route: the OpenRouter fan-out shares a model+ // id across keys, and the first key answers for the lane.+ const seen = new Set();+ const transports = rosterTransports(m.id).filter((t) => {+ const lane = t.name.split('#')[0];+ const k = `${lane}|${t.model}`;+ if (seen.has(k)) return false;+ seen.add(k);+ return true;+ });+ const verdicts = await Promise.all(+ transports.map(async (t) => ({ lane: t.name.split('#')[0], model: t.model, ...(await probeRosterTransport(t)) })),+ );+ models[m.id] = judgeRosterModel(verdicts);+ }),+ );+ return { checkedAt: new Date().toISOString(), models };+}++/**+ * Live health of every roster model, cached for five minutes.+ * @param {{ fresh?: boolean }} [opts] `fresh` skips the cache (ops dashboards)+ */+export async function probeRosterHealth({ fresh = false } = {}) {+ const { cacheGet, cacheSet } = await import('./cache.js');+ if (!fresh) {+ const cached = await cacheGet(ROSTER_HEALTH_KEY).catch(() => null);+ if (cached?.models) return cached;+ }+ if (!rosterSweep) {+ rosterSweep = sweepRoster()+ .then(async (report) => {+ await cacheSet(ROSTER_HEALTH_KEY, report, ROSTER_HEALTH_TTL_S).catch(() => {});+ return report;+ })+ .finally(() => {+ rosterSweep = null;+ });+ }+ return rosterSweep;+}++/** The cached roster health without probing, or null when nothing is cached. */+export async function cachedRosterHealth() {+ const { cacheGet } = await import('./cache.js');+ const cached = await cacheGet(ROSTER_HEALTH_KEY).catch(() => null);+ return cached?.models ? cached : null;+}diff --git a/api/_lib/llm-pricing.js b/api/_lib/llm-pricing.jsindex d48ec467d..d56b32f8e 100644--- a/api/_lib/llm-pricing.js+++ b/api/_lib/llm-pricing.js@@ -27,6 +27,7 @@// gap is visible instead of masquerading as free traffic.import { isPaidModel } from './chat-models.js';+import { ROSTER, isVertexRoute } from './model-roster.js';// USD per 1,000,000 tokens, [input, output]. Keys are matched by prefix so a// dated alias (claude-haiku-4-5-20251001) resolves to its family price.@@ -74,6 +75,15 @@ const PRICE_PER_MTOK = {// OpenRouter IBM Granite (BYOK) — the funded key draws real spend, so it is// metered here despite openrouter being a free provider (see isPaidModel).'ibm-granite/granite-4.1-8b': [0.05, 0.1],+ // Open-model roster: the roster id and each Vertex upstream id price at the+ // row's Vertex list price, so a turn metered under either name (the catalog+ // quotes the roster id, the ledger records the upstream id) costs the same.+ ...Object.fromEntries(+ ROSTER.flatMap((m) => [+ [m.id, m.price],+ ...m.routes.filter(isVertexRoute).map((r) => [r.model, m.price]),+ ]),+ ),};// Providers whose marginal cost to the platform is zero (platform-funded freediff --git a/api/_lib/llm-tool-chain.js b/api/_lib/llm-tool-chain.jsindex 6b4a7b641..2429be672 100644--- a/api/_lib/llm-tool-chain.js+++ b/api/_lib/llm-tool-chain.js@@ -10,13 +10,15 @@// handles them all.import { env } from './env.js';-import { DEFAULT_FREE_MODEL, MODEL_CATALOG } from './chat-models.js';+import { DEFAULT_FREE_MODEL, MODEL_CATALOG, resolveModelId } from './chat-models.js';import {vertexGeminiAvailable,vertexGeminiModel,vertexGeminiChatUrl,vertexGeminiHeaders,+ vertexGeminiBudget,} from './vertex-gemini.js';+import { rosterTransports } from './model-routes.js';// ── provider chain (free-first, OpenAI-compatible tool-calling + streaming) ────// Mirrors the platform policy in api/_lib/llm.js: free platform keys lead, the@@ -111,6 +113,14 @@ export async function streamRound(provider, { messages, tools, onContent, temper// 400 here would fail the rung over for no reason. Other lanes still get// their usage read when they volunteer it.if (USAGE_OPTION_LANES.has(baseLane(provider.name))) body.stream_options = { include_usage: true };+ // Gemini on a roster Vertex route reasons by default and bills that+ // reasoning against max_tokens without returning it; cap it and fund it on+ // top so the visible budget stays what the loop asked for.+ if (provider.name === 'vertex' && String(provider.model).startsWith('google/')) {+ const budget = vertexGeminiBudget(body.max_tokens);+ body.max_tokens = budget.max_tokens;+ body.extra_body = budget.extra_body;+ }if (Array.isArray(tools) && tools.length) { body.tools = tools; body.tool_choice = 'auto'; }// Keyless lanes (the Vertex Gemini credits anchor) mint their auth per request// via getHeaders; a token-exchange failure throws here and fails over to the@@ -209,11 +219,31 @@ export function anthropicMirrorId(model) {/*** A single tool-loop rung that serves exactly `model`, or null when no* configured key can reach it. Used to honor an explicit model choice while- * the free chain stays behind it as the failover.+ * the free chain stays behind it as the failover. Roster models have several+ * rungs; this returns the first reachable one (modelRungs returns them all).* @param {string} model a MODEL_CATALOG id*/export function modelRung(model) {+ return modelRungs(model)[0] || null;+}++/**+ * Every tool-loop rung that serves exactly `model`, in failover order. A roster+ * model (model-roster.js) contributes one rung per reachable route; any other+ * catalog model contributes its single lane. Models without tool calling have+ * no rungs: the tool loop must never be pointed at them.+ * @param {string} requested a MODEL_CATALOG id (a retired id maps forward)+ */+export function modelRungs(requested) {+ const model = resolveModelId(requested);const meta = MODEL_CATALOG[model];+ if (!meta || !meta.tools) return [];+ if (meta.provider === 'roster') return rosterTransports(model);+ const rung = singleLaneRung(model, meta);+ return rung ? [rung] : [];+}++function singleLaneRung(model, meta) {if (!meta || !meta.tools) return null;if (meta.provider === 'anthropic') {if (!env.OPENROUTER_API_KEY) return null;@@ -236,13 +266,16 @@ export function modelRung(model) {/*** The provider chain for a request that may name a model: the named model's- * rung first (when reachable), then the free-first platform chain.+ * rungs first (every route that serves it, in order), then the free-first+ * platform chain behind them, minus any rung that would repeat one of them.* @param {string|null} [model]*/export function providerChainFor(model) {const chain = providerChain();if (!model) return chain;- const rung = modelRung(model);- return rung ? [rung, ...chain.filter((p) => !(p.name === rung.name && p.model === rung.model))] : chain;+ const rungs = modelRungs(model);+ if (!rungs.length) return chain;+ const seen = new Set(rungs.map((r) => `${r.name}|${r.model}`));+ return [...rungs, ...chain.filter((p) => !seen.has(`${p.name}|${p.model}`))];}diff --git a/api/_lib/migrations/20260922210000_free_tier_models.sql b/api/_lib/migrations/20260922210000_free_tier_models.sqlnew file mode 100644index 000000000..02d17dca3--- /dev/null+++ b/api/_lib/migrations/20260922210000_free_tier_models.sql@@ -0,0 +1,37 @@+-- Free-tier model allowance: a daily message budget on the free open models.+--+-- The open-model roster (api/_lib/model-roster.js) marks some models `free`.+-- A message sent on one of them costs the caller nothing, but it draws one unit+-- from a daily allowance so the free lanes behind it (and the Vertex credits+-- tail) cannot be drained by one account. api/_lib/free-tier.js owns both+-- tables' rows; nothing else writes them.+--+-- app_settings['free_tier'] the allowance: messages per UTC day for a+-- signed-in account and for an anonymous caller+-- (keyed by IP). Edit the row to change the+-- allowance; the server re-reads it every minute+-- and /pricing shows the live numbers.+-- free_tier_usage one row per (subject, UTC day). `subject` is+-- 'user:<uuid>' or 'ip:<sha256 prefix>'; the raw+-- IP is never stored. Past days are kept as usage+-- history (one small row per active caller per+-- day); free-tier.js prunes rows past 90 days.++CREATE TABLE IF NOT EXISTS app_settings (+ key text PRIMARY KEY,+ value jsonb NOT NULL,+ updated_at timestamptz NOT NULL DEFAULT now()+);++INSERT INTO app_settings (key, value)+VALUES ('free_tier', '{"daily_messages": 100, "anon_daily_messages": 20}'::jsonb)+ON CONFLICT (key) DO NOTHING;++CREATE TABLE IF NOT EXISTS free_tier_usage (+ subject text NOT NULL,+ day date NOT NULL,+ used int NOT NULL DEFAULT 0 CHECK (used >= 0),+ updated_at timestamptz NOT NULL DEFAULT now(),+ PRIMARY KEY (subject, day)+);+CREATE INDEX IF NOT EXISTS free_tier_usage_day_idx ON free_tier_usage (day);diff --git a/api/_lib/model-roster.js b/api/_lib/model-roster.jsnew file mode 100644index 000000000..69cd1eb4f--- /dev/null+++ b/api/_lib/model-roster.js@@ -0,0 +1,301 @@+// The open-model roster: every open-weights and Gemini model a user can pick+// for an agent's brain, with the ordered transport routes that serve it.+//+// One row per model. A row is the whole truth about that model on this+// platform: what to call it, who makes it, how much context it takes, whether+// it can call tools, what it costs per million tokens, whether the free tier+// covers it, and the ordered list of upstream routes that can serve it.+//+// Routes are tried in order and every route serves the SAME model (never a+// look-alike), so a failover never changes what the user picked. Free lanes the+// platform already holds lead; Vertex AI Model Garden (GCP credits, standing+// owner approval) is the route every paid model starts on and the credits-funded+// tail of the free ones that have a Vertex twin. When every route of a model+// fails, the caller's normal platform chain takes over behind it+// (llm-tool-chain.js providerChainFor, brain/chat.js freeFallbackChain), so a+// dead model degrades to an answer from another model rather than to an error.+//+// Lanes (the `lane` field of a route):+// vertex Vertex AI OpenAI-compatible endpoint (endpoints/openapi).+// Serves Gemini and every Model Garden MaaS model (Llama,+// DeepSeek, Qwen, Kimi). Keyless: a GCP OAuth token per call.+// vertex-mistral Mistral partner models on Vertex. Not on endpoints/openapi;+// served by publishers/mistralai/models/<id>:streamRawPredict,+// which takes and returns the Mistral chat format (OpenAI wire).+// nvidia | groq | ovh | openrouter | mistral | sambanova | cerebras | gemini+// The platform's existing free lanes (docs/ops/llm-lanes.md).+//+// Prices are the Vertex list price per million tokens [input, output], which is+// what the platform meters a paid route at (llm-pricing.js reads them from+// here). A free model's price is still shown: it is what a message costs the+// platform when the free lanes are exhausted and a paid tail answers.+//+// Verified 2026-09-22 with a real tool-calling request per free route:+// groq qwen/qwen3.8-27b, ovh Mistral-Small-3.2-24B-Instruct-2506 and nvidia+// deepseek-ai/deepseek-v4.1-flash each returned a get_price tool call. OVH+// answered 429 to this workspace's shared egress IP (it serves from the Cloud+// Run egress, docs/ops/llm-lanes.md). Every Vertex route answered 403+// "Lightning dunning decision is deny", a billing hold on the whole GCP+// project that only the owner can clear. The Vertex ids and regions below are+// the Model Garden MaaS ids; they serve the moment the hold lifts, and+// llm-health.js probeRosterHealth reports each route's live state so the+// picker shows "provider degraded" until then.++/**+ * @typedef {{ lane: string, model: string, location?: string }} RosterRoute+ * @typedef {{+ * id: string,+ * label: string,+ * family: string,+ * description: string,+ * context: number,+ * maxOutput: number,+ * tools: boolean,+ * free: boolean,+ * reasoning?: boolean,+ * price: [number, number],+ * routes: RosterRoute[],+ * }} RosterModel+ */++/** @type {RosterModel[]} */+export const ROSTER = [+ // ── Meta Llama ────────────────────────────────────────────────────────────+ {+ id: 'llama-3.3-70b',+ label: 'Llama 3.3 70B',+ family: 'Meta',+ description: 'Meta’s proven open 70B. Reliable tool use, free tier.',+ context: 131_072,+ maxOutput: 8192,+ tools: true,+ free: true,+ price: [0.72, 0.72],+ routes: [+ { lane: 'ovh', model: 'Meta-Llama-3_3-70B-Instruct' },+ { lane: 'sambanova', model: 'Meta-Llama-3.3-70B-Instruct' },+ { lane: 'cerebras', model: 'llama-3.3-70b' },+ { lane: 'vertex', model: 'meta/llama-3.3-70b-instruct-maas', location: 'us-central1' },+ ],+ },+ {+ id: 'llama-4-maverick',+ label: 'Llama 4 Maverick',+ family: 'Meta',+ description: 'Llama 4 flagship: 128-expert MoE, long context, strong multilingual tool use.',+ context: 524_288,+ maxOutput: 8192,+ tools: true,+ free: false,+ price: [0.35, 1.15],+ routes: [{ lane: 'vertex', model: 'meta/llama-4-maverick-17b-128e-instruct-maas', location: 'us-east5' }],+ },+ {+ id: 'llama-4-scout',+ label: 'Llama 4 Scout',+ family: 'Meta',+ description: 'Efficient Llama 4 with a very long context window. Fast and cheap.',+ context: 1_310_720,+ maxOutput: 8192,+ tools: true,+ free: false,+ price: [0.25, 0.7],+ routes: [{ lane: 'vertex', model: 'meta/llama-4-scout-17b-16e-instruct-maas', location: 'us-east5' }],+ },++ // ── DeepSeek ──────────────────────────────────────────────────────────────+ {+ id: 'deepseek-v4-flash',+ label: 'DeepSeek V4.1 Flash',+ family: 'DeepSeek',+ description: 'Current DeepSeek generation, tuned for speed. Tool calling, free tier.',+ context: 1_048_576,+ maxOutput: 8192,+ tools: true,+ free: true,+ reasoning: true,+ price: [0.15, 0.6],+ routes: [{ lane: 'nvidia', model: 'deepseek-ai/deepseek-v4.1-flash' }],+ },+ {+ id: 'deepseek-v3.1',+ label: 'DeepSeek V3.1',+ family: 'DeepSeek',+ description: 'Hybrid thinking model. Strong coding and agentic tool use.',+ context: 163_840,+ maxOutput: 8192,+ tools: true,+ free: false,+ price: [0.6, 1.7],+ routes: [{ lane: 'vertex', model: 'deepseek-ai/deepseek-v3.1-maas', location: 'us-west2' }],+ },+ {+ id: 'deepseek-r1',+ label: 'DeepSeek R1',+ family: 'DeepSeek',+ description: 'Open reasoning model for math, code and planning. Chat only: no tool calling.',+ context: 163_840,+ maxOutput: 8192,+ tools: false,+ free: false,+ reasoning: true,+ price: [1.35, 5.4],+ routes: [{ lane: 'vertex', model: 'deepseek-ai/deepseek-r1-0528-maas', location: 'us-central1' }],+ },++ // ── Moonshot Kimi ─────────────────────────────────────────────────────────+ {+ id: 'kimi-k2',+ label: 'Kimi K2 Thinking',+ family: 'Moonshot',+ description: 'Long-horizon agentic model built for long chains of sequential tool calls.',+ context: 262_144,+ maxOutput: 8192,+ tools: true,+ free: false,+ reasoning: true,+ price: [0.6, 2.5],+ routes: [{ lane: 'vertex', model: 'moonshotai/kimi-k2-thinking-maas', location: 'global' }],+ },++ // ── Mistral ───────────────────────────────────────────────────────────────+ {+ id: 'mistral-small',+ label: 'Mistral Small 3',+ family: 'Mistral',+ description: 'Compact 24B with native function calling. Fast, free tier.',+ context: 131_072,+ maxOutput: 8192,+ tools: true,+ free: true,+ price: [0.1, 0.3],+ routes: [+ { lane: 'ovh', model: 'Mistral-Small-3.2-24B-Instruct-2506' },+ { lane: 'mistral', model: 'mistral-small-latest' },+ { lane: 'vertex-mistral', model: 'mistral-small-2503', location: 'us-central1' },+ ],+ },+ {+ id: 'mistral-large',+ label: 'Mistral Large',+ family: 'Mistral',+ description: 'Mistral’s flagship. Top-tier reasoning, multilingual, function calling.',+ context: 131_072,+ maxOutput: 8192,+ tools: true,+ free: false,+ price: [2, 6],+ routes: [+ { lane: 'vertex-mistral', model: 'mistral-large-2411', location: 'us-central1' },+ { lane: 'mistral', model: 'mistral-large-latest' },+ ],+ },++ // ── Qwen ──────────────────────────────────────────────────────────────────+ {+ id: 'qwen3.8-27b',+ label: 'Qwen 3.8 27B',+ family: 'Qwen',+ description: 'Latest dense Qwen 3. Fast, sharp tool use, three free lanes behind it.',+ context: 131_072,+ maxOutput: 8192,+ tools: true,+ free: true,+ price: [0.42, 3],+ routes: [+ { lane: 'groq', model: 'qwen/qwen3.8-27b' },+ { lane: 'openrouter', model: 'qwen/qwen3.8-27b:free' },+ { lane: 'ovh', model: 'Qwen3.8-27B' },+ ],+ },+ {+ id: 'qwen3-235b',+ label: 'Qwen 3 235B',+ family: 'Qwen',+ description: 'Qwen 3 flagship MoE. Excellent multilingual reasoning and tool use.',+ context: 262_144,+ maxOutput: 8192,+ tools: true,+ free: false,+ price: [0.22, 0.88],+ routes: [{ lane: 'vertex', model: 'qwen/qwen3-235b-a22b-instruct-2507-maas', location: 'us-south1' }],+ },++ // ── Google Gemini ─────────────────────────────────────────────────────────+ {+ id: 'gemini-2.5-pro',+ label: 'Gemini 2.5 Pro',+ family: 'Google',+ description: 'Google’s most capable 2.5 model. 1M context, deep reasoning.',+ context: 1_048_576,+ maxOutput: 16384,+ tools: true,+ free: false,+ reasoning: true,+ price: [1.25, 10],+ routes: [+ { lane: 'vertex', model: 'google/gemini-2.5-pro', location: 'global' },+ { lane: 'gemini', model: 'gemini-2.5-pro' },+ ],+ },+ {+ id: 'gemini-2.5-flash',+ label: 'Gemini 2.5 Flash',+ family: 'Google',+ description: 'Fast, 1M-context Gemini with thinking. Great price to performance.',+ context: 1_048_576,+ maxOutput: 16384,+ tools: true,+ free: false,+ reasoning: true,+ price: [0.3, 2.5],+ routes: [+ { lane: 'vertex', model: 'google/gemini-2.5-flash', location: 'global' },+ { lane: 'gemini', model: 'gemini-2.5-flash' },+ ],+ },+];++const BY_ID = new Map(ROSTER.map((m) => [m.id, m]));++/** The roster row for a model id, or null. */+export function rosterModel(id) {+ return (typeof id === 'string' && BY_ID.get(id)) || null;+}++/** Whether an id names a roster model. */+export function isRosterModel(id) {+ return BY_ID.has(id);+}++/** Roster ids the free tier covers. */+export function freeRosterIds() {+ return ROSTER.filter((m) => m.free).map((m) => m.id);+}++/** Whether a route runs on Vertex (billed to GCP credits). */+export function isVertexRoute(route) {+ return route?.lane === 'vertex' || route?.lane === 'vertex-mistral';+}++/** Vertex host for a location: the global endpoint has no region prefix. */+export function vertexHost(location) {+ return location === 'global' ? 'aiplatform.googleapis.com' : `${location}-aiplatform.googleapis.com`;+}++/**+ * The full URL a Vertex route is called on. `vertex` routes use the+ * OpenAI-compatible chat-completions endpoint; `vertex-mistral` routes use the+ * partner rawPredict surface (streaming or not).+ * @param {RosterRoute} route+ * @param {{ stream?: boolean }} [opts]+ */+export function vertexRouteUrl(route, { stream = true } = {}) {+ const project = process.env.GOOGLE_CLOUD_PROJECT;+ const location = route.location || 'global';+ const root = `https://${vertexHost(location)}/v1/projects/${project}/locations/${location}`;+ if (route.lane === 'vertex-mistral') {+ return `${root}/publishers/mistralai/models/${route.model}:${stream ? 'streamRawPredict' : 'rawPredict'}`;+ }+ return `${root}/endpoints/openapi/chat/completions`;+}diff --git a/api/_lib/model-routes.js b/api/_lib/model-routes.jsnew file mode 100644index 000000000..f4a978ab3--- /dev/null+++ b/api/_lib/model-routes.js@@ -0,0 +1,117 @@+// Turn an open-model roster route (api/_lib/model-roster.js) into a concrete+// OpenAI-wire transport: the URL to POST, how to authenticate, and the upstream+// model id. One resolver for every consumer, so the tool loop+// (llm-tool-chain.js), /brain streaming (brain/chat.js) and the health probe+// (llm-health.js) can never disagree about where a model lives.+//+// A transport has the shape streamRound() in llm-tool-chain.js already takes:+// { name, url, key, model, catalogModel, extraHeaders?, getHeaders? }+// `name` is the ledger provider (llm-pricing.js prices it), `catalogModel` is+// the roster id the user picked, `model` is what the upstream is sent.+// A route whose lane has no credential on this deployment resolves to null and+// is skipped, exactly like a provider with no key in the platform chains.++import { env } from './env.js';+import { getGcpAccessToken } from './gcp-auth.js';+import { rosterModel, vertexRouteUrl } from './model-roster.js';++const OPENROUTER_HEADERS = { 'HTTP-Referer': 'https://three.ws', 'X-Title': 'three.ws' };++// Keyed lanes: URL plus the env credential that unlocks them. OVH is keyless+// (its documented anonymous tier), so its key resolves to null and is allowed.+const KEYED_LANES = {+ groq: { url: 'https://api.groq.com/openai/v1/chat/completions', key: () => env.GROQ_API_KEY },+ nvidia: { url: 'https://integrate.api.nvidia.com/v1/chat/completions', key: () => env.NVIDIA_API_KEY },+ sambanova: { url: 'https://api.sambanova.ai/v1/chat/completions', key: () => env.SAMBANOVA_API_KEY },+ cerebras: { url: 'https://api.cerebras.ai/v1/chat/completions', key: () => env.CEREBRAS_API_KEY },+ mistral: { url: 'https://api.mistral.ai/v1/chat/completions', key: () => env.MISTRAL_API_KEY },+ gemini: {+ url: 'https://generativelanguage.googleapis.com/v1beta/openai/chat/completions',+ key: () => env.GEMINI_API_KEY,+ },+ ovh: { url: 'https://oai.endpoints.kepler.ai.cloud.ovh.net/v1/chat/completions', key: () => null, keyless: true },+};++async function vertexHeaders() {+ const token = await getGcpAccessToken();+ return { authorization: `Bearer ${token}`, 'content-type': 'application/json' };+}++function openrouterKeys() {+ return [...new Set([env.OPENROUTER_API_KEY, ...(env.OPENROUTER_FALLBACK_KEYS || [])].filter(Boolean))];+}++/**+ * Resolve one route to zero or more transports. OpenRouter `:free` routes fan+ * out to one transport per key (every key has its own free quota), matching+ * how the platform chain treats that lane.+ * @param {import('./model-roster.js').RosterRoute} route+ * @param {string} catalogModel the roster id+ * @returns {object[]}+ */+export function routeTransports(route, catalogModel) {+ if (route.lane === 'vertex' || route.lane === 'vertex-mistral') {+ if (!process.env.GOOGLE_CLOUD_PROJECT) return [];+ return [+ {+ name: route.lane === 'vertex' ? 'vertex' : 'vertex-mistral',+ url: vertexRouteUrl(route, { stream: true }),+ key: null,+ model: route.model,+ catalogModel,+ location: route.location || 'global',+ getHeaders: vertexHeaders,+ },+ ];+ }+ if (route.lane === 'openrouter') {+ // Only genuinely free routes ride the fallback keys; those accounts are+ // unfunded and a paid id would 402 on every one of them.+ if (!route.model.endsWith(':free')) return [];+ return openrouterKeys().map((key, i) => ({+ name: i === 0 ? 'openrouter' : `openrouter#${i + 1}`,+ url: 'https://openrouter.ai/api/v1/chat/completions',+ key,+ model: route.model,+ catalogModel,+ extraHeaders: OPENROUTER_HEADERS,+ }));+ }+ const lane = KEYED_LANES[route.lane];+ if (!lane) return [];+ const key = lane.key();+ if (!key && !lane.keyless) return [];+ const transport = { name: route.lane, url: lane.url, key, model: route.model, catalogModel };+ // A keyless lane still needs a content-type header and must not send a+ // literal "Bearer null", so it authenticates through getHeaders.+ if (lane.keyless) transport.getHeaders = async () => ({ 'content-type': 'application/json' });+ return [transport];+}++/**+ * Every transport that can serve a roster model on this deployment, in route+ * order. Empty when the id is not a roster model or no route is reachable.+ * @param {string} modelId+ */+export function rosterTransports(modelId) {+ const row = rosterModel(modelId);+ if (!row) return [];+ return row.routes.flatMap((route) => routeTransports(route, modelId));+}++/** Whether any route of a roster model is reachable on this deployment. */+export function rosterModelAvailable(modelId) {+ return rosterTransports(modelId).length > 0;+}++/**+ * Headers for one call on a transport: a keyless/token lane mints its own, a+ * keyed lane sends its bearer.+ * @param {object} transport+ */+export async function transportHeaders(transport) {+ const base = transport.getHeaders+ ? await transport.getHeaders()+ : { 'content-type': 'application/json', authorization: `Bearer ${transport.key}` };+ return { ...base, ...(transport.extraHeaders || {}) };+}diff --git a/api/brain/chat.js b/api/brain/chat.jsindex 69a246587..d5f3d99d3 100644--- a/api/brain/chat.js+++ b/api/brain/chat.js@@ -20,6 +20,8 @@ import { getSessionUser, authenticateBearer, extractBearer } from '../_lib/auth.import { limits, clientIp } from '../_lib/rate-limit.js';import { watsonxConfig, watsonxChatRequest } from '../_lib/watsonx.js';import { DEFAULT_FREE_MODEL, modelThinksByDefault } 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,@@ -44,17 +46,25 @@ const WATSONX_HEADERS_TIMEOUT_MS = 45_000;// 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',- 'nvidia-deepseek-v4',- 'nvidia-kimi-k2',- 'nvidia-llama4-maverick',- 'nvidia-minimax-m2',+ ...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,@@ -63,15 +73,17 @@ export const maxDuration = 120;// OpenRouter; buildFallback() reuses the OpenRouter id to route *around* a native// provider outage (quota/billing/rate-limit) at request time.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: 'GPT-OSS 120B',- network: 'OpenAI · OpenRouter',+ label: 'Gemma 4 31B',+ network: 'Google · OpenRouter',tier: 'balanced',maxOutput: 8192,- description: 'Open-weight 120B from OpenAI. Fast, capable, free tier. Platform default.',- // OpenRouter-only — no first-party key for the free tier. The 120B free- // endpoint was retired upstream; 20B is the surviving GPT-OSS free route.- openrouterModel: 'google/gemma-4-31b-it:free',+ 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',@@ -280,18 +292,6 @@ const PROVIDERS = {// OpenRouter dropped x-ai/grok-4.1-fast from its catalog (verified// 2026-07-22), so this tier is native xAI only, with no mirror route.},- 'groq-llama': {- label: 'Llama 3.3 70B',- network: 'Groq',- tier: 'fast',- maxOutput: 8192,- description: 'Open-weight on Groq. Extremely fast inference.',- native: () =>- env.GROQ_API_KEY- ? createOpenAI({ apiKey: env.GROQ_API_KEY, baseURL: 'https://api.groq.com/openai/v1' }).chat('llama-3.3-70b-versatile')- : null,- openrouterModel: 'meta-llama/llama-3.3-70b-instruct',- },'qwen-plus': {label: 'Qwen Plus',network: 'DashScope',@@ -409,41 +409,25 @@ const PROVIDERS = {reasoningTrace: true,native: () => (env.NVIDIA_API_KEY ? nvidia('nvidia/nemotron-3.5-lightning-30b-a3b') : null),},- 'nvidia-deepseek-v4': {- label: 'DeepSeek V4 Pro',- network: 'NVIDIA NIM',- tier: 'reasoning',- maxOutput: 16384,- description: 'DeepSeek V4 Pro hosted on NVIDIA NIM. Deep reasoning, free tier.',- reasoningTrace: true,- native: () => (env.NVIDIA_API_KEY ? nvidia('deepseek-ai/deepseek-v4-pro') : null),- },- 'nvidia-kimi-k2': {- label: 'Kimi K2.6',- network: 'NVIDIA NIM',- tier: 'flagship',- maxOutput: 16384,- description: 'Moonshot Kimi K2.6 on NIM. Long-context agentic model, free tier.',- native: () => (env.NVIDIA_API_KEY ? nvidia('moonshotai/kimi-k2.6') : null),- },- 'nvidia-llama4-maverick': {- label: 'Llama 4 Maverick',- network: 'NVIDIA NIM',- tier: 'balanced',- maxOutput: 8192,- description: 'Meta Llama 4 Maverick (128-expert MoE) on NIM. Fast, multimodal-capable.',- native: () => (env.NVIDIA_API_KEY ? nvidia('nvidia/nemotron-3-super-120b-a12b') : null),- },- 'nvidia-minimax-m2': {- label: 'MiniMax M2.7',- network: 'NVIDIA NIM',- tier: 'balanced',- maxOutput: 8192,- description: 'MiniMax M2.7 on NIM. Strong general reasoning and chat, free tier.',- native: () => (env.NVIDIA_API_KEY ? nvidia('minimaxai/minimax-m2.7') : 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@@ -465,6 +449,10 @@ function buildPrimary(spec) {// (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) {@@ -506,11 +494,13 @@ function buildFallback(spec, primary) {// Exported for the anchor regression tests (tests/api/llm-vertex-anchor-surfaces).export function freeFallbackChain(providerKey, spec, primary) {const chain = [];- if (env.GROQ_API_KEY && providerKey !== 'groq-llama') {+ // 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/llama-3.3-70b-versatile',- model: createOpenAI({ apiKey: env.GROQ_API_KEY, baseURL: 'https://api.groq.com/openai/v1' }).chat('llama-3.3-70b-versatile'),- meter: { provider: 'groq', model: 'llama-3.3-70b-versatile' },+ 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) => {@@ -587,6 +577,27 @@ function withVertexExtraBody(body, extraBody) {}}+// 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.@@ -637,6 +648,11 @@ function openrouter(key = openrouterKeys()[0]) {// 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',@@ -858,7 +874,9 @@ export function getAvailableProviders() {network: spec.network,tier: spec.tier,maxOutput: spec.maxOutput,+ context: spec.context || null,description: spec.description,+ roster: Boolean(spec.roster),available,// `available` means the deployment holds a route for the model;// `requiresAuth` means the caller still needs a session to use it@@ -877,10 +895,19 @@ export function getAvailableProviders() {// 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',};/**@@ -908,6 +935,14 @@ export function resolveBrain(providerKey) {};}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,@@ -1060,7 +1095,13 @@ export async function streamBrain(res, { plan, providerKey, messages, system, ma? [{ label: 'watsonx', watsonx: true }]: primary.kind === 'vertex'? [{ label: 'vertex', vertex: true, model: primary.model, meter: { provider: 'vertex-anthropic', model: primary.model } }]- : [{ label: 'primary', model: primary.model, meter: meterForPrimary(spec, primary) }];+ : 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',@@ -1068,7 +1109,13 @@ export async function streamBrain(res, { plan, providerKey, messages, system, mameter: { provider: 'openrouter', model: spec.openrouterModel },});}- for (const f of freeFallbackChain(providerKey, spec, primary)) attempts.push(f);+ // 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()) {@@ -1102,7 +1149,10 @@ export async function streamBrain(res, { plan, providerKey, messages, system, maif (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.vertexGemini) {+ 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 thediff --git a/src/brain.js b/src/brain.jsindex 86eb969ee..7ebf9b403 100644--- a/src/brain.js+++ b/src/brain.js@@ -22,14 +22,20 @@ const NETWORK_COLORS = {'DeepSeek': '#888888','IBM watsonx.ai': '#0f62fe','NVIDIA NIM': '#76b900',+ 'Google · OpenRouter': '#34a853',+ 'Meta': '#0866ff',+ 'Moonshot': '#9b7bff',+ 'Mistral': '#ff7000',+ 'Qwen': '#615ced',+ 'Google': '#34a853',};const UNKNOWN_NETWORK_COLOR = '#8a8a8a';// Preferred opening line-up, filtered against what the server reports as// usable for THIS visitor. Anything unusable falls through to the first live// model, so the page never boots with a column that can only answer 401.-const DEFAULT_MODEL_KEYS = ['gpt-oss-120b', 'claude-sonnet-5', 'gpt-5.6-luna', 'groq-llama'];-const ANON_DEFAULT_MODEL_KEYS = ['gpt-oss-120b', 'nvidia-kimi-k2', 'nvidia-nemotron-120b', 'nvidia-llama4-maverick'];+const DEFAULT_MODEL_KEYS = ['gpt-oss-120b', 'claude-sonnet-5', 'llama-3.3-70b', 'deepseek-v4-flash'];+const ANON_DEFAULT_MODEL_KEYS = ['gpt-oss-120b', 'llama-3.3-70b', 'qwen3.8-27b', 'mistral-small'];const PMAP = new Map();diff --git a/src/dashboard-next/pages/brain.js b/src/dashboard-next/pages/brain.jsindex c47e9c384..3285e08a0 100644--- a/src/dashboard-next/pages/brain.js+++ b/src/dashboard-next/pages/brain.js@@ -31,7 +31,6 @@ const PROVIDERS = [{ key: 'o3', label: 'o3', short: 'o3', network: 'OpenAI', color: '#c0e4ff', ctx: '200K', tier: 'Reasoning' },{ key: 'o3-pro', label: 'o3-pro', short: 'o3-pro', network: 'OpenAI', color: '#cce9ff', ctx: '200K', tier: 'Reasoning' },{ key: 'o3-mini', label: 'o3-mini', short: 'o3-mini', network: 'OpenAI', color: '#5cb0f4', ctx: '128K', tier: 'Reasoning' },- { key: 'groq-llama', label: 'Llama 3.3 70B', short: 'Llama 3.3', network: 'Groq', color: '#ff9a3c', ctx: '128K', tier: 'Fast' },{ key: 'qwen-plus', label: 'Qwen Plus', short: 'Qwen+', network: 'DashScope', color: '#69db7c', ctx: '131K', tier: 'Balanced' },{ key: 'modelscope-qwen', label: 'Qwen3-Coder 480B', short: 'Qwen3-Code', network: 'ModelScope', color: '#40c057', ctx: '32K', tier: 'Flagship' },{ key: 'deepseek-r1', label: 'DeepSeek R1', short: 'DeepSeek', network: 'DeepSeek', color: '#888888', ctx: '64K', tier: 'Reasoning' },@@ -68,7 +67,7 @@ const S = {personaEnabled: true,playMode: 'compare',focusKey: 'claude-sonnet-4-6',- active: new Set(['claude-sonnet-4-6', 'gpt-5.6-luna', 'groq-llama', 'deepseek-r1']),+ active: new Set(['claude-sonnet-4-6', 'gpt-5.6-luna', 'llama-3.3-70b', 'deepseek-v4-flash']),sessions: [],currentId: null,streaming: false,@@ -683,6 +682,39 @@ async function saveToAgent() {// ── Provider availability ────────────────────────────────────────────────+// Colors for networks the static registry above does not carry (the open-model+// roster families and anything the server adds later).+const SERVER_NETWORK_COLORS = {+ Meta: '#0866ff', DeepSeek: '#4d6bfe', Moonshot: '#9b7bff', Mistral: '#ff7000',+ Qwen: '#615ced', Google: '#34a853', 'Google · OpenRouter': '#34a853', 'NVIDIA NIM': '#76b900',+};++function formatCtx(tokens) {+ if (!tokens) return '';+ return tokens >= 1_000_000 ? `${Math.round(tokens / 1_048_576)}M` : `${Math.round(tokens / 1024)}K`;+}++// The server roster is the source of truth: any model it serves that the+// static registry does not list (the open-model roster) joins the grid, so a+// model added server-side is selectable here without a client release.+function mergeServerProviders(list) {+ for (const sp of list) {+ if (PMAP.has(sp.key)) continue;+ const tier = sp.tier ? sp.tier[0].toUpperCase() + sp.tier.slice(1) : 'Balanced';+ const entry = {+ key: sp.key,+ label: sp.label,+ short: sp.label,+ network: sp.network,+ color: SERVER_NETWORK_COLORS[sp.network] || '#8a8a8a',+ ctx: formatCtx(sp.context),+ tier,+ };+ PROVIDERS.push(entry);+ PMAP.set(sp.key, entry);+ }+}+async function fetchAvailability() {try {const r = await fetch('/api/brain/chat', { method: 'GET', credentials: 'include' });@@ -690,6 +722,7 @@ async function fetchAvailability() {const json = await r.json();if (Array.isArray(json.providers)) {S.avail = json.providers;+ mergeServerProviders(json.providers);for (const key of [...S.active]) {const found = json.providers.find(p => p.key === key);if (found && !found.available) S.active.delete(key);diff --git a/tests/inference-billing.test.js b/tests/inference-billing.test.jsnew file mode 100644index 000000000..545440818--- /dev/null+++ b/tests/inference-billing.test.js@@ -0,0 +1,111 @@+import { describe, it, expect } from 'vitest';+import {+ priceInference,+ normalizeInferenceBudget,+ getInferenceBudget,+ applyInferenceBudget,+ exhaustedWindow,+ suggestedBudget,+ inferencePricing,+ estimateTokens,+} from '../api/_lib/inference-billing.js';+import { normalizeTopupAmount, creditsForUsdc } from '../api/_lib/inference-topup.js';+import { normalizeIntent, describeIntent } from '../api/_lib/wallet-intents.js';+import { INFERENCE_USD_PER_MTOK, INFERENCE_MIN_CALL_USD, CATALOG } from '../api/_lib/pricing/catalog.js';++describe('inference pricing', () => {+ it('prices tokens at the published per-million rate, rounded up to the micro-dollar', () => {+ expect(priceInference({ inputTokens: 962, outputTokens: 5 })).toBe(0.000491);+ expect(priceInference({ inputTokens: 1_000_000, outputTokens: 0 })).toBe(INFERENCE_USD_PER_MTOK.input);+ expect(priceInference({ inputTokens: 0, outputTokens: 1_000_000 })).toBe(INFERENCE_USD_PER_MTOK.output);+ });++ it('never charges less than the minimum per call', () => {+ expect(priceInference({ inputTokens: 0, outputTokens: 0 })).toBe(INFERENCE_MIN_CALL_USD);+ expect(priceInference({ inputTokens: 3 })).toBe(INFERENCE_MIN_CALL_USD);+ });++ it('publishes the rate, the 1:1 USDC credit rate and a zero top-up fee', () => {+ expect(inferencePricing()).toMatchObject({ model: 'three-ws/agent', usdc_credit_rate: 1, topup_fee_usd: 0 });+ expect(CATALOG['inference.agent']).toMatchObject({ category: 'inference', usd: null });+ });++ it('estimates tokens at about four characters each', () => {+ expect(estimateTokens('abcdefgh')).toBe(2);+ expect(estimateTokens(null)).toBe(0);+ });+});++describe('inference budgets', () => {+ it('accepts either field style and clears on null or empty', () => {+ expect(normalizeInferenceBudget({ daily: 1, monthly: 20 })).toEqual({ daily_usd: 1, monthly_usd: 20 });+ expect(normalizeInferenceBudget({ daily_usd: 0.5 })).toEqual({ daily_usd: 0.5, monthly_usd: null });+ expect(normalizeInferenceBudget(null)).toBeNull();+ expect(normalizeInferenceBudget({})).toBeNull();+ });++ it('rejects non-positive, oversized, inverted and malformed budgets', () => {+ expect(() => normalizeInferenceBudget({ daily: -1 })).toThrow(/positive/);+ expect(() => normalizeInferenceBudget({ daily: 1e9 })).toThrow(/exceed/);+ expect(() => normalizeInferenceBudget({ daily: 10, monthly: 5 })).toThrow(/larger/);+ expect(() => normalizeInferenceBudget('5')).toThrow(/object/);+ });++ it('stores the budget on meta and drops a prior exhaustion stamp', () => {+ const meta = { solana_address: 'x', inference_budget: { daily_usd: 1, exhausted: { key: '2026-09-22' } } };+ const next = applyInferenceBudget(meta, { daily_usd: 2, monthly_usd: null });+ expect(next.solana_address).toBe('x');+ expect(next.inference_budget.daily_usd).toBe(2);+ expect(next.inference_budget.exhausted).toBeUndefined();+ expect(getInferenceBudget(next)).toEqual({ daily_usd: 2, monthly_usd: null });+ expect(applyInferenceBudget(next, null).inference_budget).toBeUndefined();+ });++ it('names the window that is used up, daily first', () => {+ const budget = { daily_usd: 1, monthly_usd: 10 };+ expect(exhaustedWindow(budget, { today_usd: 0.5, month_usd: 3 })).toBeNull();+ expect(exhaustedWindow(budget, { today_usd: 1, month_usd: 3 })).toBe('daily');+ expect(exhaustedWindow(budget, { today_usd: 0.2, month_usd: 10 })).toBe('monthly');+ expect(exhaustedWindow(null, { today_usd: 99, month_usd: 99 })).toBeNull();+ });++ it('suggests a raise that actually readmits the next call', () => {+ expect(suggestedBudget(0.0002, 0.000491)).toBeGreaterThan(0.000491);+ expect(suggestedBudget(1, 0.5)).toBe(2);+ });+});++describe('wallet top-ups', () => {+ it('bounds and truncates amounts to USDC precision', () => {+ expect(normalizeTopupAmount(1.1234567)).toBe(1.123456);+ expect(() => normalizeTopupAmount(0.05)).toThrow(/smallest/);+ expect(() => normalizeTopupAmount(5000)).toThrow(/largest/);+ expect(() => normalizeTopupAmount('abc')).toThrow(/positive/);+ });++ it('credits one dollar per USDC with no fee', () => {+ expect(creditsForUsdc(5)).toBe(5);+ });+});++describe('the fund_inference wallet intent', () => {+ it('compiles "when credits fall below 100, top up 5 USDC"', () => {+ const r = normalizeIntent({+ trigger_type: 'credits_below',+ trigger_config: { threshold_usd: 100 },+ action_type: 'fund_inference',+ action_config: { amount_usdc: 5 },+ });+ expect(r.ok).toBe(true);+ expect(r.intent.trigger).toEqual({ type: 'credits_below', threshold_usd: 100 });+ expect(r.intent.action).toEqual({ type: 'fund_inference', amount_usdc: 5 });+ expect(describeIntent(r.intent)).toMatch(/at most once a day/);+ });++ it('requires a threshold and an amount, and refuses other pairings', () => {+ expect(normalizeIntent({ trigger_type: 'credits_below', action_type: 'fund_inference', action_config: { amount_usdc: 5 } }).error).toBe('needs_threshold');+ expect(normalizeIntent({ trigger_type: 'credits_below', trigger_config: { threshold_usd: 1 }, action_type: 'fund_inference' }).error).toBe('needs_amount');+ expect(normalizeIntent({ trigger_type: 'on_tip_received', action_type: 'fund_inference', action_config: { amount_usdc: 5 } }).error).toBe('bad_pairing');+ expect(normalizeIntent({ trigger_type: 'credits_below', trigger_config: { threshold_usd: 1 }, action_type: 'tip', action_config: { amount_sol: 1, destination: 'x' } }).error).toBe('bad_pairing');+ });+});