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(agents): pick the model per message and bill a named paid model at its list price against the agent budget
nirholasaca6f78bda92
diff --git a/api/_lib/agent-message.js b/api/_lib/agent-message.jsnew file mode 100644index 000000000..7fd209d38--- /dev/null+++ b/api/_lib/agent-message.js@@ -0,0 +1,123 @@+// One agent turn on a chosen model: persona in, answer out.+//+// The model is decided by api/_lib/agent-model.js (per-message override, then+// the agent's default, then the platform chain). This module runs the turn:+// the agent's persona and the server tool note as the system prompt, the+// read-only tool registry (api/_lib/agent-tools.js) when the model can call+// tools, and the shared step loop (api/_lib/agent-loop.js), which fails over+// across the chain before any byte streams.+//+// It does no billing and writes no thread rows: callers own those, because+// they differ (the v1 messages API bills credits and writes the owner's thread;+// call_agent answers a stranger and writes nothing). Every caller gets back the+// same summary: the answer, the model that actually served it, token usage,+// platform cost, and the tool calls made.++import { agentToolSchemas, agentToolHandlers } from './agent-tools.js';+import { AGENT_SYSTEM_NOTE, createAgentLoop, finalAnswer, initialLoopState, loopFinished } from './agent-loop.js';+import { modelChain } from './agent-model.js';++const MAX_TOOL_ROUNDS = 4;+const MAX_PERSONA_CHARS = 8000;++/**+ * The system prompt an agent answers under: its persona (or a name and+ * description fallback), the platform's one-coin rule, and the tool note when+ * tools are offered.+ * @param {{ name?: string, description?: string, persona_prompt?: string, system_prompt?: string, meta?: object }} agent+ * @param {{ tools: boolean }} o+ */+export function agentSystemPrompt(agent, { tools }) {+ const name = String(agent?.name || 'this agent').trim() || 'this agent';+ const persona = String(agent?.persona_prompt || agent?.system_prompt || agent?.meta?.brain?.instructions || '').trim();+ const desc = String(agent?.description || '').trim();+ const parts = [persona ? persona.slice(0, MAX_PERSONA_CHARS) : `You are ${name}, an agent on three.ws.${desc ? ` ${desc}` : ''}`];+ parts.push(+ 'If tokens or coins come up, the only coin you may name, endorse, or recommend is $THREE ' ++ '(contract FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump).',+ );+ if (tools) parts.push(AGENT_SYSTEM_NOTE);+ return parts.join('\n\n');+}++/**+ * Run one turn.+ *+ * @param {object} o+ * @param {object} o.agent agent_identities row (name, persona_prompt, description, meta)+ * @param {string} o.message the user's message+ * @param {Array<{role:'user'|'assistant', content:string}>} [o.history] prior turns, oldest first+ * @param {string|null} [o.model] resolved catalog id, or null for the platform chain+ * @param {number|null} [o.temperature]+ * @param {string} [o.operationId]+ * @returns {Promise<{+ * content: string, model: string|null, provider: string|null, tools: boolean,+ * usage: { input: number, output: number, estimated: boolean },+ * costMicroUsd: number|null, modelCalls: object[],+ * toolCalls: Array<{ name: string, args: object, error: string|null }>,+ * }>}+ */+export async function runAgentMessage({ agent, message, history = [], model = null, temperature = null, operationId }) {+ const { chain, tools } = modelChain(model);+ if (!chain.length) {+ throw Object.assign(new Error('No language model is reachable on this deployment right now.'), {+ status: 503,+ code: 'llm_unavailable',+ expose: true,+ });+ }++ const messages = [+ { role: 'system', content: agentSystemPrompt(agent, { tools }) },+ ...history.filter((m) => m && (m.role === 'user' || m.role === 'assistant') && m.content),+ { role: 'user', content: String(message) },+ ];++ const modelCalls = [];+ const toolCalls = [];+ const loop = createAgentLoop({+ chain,+ toolSchemas: tools ? agentToolSchemas() : [],+ toolHandlers: tools ? agentToolHandlers() : {},+ maxToolRounds: MAX_TOOL_ROUNDS,+ ...(temperature != null ? { temperature } : {}),+ onEvent: (event) => {+ if (event.kind === 'model_call') modelCalls.push(event);+ if (event.kind === 'tool_result') toolCalls.push({ name: event.tool, args: event.args, error: event.error || null });+ if (event.kind === 'tool_blocked') toolCalls.push({ name: event.tool, args: event.args, error: `blocked: ${event.reason}` });+ },+ });++ let { state, context } = initialLoopState({+ operationId: operationId || `msg-${Date.now().toString(36)}`,+ messages,+ maxSteps: MAX_TOOL_ROUNDS * 2 + 3,+ });+ while (!loopFinished(state, context)) {+ ({ state, context } = await loop.step(state, context));+ }+ if (state.status === 'error') {+ const detail = String(state.error?.message || state.error || 'the model could not answer').slice(0, 300);+ throw Object.assign(new Error(detail), { status: 502, code: 'model_failed', expose: true });+ }++ const last = modelCalls.at(-1) || null;+ const usage = { input: 0, output: 0, estimated: false };+ let costMicroUsd = 0;+ for (const call of modelCalls) {+ usage.input += call.usage?.input || 0;+ usage.output += call.usage?.output || 0;+ if (call.usage?.estimated) usage.estimated = true;+ costMicroUsd = costMicroUsd == null || call.costMicroUsd == null ? null : costMicroUsd + call.costMicroUsd;+ }+ return {+ content: finalAnswer(state),+ model: last?.model || model,+ provider: last?.provider || null,+ tools,+ usage,+ costMicroUsd,+ modelCalls,+ toolCalls,+ };+}diff --git a/api/_lib/agent-model.js b/api/_lib/agent-model.jsnew file mode 100644index 000000000..0e4bdf099--- /dev/null+++ b/api/_lib/agent-model.js@@ -0,0 +1,127 @@+// Which model answers one message or run, and the provider chain that serves it.+//+// Every surface that talks to an agent (the v1 messages API, the MCP call_agent+// tool, the agent-screen concierge, the chat gateways, v1 runs) asks this module+// the same two questions, so a model picked in one place means the same thing+// everywhere:+//+// 1. Which model? A per-message override wins, then the agent's default, then+// the platform's free-first chain (no model named).+// 2. Which chain? The chosen model's own routes first (model-roster.js routes+// for an open model, its single lane otherwise), then the platform chain+// behind them, so a dead route degrades to another model's answer instead+// of an error.+//+// A model without tool calling is refused for runs (a run IS a tool loop) and+// allowed for chat, where the turn simply runs without tools.+//+// An agent's default model can live in three places, written by different+// surfaces over the years. They are read in this order:+// meta.runtime.model the v1 Agents API and the agent editor's picker+// meta.brain.provider the MCP create_agent tool and the brain picker+// meta.brain.model the old Library brain tab+// Only an id the model catalog knows counts; anything else (a retired brain+// key, a raw upstream id) is ignored and the platform chain answers.++import { MODEL_CATALOG, resolveModelId, isPaidModel } from './chat-models.js';+import { providerChain, providerChainFor } from './llm-tool-chain.js';+import { rosterTransports } from './model-routes.js';++/** A model choice the caller has to fix: unknown id, no tools for a run, sign-in needed. */+export class ModelChoiceError extends Error {+ /**+ * @param {number} status+ * @param {string} code+ * @param {string} message+ */+ constructor(status, code, message) {+ super(message);+ this.name = 'ModelChoiceError';+ this.status = status;+ this.code = code;+ this.expose = true;+ }+}++/** The catalog id for `id` (a retired id maps forward), or null when the catalog does not know it. */+export function catalogModelId(id) {+ if (typeof id !== 'string' || !id.trim()) return null;+ const resolved = resolveModelId(id.trim());+ return MODEL_CATALOG[resolved] ? resolved : null;+}++/** Whether a catalog model can call tools. */+export function modelHasTools(id) {+ const model = catalogModelId(id);+ return Boolean(model && MODEL_CATALOG[model].tools);+}++/**+ * The agent's default model, or null when it has none the catalog knows.+ * @param {object|null|undefined} meta agent_identities.meta+ */+export function agentDefaultModel(meta) {+ const m = meta && typeof meta === 'object' ? meta : {};+ for (const candidate of [m.runtime?.model, m.brain?.provider, m.brain?.model]) {+ const id = catalogModelId(candidate);+ if (id) return id;+ }+ return null;+}++/**+ * Decide the model for one message or run.+ *+ * @param {object} o+ * @param {string|null} [o.requested] per-message (or per-run) override+ * @param {object|null} [o.agentMeta] the agent's meta, for its default+ * @param {'chat'|'run'} [o.purpose]+ * @param {boolean} [o.signedIn] false clamps paid models away+ * @returns {{ model: string|null, source: 'message'|'agent'|'platform', tools: boolean }}+ * @throws {ModelChoiceError}+ */+export function resolveMessageModel({ requested = null, agentMeta = null, purpose = 'chat', signedIn = true } = {}) {+ if (requested != null && requested !== '') {+ const model = catalogModelId(requested);+ if (!model) {+ throw new ModelChoiceError(400, 'unknown_model', `Unknown model "${String(requested).slice(0, 80)}". Pick an id from GET /api/models.`);+ }+ const tools = MODEL_CATALOG[model].tools === true;+ if (purpose === 'run' && !tools) {+ throw new ModelChoiceError(400, 'model_lacks_tools', `${model} has no tool calling, so it can chat but cannot run a task. Pick a model with tool support for runs.`);+ }+ if (!signedIn && isPaidModel(model)) {+ throw new ModelChoiceError(401, 'sign_in_required', `${model} is a paid model. Sign in to use it, or pick a free model.`);+ }+ return { model, source: 'message', tools };+ }++ const fallback = agentDefaultModel(agentMeta);+ if (fallback) {+ const tools = MODEL_CATALOG[fallback].tools === true;+ if (purpose === 'run' && !tools) {+ throw new ModelChoiceError(400, 'model_lacks_tools', `This agent's default model (${fallback}) has no tool calling, so it cannot run a task. Name a tool-capable model for this run, or change the agent's default.`);+ }+ // A signed-out visitor never spends the platform's paid keys, even on an+ // agent whose owner picked a paid default: the free chain answers them.+ if (!signedIn && isPaidModel(fallback)) return { model: null, source: 'platform', tools: true };+ return { model: fallback, source: 'agent', tools };+ }+ return { model: null, source: 'platform', tools: true };+}++/**+ * The provider chain for a resolved model, and whether the turn may offer tools.+ * A chat-only model leads with its own routes and runs without tools; the+ * platform chain stays behind it (also without tools for that turn) so the+ * message is still answered when every route of the model is down.+ * @param {string|null} model a catalog id, or null for the platform chain+ * @returns {{ chain: object[], tools: boolean }}+ */+export function modelChain(model) {+ if (!model) return { chain: providerChain(), tools: true };+ if (MODEL_CATALOG[model]?.tools) return { chain: providerChainFor(model), tools: true };+ const own = MODEL_CATALOG[model]?.provider === 'roster' ? rosterTransports(model) : [];+ const seen = new Set(own.map((r) => `${r.name}|${r.model}`));+ return { chain: [...own, ...providerChain().filter((p) => !seen.has(`${p.name}|${p.model}`))], tools: false };+}diff --git a/api/_lib/inference-billing.js b/api/_lib/inference-billing.jsindex 349c41d3b..1b16fa931 100644--- a/api/_lib/inference-billing.js+++ b/api/_lib/inference-billing.js@@ -163,11 +163,13 @@ export function applyInferenceBudget(meta, budget) {/*** Every credit_ledger action that is model spend on behalf of one agent, booked* with ref_type 'agent' and ref_id = the agent id: the flat three-ws/agent rate- * (chat completions, the strategy loop) and the metered spend of a v1 run's- * paid model lanes. The per-agent budget is judged against all of them, so an- * agent cannot outrun its budget by spending through a different surface.+ * (chat completions, the strategy loop), the metered spend of a v1 run's paid+ * model lanes, and a v1 chat message that named a paid model and was billed at+ * its list price (api/_lib/agents-v1/billing.js). The per-agent budget is+ * judged against all of them, so an agent cannot outrun its budget by spending+ * through a different surface or by naming an expensive model.*/-export const AGENT_SPEND_ACTIONS = Object.freeze([INFERENCE_ACTION, 'agent_run_step']);+export const AGENT_SPEND_ACTIONS = Object.freeze([INFERENCE_ACTION, 'agent_run_step', 'agent.model']);/** Inference credits an agent has burned today and this month (UTC). */export async function agentInferenceSpend(agentId) {@@ -182,7 +184,7 @@ export async function agentInferenceSpend(agentId) {)::int AS calls_todayFROM credit_ledgerWHERE ref_type = 'agent' AND ref_id = ${String(agentId)}- AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})+ AND action = ANY(${AGENT_SPEND_ACTIONS})AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')`;return {@@ -391,6 +393,10 @@ export async function resumeAfterBudgetChange(agentId, previousMeta) {* the full price (the call was admitted with a thin balance), the remaining* balance is taken instead and the shortfall reported, never a negative balance.*+ * `priceUsd` replaces the published-rate price for a call that named a paid+ * model and is billed at that model's list price; `billedModel` records the+ * model id the price is for.+ ** @returns {Promise<{ chargedUsd: number, pricedUsd: number, balanceUsd: number, shortfallUsd: number, replay: boolean }>}*/export async function chargeInference({@@ -403,10 +409,15 @@ export async function chargeInference({estimated = false,provider = null,model = null,+ priceUsd = null,+ billedModel = INFERENCE_MODEL_ID,}) {- const pricedUsd = priceInference({ inputTokens, outputTokens });+ const pricedUsd =+ Number.isFinite(priceUsd) && priceUsd > 0+ ? Math.max(INFERENCE_MIN_CALL_USD, Math.ceil(priceUsd * 1e6 - 1e-9) / 1e6)+ : priceInference({ inputTokens, outputTokens });const meta = {- model: INFERENCE_MODEL_ID,+ model: billedModel,agent_id: agentId,api_key_id: apiKeyId,input_tokens: inputTokens,@@ -461,7 +472,7 @@ export async function inferenceUsage({ userId, agent = null }) {SELECT COALESCE(SUM(-amount_usd), 0)::float8 AS spent7,COUNT(*)::int AS calls7FROM credit_ledger- WHERE user_id = ${userId} AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})+ WHERE user_id = ${userId} AND action = ANY(${AGENT_SPEND_ACTIONS})AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))AND created_at > now() - interval '7 days'`,@@ -481,7 +492,7 @@ export async function inferenceUsage({ userId, agent = null }) {COALESCE(SUM((meta->>'input_tokens')::bigint), 0)::bigint AS input_tokens,COALESCE(SUM((meta->>'output_tokens')::bigint), 0)::bigint AS output_tokensFROM credit_ledger- WHERE user_id = ${userId} AND action IN (${AGENT_SPEND_ACTIONS[0]}, ${AGENT_SPEND_ACTIONS[1]})+ WHERE user_id = ${userId} AND action = ANY(${AGENT_SPEND_ACTIONS})AND (${agentId}::text IS NULL OR (ref_type = 'agent' AND ref_id = ${agentId ? String(agentId) : null}))AND created_at >= (date_trunc('month', now() AT TIME ZONE 'UTC') AT TIME ZONE 'UTC')`,