Skip to content

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.

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.js
new file mode 100644
index 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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 free
diff --git a/api/_lib/llm-tool-chain.js b/api/_lib/llm-tool-chain.js
index 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.sql
new file mode 100644
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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, ma
meter: { 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, ma
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.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 the
diff --git a/src/brain.js b/src/brain.js
index 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.js
index 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.js
new file mode 100644
index 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');
+ });
+});