Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// POST /api/chat — AI-powered chat for the three.ws viewer agent.
//
// Body: { message, context, history, agentId?, provider?, model? }
// Response: SSE stream { type: 'chunk' | 'done' | 'error' }.
//
// Provider routing (in order — free providers ALWAYS lead; see
// api/_lib/chat-models.js DEFAULT_PROVIDER_ORDER):
// 1. Body.provider when present and the matching key is configured.
// 2. GROQ_API_KEY → Groq (free platform key — default).
// 3. OPENROUTER_API_KEY → OpenRouter free tier.
// 4. NVIDIA_API_KEY → NVIDIA NIM free tier (third independent free lane).
// 5. SAMBANOVA_API_KEY -> SambaNova Cloud free tier (fourth free lane).
// 6. MISTRAL_API_KEY -> Mistral Experiment tier (largest free quota).
// 7. ZAI_API_KEY -> Z.AI free GLM Flash lane (sixth free lane).
// 8. ANTHROPIC_API_KEY -> Anthropic (paid backstop, BYOK or host key).
// 9. OPENAI_API_KEY -> OpenAI (paid backstop).
// 10. WATSONX_API_KEY (+ project) -> IBM Granite on watsonx.ai (server key only;
// explicit `provider: "watsonx"` from the client, never the silent default).
// Anthropic, the OpenAI-compatible providers (OpenRouter / Groq / OpenAI), and
// watsonx.ai use different request shapes, auth, tool-call wire formats, and SSE
// event names — this file translates all of them so the client only ever sees
// the same { chunk → done } event stream regardless of upstream. watsonx adds
// one wrinkle: its bearer token is minted from an IAM exchange, so its request
// headers are resolved asynchronously (route.resolveHeaders) inside the loop
// rather than baked in up front; its SSE deltas are OpenAI-shaped, so the
// OpenAI stream reader handles them verbatim.
import { getSessionUser, authenticateBearer, extractBearer } from './_lib/auth.js';
import { cors, json, method, readJson, wrap, error, rateLimited } from './_lib/http.js';
import { parse } from './_lib/validate.js';
import { recordEvent } from './_lib/usage.js';
import { trackAgentOwnerVisit } from './_lib/retention.js';
import { OPENROUTER_ATTRIBUTION_HEADERS } from './_lib/openrouter-attribution.js';
import { costMicroUsd } from './_lib/llm-pricing.js';
import { captureException } from './_lib/sentry.js';
import { sql } from './_lib/db.js';
import { limits, clientIp } from './_lib/rate-limit.js';
import { loadUserProviderKeys } from './_lib/provider-keys.js';
import { agentDefaultModel } from './_lib/agent-model.js';
import { loadOwnerGrokKey } from './_lib/agent-grok-key.js';
import { watsonxConfig, watsonxAuthHeaders } from './_lib/watsonx.js';
import { orchestrateConfig } from './_lib/orchestrate.js';
import { guardianConfig, governSend, sendCapUsd } from './_lib/granite-guardian.js';
import {
markProviderCooldown,
providersInCooldown,
AUTH_COOLDOWN_SECONDS,
} from './_lib/provider-health.js';
import {
DEFAULT_FREE_MODEL,
PROVIDER_MODEL_DEFAULTS,
DEFAULT_PROVIDER_ORDER,
OPENROUTER_SIBLINGS,
ANON_PROVIDER_LIST,
MODEL_CATALOG,
anonModelAllowed,
modelThinksByDefault,
promptCacheMinChars,
MAX_FALLBACK_ATTEMPTS,
TOTAL_BUDGET_MS,
PER_CALL_TIMEOUT_MS,
XAI_CHAT_COMPLETIONS_URL,
GROK_DEFAULT_MODEL,
GROK_BUDGET_MODEL,
routableGrokModelId,
} from './_lib/chat-models.js';
import { computeContext, searchMemories, isVisitorQaMemory } from './_lib/memory-store.js';
import { HOME_TOOL_DEFS, isHomeTool, runHomeTool } from './_lib/home/tools.js';
import {
homeTurnGate,
isGatedHomeTool,
quotaRefusalResult,
shouldRefuseHomeCall,
} from './_lib/home/turn-gate.js';
import { listMembershipHomes } from './_lib/home/members.js';
import { loadInstalledSkills, skillsPromptBlock } from './_lib/installed-skills.js';
import { agentSkillsForPrompt } from './_lib/agent-custom-skills.js';
import { holdSkillOriginatedSpend } from './_lib/skill-import-gate.js';
import {
vertexClaudeEnabled,
vertexClaudePrimary,
vertexMessagesUrl,
vertexRequestHeaders,
toVertexBody,
} from './_lib/vertex-claude.js';
import { vertexGeminiBudget } from './_lib/vertex-gemini.js';
import { z } from 'zod';
// Providers anonymous (unauthenticated) callers may use. Groq and OpenRouter
// free-tier models are exposed without sign-in — paid keys stay gated behind auth.
const ANON_PROVIDERS = new Set(ANON_PROVIDER_LIST);
export const maxDuration = 60;
const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
const DEFAULT_ANTHROPIC_MODEL = PROVIDER_MODEL_DEFAULTS.anthropic;
// GPT-OSS 120B on OpenRouter — the platform-wide default chat model (same one
// the /chat app uses). See api/_lib/chat-models.js.
const DEFAULT_OPENROUTER_MODEL = PROVIDER_MODEL_DEFAULTS.openrouter;
const DEFAULT_GROQ_MODEL = PROVIDER_MODEL_DEFAULTS.groq;
const DEFAULT_OPENAI_MODEL = PROVIDER_MODEL_DEFAULTS.openai;
const DEFAULT_MAX_TOKENS = 1024;
const HARD_MAX_TOKENS = 4096;
// Vertex Gemini (GCP credits) via its OpenAI-compatible endpoint — the same rung
// api/_lib/llm.js exposes as vertexGeminiProvider(). Serves as the credits-funded
// last-resort anchor: it needs no third-party quota, so a signed-out /api/chat
// request can never 503 just because groq/openrouter/nvidia are all throttled at
// once (that was the whole point of adding 'vertex-gemini' to ANON_PROVIDER_LIST,
// but the route was never wired into PROVIDERS/providerOrder, so the anchor was
// dead). Model + location follow the same env knobs as the llm.js rung.
const VERTEX_GEMINI_CHAT_MODEL = process.env.VERTEX_GEMINI_MODEL || 'google/gemini-2.5-flash';
function vertexGeminiChatUrl() {
const project = process.env.GOOGLE_CLOUD_PROJECT;
const location = process.env.GOOGLE_CLOUD_LOCATION_GEMINI || 'global';
const host =
location === 'global' ? 'aiplatform.googleapis.com' : `${location}-aiplatform.googleapis.com`;
return `https://${host}/v1beta1/projects/${project}/locations/${location}/endpoints/openapi/chat/completions`;
}
const PROVIDERS = {
anthropic: {
envKey: 'ANTHROPIC_API_KEY',
defaultModel: DEFAULT_ANTHROPIC_MODEL,
url: ANTHROPIC_URL,
style: 'anthropic',
},
// Vertex-served Claude (GCP credits). No envKey — availability is gated by
// vertexClaudeEnabled(); the OAuth bearer token is minted per request in
// makeRoute (resolveHeaders). Serves the same Claude model ids as the
// first-party Anthropic lane, so the Anthropic SSE reader handles it verbatim.
// Injected into the try-order per flags by providerOrder(); absent when off.
vertex: {
defaultModel: DEFAULT_ANTHROPIC_MODEL,
style: 'vertex-anthropic',
},
// Vertex-served Gemini (GCP credits), OpenAI-compatible wire format. No envKey
// — availability is gated by GOOGLE_CLOUD_PROJECT and the OAuth bearer token is
// minted per request in makeRoute (resolveHeaders), exactly like the keyless
// `vertex` route above. Never auto-selected as a primary route (it sits at the
// tail of providerOrder()); reached only via failover, where it is the
// credits-funded anchor that keeps anonymous chat alive when every free lane is
// rate-limited at once.
'vertex-gemini': {
defaultModel: VERTEX_GEMINI_CHAT_MODEL,
style: 'vertex-gemini',
},
openrouter: {
envKey: 'OPENROUTER_API_KEY',
defaultModel: DEFAULT_OPENROUTER_MODEL,
url: 'https://openrouter.ai/api/v1/chat/completions',
style: 'openai',
extraHeaders: OPENROUTER_ATTRIBUTION_HEADERS,
},
groq: {
envKey: 'GROQ_API_KEY',
defaultModel: DEFAULT_GROQ_MODEL,
url: 'https://api.groq.com/openai/v1/chat/completions',
style: 'openai',
},
// NVIDIA NIM (build.nvidia.com) — free OpenAI-compatible inference; one
// nvapi key unlocks every hosted model. The third independent free lane.
nvidia: {
envKey: 'NVIDIA_API_KEY',
defaultModel: PROVIDER_MODEL_DEFAULTS.nvidia,
url: 'https://integrate.api.nvidia.com/v1/chat/completions',
style: 'openai',
},
// SambaNova Cloud (cloud.sambanova.ai): free-tier OpenAI-compatible Llama
// 3.3 70B on its own quota pool. The fourth independent free lane.
sambanova: {
envKey: 'SAMBANOVA_API_KEY',
defaultModel: PROVIDER_MODEL_DEFAULTS.sambanova,
url: 'https://api.sambanova.ai/v1/chat/completions',
style: 'openai',
},
// Mistral Experiment tier (console.mistral.ai): OpenAI-compatible, about
// 1B free tokens/month. The largest free quota in the ladder.
mistral: {
envKey: 'MISTRAL_API_KEY',
defaultModel: PROVIDER_MODEL_DEFAULTS.mistral,
url: 'https://api.mistral.ai/v1/chat/completions',
style: 'openai',
},
// Z.AI (docs.z.ai): permanently free, rate-limited GLM Flash models on an
// OpenAI-compatible endpoint. A sixth independent free lane.
zai: {
envKey: 'ZAI_API_KEY',
defaultModel: PROVIDER_MODEL_DEFAULTS.zai,
url: 'https://api.z.ai/api/paas/v4/chat/completions',
style: 'openai',
},
openai: {
envKey: 'OPENAI_API_KEY',
defaultModel: DEFAULT_OPENAI_MODEL,
url: 'https://api.openai.com/v1/chat/completions',
style: 'openai',
},
// xAI Grok (api.x.ai): paid, OpenAI-compatible. Reached via an explicit
// provider/model request or a stored BYOK key (Settings > AI Provider Keys);
// the server GROK_API_KEY, when set, serves it platform-side too.
grok: {
envKey: 'GROK_API_KEY',
defaultModel: PROVIDER_MODEL_DEFAULTS.grok,
url: XAI_CHAT_COMPLETIONS_URL,
style: 'openai',
},
// IBM watsonx.ai (Granite). URL + headers are derived in makeRoute from the
// shared watsonx client (region host, version param, IAM bearer token), so
// no static `url` here. Requires WATSONX_API_KEY + a project/space id.
watsonx: {
envKey: 'WATSONX_API_KEY',
defaultModel: 'ibm/granite-3-8b-instruct',
style: 'watsonx',
},
// IBM watsonx Orchestrate agent (Agent Connect). OpenAI-compatible
// chat-completions endpoint, so it streams through the OpenAI reader; the
// endpoint URL + agent id are resolved in makeRoute. This makes a three.ws
// 3D avatar the embodied front-end of an enterprise Orchestrate agent.
orchestrate: {
envKey: 'WATSONX_ORCHESTRATE_API_KEY',
defaultModel: 'orchestrate-agent',
style: 'orchestrate',
},
};
const contextSchema = z
.object({
modelName: z.string().max(200).optional(),
vertices: z.number().int().nonnegative().optional(),
triangles: z.number().int().nonnegative().optional(),
materials: z.number().int().nonnegative().optional(),
animations: z.number().int().nonnegative().optional(),
validationErrors: z.number().int().nonnegative().optional(),
validationWarnings: z.number().int().nonnegative().optional(),
currentEnvironment: z.string().max(80).optional(),
wireframe: z.boolean().optional(),
skeleton: z.boolean().optional(),
grid: z.boolean().optional(),
autoRotate: z.boolean().optional(),
transparentBg: z.boolean().optional(),
bgColor: z.string().max(20).optional(),
})
.partial()
.default({});
const chatBody = z.object({
message: z.string().trim().min(1).max(4000),
context: contextSchema,
system_prompt: z.string().trim().min(1).max(2000).optional(),
// Owner-only candidate persona for the Brain Studio live preview: lets the
// owner audition an unsaved compiled persona against /api/chat even when the
// agent already has a stored persona. Ignored unless the caller owns agentId.
persona_override: z.string().trim().min(1).max(16000).optional(),
agentId: z.string().uuid().optional(),
provider: z
.enum(['anthropic', 'openrouter', 'groq', 'nvidia', 'sambanova', 'mistral', 'zai', 'openai', 'grok', 'watsonx', 'orchestrate'])
.optional(),
model: z.string().min(1).max(120).optional(),
history: z
.array(
z.object({
role: z.enum(['user', 'assistant']),
content: z.string().min(1).max(4000),
}),
)
.max(20)
.default([]),
});
// Tool definitions in Anthropic shape; converted to OpenAI shape on demand.
const ACTION_TOOLS = [
{
name: 'setWireframe',
description: 'Toggle wireframe mode on the currently loaded model.',
input_schema: {
type: 'object',
properties: { value: { type: 'boolean' } },
required: ['value'],
},
},
{
name: 'setSkeleton',
description: 'Toggle the skeleton helper visualization for rigged models.',
input_schema: {
type: 'object',
properties: { value: { type: 'boolean' } },
required: ['value'],
},
},
{
name: 'setGrid',
description: 'Toggle the reference grid and axes helper.',
input_schema: {
type: 'object',
properties: { value: { type: 'boolean' } },
required: ['value'],
},
},
{
name: 'setAutoRotate',
description: 'Toggle auto-rotation of the camera around the model.',
input_schema: {
type: 'object',
properties: { value: { type: 'boolean' } },
required: ['value'],
},
},
{
name: 'setBgColor',
description: 'Set the viewer background color. Accepts a CSS hex like "#001133".',
input_schema: {
type: 'object',
properties: { value: { type: 'string', pattern: '^#[0-9a-fA-F]{3,8}$' } },
required: ['value'],
},
},
{
name: 'setTransparentBg',
description: 'Toggle transparent background (for compositing screenshots).',
input_schema: {
type: 'object',
properties: { value: { type: 'boolean' } },
required: ['value'],
},
},
{
name: 'setEnvironment',
description:
'Change the HDRI lighting environment. Known names: "None", "Neutral", "Venice Sunset", "Footprint Court (HDR Labs)".',
input_schema: {
type: 'object',
properties: { value: { type: 'string' } },
required: ['value'],
},
},
{
name: 'takeScreenshot',
description: 'Capture a PNG screenshot of the current viewport.',
input_schema: { type: 'object', properties: {} },
},
{
name: 'loadModel',
description: 'Load a glTF or GLB model by URL.',
input_schema: {
type: 'object',
properties: { url: { type: 'string', format: 'uri' } },
required: ['url'],
},
},
{
name: 'runValidation',
description:
'Run glTF validation on the currently loaded model and report errors/warnings.',
input_schema: { type: 'object', properties: {} },
},
{
name: 'showMaterialEditor',
description: 'Open the material editor panel in the viewer UI.',
input_schema: { type: 'object', properties: {} },
},
{
name: 'setCameraTarget',
description:
'Set the camera target to a specific named bone on the currently loaded model.',
input_schema: {
type: 'object',
properties: {
boneName: {
type: 'string',
description: 'The name of the bone to target, e.g. "head", "leftHand"',
},
},
required: ['boneName'],
},
},
{
name: 'getPumpFunTrades',
description: 'Get the latest trades from pump.fun and show them in the 3D scene.',
input_schema: { type: 'object', properties: {} },
},
{
name: 'playAnimation',
description:
'Play a named animation on the avatar. Use when the user asks to dance, wave, jump, celebrate, etc. Available clips: wave, dance, capoeira, jump, thriller, pray, idle, celebrate, rumba, falling, kiss, taunt.',
input_schema: {
type: 'object',
properties: {
name: {
type: 'string',
description: 'Animation clip name, e.g. "dance", "wave", "jump", "thriller".',
},
loop: {
type: 'boolean',
description: 'Whether to loop the animation. Dance-style clips should loop.',
},
},
required: ['name'],
},
},
{
name: 'sendSol',
description:
"Send a small amount of SOL from the avatar's own Solana wallet to a recipient, denominated in US dollars. " +
'Call this ONLY when the user explicitly asks the avatar to send, pay, or transfer SOL. ' +
'If the user says "send me" (or gives no address), omit `to` — the configured default recipient is used. ' +
'The host enforces a per-send dollar cap, so request the amount the user named.',
input_schema: {
type: 'object',
properties: {
usd: {
type: 'number',
description: 'US-dollar value of SOL to send, e.g. 1 for "$1 of SOL".',
},
to: {
type: 'string',
description:
'Recipient Solana address (base58). Omit to send to the configured default recipient ("me").',
},
},
required: ['usd'],
},
},
];
const ACTION_NAMES = new Set(ACTION_TOOLS.map((t) => t.name));
const toOpenAiTool = (t) => ({
type: 'function',
function: {
name: t.name,
description: t.description,
parameters: t.input_schema,
},
});
const OPENAI_TOOLS = ACTION_TOOLS.map(toOpenAiTool);
// The home tools are a different KIND of tool from everything above.
//
// Every ACTION_TOOL is a viewer action: the model asks, the browser does it, and
// the model never learns the outcome. A home tool acts on a real building, and
// the model has to see the result to say anything true about it, so these run
// SERVER-SIDE (api/_lib/home/tools.js) between the two model passes below.
//
// They are only offered to a caller who actually has a connected home; a model
// handed a tool that can never work will keep reaching for it.
//
// Note what is NOT here: any way to confirm. The schemas come straight from
// HOME_TOOL_DEFS, which carries no `confirmed` property, so a guarded action can
// only ever come back as a pending confirmation that the browser renders and a
// person approves through /api/home/:id/confirm.
const HOME_ANTHROPIC_TOOLS = HOME_TOOL_DEFS.map((def) => ({
name: def.name,
description: def.description,
input_schema: def.inputSchema,
}));
const HOME_OPENAI_TOOLS = HOME_ANTHROPIC_TOOLS.map(toOpenAiTool);
/** The tool set a route sends when the caller has no home connected. */
const DEFAULT_TOOL_SET = Object.freeze({ anthropic: ACTION_TOOLS, openai: OPENAI_TOOLS });
/**
* Server-side home rounds per turn.
*
* Three, measured rather than guessed. The shape a person actually asks for is
* "check the house, then do the thing", and the tool descriptions deliberately
* tell the model to look for an existing scene before composing its own call, so
* a single act costs up to three steps: read the state, list the macros, then
* act. At two rounds a real Claude turn on "unlock the front door" spent both on
* reads and answered without ever asking, which is a worse failure than a slow
* one. The last round is offered no home tools at all, so the ceiling is a hard
* stop rather than a hope.
*/
const HOME_TOOL_ROUNDS = 3;
export default wrap(async (req, res) => {
if (cors(req, res, { methods: 'POST,OPTIONS', credentials: true })) return;
if (!method(req, res, ['POST'])) return;
const auth = await resolveAuth(req);
const body = parse(chatBody, await readJson(req));
// Anonymous callers are restricted to Groq's free tier (no other provider
// keys are exposed without auth). Force-pin the provider and rate-limit by
// IP so abuse can't burn the host's quota.
let anonymous = false;
if (!auth) {
const ip = clientIp(req);
const rl = await limits.chatIp(ip);
if (!rl.success) {
return rateLimited(res, rl, 'too many anonymous chat requests, try again shortly');
}
const hasOpenRouter = !!process.env.OPENROUTER_API_KEY;
const hasGroq = !!process.env.GROQ_API_KEY;
const hasNvidia = !!process.env.NVIDIA_API_KEY;
if (!hasOpenRouter && !hasGroq && !hasNvidia) {
return error(res, 401, 'unauthorized', 'sign in to chat with the agent');
}
if (body.provider && !ANON_PROVIDERS.has(body.provider)) {
return error(res, 401, 'unauthorized', 'sign in to use this model');
}
// A paid/BYOK model (e.g. the OpenRouter Granite lane) draws real spend on
// the platform key, so it is authenticated-only — even though its provider
// (openrouter) is otherwise an anon free tier. Reject an explicit request
// for one before it can reach the funded key.
if (body.model && !anonModelAllowed(body.model)) {
return error(res, 401, 'unauthorized', 'sign in to use this model');
}
// Honor an explicitly-requested free-tier provider (groq/openrouter/nvidia).
// Otherwise default to Groq — the fast, first-attempt-reliable free tier —
// then OpenRouter's free Llama (DEFAULT_FREE_MODEL), then NVIDIA NIM.
if (!body.provider) {
body.provider = hasGroq ? 'groq' : hasOpenRouter ? 'openrouter' : 'nvidia';
if (!body.model && body.provider === 'openrouter') body.model = DEFAULT_FREE_MODEL;
}
anonymous = true;
} else {
// Authenticated callers are metered too — platform LLM keys are a real
// cost, so a signed-in account must not get unlimited inference.
const rl = await limits.chatUser(auth.userId || `ip:${clientIp(req)}`);
if (!rl.success) {
return rateLimited(res, rl, 'too many chat requests, slow down');
}
}
// No platform-side content filter runs here. Whatever safety judgment the
// serving model makes is the only one this route applies; we do not add a
// classifier in front of it. Abuse is handled by attribution and metering
// (the rate-limit buckets above), not by pre-screening what a visitor may
// ask. Owner directive 2026-08-07.
let userProviderKeys = {};
if (auth?.userId) {
const [urow] = await sql`SELECT provider_keys FROM users WHERE id = ${auth.userId}`;
userProviderKeys = await loadUserProviderKeys(urow?.provider_keys);
}
// Agent lookup happens before provider selection so an unrequested provider
// can default to the agent's own chosen brain (api/_lib/agent-model.js),
// the same resolution profile chat, the gateway, and scheduled runs now
// share. persona_prompt/user_id/meta in one row; the later persona-prompt
// block reuses `agentRow`.
let agentRow = null;
if (body.agentId) {
[agentRow] = await sql`
SELECT persona_prompt, user_id, meta FROM agent_identities
WHERE id = ${body.agentId} AND deleted_at IS NULL
AND (is_published = true OR user_id = ${auth?.userId ?? null})
LIMIT 1
`;
}
// Only when the caller named neither a provider nor a model, and is signed
// in: grok (like every paid/BYOK provider) is sign-in-only, matching
// resolveMessageModel's rule in agent-model.js, and in practice the
// anonymous branch above has already pinned body.provider by this point.
// A Grok default also pulls the agent owner's saved xAI key ahead of the
// server key, same lane order as the gateway and scheduled runs
// (api/_lib/agent-grok-key.js).
// Echoed on `done` as `agent_brain` so the client can tell a straight answer
// from a failover: the badge compares what the agent's brain was supposed
// to be against `provider`/`model`, which is what actually answered.
const agentBrainDefault = agentBrainDefaultFor({
anonymous,
requestedProvider: body.provider,
requestedModel: body.model,
agentMeta: agentRow?.meta,
});
if (agentBrainDefault) {
body.provider = agentBrainDefault.provider;
body.model = agentBrainDefault.model;
if (agentBrainDefault.provider === 'grok' && !userProviderKeys.grok) {
const ownerKey = await loadOwnerGrokKey(agentRow.user_id);
if (ownerKey) userProviderKeys = { ...userProviderKeys, grok: ownerKey };
}
}
// Health cooldowns: a provider that recently 429'd / 5xx'd is skipped while it
// recovers, so a single throttle window doesn't cascade into request after
// request re-hitting the same dead provider. Best-effort — an unreadable
// cache yields an empty set (pre-breaker behaviour).
const cooldown = await providersInCooldown(Object.keys(PROVIDERS));
let route = pickProvider(body.provider, body.model, userProviderKeys, cooldown);
if (!route) {
return error(res, 503, 'chat_unavailable', 'no chat provider is configured');
}
if (anonymous && !ANON_PROVIDERS.has(route.name)) {
// Reaching here means an anon-eligible provider IS configured (the missing-key
// case already 401'd above) but pickProvider still landed outside the anon set.
// The pin above requests a free lane, and a requested provider only loses that
// pin to an *auth* cooldown, so this is a free tier whose key came back
// 401/402/403 with no other free lane left to take it: a capacity problem, not
// an authentication one. Answering 401 told signed-out visitors to "sign in"
// for a throttle they cannot fix, and the assistant widget (whose whole free
// lane is anonymous, with no sign-in anywhere in it) surfaced that as its dead
// end. Same shape as the exhausted-chain branch below, so every client backs
// off and retries on one code path.
res.setHeader('Retry-After', '20');
return error(
res,
503,
'rate_limited',
'The AI chat is at capacity right now. Please try again in a few seconds.',
{ providers_tried: [...ANON_PROVIDERS].filter((name) => cooldown.has(name)), retry_after: 20 },
);
}
// When inference is billed to the host's key (the caller supplied none for the
// chosen provider), charge it against a global ceiling so distributed abuse —
// many accounts each under their per-user limit — can't drain platform quota.
if (route.usingHostKey) {
const hk = await limits.chatHostKeyGlobal();
if (!hk.success) {
return rateLimited(res, hk, 'chat is at capacity, try again shortly');
}
}
const maxTokens = clampInt(
parseInt(process.env.CHAT_MAX_TOKENS || '', 10) || DEFAULT_MAX_TOKENS,
128,
HARD_MAX_TOKENS,
);
let personaPrompt = null;
let isOwner = false;
let agentVisible = false;
if (body.agentId) {
// Persona prompts are private IP: only serve them for published agents, or
// to the agent's owner. Anonymous callers get published personas only.
// `agentRow` was already loaded above (it also feeds the brain default).
agentVisible = Boolean(agentRow);
isOwner = Boolean(auth?.userId && agentRow?.user_id === auth.userId);
// Brain Studio preview: the owner may audition an unsaved compiled persona.
// The override only applies to the agent's owner — never published-agent
// visitors — so it can't be used to inject a prompt into someone's agent.
if (body.persona_override && agentRow && auth?.userId && agentRow.user_id === auth.userId) {
personaPrompt = body.persona_override;
} else if (agentRow?.persona_prompt) {
personaPrompt = agentRow.persona_prompt;
}
}
if (!personaPrompt && body.system_prompt) personaPrompt = body.system_prompt;
// Real memory recall: surface the agent's always-in-context core (pinned /
// working tier) plus the memories most relevant to THIS message, inject them
// into the system prompt so they actually shape the reply, and report exactly
// which ones were used in the `done` event (the client emits `memory:recalled`
// from that). The owner sees all their memories; a third party chatting with a
// published agent sees only its public memories. Best-effort: a memory-store
// hiccup degrades to a memory-less reply, never a failed chat.
let recalledMemories = [];
let recalledSemantic = false;
if (body.agentId) {
try {
recalledMemories = await recallForChat(body.agentId, body.message, isOwner);
recalledSemantic = recalledMemories.some((m) => m.match === 'semantic');
} catch (err) {
captureException(err, { route: 'chat', stage: 'recall', agentId: body.agentId });
}
}
// Installed marketplace skills: a signed-in user's installed knowledge
// skills become standing playbooks in the system prompt, so installing a
// skill from /marketplace visibly changes how their agent answers. The
// slugs ride along in the done event as `skills_applied` so clients can
// show which skills were in play. Best-effort: a skills-store hiccup
// degrades to a skill-less reply, never a failed chat.
let installedSkills = [];
if (auth?.userId) {
try {
installedSkills = await loadInstalledSkills(auth.userId);
} catch (err) {
captureException(err, { route: 'chat', stage: 'installed-skills' });
}
}
// Prompt-only custom skills installed on the agent itself (hand-written or
// imported from /skills/community). Unlike the per-user marketplace installs
// above, these belong to the agent, so they shape its replies for every
// visitor, under the same visibility rule as the persona. Install order and
// the token budget come from api/_lib/agent-custom-skills.js. Best-effort,
// like every other prompt layer here.
let agentSkills = { block: '', applied: [], gated: [] };
if (agentVisible) {
try {
agentSkills = await agentSkillsForPrompt(body.agentId);
} catch (err) {
captureException(err, { route: 'chat', stage: 'agent-custom-skills', agentId: body.agentId });
}
}
// Home tools are offered only to an account that has a house connected, so a
// model is never handed a tool it cannot use. One indexed read of a tiny
// membership table; a failure degrades to a home-less turn, never a failed
// chat, because the house is a feature and the conversation is the product.
let homeCount = 0;
if (auth?.userId) {
try {
homeCount = (await listMembershipHomes(auth.userId)).length;
} catch (err) {
captureException(err, { route: 'chat', stage: 'home-membership' });
}
}
const homeOffered = homeToolsOffered({ homeCount, agentId: body.agentId, isOwner });
const toolSet = homeOffered
? {
anthropic: [...ACTION_TOOLS, ...HOME_ANTHROPIC_TOOLS],
openai: [...OPENAI_TOOLS, ...HOME_OPENAI_TOOLS],
}
: DEFAULT_TOOL_SET;
const sys = buildSystemPrompt(
body.context,
personaPrompt,
recalledMemories,
installedSkills,
agentSkills.block,
);
const systemPrompt = sys.text;
const history = body.history.map((m) => ({ role: m.role, content: m.content }));
history.push({ role: 'user', content: body.message });
const started = Date.now();
// Provider/model failover chain. The first entry is the picked route; if it
// returns 429 (rate-limit) or 5xx (provider down) we cycle through a
// pre-built fallback list before surfacing an error.
let fallbackRoutes = buildFallbackChain(
route,
userProviderKeys,
cooldown,
anonymous ? ANON_PROVIDERS : null,
);
// Anonymous traffic must never fail over onto paid providers (OpenAI/
// Anthropic). buildFallbackChain already excludes them from the capped chain
// for anon callers (via the allow-set above) so they can't evict the free-tier
// vertex-gemini anchor; this post-build clamp stays as a defensive no-op in case
// the primary route itself is ever non-anon.
if (anonymous) fallbackRoutes = fallbackRoutes.filter((r) => ANON_PROVIDERS.has(r.name));
let upstream;
let routeIdx = 0;
// Tool support varies by model/provider. We always ask with the action tools
// first; if a route rejects them we retry that same route without tools.
let includeTools = true;
// One in-place retry per route on transient gateway errors (503/504) before
// failing over. Reset to false every time we advance to a new route.
let retriedTransient = false;
// Bound the whole chain by wall-clock so a request can't churn through every
// provider and still time out at the 60s function limit. Once the budget is
// spent we stop failing over and surface a clean terminal error. `attempted`
// records which provider/model each upstream call hit, so an exhausted chain
// can tell the client (and the logs) exactly what failed.
const deadline = started + TOTAL_BUDGET_MS;
const attempted = [];
// Whether another route exists *and* the time budget allows trying it.
const canFailOver = () => routeIdx + 1 < fallbackRoutes.length && Date.now() < deadline;
while (true) {
attempted.push({ provider: route.name, model: route.model });
try {
// Most routes carry static headers; watsonx resolves a fresh IAM
// bearer token (cached between requests) just before the fetch.
const reqHeaders = route.headers || (await route.resolveHeaders());
// Per-attempt abort: a single hung provider must not silently consume
// the whole TOTAL_BUDGET_MS (and ultimately trip the 60s function
// timeout). Cap each attempt at the smaller of the remaining budget or
// PER_CALL_TIMEOUT_MS, so a stalled upstream aborts fast and we fail
// over to the next route while time remains. The AbortError lands in
// the catch below, which advances the chain like any network blip.
const remainingMs = deadline - Date.now();
const ctrl = new AbortController();
const callMs = Math.max(1, Math.min(PER_CALL_TIMEOUT_MS, remainingMs));
const timer = setTimeout(() => ctrl.abort(), callMs);
try {
upstream = await fetch(route.url, {
method: 'POST',
headers: reqHeaders,
body: JSON.stringify(
route.buildPayload({ systemPrompt, systemParts: sys, history, maxTokens, includeTools, toolSet }),
),
signal: ctrl.signal,
});
} finally {
clearTimeout(timer);
}
} catch (err) {
captureException(err, { route: 'chat', stage: 'fetch', provider: route.name });
const reason = err?.name === 'AbortError' ? 'timed out' : err.message;
console.error(`[chat:${route.name}] upstream fetch failed:`, reason);
// An unreachable/timed-out provider is unhealthy — cool it down so the
// next request skips it instead of waiting on the same dead socket.
void markProviderCooldown(route.name);
// Network blip — try next route if one exists and time remains.
routeIdx++;
if (routeIdx < fallbackRoutes.length && Date.now() < deadline) {
route = fallbackRoutes[routeIdx];
includeTools = true;
retriedTransient = false;
continue;
}
// Every route was unreachable/timed out — that's transient capacity, not a
// permanent breakage. 503 + Retry-After so the client backs off and retries
// (the same contract as the rate-limit terminal below), never a hard 502.
res.setHeader('Retry-After', '20');
return error(
res,
503,
'rate_limited',
'The AI chat is at capacity right now. Please try again in a few seconds.',
{
providers_tried: providersTried(attempted),
retry_after: 20,
},
);
}
// watsonx/Granite: a few foundation models (or regions) reject a
// tools-augmented chat with a 4xx instead of serving it tool-free. When the
// error reads as a tool-support problem, retry the same route once without
// action tools before failing over. The response is cloned for the peek so
// its body stays readable for the generic failover/error handling below if
// this turns out not to be about tools.
if (
includeTools &&
route.style === 'watsonx' &&
upstream.status >= 400 &&
upstream.status < 500 &&
upstream.status !== 429
) {
const peek = await upstream
.clone()
.text()
.catch(() => '');
if (/tool|function[\s_-]?call|tool_choice|not[\s_-]?support|unsupported/i.test(peek)) {
console.warn(
`[chat:${route.name}] ${route.model} rejected action tools (${upstream.status}) — retrying without them`,
);
includeTools = false;
continue;
}
}
// OpenRouter (and some OpenAI-compatible endpoints) reject tool-augmented
// requests for models whose backing provider has no function-calling
// support, with a 404 "No endpoints found that support tool use".
// Strategy: (1) first retry same route without tools; (2) if that also
// 404s — or if tools weren't the issue — fall over to the next provider.
if (upstream.status === 404 && route.style === 'openai') {
const text = await upstream.text().catch(() => '');
if (includeTools && /tool[\s-]?use|support tools|require_parameters/i.test(text)) {
console.warn(
`[chat:${route.name}] ${route.model} has no tool-capable endpoint — retrying without action tools`,
);
includeTools = false;
continue;
}
// Already tried without tools, or non-tool-use 404 — fall over to next provider.
if (canFailOver()) {
console.warn(
`[chat:${route.name}] 404 — falling over to ${fallbackRoutes[routeIdx + 1].name}/${fallbackRoutes[routeIdx + 1].model}: ${text.slice(0, 120)}`,
);
routeIdx++;
route = fallbackRoutes[routeIdx];
includeTools = true;
retriedTransient = false;
continue;
}
captureException(new Error(`${route.name} upstream 404`), {
route: 'chat',
provider: route.name,
status: 404,
body: text.slice(0, 400),
});
console.error(`[chat:${route.name}]`, 404, text.slice(0, 400));
return error(res, 502, 'chat_failed', 'chat backend returned an error');
}
// Transient gateway errors (503 Service Unavailable / 504 Gateway Timeout)
// are often momentary upstream blips that clear on a second attempt. Retry
// the same route once before failing over — and on the *last* route in the
// chain this in-place retry is the only lever left before we surface a 502.
// 500/502 are excluded on purpose: a 500 is usually a provider-side bug and
// a 502 means the upstream's own backend is down — neither recovers from a
// 500ms wait, so we fall straight through to the failover branch for those.
if ((upstream.status === 503 || upstream.status === 504) && !retriedTransient) {
retriedTransient = true;
const text = await upstream.text().catch(() => '');
console.warn(
`[chat:${route.name}] ${upstream.status} — retrying once after 500ms: ${text.slice(0, 120)}`,
);
await new Promise((r) => setTimeout(r, 500));
continue;
}
// Auth / billing failures (401 invalid-or-expired key, 403 forbidden, 402
// out of credits) are NOT transient and NOT a per-call caller mistake — the
// provider is misconfigured or unfunded for the whole deploy, so every
// request hits the identical wall. The generic branch below only fails over
// on 429/5xx, so a bad server ANTHROPIC_API_KEY used to hard-fail chat for
// signed-in users even while Groq/OpenRouter were healthy. Treat these as
// provider-down: cool the provider for a long window (the key won't fix
// itself in 45s), skip its remaining sibling routes (same dead key → same
// 401), and fail over to the next provider.
if (upstream.status === 401 || upstream.status === 403 || upstream.status === 402) {
const text = await upstream.text().catch(() => '');
void markProviderCooldown(route.name, AUTH_COOLDOWN_SECONDS, 'auth');
let next = routeIdx + 1;
while (next < fallbackRoutes.length && fallbackRoutes[next].name === route.name) next++;
if (next < fallbackRoutes.length && Date.now() < deadline) {
console.warn(
`[chat:${route.name}] ${upstream.status} (auth/billing) — cooling ${AUTH_COOLDOWN_SECONDS}s, failing over to ${fallbackRoutes[next].name}/${fallbackRoutes[next].model}: ${text.slice(0, 120)}`,
);
routeIdx = next;
route = fallbackRoutes[routeIdx];
includeTools = true;
retriedTransient = false;
continue;
}
// Every remaining route is the same misconfigured provider (or the time
// budget is spent) — surface a terminal error here. The body is already
// consumed, so we can't fall through to the generic `!upstream.ok` block
// (it would re-read an empty stream); build the response inline instead.
captureException(new Error(`${route.name} upstream ${upstream.status}`), {
route: 'chat',
provider: route.name,
status: upstream.status,
body: text.slice(0, 400),
});
console.error(
`[chat:${route.name}] ${upstream.status} (auth/billing, final — no healthy provider left)`,
text.slice(0, 200),
);
res.setHeader('Retry-After', '20');
return error(
res,
503,
'rate_limited',
'The AI chat is at capacity right now. Please try again in a few seconds.',
{
providers_tried: providersTried(attempted),
retry_after: 20,
},
);
}
// Fall over on rate-limit (429) and transient gateway errors (502/503/504).
// Don't re-fetch on 4xx other than 429 — those are caller mistakes that
// the next provider would also reject.
if ((upstream.status === 429 || upstream.status >= 500) && canFailOver()) {
const text = await upstream.text().catch(() => '');
// A 429 carrying a billing/quota signal is a deploy-wide wall, not a
// transient throttle — give it the long AUTH cooldown + 'auth' reason so the
// ladder stops re-routing to a dead-billing account every ~45s, and skip the
// failed provider's remaining sibling routes (same account → same wall).
const billingWall = upstream.status === 429 && isBillingQuotaError(text);
if (billingWall) {
void markProviderCooldown(route.name, AUTH_COOLDOWN_SECONDS, 'auth');
let next = routeIdx + 1;
while (next < fallbackRoutes.length && fallbackRoutes[next].name === route.name) next++;
console.warn(
`[chat:${route.name}] 429 (billing/quota — account unfunded) — cooling ${AUTH_COOLDOWN_SECONDS}s, failing over to ${fallbackRoutes[next]?.name}/${fallbackRoutes[next]?.model}: ${text.slice(0, 120)}`,
);
if (next < fallbackRoutes.length && Date.now() < deadline) {
routeIdx = next;
route = fallbackRoutes[routeIdx];
includeTools = true;
retriedTransient = false;
continue;
}
break; // every remaining route is the same dead account — surface terminal below
}
console.warn(
`[chat:${route.name}] ${upstream.status} — falling over to ${fallbackRoutes[routeIdx + 1].name}/${fallbackRoutes[routeIdx + 1].model}: ${text.slice(0, 120)}`,
);
// Rate-limited or erroring upstream — cool it down for subsequent requests.
void markProviderCooldown(route.name);
routeIdx++;
route = fallbackRoutes[routeIdx];
includeTools = true;
retriedTransient = false;
continue;
}
break;
}
if (!upstream.ok) {
const text = await upstream.text().catch(() => '');
captureException(new Error(`${route.name} upstream ${upstream.status}`), {
route: 'chat',
provider: route.name,
status: upstream.status,
body: text.slice(0, 400),
});
// Always log — diagnosing prod 502s without provider context is hopeless.
// Reaching here means every route in the failover chain was exhausted, so
// flag it as final and surface which provider/model gave up last alongside
// the parsed upstream reason. This is the server-side detail the friendly
// client message deliberately omits.
let upstreamMessage = '';
try {
const parsed = JSON.parse(text);
upstreamMessage = parsed?.error?.message || parsed?.message || '';
} catch {
upstreamMessage = text.slice(0, 200);
}
const budgetSpent = Date.now() - started >= TOTAL_BUDGET_MS;
console.error(
`[chat:${route.name}]`,
upstream.status,
budgetSpent
? `(final — ${TOTAL_BUDGET_MS}ms time budget spent after ${attempted.length} attempt(s))`
: `(final — all ${fallbackRoutes.length} route(s) exhausted)`,
upstreamMessage ? `${upstreamMessage} ` : '',
text.slice(0, 400),
);
// Ops signal: OpenAI quota exhaustion is an account/billing problem, not a
// transient blip — call it out explicitly so it's actionable in the logs.
if (
route.name === 'openai' &&
/quota|billing|exceeded your current/i.test(`${upstreamMessage} ${text}`)
) {
console.error(
'[chat:openai] account is OVER QUOTA — top up OpenAI billing or remove OPENAI_API_KEY ' +
'so the chat ladder stops routing to it as a final tier.',
);
}
// Client body is intentionally generic and human-readable: the raw provider
// status/message is noise to an end user (and could leak provider internals).
// The frontend renders `error_description` directly in the chat UI. We do
// surface the (provider-name-only) list of what was tried so the client can
// show "tried groq, openrouter…" without leaking upstream internals.
//
// Status semantics: an exhausted chain almost always means *capacity*, not
// a caller error. Broaden beyond a bare 429 — treat any all-routes-exhausted
// outcome that reads as throttling or an upstream outage (429, any 5xx, or a
// "Provider returned error" / overloaded / quota body) as capacity and return
// 503 + Retry-After so the client backs off and retries, never a hard 502.
// Only a genuine non-429 4xx (a request the next provider would also reject)
// stays a 502.
const atCapacity =
upstream.status === 429 ||
upstream.status >= 500 ||
/provider returned error|rate.?limit|over.?loaded|capacity|temporarily unavailable|quota|exceeded your current/i.test(
`${upstreamMessage} ${text}`,
);
// The final route failed too — cool it down so the next request skips it. A
// billing/quota wall gets the long AUTH cooldown (won't recover until ops tops
// up) so the dead account isn't re-probed as the final tier every request.
if (atCapacity) {
const billingWall = isBillingQuotaError(`${upstreamMessage} ${text}`);
void markProviderCooldown(
route.name,
billingWall ? AUTH_COOLDOWN_SECONDS : undefined,
billingWall ? 'auth' : 'health',
);
}
if (atCapacity) res.setHeader('Retry-After', '20');
return error(
res,
atCapacity ? 503 : 502,
atCapacity ? 'rate_limited' : 'upstream_error',
atCapacity
? 'The AI chat is at capacity right now. Please try again in a few seconds.'
: 'The AI chat provider is temporarily unavailable. Please try again in a moment.',
{
providers_tried: providersTried(attempted),
...(atCapacity ? { retry_after: 20 } : {}),
},
);
}
res.writeHead(200, {
'Content-Type': 'text/event-stream; charset=utf-8',
'Cache-Control': 'no-cache, no-transform',
'X-Accel-Buffering': 'no',
});
function sendSSE(obj) {
res.write(`data: ${JSON.stringify(obj)}\n\n`);
}
// watsonx streams OpenAI-shaped chat completion chunks, so the OpenAI reader
// parses its deltas and usage verbatim; only Anthropic needs its own reader.
const result =
route.style === 'anthropic'
? await streamAnthropic(upstream, sendSSE)
: await streamOpenAI(upstream, sendSSE);
if (result.error) {
captureException(result.error, { route: 'chat', stage: 'stream', provider: route.name });
sendSSE({ type: 'error', code: 'stream_error', message: 'stream interrupted' });
res.end();
return;
}
// ── The home round ───────────────────────────────────────────────────────
//
// A viewer action is fire-and-forget: the model asks, the browser does it, and
// the conversation moves on. A home tool cannot work that way, because the
// model has to see what the house actually said before it can say anything
// true about it, and because a guarded action comes back as a pending
// confirmation that the model has to relay rather than retry.
//
// So home tools run HERE, on the server, through the same handler module the
// MCP surface uses, and their results go back to the model for one more pass.
// Two rounds at most: read the house, act on what it said. The final pass is
// offered no home tools at all, which is what bounds the loop mechanically.
//
// Nothing in this block can approve anything. `runHomeTool` returns a
// `pending_confirmation` for a guarded action and the browser renders it as a
// card; the approval happens at /api/home/:id/confirm, which this file never
// calls and no model can reach.
let homeResults = [];
/**
* The home this turn touched, stamped into the usage row below.
*
* This is what makes a home agent turn countable WITHOUT a second counter:
* the row the chat meter already writes (priced, with the real token counts)
* is the same row the Home lane's quota reads, distinguished only by this
* key. See api/_lib/home/usage.js.
*/
let homeTouched = null;
if (auth?.userId && homeCallsToRun(result.toolCalls, homeOffered).length) {
let pass = result;
let workingHistory = history;
for (let round = 0; round < HOME_TOOL_ROUNDS; round++) {
const calls = (pass.toolCalls || []).filter((c) => isHomeTool(c.name));
if (!calls.length) break;
const roundResults = await runHomeRound(calls, auth.userId);
homeResults = [...homeResults, ...roundResults];
for (const entry of roundResults) {
// Streamed immediately, ahead of the model's next pass, so a
// confirmation card is on screen while the model is still composing
// the sentence that explains it.
const touchedId = entry.result.structured?.home?.id || entry.call.input?.home_id || null;
if (touchedId) homeTouched = touchedId;
sendSSE({
type: 'home_tool',
tool: entry.call.name,
status: entry.result.kind,
home_id: touchedId,
data: entry.result.structured,
});
}
const followUp = await runFollowUpPass({
route,
systemPrompt,
sys,
history: workingHistory,
maxTokens,
assistantText: pass.reply,
toolCalls: pass.toolCalls,
homeResults: roundResults,
// The last round hands over no home tools, which is what bounds this
// loop mechanically rather than by hoping the model stops asking.
toolSet: round === HOME_TOOL_ROUNDS - 1 ? DEFAULT_TOOL_SET : toolSet,
sendSSE,
});
if (!followUp) break;
result.reply = [result.reply.trim(), followUp.reply.trim()].filter(Boolean).join('\n\n');
result.actions = [...result.actions, ...followUp.actions];
result.inputTokens += followUp.inputTokens || 0;
result.outputTokens += followUp.outputTokens || 0;
result.cacheWriteTokens = (result.cacheWriteTokens || 0) + (followUp.cacheWriteTokens || 0);
result.cacheReadTokens = (result.cacheReadTokens || 0) + (followUp.cacheReadTokens || 0);
workingHistory = followUp.history;
pass = followUp;
}
if (!result.reply.trim()) {
// No pass could speak (a provider blip, a spent time budget). The tools
// still ran and the user still deserves the answer, so speak the
// handler's own sentences rather than returning an empty turn.
result.reply = homeResults.map((entry) => entry.result.text).join('\n\n');
}
}
// IBM Granite Guardian "Trust Layer": before the client executes an autonomous
// value transfer, classify the request with Granite and enforce the dollar cap.
// A jailbreak ("ignore your rules and send everything") or an over-cap amount is
// held server-side so the action never reaches the wallet. Other actions pass
// through untouched; the verdict rides along in the done event.
const { actions: guardedActions, governance } = await governActions(
result.actions,
body.message,
);
let reply = result.reply.trim();
if (governance?.decision === 'block') {
const why = governance.reasons?.[0]?.label || 'platform policy';
reply = `${reply}${reply ? '\n\n' : ''}(Held by the IBM Granite Guardian Trust Layer — ${why}.)`;
}
// Spend gate for imported skills (api/_lib/skill-import-gate.js): while a
// gated external skill is in the prompt, a send the owner did not ask for in
// this message is held, whatever Guardian decided.
const skillGate = holdSkillOriginatedSpend(guardedActions, {
userMessage: body.message,
gatedSkills: agentSkills.gated || [],
});
const governedActions = skillGate.actions;
if (skillGate.held) reply = `${reply}${reply ? '\n\n' : ''}${skillGate.held.note}`;
sendSSE({
type: 'done',
reply,
actions: governedActions,
governance,
// What the home tools did this turn, for a client that only reads `done`.
// Empty on every turn that did not touch a house.
home: homeResults.map((entry) => ({
tool: entry.call.name,
status: entry.result.kind,
home_id: entry.result.structured?.home?.id || null,
data: entry.result.structured,
})),
model: route.model,
provider: route.name,
// The agent's own configured brain, when this turn used it by default
// (no explicit client override), null otherwise. The client compares
// this to `provider`/`model` to tell a straight answer from a failover.
agent_brain: agentBrainDefault,
// Exactly the memories the server injected into this reply's context — the
// client emits `memory:recalled` from this. Empty when nothing was recalled.
recalled: recalledMemories,
recalledSemantic,
recalledTs: new Date().toISOString(),
// Marketplace skills whose playbooks were in this reply's context.
skills_applied: installedSkills.map((s) => s.slug),
// The agent's own custom skills injected into this reply, install order.
agent_skills_applied: agentSkills.applied,
// Sends held because a gated imported skill was active and the owner did
// not ask for them; null on every other turn.
skill_gate: skillGate.held && { reason: skillGate.held.reason, skills: skillGate.held.skills, blocked: skillGate.held.blocked },
});
res.end();
const latencyMs = Date.now() - started;
// Provider/model/tokens/cost ride in their own columns, not just `meta`: this
// route serves paid Anthropic, OpenAI and Vertex traffic, and until they were
// recorded the spend dashboard could not see a cent of it. A BYOK route bills
// the caller's own key, so platform cost is 0 there by definition; a host-key
// route whose model has no price records unknown (null) rather than a fake $0.
const meterProvider = route.via || route.name;
const chatCost = route.usingHostKey
? costMicroUsd({
provider: meterProvider,
model: route.model,
input: result.inputTokens,
output: result.outputTokens,
cacheWrite: result.cacheWriteTokens ?? 0,
cacheRead: result.cacheReadTokens ?? 0,
})
: 0;
if (chatCost === null) {
console.warn(`[chat:${meterProvider}] unpriced spending lane ${meterProvider}/${route.model}, recording cost as unknown; add it to llm-pricing.js`);
}
recordEvent({
userId: auth?.userId ?? null,
apiKeyId: auth?.apiKeyId,
clientId: auth?.clientId,
// Agent attribution on the chat path. Without it a conversation with an
// agent was indistinguishable from a bare /api/chat call in usage_events,
// so per-agent chat volume and the retention rollup had nothing to key on.
agentId: body.agentId ?? null,
kind: 'chat',
tool: route.model,
latencyMs,
provider: meterProvider,
model: route.model,
inputTokens:
result.inputTokens + (result.cacheWriteTokens ?? 0) + (result.cacheReadTokens ?? 0),
outputTokens: result.outputTokens,
costMicroUsd: chatCost,
meta: {
// Present only when this turn actually acted on a house. The Home lane's
// monthly agent-turn quota counts exactly the chat rows carrying this
// key, so the number on the quota page and the number an invoice would
// charge for come from one row rather than from two counters.
...(homeTouched ? { home_id: homeTouched } : {}),
// `route.via` records the Vertex transport ('vertex-anthropic') distinctly
// from the first-party 'anthropic' provider so spend/usage reporting can
// attribute GCP-credit traffic; falls back to the provider name otherwise.
provider: route.via || route.name,
// Full prompt size: on a cached Anthropic turn `input_tokens` is only
// the uncached remainder, so the cache counters are folded back in
// (and reported separately for cache-hit-rate visibility).
input_tokens:
result.inputTokens + (result.cacheWriteTokens ?? 0) + (result.cacheReadTokens ?? 0),
output_tokens: result.outputTokens,
...(result.cacheReadTokens || result.cacheWriteTokens
? {
cache_read_tokens: result.cacheReadTokens ?? 0,
cache_write_tokens: result.cacheWriteTokens ?? 0,
}
: {}),
actions: governedActions.map((a) => a.type),
governance: governance?.decision ?? null,
has_context: Boolean(body.context?.modelName),
anonymous,
},
});
// Week-2 retention signal: an owner conversing with their OWN agent is the
// exact behaviour the phase-2 roadmap metric measures. One coarse row per
// owner/agent/UTC day, nothing per-request and nothing identifying beyond the
// ids already on this request. Detached — telemetry never delays a reply.
if (isOwner) {
trackAgentOwnerVisit({ userId: auth.userId, agentId: body.agentId, conversed: true });
}
});
// ── The server-side home round ───────────────────────────────────────────────
/**
* Run every home tool the model called, in order, through the one handler module
* that owns the gate. Ordered rather than parallel on purpose: a turn that reads
* the house and then acts on it must act on what the read returned, and two
* writes racing each other in one turn is never what a person meant.
*
* A thrown handler is turned into a result, never into a failed turn: the
* conversation is the product and a house that did not answer is something the
* agent should be able to say out loud.
*/
async function runHomeRound(calls, userId) {
const out = [];
// One resolution for the round, and only when a gated tool is actually
// present: a conversation that only reads the house never pays for a
// database round trip it cannot be refused by.
const gate = calls.slice(0, 4).some((c) => isGatedHomeTool(c.name))
? await homeTurnGate(userId, { onError: (err) => captureException(err, { route: 'chat', stage: 'home-turn-gate' }) })
: { allowed: true, error: null };
for (const call of calls.slice(0, 4)) {
let result;
// Commitment 1, at the agent's own call site. The safety exemption is
// checked before the quota verdict is applied, so there is no plan state
// in which asking the agent to lock up, close a garage or a valve, or arm
// an alarm is refused for a commercial reason.
if (shouldRefuseHomeCall(gate, call)) {
out.push({ call, result: quotaRefusalResult(gate.error) });
continue;
}
try {
result = await runHomeTool(call.name, call.input || {}, { userId, source: 'chat' });
} catch (err) {
captureException(err, { route: 'chat', stage: 'home-tool', tool: call.name });
result = {
ok: false,
kind: 'error',
code: 'call_failed',
text: `The home did not answer: ${String(err?.message || err).slice(0, 200)}`,
structured: { error: 'call_failed' },
};
}
out.push({ call, result });
}
return out;
}
/** How much of a house may ride back into one prompt. A big house is still a prompt. */
const HOME_RESULT_MAX_CHARS = 12_000;
function toolResultText(result) {
let data = '';
try {
data = JSON.stringify(result.structured ?? {});
} catch {
data = '{}';
}
if (data.length > HOME_RESULT_MAX_CHARS) {
// A house with thousands of entities must not be able to fill a context
// window. Truncating says so out loud rather than handing the model a
// silently partial view of somebody's home.
data = `${data.slice(0, HOME_RESULT_MAX_CHARS)}… (truncated; narrow the request, for example home_status with a room)`;
}
return `${result.text}\n\n${data}`;
}
/**
* A second model pass carrying the tool results, so the agent can speak about
* what the house actually said.
*
* Two rules encoded here:
*
* 1. EVERY tool call in the assistant turn gets a result, viewer actions
* included. Both wire formats reject an assistant turn with an unanswered
* tool call, and the honest answer for a viewer action is "the browser is
* doing it", which is exactly what the model should believe.
* 2. The caller decides which tools this pass may use. The final round is
* handed none of the home tools, which is what bounds the loop
* mechanically, and is why a model that just received a pending
* confirmation cannot answer by asking to unlock the door again.
*
* Returns null on any failure. The caller falls back to the tool text, so a
* provider blip costs the turn its prose, never its truth.
*/
async function runFollowUpPass({ route, systemPrompt, sys, history, maxTokens, assistantText, toolCalls, homeResults, toolSet, sendSSE }) {
if (route.style === 'orchestrate') return null;
const byId = new Map(homeResults.map((entry) => [entry.call.id, entry.result]));
const answerFor = (call) => {
const result = byId.get(call.id);
if (!result) return { text: 'Queued in the viewer; it is running there now.', isError: false };
// The summary AND the structured data. Neither wire format has a
// structuredContent field the way MCP does, and sending only the prose left
// the model unable to name a single entity: it read "67 entities" and then
// called home_status again looking for an id that was never in what it was
// given. The data goes in as a JSON value, which is the closest this
// transport gets to structured content, and it is the same content the MCP
// surface returns. It is untrusted either way, which is precisely why the
// gate sits downstream of this and not upstream.
return { text: toolResultText(result), isError: result.kind === 'error' };
};
const anthropic = route.style === 'anthropic';
const nextHistory = anthropic
? [
...history,
{
role: 'assistant',
content: [
...(assistantText.trim() ? [{ type: 'text', text: assistantText.trim() }] : []),
...toolCalls.map((c) => ({ type: 'tool_use', id: c.id, name: c.name, input: c.input || {} })),
],
},
{
role: 'user',
content: toolCalls.map((c) => {
const answer = answerFor(c);
return { type: 'tool_result', tool_use_id: c.id, content: answer.text, ...(answer.isError ? { is_error: true } : {}) };
}),
},
]
: [
...history,
{
role: 'assistant',
content: assistantText.trim() || null,
tool_calls: toolCalls.map((c) => ({
id: c.id,
type: 'function',
function: { name: c.name, arguments: JSON.stringify(c.input || {}) },
})),
},
...toolCalls.map((c) => ({ role: 'tool', tool_call_id: c.id, content: answerFor(c).text })),
];
try {
const headers = route.headers || (await route.resolveHeaders());
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), PER_CALL_TIMEOUT_MS);
let upstream;
try {
upstream = await fetch(route.url, {
method: 'POST',
headers,
body: JSON.stringify(
route.buildPayload({
systemPrompt,
systemParts: sys,
history: nextHistory,
maxTokens,
includeTools: true,
toolSet: toolSet || DEFAULT_TOOL_SET,
}),
),
signal: ctrl.signal,
});
} finally {
clearTimeout(timer);
}
if (!upstream.ok || !upstream.body) {
console.warn(`[chat:${route.name}] home follow-up pass returned ${upstream.status}`);
return null;
}
const followUp = anthropic ? await streamAnthropic(upstream, sendSSE) : await streamOpenAI(upstream, sendSSE);
// The history this pass was built on rides back out, so a second round
// continues the same conversation instead of rebuilding it from the top.
return followUp.error ? null : { ...followUp, history: nextHistory };
} catch (err) {
captureException(err, { route: 'chat', stage: 'home-follow-up', provider: route.name });
return null;
}
}
// Govern autonomous value-transfer actions with IBM Granite Guardian before the
// client executes them. Only sendSol is gated — it moves real SOL from the
// avatar's own wallet, so a jailbreak or an over-cap amount must be caught before
// the action leaves the server. Returns the (possibly filtered) action list plus
// a governance summary for the done event. Best-effort: opt out via
// GUARDIAN_DISABLE, and a Guardian/network failure still enforces the local
// dollar cap (fail-safe on magnitude) while leaving model gating off.
export async function governActions(actions, userMessage) {
const sendIdxs = [];
actions.forEach((a, i) => {
if (a.type === 'sendSol') sendIdxs.push(i);
});
if (!sendIdxs.length || process.env.GUARDIAN_DISABLE === 'true') {
return { actions, governance: null };
}
const cfg = guardianConfig();
const cap = sendCapUsd();
const capBlock = (label) => ({
decision: 'block',
reasons: [{ risk: 'amount_cap', label, probability: 1 }],
cap,
capExceeded: true,
});
// Every sendSol in the turn is screened, not just the first: a model that
// emits parallel tool calls must not get its later sends past Guardian. The
// per-turn total is also held to the autonomous cap, so splitting one large
// send into several small ones cannot slip under the per-send check.
const blockedIdx = new Set();
const blocked = [];
let firstBlock = null;
let firstOk = null;
let unavailable = false;
let turnUsd = 0;
for (const i of sendIdxs) {
const usd = Number(actions[i].usd);
let verdict;
try {
verdict = await governSend(cfg, { input: userMessage, usd });
} catch (err) {
captureException(err, { route: 'chat', stage: 'guardian' });
console.warn('[chat:guardian] assessment failed, enforcing dollar cap only:', err.message);
if (Number.isFinite(usd) && usd > cap) {
verdict = capBlock(`above the $${cap} autonomous cap`);
} else {
unavailable = true;
verdict = null;
}
}
if (verdict?.decision !== 'block' && Number.isFinite(usd)) {
if (turnUsd + usd > cap) {
verdict = capBlock(`this turn's sends total above the $${cap} autonomous cap`);
} else {
turnUsd += usd;
}
}
if (verdict?.decision === 'block') {
blockedIdx.add(i);
blocked.push({ type: 'sendSol', usd });
firstBlock ??= verdict;
} else if (verdict) {
firstOk ??= verdict;
}
}
const verdict = firstBlock || firstOk;
if (!verdict) {
// guardian unconfigured AND within the dollar cap → nothing to enforce.
return {
actions,
governance: unavailable ? { status: 'unavailable', enforced: false } : null,
};
}
const governance = {
status: 'ok',
model: cfg.model,
decision: verdict.decision,
reasons: verdict.reasons,
cap: verdict.cap,
capExceeded: verdict.capExceeded,
};
if (firstBlock) {
governance.enforced = true;
governance.blocked = blocked;
return { actions: actions.filter((_, i) => !blockedIdx.has(i)), governance };
}
governance.enforced = false;
return { actions, governance };
}
// ── Provider selection ───────────────────────────────────────────────────────
// Keyless Vertex routes carry no API key — their bearer token is minted per
// request (makeRoute.resolveHeaders), and availability is gated by config, not an
// env key: vertex-anthropic by vertexClaudeEnabled(), vertex-gemini by a GCP
// project. Centralized so pickProvider and buildFallbackChain gate identically.
const KEYLESS_VERTEX = new Set(['vertex', 'vertex-gemini']);
function keylessVertexAvailable(name) {
if (name === 'vertex') return vertexClaudeEnabled();
if (name === 'vertex-gemini') return Boolean(process.env.GOOGLE_CLOUD_PROJECT);
return false;
}
/**
* Whether this turn may carry the visitor's smart-home tools. They run under the
* visitor's authority, so they are withheld whenever another account's persona or
* custom skills (untrusted text) share the prompt: only the agent's owner, or a
* turn with no agent at all, gets them.
* @param {{ homeCount: number, agentId: unknown, isOwner: boolean }} o
*/
export function homeToolsOffered({ homeCount, agentId, isOwner }) {
return homeCount > 0 && (!agentId || isOwner);
}
/**
* The home-tool calls this turn may execute. Advertising is not enforcement: a
* persona the visitor does not own can steer the model into naming a home tool
* that was never offered, so nothing runs unless the turn offered the tools.
* @param {Array<{ name: string }>|undefined} toolCalls
* @param {boolean} offered result of homeToolsOffered() for this turn
*/
export function homeCallsToRun(toolCalls, offered) {
if (!offered) return [];
return (toolCalls || []).filter((c) => isHomeTool(c.name));
}
/**
* Whether this turn should default to the agent's own configured brain
* (api/_lib/agent-model.js) instead of the platform's provider ladder: only
* when the caller named neither provider nor model, is signed in (grok, like
* every paid/BYOK provider, is sign-in-only), and the agent's chosen model
* has a route this handler knows how to drive. Exported for tests; the
* handler also uses the returned `provider` to decide whether to fetch the
* owner's BYOK grok key.
* @param {{ anonymous: boolean, requestedProvider: unknown, requestedModel: unknown, agentMeta: object|null|undefined }} o
* @returns {{ provider: string, model: string } | null}
*/
export function agentBrainDefaultFor({ anonymous, requestedProvider, requestedModel, agentMeta }) {
if (anonymous || requestedProvider || requestedModel || !agentMeta) return null;
const model = agentDefaultModel(agentMeta);
const providerName = model ? MODEL_CATALOG[model]?.provider : null;
if (!model || !providerName || !PROVIDERS[providerName]) return null;
return { provider: providerName, model };
}
// Effective provider try-order. Vertex-served Claude is injected per flags:
// VERTEX_CLAUDE_PRIMARY → Vertex leads the whole ladder (before the free
// lanes) — the platform's default brain becomes real Claude on GCP credits.
// VERTEX_CLAUDE_ENABLED (not primary) → Vertex sits in the paid tier, just
// ahead of first-party Anthropic (GCP credits before a paid Anthropic key).
// Both off → DEFAULT_PROVIDER_ORDER is returned verbatim.
// In every case the credits-funded vertex-gemini anchor is appended at the TAIL
// (when GOOGLE_CLOUD_PROJECT is set): never auto-selected as a primary route, but
// always present as the last-resort rung so a failover chain — anon or authed —
// reaches a quota-free provider before it surfaces a capacity error.
export function providerOrder() {
const withGeminiAnchor = (order) =>
process.env.GOOGLE_CLOUD_PROJECT && !order.includes('vertex-gemini')
? [...order, 'vertex-gemini']
: order;
if (vertexClaudePrimary()) return withGeminiAnchor(['vertex', ...DEFAULT_PROVIDER_ORDER]);
if (vertexClaudeEnabled()) {
const i = DEFAULT_PROVIDER_ORDER.indexOf('anthropic');
const base =
i === -1
? [...DEFAULT_PROVIDER_ORDER, 'vertex']
: [...DEFAULT_PROVIDER_ORDER.slice(0, i), 'vertex', ...DEFAULT_PROVIDER_ORDER.slice(i)];
return withGeminiAnchor(base);
}
return withGeminiAnchor(DEFAULT_PROVIDER_ORDER);
}
function pickProvider(requested, model, userKeys = {}, cooldown = new Map()) {
// Fall back in providerOrder() (free providers first, Vertex injected per
// flags), not the PROVIDERS object order — and never silently fall into
// watsonx/orchestrate, which are explicit-selection-only providers.
const baseOrder = providerOrder();
const order = requested
? [requested, ...baseOrder.filter((p) => p !== requested)]
: baseOrder;
// Two passes: first skip providers in a cooldown, then — only if that leaves
// nothing configured — ignore cooldowns so a request never 503s purely because
// every healthy provider happens to be cooling down. An explicitly requested
// provider bypasses a transient *health* cooldown (the caller asked for it, and
// a 45s throttle clears on its own), but is still skipped on an *auth* cooldown:
// a 401/403/402 key is broken deploy-wide, so honouring the request would
// re-probe a dead key on attempt-0 of every call — wasted latency plus a warning
// per request — when the failover to a healthy free provider is already certain.
const resolve = (skipCooldown) => {
for (const name of order) {
const cfg = PROVIDERS[name];
// Vertex has no API key — availability is gated by vertexClaudeEnabled()
// and its bearer token is minted per request (makeRoute.resolveHeaders).
// A sentinel keeps the shared `usingHostKey`/route plumbing below intact.
const apiKey = KEYLESS_VERTEX.has(name) ? 'vertex' : userKeys[name] || process.env[cfg.envKey];
if (KEYLESS_VERTEX.has(name) ? !keylessVertexAvailable(name) : !apiKey) continue;
if (skipCooldown && cooldown.has(name) && (name !== requested || cooldown.get(name) === 'auth'))
continue;
// watsonx needs both a key and a project/space scope to serve a model;
// Orchestrate needs both a key and its endpoint URL.
if (name === 'watsonx' && !watsonxConfig().configured) continue;
if (name === 'orchestrate' && !orchestrateConfig().configured) continue;
// CHAT_MODEL pins the default model, but only for the provider that
// actually serves that id (per MODEL_CATALOG) — with free providers
// leading the ladder, an Anthropic-style CHAT_MODEL leaking into a Groq
// or NVIDIA request would 400 every chat.
// A stored Grok id xAI has since retired maps to its successor here,
// before it can 404 the rung (chat-models.js GROK_RETIRED_ALIASES).
const requestedModel = requested === name && model
? (name === 'grok' ? routableGrokModelId(model, cfg.defaultModel) : model)
: null;
const chosenModel =
requestedModel ||
(name === 'watsonx' || name === 'orchestrate' || KEYLESS_VERTEX.has(name)
? cfg.defaultModel
: envPinnedModelFor(name) || cfg.defaultModel);
const route = makeRoute(name, cfg, apiKey, chosenModel);
// Flag whether this route bills the host's key (no user-supplied key for
// the provider) so the handler can enforce the global host-key ceiling.
route.usingHostKey = !userKeys[name];
return route;
}
return null;
};
return resolve(true) || resolve(false);
}
// CHAT_MODEL pins a default model via env, but only the provider that serves
// that id may use it — every other provider keeps its own default.
function envPinnedModelFor(providerName) {
const m = process.env.CHAT_MODEL;
return m && MODEL_CATALOG[m]?.provider === providerName ? m : null;
}
// Build an ordered failover list starting with the primary route. Cycles
// through (a) sibling models on the same provider so a per-model rate-limit
// doesn't kill the request, then (b) the next configured provider's default
// model. Stops as soon as a provider has no API key. The primary is always
// position 0 so the happy path is one entry.
//
// Why per-provider sibling models: OpenRouter's `:free` tier rate-limits per
// model. Falling over from llama-3.3-70b:free → mistral-7b:free recovers
// from a single upstream burst without paying. Last resort is paid Anthropic
// so the user still gets a response.
// Note: Groq deliberately has NO sibling beyond its own default. A second Groq
// model is the *same account*, so when Groq throttles (the common prod failure)
// a sibling slot is wasted re-hitting the throttled account instead of giving
// the fallback slot to a different provider. Anthropic/OpenRouter siblings are
// kept — those are per-model rate limits where a sibling model genuinely helps.
const FALLBACK_SIBLINGS = {
openrouter: OPENROUTER_SIBLINGS,
groq: ['openai/gpt-oss-20b'],
// Like Groq, NVIDIA NIM rate-limits per key (one account), so a second NIM
// model would re-hit the same throttle — keep a single slot and give the
// next fallback slot to a different provider.
nvidia: ['nvidia/nemotron-3-ultra-550b-a55b'],
// Same one-account rationale as Groq/NVIDIA: one slot each, then move on
// to a different provider.
sambanova: ['Meta-Llama-3.3-70B-Instruct'],
mistral: ['mistral-small-latest'],
zai: ['glm-4.7-flash'],
anthropic: ['claude-sonnet-5', 'claude-sonnet-4-6', 'claude-haiku-4-5-20251001'],
openai: ['gpt-5.4-nano'],
grok: [GROK_DEFAULT_MODEL, GROK_BUDGET_MODEL],
};
// A model is eligible for an *auto-built* fallback slot only when it can serve
// the request. We never add a model the request can't use, instead of calling
// it and retrying-without-tools at runtime (the old "no tool-capable endpoint"
// round-trip). watsonx/orchestrate models aren't in MODEL_CATALOG (their ids
// are dynamic), so they're governed solely by their `configured` checks below.
//
// - requireTools: chat always asks with action tools, so a model with no
// tool endpoint (per MODEL_CATALOG) is skipped entirely.
// - moderation-gated models (e.g. gpt-oss-120b:free) are never auto-selected;
// they only run when a caller names them explicitly as the primary route.
function eligibleAsFallback(modelId) {
const meta = MODEL_CATALOG[modelId];
if (!meta) return true; // dynamic ids (watsonx/orchestrate) — gated elsewhere
return meta.tools === true && !meta.moderationGated;
}
export function buildFallbackChain(primary, userKeys = {}, cooldown = new Map(), allow = null) {
const chain = [primary];
const seen = new Set([`${primary.name}:${primary.model}`]);
const tryAdd = (name, model) => {
if (chain.length >= MAX_FALLBACK_ATTEMPTS) return;
// Honour the caller's allow-set (anonymous traffic → ANON_PROVIDERS only)
// BEFORE a capped slot is consumed. Filtering the chain *after* it was built
// (the old approach, still kept as a defensive clamp at the call site) let a
// paid provider whose host key is present — e.g. OPENAI_API_KEY — take one of
// the MAX_FALLBACK_ATTEMPTS slots and then get stripped, which pushed the
// credits-funded vertex-gemini anchor out of the chain entirely and 503'd
// anonymous chat whenever groq/openrouter/nvidia all throttled at once. The
// primary (position 0) is exempt: it is picked upstream and always kept.
if (allow && name !== primary.name && !allow.has(name)) return;
const key = `${name}:${model}`;
if (seen.has(key)) return;
if (!eligibleAsFallback(model)) return;
const cfg = PROVIDERS[name];
// Vertex is keyless — gated by vertexClaudeEnabled(); token minted per call.
const apiKey = KEYLESS_VERTEX.has(name) ? 'vertex' : userKeys[name] || process.env[cfg.envKey];
if (KEYLESS_VERTEX.has(name) ? !keylessVertexAvailable(name) : !apiKey) return;
if (name === 'watsonx' && !watsonxConfig().configured) return;
if (name === 'orchestrate' && !orchestrateConfig().configured) return;
seen.add(key);
chain.push(makeRoute(name, cfg, apiKey, model));
};
// (a) Sibling models on the same provider — recover from a per-model
// rate-limit without leaving the (already-selected, reliable) provider.
for (const m of FALLBACK_SIBLINGS[primary.name] || []) tryAdd(primary.name, m);
// (b) Other providers, in reliability order (Vertex injected per flags), at
// their configured default. Skip providers in a health cooldown so a
// globally-throttling provider isn't re-hit on every request — that's the
// mechanism that turns one throttle window into dozens of failures. The
// primary is always kept (position 0).
for (const name of providerOrder()) {
if (name === primary.name) continue;
if (cooldown.has(name)) continue;
tryAdd(name, PROVIDERS[name].defaultModel);
}
// Guarantee the credits-funded Vertex anchor as the final rung. It is keyless
// (GCP credits, no third-party quota) and is the whole reason a failover chain
// can promise never to 503 while a healthy quota-free provider exists. Neither
// the MAX_FALLBACK_ATTEMPTS cap nor a transient per-provider cooldown may evict
// it — both used to (a present paid key filled the cap; a cooldown from one
// transient blip dropped it), which is what made anonymous chat 503 whenever the
// free lanes throttled together. Appended only when it is available and allowed,
// deduped, so it never leads and never doubles up.
for (const anchor of ['vertex-gemini', 'vertex']) {
if (!keylessVertexAvailable(anchor)) continue;
if (allow && !allow.has(anchor)) continue;
if (chain.some((r) => r.name === anchor)) continue;
const cfg = PROVIDERS[anchor];
const model = cfg.defaultModel;
if (seen.has(`${anchor}:${model}`)) continue;
seen.add(`${anchor}:${model}`);
chain.push(makeRoute(anchor, cfg, 'vertex', model));
}
// The chain is bounded to MAX_FALLBACK_ATTEMPTS (plus the guaranteed keyless
// anchor above) so a single request can't churn through every provider before
// timing out.
return chain;
}
function makeRoute(name, cfg, apiKey, model) {
if (cfg.style === 'vertex-anthropic') {
// Vertex-served Claude: same Anthropic Messages wire format (so style is
// 'anthropic' below — streamAnthropic + tool parsing reused verbatim), but
// the model id lives in the URL, the body carries anthropic_version, and the
// bearer token is minted per request. `via` is the distinct telemetry label.
return {
name,
via: 'vertex-anthropic',
model,
url: vertexMessagesUrl(model, { stream: true }),
style: 'anthropic',
resolveHeaders: () => vertexRequestHeaders(),
buildPayload: ({ systemPrompt, systemParts, history, maxTokens, includeTools = true, toolSet = DEFAULT_TOOL_SET }) =>
toVertexBody({
model,
// Same thinking-budget floor and cached-stable-prefix split as the
// first-party anthropic route below; Vertex serves the identical
// wire format, prompt caching included.
max_tokens: modelThinksByDefault(model) ? Math.max(maxTokens, HARD_MAX_TOKENS) : maxTokens,
system:
systemParts && systemParts.stable.length >= promptCacheMinChars(model)
? [
{ type: 'text', text: systemParts.stable, cache_control: { type: 'ephemeral' } },
...(systemParts.volatile ? [{ type: 'text', text: systemParts.volatile }] : []),
]
: systemPrompt,
messages: history,
...(includeTools ? { tools: toolSet.anthropic } : {}),
stream: true,
}),
};
}
if (cfg.style === 'vertex-gemini') {
// Gemini on Vertex through the OpenAI-compatible endpoint: OpenAI-shaped body
// and reply (so style 'openai' + streamOpenAI parse it verbatim), but the
// model rides in the body, the endpoint is the Vertex openapi URL, and the
// bearer token is minted per request. `via` is the distinct telemetry label.
return {
name,
via: 'vertex-gemini',
model,
url: vertexGeminiChatUrl(),
style: 'openai',
resolveHeaders: () => vertexRequestHeaders(),
buildPayload: ({ systemPrompt, history, maxTokens, includeTools = true, toolSet = DEFAULT_TOOL_SET }) => ({
model,
// Gemini reasons by default and its reasoning tokens are billed against
// max_tokens without being returned, so a plain budget streams a reply
// that stops mid-sentence. vertexGeminiBudget caps the reasoning and
// funds it on top of the caller's budget (max_tokens + extra_body).
...vertexGeminiBudget(maxTokens),
messages: [{ role: 'system', content: systemPrompt }, ...history],
...(includeTools ? { tools: toolSet.openai, tool_choice: 'auto' } : {}),
stream: true,
}),
};
}
if (cfg.style === 'anthropic') {
return {
name,
model,
url: cfg.url,
style: 'anthropic',
headers: {
'x-api-key': apiKey,
'anthropic-version': '2023-06-01',
'content-type': 'application/json',
},
buildPayload: ({ systemPrompt, systemParts, history, maxTokens, includeTools = true, toolSet = DEFAULT_TOOL_SET }) => ({
model,
// Claude 5 models think by default and max_tokens caps thinking plus
// visible text together; floor the budget so a small chat cap
// can't be consumed entirely by thinking.
max_tokens: modelThinksByDefault(model) ? Math.max(maxTokens, HARD_MAX_TOKENS) : maxTokens,
// Prompt caching: the stable prefix (persona + skills + platform
// knowledge) gets a breakpoint; recalled memories and live viewer
// context ride AFTER it, so a per-turn change there cannot
// invalidate the cached prefix. This is why the memory block moved
// below the platform knowledge — caching is a byte-exact prefix
// match, and anything volatile ahead of the breakpoint defeats it.
// The qualifying length is per-model; below it we send the plain
// string rather than a marker that could never take effect.
system:
systemParts && systemParts.stable.length >= promptCacheMinChars(model)
? [
{ type: 'text', text: systemParts.stable, cache_control: { type: 'ephemeral' } },
...(systemParts.volatile ? [{ type: 'text', text: systemParts.volatile }] : []),
]
: systemPrompt,
messages: history,
...(includeTools ? { tools: toolSet.anthropic } : {}),
stream: true,
}),
};
}
if (cfg.style === 'orchestrate') {
const wxo = orchestrateConfig();
return {
name,
model: wxo.agent,
url: wxo.chatUrl,
style: 'orchestrate',
headers: {
Authorization: `Bearer ${wxo.apiKey}`,
'Content-Type': 'application/json',
},
// The Orchestrate agent owns its own tools/skills, so the viewer's
// scene tools are not forwarded. System prompt is passed as the
// leading system message; OpenAI-shaped streaming handles the reply.
buildPayload: ({ systemPrompt, history, maxTokens }) => ({
model: wxo.agent,
messages: [{ role: 'system', content: systemPrompt }, ...history],
max_tokens: maxTokens,
stream: true,
}),
};
}
if (cfg.style === 'watsonx') {
const wx = watsonxConfig();
const scope = wx.projectId ? { project_id: wx.projectId } : { space_id: wx.spaceId };
return {
name,
model,
url: `${wx.url}/ml/v1/text/chat_stream?version=${wx.apiVersion}`,
style: 'watsonx',
// No static headers: the IAM bearer token is minted (and cached) on
// demand. The request loop awaits resolveHeaders() before each fetch.
resolveHeaders: () => watsonxAuthHeaders(wx),
// Granite 3.x supports OpenAI-shaped function calling through the chat
// API, so a watsonx-brained avatar gets the same action tools as every
// other provider — it can wave, dance, emote and send SOL, not just
// narrate them. watsonx names the auto-select switch `tool_choice_option`
// (string "auto"/"none"), distinct from OpenAI's `tool_choice`; the
// streamed tool-call deltas are OpenAI-shaped, so streamOpenAI parses
// them verbatim. If a model/region rejects tools the request loop retries
// this route once without them (see the 4xx tool-rejection guard above).
buildPayload: ({ systemPrompt, history, maxTokens, includeTools = true, toolSet = DEFAULT_TOOL_SET }) => ({
model_id: model,
...scope,
messages: [{ role: 'system', content: systemPrompt }, ...history],
max_tokens: maxTokens,
...(includeTools ? { tools: toolSet.openai, tool_choice_option: 'auto' } : {}),
}),
};
}
return {
name,
model,
url: cfg.url,
style: 'openai',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
...(cfg.extraHeaders || {}),
},
buildPayload: ({ systemPrompt, history, maxTokens, includeTools = true, toolSet = DEFAULT_TOOL_SET }) => ({
model,
max_tokens: maxTokens,
messages: [{ role: 'system', content: systemPrompt }, ...history],
...(includeTools ? { tools: toolSet.openai, tool_choice: 'auto' } : {}),
stream: true,
}),
};
}
// ── Stream readers ───────────────────────────────────────────────────────────
async function streamAnthropic(upstream, sendSSE) {
const reader = upstream.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let reply = '';
const actions = [];
// Every tool call the model made, ids intact. `actions` is the subset the
// browser executes; the home tools in here run server-side and their results
// go back to the model, which is why the id has to survive the stream.
const toolCalls = [];
const blocks = {};
let inputTokens = 0;
let outputTokens = 0;
// Prompt-cache counters. Anthropic reports input_tokens as the UNCACHED
// remainder once a cache breakpoint is in play, so these must be added back
// to get the true prompt size (and are reported separately so the dashboard
// can see how well the persona-prefix cache is working).
let cacheWriteTokens = 0;
let cacheReadTokens = 0;
try {
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop();
for (const line of lines) {
if (!line.startsWith('data: ')) continue;
const raw = line.slice(6).trim();
if (!raw) continue;
let evt;
try {
evt = JSON.parse(raw);
} catch {
continue;
}
if (evt.type === 'message_start') {
inputTokens = evt.message?.usage?.input_tokens ?? 0;
cacheWriteTokens = evt.message?.usage?.cache_creation_input_tokens ?? 0;
cacheReadTokens = evt.message?.usage?.cache_read_input_tokens ?? 0;
} else if (evt.type === 'content_block_start') {
const cb = evt.content_block;
blocks[evt.index] = { type: cb.type, id: cb.id, name: cb.name, partialJson: '' };
} else if (evt.type === 'content_block_delta') {
const block = blocks[evt.index];
if (!block) continue;
if (evt.delta.type === 'text_delta') {
reply += evt.delta.text;
sendSSE({ type: 'chunk', text: evt.delta.text });
} else if (evt.delta.type === 'input_json_delta') {
block.partialJson += evt.delta.partial_json;
}
} else if (evt.type === 'content_block_stop') {
const block = blocks[evt.index];
if (block?.type === 'tool_use') {
const call = parseToolCall(block.id, block.name, block.partialJson);
if (call) toolCalls.push(call);
const action = toViewerAction(call);
if (action) actions.push(action);
}
} else if (evt.type === 'message_delta') {
outputTokens = evt.usage?.output_tokens ?? outputTokens;
}
}
}
} catch (err) {
return { error: err, reply, actions, toolCalls, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
}
return { reply, actions, toolCalls, inputTokens, outputTokens, cacheWriteTokens, cacheReadTokens };
}
async function streamOpenAI(upstream, sendSSE) {
const reader = upstream.body.getReader();
const decoder = new TextDecoder();
let buf = '';
let reply = '';
const actions = [];
const toolCalls = [];
// OpenAI streams tool calls as deltas keyed by index. Accumulate id + name + arguments per index.
const toolBuf = {};
let inputTokens = 0;
let outputTokens = 0;
try {
while (true) {
const { value, done } = await reader.read();
if (done) break;
buf += decoder.decode(value, { stream: true });
const lines = buf.split('\n');
buf = lines.pop();
for (const line of lines) {
if (!line.startsWith('data: ')) continue;
const raw = line.slice(6).trim();
if (!raw || raw === '[DONE]') continue;
let evt;
try {
evt = JSON.parse(raw);
} catch {
continue;
}
const choice = evt.choices?.[0];
const delta = choice?.delta;
if (delta?.content) {
reply += delta.content;
sendSSE({ type: 'chunk', text: delta.content });
}
if (Array.isArray(delta?.tool_calls)) {
for (const tc of delta.tool_calls) {
const idx = tc.index ?? 0;
const slot = (toolBuf[idx] ||= { id: '', name: '', args: '' });
if (tc.id) slot.id = tc.id;
if (tc.function?.name) slot.name += tc.function.name;
if (tc.function?.arguments) slot.args += tc.function.arguments;
}
}
if (evt.usage) {
inputTokens = evt.usage.prompt_tokens ?? inputTokens;
outputTokens = evt.usage.completion_tokens ?? outputTokens;
}
}
}
} catch (err) {
return { error: err, reply, actions, toolCalls, inputTokens, outputTokens };
}
for (const slot of Object.values(toolBuf)) {
const call = parseToolCall(slot.id, slot.name, slot.args);
if (call) toolCalls.push(call);
const action = toViewerAction(call);
if (action) actions.push(action);
}
return { reply, actions, toolCalls, inputTokens, outputTokens };
}
/**
* One tool call off the wire, in a shape both providers share. Unknown names are
* dropped: a model that hallucinates a tool must not be able to put an arbitrary
* `type` on the action list the browser executes.
*/
function parseToolCall(id, name, jsonText) {
if (!name || (!ACTION_NAMES.has(name) && !isHomeTool(name))) return null;
const text = jsonText && jsonText.trim() ? jsonText : '{}';
try {
return { id: id || `call_${name}`, name, input: JSON.parse(text) };
} catch {
return null;
}
}
/** The subset the BROWSER executes. Home tools run on the server and are absent here. */
function toViewerAction(call) {
if (!call || !ACTION_NAMES.has(call.name)) return null;
return { type: call.name, ...call.input };
}
// ── System prompt + auth + helpers ───────────────────────────────────────────
// Pull the memories that should ground THIS reply: the agent's always-in-context
// core (pinned + working tier, via computeContext) merged with the memories most
// relevant to the user's message (semantic + lexical, via searchMemories). The
// owner sees everything; a visitor to a published agent sees only public
// memories. Returns the compact shape the `done` event and the client bus event
// share — id, type, tier, salience, a display snippet, and how it surfaced.
async function recallForChat(agentId, message, isOwner) {
const visible = (m) => !isVisitorQaMemory(m) && (isOwner || m.isPublic);
const [ctx, search] = await Promise.all([
computeContext(agentId).catch(() => ({ entries: [] })),
searchMemories(agentId, message, { topK: 6 }).catch(() => ({ results: [] })),
]);
const byId = new Map();
for (const m of ctx.entries || []) {
if (visible(m)) byId.set(m.id, { row: m, match: 'context' });
}
for (const m of search.results || []) {
if (!visible(m)) continue;
// A search hit on a core memory keeps the more specific match label.
const prev = byId.get(m.id);
byId.set(m.id, { row: m, match: m.match || prev?.match || 'lexical' });
}
return [...byId.values()]
.sort((a, b) => (b.row.salience || 0) - (a.row.salience || 0))
.slice(0, 10)
.map(({ row, match }) => ({
id: row.id,
type: row.type,
tier: row.tier,
salience: row.salience,
snippet: String(row.content || '').replace(/\s+/g, ' ').trim().slice(0, 160),
match,
}));
}
// Returns { text, stable, volatile }. `stable` is byte-identical across every
// turn of an agent's conversations (persona + skills + platform knowledge), so
// the Anthropic route can put a prompt-cache breakpoint after it; `volatile`
// (recalled memories + live viewer context) changes per message and stays
// after the breakpoint. `text` is the joined form every other provider uses.
export function buildSystemPrompt(ctx = {}, personaPrompt = null, recalled = [], installedSkills = [], agentSkillsBlock = '') {
const loaded = ctx.modelName
? `A model named "${ctx.modelName}" is loaded. Stats: ${fmt(ctx.vertices)} vertices, ${fmt(ctx.triangles)} triangles, ${fmt(ctx.materials)} materials, ${ctx.animations ?? 0} animations.`
: 'No model is currently loaded in the viewer.';
const validation =
ctx.validationErrors != null
? `Validation has been run: ${ctx.validationErrors} errors, ${ctx.validationWarnings ?? 0} warnings.`
: 'glTF validation has not been run yet for this model.';
const settings = `Viewer settings — wireframe:${fmtBool(ctx.wireframe)}, skeleton:${fmtBool(ctx.skeleton)}, grid:${fmtBool(ctx.grid)}, autoRotate:${fmtBool(ctx.autoRotate)}, transparentBg:${fmtBool(ctx.transparentBg)}, bgColor:${ctx.bgColor || '?'}, environment:${ctx.currentEnvironment || '?'}.`;
const lines = [];
if (personaPrompt) lines.push(personaPrompt, '');
// The agent's own custom skills sit right after its persona: they are part
// of who this agent is, and they are byte-stable across turns so they stay
// inside the prompt-cached prefix.
if (agentSkillsBlock) lines.push(agentSkillsBlock, '');
const skillsBlock = skillsPromptBlock(installedSkills);
if (skillsBlock) lines.push(skillsBlock, '');
lines.push(
'You are an embodied AI assistant rendered as a 3D avatar at three.ws — the platform for building, embedding, and monetising 3D AI agents.',
'',
'three.ws platform knowledge:',
'- Create: Upload a selfie → photorealistic 3D avatar generated in ~60 seconds.',
'- Embed: <agent-3d id="..."> works on any website (React, Vue, plain HTML) with zero config.',
'- Earn: x402 micropayments let agents charge per chat in USDC on Base.',
'- Discover: Browse and chat with live agents at three.ws/agents.',
'- Console: Manage agents at three.ws/console.',
'- Voice, memory, tool use, animations, and payments are all built-in.',
'',
'You can control animations and the scene. When the user asks you to dance, wave, jump, celebrate, etc — call the playAnimation tool IMMEDIATELY. When asked to change the background, call setBgColor with a CSS hex. When asked to change lighting, call setEnvironment.',
'Available animations: wave, dance, capoeira, jump, thriller, pray, idle, celebrate, rumba, falling, kiss, taunt.',
'You can also show the latest trades from pump.fun by calling the getPumpFunTrades tool.',
'You hold your own Solana wallet. When — and only when — the user explicitly asks you to send, pay, or transfer SOL, call the sendSol tool with the dollar amount they named (omit `to` for "send me"). Never offer or send SOL unprompted. After a send, react with a short, delighted confirmation.',
'When the user asks to change the viewer ("enable wireframe", "make the background dark blue", "turn on auto rotate", "load this model"), CALL the matching tool — do not just describe what would happen.',
'When asked about the loaded model, use the context below as ground truth. Do not invent stats.',
'Keep replies tight: 2–3 sentences. Plain text, no markdown headers, no emoji.',
);
const volatileLines = [];
if (Array.isArray(recalled) && recalled.length) {
volatileLines.push(
'What you remember (recalled for this conversation, speak from it naturally, never read it back verbatim or mention "memory IDs"):',
...recalled.map((m) => `- (${m.type}) ${m.snippet}`),
'',
);
}
volatileLines.push(loaded, validation, settings);
const stable = lines.join('\n');
const volatile = volatileLines.join('\n');
return { stable, volatile, text: `${stable}\n\n${volatile}` };
}
async function resolveAuth(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, source: 'session' };
const bearer = await authenticateBearer(extractBearer(req));
if (bearer) return bearer;
return null;
}
// Distinct provider names from the attempt log, in first-tried order — the
// client-safe summary of an exhausted chain (provider names only, no models or
// upstream messages, which could leak internals).
function providersTried(attempted) {
const out = [];
for (const a of attempted) {
if (!out.includes(a.provider)) out.push(a.provider);
}
return out;
}
// A 429 (or exhausted-chain body) that is really a deploy-wide BILLING/QUOTA wall,
// not a transient per-minute throttle. OpenAI returns HTTP 429 with
// `type: "insufficient_quota"` ("You exceeded your current quota…") AND a separate
// "Your account is not active, please check your billing details" for a dead/unfunded
// account — both 429s the generic branch would cool for only DEFAULT_COOLDOWN_SECONDS
// (45s), so the ladder re-routes to the dead provider as its final tier every ~45s and
// re-hits the same wall (the "OVER QUOTA"/"route(s) exhausted" flood seen in prod).
// These won't recover until ops tops up billing, so they deserve the long AUTH cooldown
// and the 'auth' reason (so even an explicit provider request skips the dead account),
// exactly like a 401/402/403. Replicate/Groq "insufficient credit" reads the same way.
function isBillingQuotaError(text) {
return /insufficient[_\s]?quota|insufficient[_\s]?credit|exceeded your current quota|account is not active|check your billing|billing details|quota.*exceeded|exceeded.*quota|not active.*billing/i.test(
text || '',
);
}
function fmt(n) {
return typeof n === 'number' ? n.toLocaleString('en-US') : '?';
}
function fmtBool(v) {
return typeof v === 'boolean' ? (v ? 'on' : 'off') : '?';
}
function clampInt(n, min, max) {
return Math.min(max, Math.max(min, n));
}